stats

A collection of functions used to compute and plot statistics relevant to Bayesian filters.

Copyright 2015 Roger R Labbe Jr.

FilterPy library. http://github.com/rlabbe/filterpy

Documentation at: https://filterpy.readthedocs.org

Supporting book at: https://github.com/rlabbe/Kalman-and-Bayesian-Filters-in-Python

This is licensed under an MIT license. See the readme.MD file for more information.


filterpy.stats.gaussian(x, mean, var)[source]

returns normal distribution (pdf) for x given a Gaussian with the specified mean and variance. All must be scalars.

gaussian (1,2,3) is equivalent to scipy.stats.norm(2,math.sqrt(3)).pdf(1) It is quite a bit faster albeit much less flexible than the latter.

Parameters:

x : scalar or array-like

The value for which we compute the probability

mean : scalar

Mean of the Gaussian

var : scalar

Variance of the Gaussian

Returns:

probability : float

probability of x for the Gaussian (mean, var). E.g. 0.101 denotes 10.1%.

Examples

>>> gaussian(8, 1, 2)
1.3498566943461957e-06
>>> gaussian([8, 7, 9], 1, 2)
array([1.34985669e-06, 3.48132630e-05, 3.17455867e-08])

filterpy.stats.mul(mean1, var1, mean2, var2)[source]

multiply Gaussians (mean1, var1) with (mean2, var2) and return the results as a tuple (mean,var).

var1 and var2 are variances - sigma squared in the usual parlance.


filterpy.stats.add(mean1, var1, mean2, var2)[source]

add the Gaussians (mean1, var1) with (mean2, var2) and return the results as a tuple (mean,var).

var1 and var2 are variances - sigma squared in the usual parlance.


filterpy.stats.logpdf(x, mean, cov, allow_singular=True)[source]

Computes the log of the probability density function of the normal N(mean, cov) for the data x. The normal may be univariate or multivariate.

Wrapper for older versions of scipy.multivariate_normal.logpdf which don’t support support the allow_singular keyword prior to verion 0.15.0.

If it is not supported, and cov is singular or not PSD you may get an exception.

x and mean may be column vectors, row vectors, or lists.


filterpy.stats.multivariate_gaussian(x, mu, cov)[source]

This is designed to replace scipy.stats.multivariate_normal which is not available before version 0.14. You may either pass in a multivariate set of data:

multivariate_gaussian (array([1,1]), array([3,4]), eye(2)*1.4)
multivariate_gaussian (array([1,1,1]), array([3,4,5]), 1.4)

or unidimensional data:

multivariate_gaussian(1, 3, 1.4)

In the multivariate case if cov is a scalar it is interpreted as eye(n)*cov

The function gaussian() implements the 1D (univariate)case, and is much faster than this function.

equivalent calls:

multivariate_gaussian(1, 2, 3)
 scipy.stats.multivariate_normal(2,3).pdf(1)
Parameters:

x : float, or np.array-like

Value to compute the probability for. May be a scalar if univariate, or any type that can be converted to an np.array (list, tuple, etc). np.array is best for speed.

mu : float, or np.array-like

mean for the Gaussian . May be a scalar if univariate, or any type that can be converted to an np.array (list, tuple, etc).np.array is best for speed.

cov : float, or np.array-like

Covariance for the Gaussian . May be a scalar if univariate, or any type that can be converted to an np.array (list, tuple, etc).np.array is best for speed.

Returns:

probability : float

probability for x for the Gaussian (mu,cov)


filterpy.stats.multivariate_multiply(m1, c1, m2, c2)[source]

Multiplies the two multivariate Gaussians together and returns the results as the tuple (mean, covariance).

Parameters:

m1 : array-like

Mean of first Gaussian. Must be convertable to an 1D array via numpy.asarray(), For example 6, [6], [6, 5], np.array([3, 4, 5, 6]) are all valid.

c1 : matrix-like

Covariance of first Gaussian. Must be convertable to an 2D array via numpy.asarray().

m2 : array-like

Mean of second Gaussian. Must be convertable to an 1D array via numpy.asarray(), For example 6, [6], [6, 5], np.array([3, 4, 5, 6]) are all valid.

c2 : matrix-like

Covariance of second Gaussian. Must be convertable to an 2D array via numpy.asarray().

Returns:

m : ndarray

mean of the result

c : ndarray

covariance of the result

Examples

m, c = multivariate_multiply([7.0, 2], [[1.0, 2.0], [2.0, 1.0]],
                             [3.2, 0], [[8.0, 1.1], [1.1,8.0]])

filterpy.stats.plot_gaussian_cdf(mean=0.0, variance=1.0, ax=None, xlim=None, ylim=(0.0, 1.0), xlabel=None, ylabel=None, label=None)[source]

Plots a normal distribution CDF with the given mean and variance. x-axis contains the mean, the y-axis shows the cumulative probability.

Parameters:

mean : scalar, default 0.

mean for the normal distribution.

variance : scalar, default 0.

variance for the normal distribution.

ax : matplotlib axes object, optional

If provided, the axes to draw on, otherwise plt.gca() is used.

xlim, ylim: (float,float), optional

specify the limits for the x or y axis as tuple (low,high). If not specified, limits will be automatically chosen to be ‘nice’

xlabel : str,optional

