MultivariateDistribution
MultivariateDistribution()A multivariate distribution from the ported Numerics library.
Stateless: the object holds its spec as a JSON string and every verb runs one method through _core.mvdist_run. Nothing holds C++ state, so instances pickle and compare across processes. Build one with :func:mvdist_normal, :func:mvdist_student_t, :func:mvdist_dirichlet, :func:mvdist_multinomial, or :func:mvdist_bivariate_empirical rather than directly.
Attributes
| Name | Description |
|---|---|
| family | str: The multivariate distribution family name. |
Methods
| Name | Description |
|---|---|
| cdf | Cumulative probability at x. See :meth:pdf. |
| conditional | Conditional distribution of a multivariate normal. |
| covariance | numpy.ndarray: The dimension x dimension covariance matrix. |
| dimension | int: The number of dimensions. |
| interval | Rectangle probability of a multivariate normal. |
| inverse_cdf | Multivariate inverse CDF (Cholesky map). |
| log_pdf | Log-density at x. See :meth:pdf. |
| mahalanobis | Mahalanobis distance of x from the distribution. |
| marginal | Marginal distribution of a multivariate normal. |
| mean | numpy.ndarray: The mean vector, length :meth:dimension. |
| median | numpy.ndarray: The median vector, length :meth:dimension. |
| mode | numpy.ndarray: The mode vector, length :meth:dimension. |
| params | Family-specific multivariate parameters. |
Probability density at x. |
|
| random | Draw from a multivariate distribution. |
| sd | numpy.ndarray: The standard-deviation vector, length :meth:dimension. |
| to_json | This distribution’s spec as the JSON the shared C++ core parses. |
| variance | numpy.ndarray: The variance vector, length :meth:dimension. |
cdf
MultivariateDistribution.cdf(x)Cumulative probability at x. See :meth:pdf.
conditional
MultivariateDistribution.conditional(given, values)Conditional distribution of a multivariate normal.
The distribution of the remaining dimensions of a :func:mvdist_normal given fixed values for a subset. Available for "MultivariateNormal" only.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| given | array-like of int | The 1-based dimensions being conditioned on. | required |
| values | array-like of float | The values given is fixed at, the same length as given. |
required |
Returns
| Name | Type | Description |
|---|---|---|
| MultivariateDistribution | Over the complement of given. |
Notes
The returned distribution inherits this one’s Genz integrator settings, as :meth:marginal does: seed, max_evaluations, abs_error, and rel_error all carry over.
covariance
MultivariateDistribution.covariance()numpy.ndarray: The dimension x dimension covariance matrix.
dimension
MultivariateDistribution.dimension()int: The number of dimensions.
interval
MultivariateDistribution.interval(lower, upper)Rectangle probability of a multivariate normal.
P(lower <= X <= upper), integrated via the ported Genz MVNDST algorithm. Available for "MultivariateNormal" only.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| lower | array-like of float | Length :meth:dimension. |
required |
| upper | array-like of float | Length :meth:dimension. |
required |
Returns
| Name | Type | Description |
|---|---|---|
| float | A single value in [0, 1]. |
inverse_cdf
MultivariateDistribution.inverse_cdf(p)Multivariate inverse CDF (Cholesky map).
Maps a vector of independent uniform draws into one point on the distribution’s scale via the Cholesky decomposition of its covariance. This is not a true multivariate quantile (there is no unique multivariate analogue of the univariate inverse CDF); it is exactly the map upstream implements: mean + L @ qnorm(p) where L is the Cholesky factor.
"MultivariateNormal" takes dimension probabilities; "MultivariateStudentT" takes dimension + 1 (the last value drives the chi-squared mixing variable) and still returns dimension values.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| p | array-like of float | Probabilities in (0, 1) (see above for the required length). |
required |
Returns
| Name | Type | Description |
|---|---|---|
| numpy.ndarray | Length :meth:dimension. |
log_pdf
MultivariateDistribution.log_pdf(x)Log-density at x. See :meth:pdf.
mahalanobis
MultivariateDistribution.mahalanobis(x)Mahalanobis distance of x from the distribution.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| x | array-like of float | The evaluation point. | required |
Returns
| Name | Type | Description |
|---|---|---|
| float |
marginal
MultivariateDistribution.marginal(indices)Marginal distribution of a multivariate normal.
Restricts a :func:mvdist_normal to a subset of its dimensions. Available for "MultivariateNormal" only; every other family raises naming itself, not a raw C++ throw.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| indices | array-like of int | The 1-based dimensions to keep. | required |
Returns
| Name | Type | Description |
|---|---|---|
| MultivariateDistribution | Over those dimensions. |
Notes
The returned distribution inherits this one’s Genz integrator settings: seed, max_evaluations, abs_error, and rel_error all carry over. A seeded parent therefore gives a seeded child, whose :meth:cdf above dimension two is reproducible and agrees between R and Python. A parent left clock-seeded gives a clock-seeded child.
mean
MultivariateDistribution.mean()numpy.ndarray: The mean vector, length :meth:dimension.
median
MultivariateDistribution.median()numpy.ndarray: The median vector, length :meth:dimension.
Defined for "MultivariateNormal" and "MultivariateStudentT" (both return the centre); not every family defines it upstream.
mode
MultivariateDistribution.mode()numpy.ndarray: The mode vector, length :meth:dimension.
Defined for "MultivariateNormal", "MultivariateStudentT", and "Dirichlet"; not every family defines it upstream.
params
MultivariateDistribution.params()Family-specific multivariate parameters.
The scalar or vector parameters specific to a multivariate family, beyond mean/covariance: df for "MultivariateStudentT"; alpha and alpha_sum for "Dirichlet"; trials and probabilities for "Multinomial".
Returns
| Name | Type | Description |
|---|---|---|
| dict | The entries relevant to this distribution’s family. |
MultivariateDistribution.pdf(x)Probability density at x.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| x | array-like of float | The evaluation point, length equal to :meth:dimension. |
required |
Returns
| Name | Type | Description |
|---|---|---|
| float |
random
MultivariateDistribution.random(n, seed=None, method='random')Draw from a multivariate distribution.
Simulate from the distribution’s own seeded Mersenne Twister stream. A given seed reproduces the same draws bit-for-bit in R, Python, and the upstream C# library. method="latin_hypercube" draws a Latin hypercube sample instead of ordinary Monte Carlo and is available for "MultivariateNormal" and "MultivariateStudentT" only; it requires an explicit seed (there is no clock-seeded LHS upstream).
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| n | int | Number of draws. | required |
| seed | int | Seed for reproducible draws; None (the default) seeds from the clock, except for method="latin_hypercube" where it is required. |
None |
| method | ('random', 'latin_hypercube') | "random" for ordinary Monte Carlo, or "latin_hypercube". |
"random" |
Returns
| Name | Type | Description |
|---|---|---|
| numpy.ndarray | n x dimension. |
sd
MultivariateDistribution.sd()numpy.ndarray: The standard-deviation vector, length :meth:dimension.
to_json
MultivariateDistribution.to_json()This distribution’s spec as the JSON the shared C++ core parses.
Returns
| Name | Type | Description |
|---|---|---|
| str | The spec JSON. |
variance
MultivariateDistribution.variance()numpy.ndarray: The variance vector, length :meth:dimension.