# API¶

class multinorm.MultiNorm(mean=None, cov=None)[source]

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:

Parameters: mean (numpy.ndarray) – Mean vector cov (numpy.ndarray) – Covariance matrix
n

Number of dimensions (int).

mean

Parameter mean values (numpy.ndarray).

cov

Covariance matrix (numpy.ndarray).

error

Parameter errors (numpy.ndarray).

Defined as $$\sigma_i = \sqrt{\Sigma_{ii}}$$.

correlation

Correlation matrix (numpy.ndarray).

Correlation $$C$$ is related to covariance $$\Sigma$$ via:

$C_{ij} = \frac{ \Sigma_{ij} }{ \sqrt{\Sigma_{ii} \Sigma_{jj}} }$
precision

Precision matrix (numpy.ndarray).

The inverse of the covariance matrix.

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

scipy

Scipy representation (scipy.stats.multivariate_normal).

Used for many computations internally.

classmethod from_error(mean=None, error=None, correlation=None)[source]

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 MultiNorm with a covariance matrix such that it’s error and correlation match the one specified here (up to rounding errors).

Parameters: mean (numpy.ndarray) – Mean vector error (numpy.ndarray) – Error vector correlation (numpy.ndarray) – Correlation matrix MultiNorm
classmethod from_samples(samples)[source]

Create MultiNorm from parameter samples.

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

Parameters: samples (numpy.ndarray) – Array of data points with shape (n_samples, n_par). MultiNorm
classmethod from_stack(distributions)[source]

Create MultiNorm by stacking distributions.

The mean vectors are concatenated, and the cov matrices are combined into a block diagonal matrix, with zeros for the off-diagonal parts.

This represents the combined measurement, assuming the individual distributions are for different parameters.

Parameters: distributions (list) – Python list of MultiNorm distributions. MultiNorm
classmethod from_product(distributions)[source]

Create MultiNorm product distribution.

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

Parameters: distributions (list) – Python list of MultiNorm distributions. MultiNorm
classmethod make_example(n_par=3, n_fix=0, random_state=0)[source]

Create MultiNorm example for testing.

This is a factory method that allows the quick creation of example MultiNorm 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: 0 Put None to choose random seed. Can also pass numpy.random.mtrand.RandomState object. MultiNorm
summary_dataframe(n_sigma=None)[source]

Summary table (pandas.DataFrame).

Parameters: n_sigma (float) – Number of standard deviations pandas.DataFrame – Summary table with one row per parameter
marginal(pars)[source]

Marginal distribution.

Parameters: pars (list) – List of parameters (integer indices) MultiNorm
conditional(pars, values=None)[source]

Conditional MultiNorm distribution.

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

Parameters: pars (list) – Fixed parameters (indices or names) values (list) – Fixed parameters (values). Default is to use the values from mean. MultiNorm
fix(pars)[source]

Fix parameters.

See Fix parameters.

Parameters: pars (list) – Parameters to fix (indices or names) MultiNorm
sigma_distance(points)[source]

Number of standard deviations from the mean.

Also called the Mahalanobis distance. See Sigmas.

Parameters: points (numpy.ndarray) – Point coordinates, 2-dim, shape (n_points, n_par). numpy.ndarray – 1-dim, shape (n_points,)
pdf(points)[source]

Probability density function.

Calls pdf method of scipy.stats.multivariate_normal.

Parameters: points (numpy.ndarray) – Point coordinates, 2-dim, shape (n_points, n_par). numpy.ndarray – 1-dim, shape (n_points,)
logpdf(points)[source]

Natural log of PDF.

Calls logpdf method of scipy.stats.multivariate_normal.

Parameters: points (numpy.ndarray) – Point coordinates, 2-dim, shape (n_points, n_par). numpy.ndarray – 1-dim, shape (n_points,)
sample(size=1, random_state=None)[source]

Draw random samples.

Calls rvs methods of scipy.stats.multivariate_normal

Parameters: size (int) – Numpy of samples to draw random_state – Seed (int) - default: 0 Put None to choose random seed. Can also pass numpy.random.mtrand.RandomState object. points (numpy.ndarray) – Point coordinates, 2-dim, shape (n_points, n_par).
make_index_mask(pars)[source]

Make index mask. TODO: document

to_uncertainties()[source]

Convert to uncertainties objects.

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

Returns: tuple (length n) of uncertainties.core.AffineScalarFunc
to_xarray(fcn='pdf', n_sigma=3, num=100)[source]

Make image of the distribution (xarray.DataArray).

This is mostly useful for visualisation, not used by other methods.

Parameters: fcn (str) – Function to compute data values. Choices: ”pdf” (pdf) ”logpdf” (logpdf) ”stat” (-2 * logpdf) ”sigma” (sigma_distance) n_sigma (int) – Number of standard deviations. Controls image coordinate range. num (int) – Number of pixels in each dimension. Controls image resolution. xarray.DataArray
error_ellipse(n_sigma=1)[source]

Error ellipse parameters.

TODO: document formulae and give example in the docs.

Parameters: n_sigma (int) – Number of standard deviations. See Sigmas. dict – Keys “xy” (center, tuple), and floats “width”, “height”, “angle”
to_matplotlib_ellipse(n_sigma=1, **kwargs)[source]

Create error ellipse (matplotlib.patches.Ellipse).

See Plot.

Parameters: n_sigma (int) – Number of standard deviations. See Sigmas. matplotlib.patches.Ellipse
plot(ax=None, n_sigma=1, **kwargs)[source]

Plot with matplotlib.

TODO: document