API

class multinorm.MultiNorm(mean=None, cov=None, names=None)

Multivariate normal distribution.

Given n parameters, the mean and names should be one-dimensional with size n, and cov should be a two-dimensional matrix of shape (n, n).

Documentation for this class:

• Tutorial Jupyter notebook: multinorm.ipynb
• Documentation: Getting started, Create, Analyse
• Equations and statistics: Theory

Note that MultiNorm objects should be used read-only, almost all properties are cached. If you need to modify values, make a new MultiNorm object.

Parameters:

• mean (numpy.ndarray) – Mean vector
• cov (numpy.ndarray) – Covariance matrix
• names (list) – Python list of parameter names (str). Default: use “par_i” with i = 0 .. N - 1.

conditional(pars, values=None)

Conditional MultiNormal distribution.

Resulting lower-dimensional distribution obtained by fixing pars to values. The output distribution is for the other parameters, the complement of pars.

See Conditional distribution.

Parameters:

• pars (list) – Fixed parameters (indices or names)
• values (list) – Fixed parameters (values). Default is to use the values from mean.

Returns:

MultiNorm – Conditional distribution

correlation

Correlation matrix (pandas.DataFrame).

Correlation \(C\) is related to covariance \(\Sigma\) via:

\[C_{ij} = \frac{ \Sigma_{ij} }{ \sqrt{\Sigma_{ii} \Sigma_{jj}} }\]

cov

Covariance matrix (pandas.DataFrame).

drop(pars)

Drop parameters.

This simply removes the entry from the mean vector, and the corresponding column and row from the cov matrix.

The computation is the same as MultiNorm.marginal(), only here the parameters to drop are given, and there the parameters to keep are given.

Parameters:pars (list) – Parameters to fix (indices or names)

err

Error vector (pandas.DataFrame).

Defined as \(\sigma_i = \sqrt{\Sigma_{ii}}\).

fix(pars)

Fix parameters.

See Fix parameters.

Parameters:pars (list) – Parameters to fix (indices or names)

classmethod from_err(mean=None, err=None, correlation=None, names=None)

Create MultiNorm from parameter errors.

With errors \(\sigma_i\) this will create a diagonal covariance matrix with

\[\Sigma_{ii} = \sigma_i^2\]

For a given correlation, or in general: this will create a MultiNormal with a covariance matrix such that it’s err and correlation match the one specified here (up to rounding errors).

Parameters:

• mean (numpy.ndarray) – Mean vector
• err (numpy.ndarray) – Error vector
• correlation (numpy.ndarray) – Correlation matrix
• names (list) – Parameter names

classmethod from_points(points, names=None)

Create MultiNorm from parameter points.

Usually the points are samples from some distribution and creating this MultiNorm distribution is an estimate / approximation of that distribution of interest.

See: From points.

Parameters:points (numpy.ndarray) – Array of data points with shape (n, 2).

classmethod from_product(distributions)

Create MultiNorm as product distribution.

This represents the joint likelihood distribution, assuming the individual distributions are from independent measurements.

See Product distribution .

Parameters:distributions (list) – Python list of MultiNorm distributions. Returns:MultiNorm – Product distribution

logpdf(points)

Natural log of PDF.

Calls scipy.stats.multivariate_normal.

classmethod make_example(n_par=3, n_fix=0, random_state=42)

Create example MultiNorm for testing.

This is a factory method that allows the quick creation of example MultiNormal with any number of parameters for testing.

See: Make example.

Parameters:

• n_par (int) – Number of parameters
• n_fix (int) – Number of fixed parameters in addition to n_par.
• random_state – Seed (int) - default: 42 Put None to choose random seed. Can also pass numpy.random.RandomState object.

marginal(pars)

Marginal MultiNormal distribution.

See Marginal distribution.

Parameters:pars (list) – List of parameters (integer indices) Returns:MultiNorm – Marginal distribution

mean

Mean vector (pandas.Series).

n

Number of dimensions of the distribution (int).

Given by the number of parameters.

names

Parameter names (list of str).

parameters

Parameter table (pandas.DataFrame).

Index is “name”, columns are “mean” and “err”

pdf(points)

Probability density function.

Calls scipy.stats.multivariate_normal.

precision

Precision matrix (pandas.DataFrame).

The inverse of the covariance matrix.

Sometimes called the “information matrix” or “Hesse matrix”.

sample(size=1, random_state=None)

Draw random samples.

Calls scipy.stats.multivariate_normal.

scipy

Frozen scipy.stats.multivariate_normal distribution object.

A cached property. Used for many computations internally.

sigma_distance(point)

Number of standard deviations from the mean (float).

Also called the Mahalanobis distance. See Sigmas.

to_matplotlib_ellipse(n_sigma=1, **kwargs)

Create matplotlib.patches.Ellipse.

See examples in Plot.

Parameters:n_sigma (int) – Number of standard deviations. See Sigmas.

to_uncertainties()

Convert to uncertainties objects.

A tuple of numbers with uncertainties (one for each parameter) is returned.

The uncertainties package makes it easy to do error propagation on derived quantities.

See examples in Analyse.