Getting started¶
Note
For a quick and hands-on introduction, start with the multinorm.ipynb Jupyter notebook tutorial, then continue reading here.
Import¶
The multinorm package offers a single class MultiNorm
,
so you always start like this:
from multinorm import MultiNorm
Create¶
To create a MultiNorm object, pass a mean
vector,
a covariance
matrix (both as Numpy arrays)
and optionally a list of parameter names
:
from multinorm import MultiNorm
mean = [10, 20, 30]
covariance = [[1, 0, 0], [0, 4, 0], [0, 0, 9]]
names = ["a", "b", "c"]
mn = MultiNorm(mean, covariance, names)
Sometimes the mean and covariance are given directly, e.g. in a publication, and you would define them in Python code as shown here, or read them from a file.
However, often you obtain these values as the result of a fit of a parametrised model to data, or estimate them in some other way.
Further examples to create MultiNorm
objects are here: Create
Read only¶
MultiNorm objects should be used read-only objects!
If you need to change something (mean
, covariance
, names
), make a new object!
TODO: make read-only as much as possible, the document remaining caveats!
Analyse¶
Once you have a MultiNorm
object representing a multivariate normal distribution,
you can access the following properties and methods to analyse it.
The object repr only shows the number of dimensions (number of parameters)
n
of the distribution:
>>> mn
MultiNorm(n=3)
To see the contents, print the object:
>>> print(mn)
MultiNorm(n=3)
names: ['a', 'b', 'c']
mean: [10. 20. 30.]
err: [1. 2. 3.]
cov:
[[1. 0. 0.]
[0. 4. 0.]
[0. 0. 9.]]
You can access the attributes like this:
>>> mn.n
3
>>> mn.mean
array([10., 20., 30.])
>>> mn.cov
array([[1., 0., 0.],
[0., 4., 0.],
[0., 0., 9.]])
>>> mn.names
['a', 'b', 'c']
The mean
and covar
are numpy.ndarray objects. To be as accurate as possible,
we always cast to 64-bit float on MultiNorm initialisation and do all computations
with 64-bit floating point precision, even if 32-bit float or integer numbers are passed in.
>>> type(mn.mean)
numpy.ndarray
>>> mn.mean.dtype
dtype('float64')
The mean
is a 1-dimensional array, and cov
is a 2-dimensional array:
>>> mn.mean.shape
(3,)
>>> mn.cov.shape
(3, 3)
Parameter error vector err()
:
>>> mn.err
array([1., 2., 3.])
Precision matrix (the inverse covariance) precision()
:
>>> mn.precision
array([[1. , 0. , 0. ],
[0. , 0.25 , 0. ],
[0. , 0. , 0.11111111]])
Correlation matrix correlation()
:
>>> mn.correlation
array([[1., 0., 0.],
[0., 1., 0.],
[0., 0., 1.]])
These are just the basic attributes and properties.
We continue with this example on the Analyse page and show
how to really do some analysis with MultiNorm
objects and methods.
Plot¶
Plot ellipse using to_matplotlib_ellipse()
:
import matplotlib.pyplot as plt
mn2 = mn.marginal()
mn2.plot()
What next?¶
The Create, Analyse and Plot tutorial pages contain further examples. The Theory and References pages contain background information and definitions, as well as links to other documents and codes.
The full API documentation is here: MultiNorm
.
Note that you can click on “source” on the right for any method or property,
and read the implementation to see what exactly it does.
It’s usually a few lines of straightforward code using Python and Numpy,
so reading the source is recommended.