API

class multinorm.MultiNorm(mean=None, cov=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

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)

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).

See Create from fit and Create from publication.

Parameters:

• mean (numpy.ndarray) – Mean vector
• error (numpy.ndarray) – Error vector
• correlation (numpy.ndarray) – Correlation matrix

Returns:

MultiNorm

classmethod from_samples(samples)

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.

See Create from samples.

Parameters:samples (numpy.ndarray) – Array of data points with shape (n_samples, n_par). Returns:MultiNorm

classmethod from_stack(distributions)

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.

See From stack and Stacked distribution.

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

classmethod from_product(distributions)

Create MultiNorm product distribution.

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

See From product and Product distribution.

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

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

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.

Returns:

MultiNorm

summary_dataframe(n_sigma=None)

Summary table (pandas.DataFrame).

• “mean” – mean
• “error” - error
• (“lo”, “hi”) - confidence interval (if n_sigma is set)

Parameters:n_sigma (float) – Number of standard deviations Returns:pandas.DataFrame – Summary table with one row per parameter

marginal(pars)

Marginal distribution.

See Marginal distribution.

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

conditional(pars, values=None)

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.

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

fix(pars)

Fix parameters.

See Fix parameters.

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

sigma_distance(points)

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). Returns:numpy.ndarray – 1-dim, shape (n_points,)

pdf(points)

Probability density function.

Calls pdf method of scipy.stats.multivariate_normal.

Parameters:points (numpy.ndarray) – Point coordinates, 2-dim, shape (n_points, n_par). Returns:numpy.ndarray – 1-dim, shape (n_points,)

logpdf(points)

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). Returns:numpy.ndarray – 1-dim, shape (n_points,)

sample(size=1, random_state=None)

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.

Returns:

points (numpy.ndarray) – Point coordinates, 2-dim, shape (n_points, n_par).

make_index_mask(pars)

Make index mask. TODO: document

to_uncertainties()

Convert to uncertainties objects.

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

See Error propagation.

Returns:tuple (length n) of uncertainties.core.AffineScalarFunc

to_xarray(fcn='pdf', n_sigma=3, num=100)

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.

Returns:

xarray.DataArray

error_ellipse(n_sigma=1)

Error ellipse parameters.

TODO: document formulae and give example in the docs.

Parameters:n_sigma (int) – Number of standard deviations. See Sigmas. Returns:dict – Keys “xy” (center, tuple), and floats “width”, “height”, “angle”

to_matplotlib_ellipse(n_sigma=1, **kwargs)

Create error ellipse (matplotlib.patches.Ellipse).

See Plot.

Parameters:n_sigma (int) – Number of standard deviations. See Sigmas. Returns:matplotlib.patches.Ellipse

plot(ax=None, n_sigma=1, **kwargs)

Plot with matplotlib.

TODO: document