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, normed=True)[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
- norm : bool, default True
Normalize the output if the input is an array of values.
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 Gaussian (mean1, var1) with (mean2, var2) and return the results as a tuple (mean, var).
Strictly speaking the product of two Gaussian PDFs is a Gaussian function, not Gaussian PDF. It is, however, proportional to a Gaussian PDF, so it is safe to treat the output as a PDF for any filter using Bayes equation, which normalizes the result anyway.
Parameters: - mean1 : scalar
mean of first Gaussian
- var1 : scalar
variance of first Gaussian
- mean2 : scalar
mean of second Gaussian
- var2 : scalar
variance of second Gaussian
Returns: - mean : scalar
mean of product
- var : scalar
variance of product
References
Bromily. “Products and Convolutions of Gaussian Probability Functions”, Tina Memo No. 2003-003. http://www.tina-vision.net/docs/memos/2003-003.pdf
Examples
>>> mul(1, 2, 3, 4) (1.6666666666666667, 1.3333333333333333)
-
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.
log_likelihood
(z, x, P, H, R)[source]¶ Returns log-likelihood of the measurement z given the Gaussian posterior (x, P) using measurement function H and measurement covariance error R
-
filterpy.stats.
likelihood
(z, x, P, H, R)[source]¶ Returns likelihood of the measurement z given the Gaussian posterior (x, P) using measurement function H and measurement covariance error R
-
filterpy.stats.
logpdf
(x, mean=None, cov=1, 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, std=None, 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 1., optional
variance for the normal distribution.
- std: scalar, default=None, optional
standard deviation of the normal distribution. Use instead of variance if desired
- 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.
-
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]¶ Deprecated function to plot a covariance ellipse. Use plot_covariance instead.
See also
plot_covariance
-
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
-
filterpy.stats.
mahalanobis
(x, mean, cov)[source]¶ Computes the Mahalanobis distance between the state vector x from the Gaussian mean with covariance cov. This can be thought as the number of standard deviations x is from the mean, i.e. a return value of 3 means x is 3 std from mean.
Parameters: - x : (N,) array_like, or float
Input state vector
- mean : (N,) array_like, or float
mean of multivariate Gaussian
- cov : (N, N) array_like or float
covariance of the multivariate Gaussian
Returns: - mahalanobis : double
The Mahalanobis distance between vectors x and mean
Examples
>>> mahalanobis(x=3., mean=3.5, cov=4.**2) # univariate case 0.125
>>> mahalanobis(x=3., mean=6, cov=1) # univariate, 3 std away 3.0
>>> mahalanobis([1., 2], [1.1, 3.5], [[1., .1],[.1, 13]]) 0.42533327058913922