label for the x-axis

ylabel : str, optional

label for the y-axis

label : str, optional

label for the legend

Returns:

axis of plot


filterpy.stats.plot_gaussian_pdf(mean=0.0, variance=1.0, ax=None, mean_line=False, xlim=None, ylim=None, xlabel=None, ylabel=None, label=None)[source]

Plots a normal distribution PDF with the given mean and variance. x-axis contains the mean, the y-axis shows the probability density.

Parameters:

mean : scalar, default 0.

mean for the normal distribution.

variance : scalar, default 0.

variance for the normal distribution.

ax : matplotlib axes object, optional

If provided, the axes to draw on, otherwise plt.gca() is used.

mean_line : boolean

draws a line at x=mean

xlim, ylim: (float,float), optional

specify the limits for the x or y axis as tuple (low,high). If not specified, limits will be automatically chosen to be ‘nice’

xlabel : str,optional

label for the x-axis

ylabel : str, optional

label for the y-axis

label : str, optional

label for the legend

Returns:

axis of plot


filterpy.stats.plot_discrete_cdf(xs, ys, ax=None, xlabel=None, ylabel=None, label=None)[source]

Plots a normal distribution CDF with the given mean and variance. x-axis contains the mean, the y-axis shows the cumulative probability.

Parameters:

xs : list-like of scalars

x values corresponding to the values in y`s. Can be `None, in which case range(len(ys)) will be used.

ys : list-like of scalars

list of probabilities to be plotted which should sum to 1.

ax : matplotlib axes object, optional

If provided, the axes to draw on, otherwise plt.gca() is used.

xlim, ylim: (float,float), optional

specify the limits for the x or y axis as tuple (low,high). If not specified, limits will be automatically chosen to be ‘nice’

xlabel : str,optional

label for the x-axis

ylabel : str, optional

label for the y-axis

label : str, optional

label for the legend

Returns:

axis of plot


filterpy.stats.plot_gaussian(mean=0.0, variance=1.0, ax=None, mean_line=False, xlim=None, ylim=None, xlabel=None, ylabel=None, label=None)[source]

DEPRECATED. Use plot_gaussian_pdf() instead. This is poorly named, as there are multiple ways to plot a Gaussian.

Plots a normal distribution PDF with the given mean and variance. x-axis contains the mean, the y-axis shows the probability density.

Parameters:

ax : matplotlib axes object, optional

If provided, the axes to draw on, otherwise plt.gca() is used.

mean_line : boolean

draws a line at x=mean

xlim, ylim: (float,float), optional

specify the limits for the x or y axis as tuple (low,high). If not specified, limits will be automatically chosen to be ‘nice’

xlabel : str,optional

label for the x-axis

ylabel : str, optional

label for the y-axis

label : str, optional

label for the legend


filterpy.stats.covariance_ellipse(P, deviations=1)[source]

returns a tuple defining the ellipse representing the 2 dimensional covariance matrix P.

Parameters:

P : nd.array shape (2,2)

covariance matrix

deviations : int (optional, default = 1)

# of standard deviations. Default is 1.

Returns (angle_radians, width_radius, height_radius)


filterpy.stats.plot_covariance_ellipse(mean, cov=None, variance=1.0, std=None, ellipse=None, title=None, axis_equal=True, show_semiaxis=False, facecolor=None, edgecolor=None, fc=u'none', ec=u'#004080', alpha=1.0, xlim=None, ylim=None, ls=u'solid')[source]

plots the covariance ellipse where

mean is a (x,y) tuple for the mean of the covariance (center of ellipse)

cov is a 2x2 covariance matrix.

variance is the normal sigma^2 that we want to plot. If list-like, ellipses for all ellipses will be ploted. E.g. [1,2] will plot the sigma^2 = 1 and sigma^2 = 2 ellipses. Alternatively, use std for the standard deviation, in which case variance will be ignored.

ellipse is a (angle,width,height) tuple containing the angle in radians, and width and height radii.

You may provide either cov or ellipse, but not both.

plt.show() is not called, allowing you to plot multiple things on the same figure.


filterpy.stats.norm_cdf(x_range, mu, var=1, std=None)[source]

computes the probability that a Gaussian distribution lies within a range of values.

Parameters:

x_range : (float, float)

tuple of range to compute probability for

mu : float

mean of the Gaussian

var : float, optional

variance of the Gaussian. Ignored if std is provided

std : float, optional

standard deviation of the Gaussian. This overrides the var parameter

Returns:

probability : float

probability that Gaussian is within x_range. E.g. .1 means 10%.


filterpy.stats.rand_student_t(df, mu=0, std=1)[source]

return random number distributed by student’s t distribution with df degrees of freedom with the specified mean and standard deviation.


filterpy.stats.NESS(xs, est_xs, ps)[source]

Computes the normalized estimated error squared test on a sequence of estimates. The estimates are optimal if the mean error is zero and the covariance matches the Kalman filter’s covariance. If this holds, then the mean of the NESS should be equal to or less than the dimension of x.

Parameters:

xs : list-like

sequence of true values for the state x

est_xs : list-like

sequence of estimates from an estimator (such as Kalman filter)

ps : list-like

sequence of covariance matrices from the estimator

Returns:

ness : list of floats

list of NESS computed for each estimate

Examples