Stats

stats

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

Gaussian

gaussian(x, mean, var, normed=True)

returns probability density function (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:

Name	Type	Description	Default
x	scalar or array - like	The value(s) for which we compute the distribution	required
mean	scalar	Mean of the Gaussian	required
var	scalar	Variance of the Gaussian	required
normed	bool	Normalize the output if the input is an array of values.	True

Returns:

Name	Type	Description
pdf	float	probability distribution 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])

Source code in bayesian_filters/stats/stats.py

def gaussian(x, mean, var, normed=True):
    """
    returns probability density function (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(s) for which we compute the distribution

    mean : scalar
        Mean of the Gaussian

    var : scalar
        Variance of the Gaussian

    normed : bool, default True
        Normalize the output if the input is an array of values.

    Returns
    -------

    pdf : float
        probability distribution 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])
    """

    pdf = ((2 * math.pi * var) ** -0.5) * np.exp((-0.5 * (np.asarray(x) - mean) ** 2.0) / var)
    if normed and len(np.shape(pdf)) > 0:
        pdf = pdf / sum(pdf)

    return pdf

Multiply Gaussians

mul(mean1, var1, mean2, var2)

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:

Name	Type	Description	Default
mean1	scalar	mean of first Gaussian	required
var1	scalar	variance of first Gaussian	required
mean2	scalar	mean of second Gaussian	required
var2	scalar	variance of second Gaussian	required

Returns:

Name	Type	Description
mean	scalar	mean of product
var	scalar	variance of product

Examples:

>>> mul(1, 2, 3, 4)
(1.6666666666666667, 1.3333333333333333)

References

Bromily. "Products and Convolutions of Gaussian Probability Functions", Tina Memo No. 2003-003. http://www.tina-vision.net/docs/memos/2003-003.pdf

Source code in bayesian_filters/stats/stats.py

def mul(mean1, var1, mean2, var2):
    """
    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

    Examples
    --------
    >>> mul(1, 2, 3, 4)
    (1.6666666666666667, 1.3333333333333333)

    References
    ----------
    Bromily. "Products and Convolutions of Gaussian Probability Functions",
    Tina Memo No. 2003-003.
    http://www.tina-vision.net/docs/memos/2003-003.pdf
    """

    mean = (var1 * mean2 + var2 * mean1) / (var1 + var2)
    var = 1 / (1 / var1 + 1 / var2)
    return (mean, var)

Add Gaussians

add(mean1, var1, mean2, var2)

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.

Source code in bayesian_filters/stats/stats.py

def add(mean1, var1, mean2, var2):
    """
    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.
    """

    return (mean1 + mean2, var1 + var2)

Log Likelihood

log_likelihood(z, x, P, H, R)

Returns log-likelihood of the measurement z given the Gaussian posterior (x, P) using measurement function H and measurement covariance error R

Source code in bayesian_filters/stats/stats.py

def log_likelihood(z, x, P, H, R):
    """
    Returns log-likelihood of the measurement z given the Gaussian
    posterior (x, P) using measurement function H and measurement
    covariance error R
    """
    S = np.dot(H, np.dot(P, H.T)) + R
    return logpdf(z, np.dot(H, x), S)

Likelihood

likelihood(z, x, P, H, R)

Returns likelihood of the measurement z given the Gaussian posterior (x, P) using measurement function H and measurement covariance error R

Source code in bayesian_filters/stats/stats.py

def likelihood(z, x, P, H, R):
    """
    Returns likelihood of the measurement z given the Gaussian
    posterior (x, P) using measurement function H and measurement
    covariance error R
    """
    return np.exp(log_likelihood(z, x, P, H, R))

Log PDF

logpdf(x, mean=None, cov=1, allow_singular=True)

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.

Source code in bayesian_filters/stats/stats.py

def logpdf(x, mean=None, cov=1, allow_singular=True):
    """
    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.
    """

    if mean is not None:
        flat_mean = np.asarray(mean).flatten()
    else:
        flat_mean = None

    flat_x = np.asarray(x).flatten()

    if _support_singular:
        return multivariate_normal.logpdf(flat_x, flat_mean, cov, allow_singular)
    return multivariate_normal.logpdf(flat_x, flat_mean, cov)

Multivariate Gaussian

multivariate_gaussian(x, mu, cov)

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:

.. code-block:: Python

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:

.. code-block:: Python

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:

.. code-block:: Python

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

Parameters:

Name	Type	Description	Default
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.	required
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.	required
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.	required

Returns:

Name	Type	Description
probability	float	probability for x for the Gaussian (mu,cov)

Source code in bayesian_filters/stats/stats.py

def multivariate_gaussian(x, mu, cov):
    """
    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:

    .. code-block:: Python

       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:

    .. code-block:: Python

       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:

    .. code-block:: Python

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

    warnings.warn(
        (
            "This was implemented before SciPy version 0.14, which implemented "
            "scipy.stats.multivariate_normal. This function will be removed in "
            "a future release of FilterPy"
        ),
        DeprecationWarning,
    )

    # force all to numpy.array type, and flatten in case they are vectors
    x = np.asarray(x, dtype=None).flatten()
    mu = np.asarray(mu, dtype=None).flatten()

    nx = len(mu)
    cov = _to_cov(cov, nx)

    norm_coeff = nx * math.log(2 * math.pi) + np.linalg.slogdet(cov)[1]

    err = x - mu
    if sp.issparse(cov):
        numerator = spln.spsolve(cov, err).T.dot(err)
    else:
        numerator = np.linalg.solve(cov, err).T.dot(err)

    return math.exp(-0.5 * (norm_coeff + numerator))

Multivariate Multiply

multivariate_multiply(m1, c1, m2, c2)

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

Examples:

.. code-block:: Python

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

Parameters:

Name	Type	Description	Default
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.	required
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.	required
c2	matrix - like	Covariance of second Gaussian. Must be convertable to an 2D array via numpy.asarray().	required

Returns:

Name	Type	Description
m	ndarray	mean of the result
c	ndarray	covariance of the result

Source code in bayesian_filters/stats/stats.py

def multivariate_multiply(m1, c1, m2, c2):
    """
    Multiplies the two multivariate Gaussians together and returns the
    results as the tuple (mean, covariance).

    Examples
    --------

    .. code-block:: Python

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

    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
    """

    C1 = np.asarray(c1)
    C2 = np.asarray(c2)
    M1 = np.asarray(m1)
    M2 = np.asarray(m2)

    sum_inv = np.linalg.inv(C1 + C2)
    C3 = np.dot(C1, sum_inv).dot(C2)

    M3 = np.dot(C2, sum_inv).dot(M1) + np.dot(C1, sum_inv).dot(M2)

    return M3, C3

Plot Gaussian CDF

plot_gaussian_cdf(mean=0.0, variance=1.0, ax=None, xlim=None, ylim=(0.0, 1.0), xlabel=None, ylabel=None, label=None)

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

Parameters:

Name	Type	Description	Default
mean	scalar	mean for the normal distribution.	0.
variance	scalar	variance for the normal distribution.	0.
ax	matplotlib axes object	If provided, the axes to draw on, otherwise plt.gca() is used.	None
xlim		specify the limits for the x or y axis as tuple (low,high). If not specified, limits will be automatically chosen to be 'nice'	None
ylim		specify the limits for the x or y axis as tuple (low,high). If not specified, limits will be automatically chosen to be 'nice'	None
xlabel	(str, optional)	label for the x-axis	None
ylabel	str	label for the y-axis	None
label	str	label for the legend	None

Returns:

Type	Description
axis of plot

Source code in bayesian_filters/stats/stats.py

def plot_gaussian_cdf(
    mean=0.0,
    variance=1.0,
    ax=None,
    xlim=None,
    ylim=(0.0, 1.0),
    xlabel=None,
    ylabel=None,
    label=None,
):
    """
    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
    """
    import matplotlib.pyplot as plt

    if ax is None:
        ax = plt.gca()

    sigma = math.sqrt(variance)
    n = norm(mean, sigma)
    if xlim is None:
        xlim = [n.ppf(0.001), n.ppf(0.999)]

    xs = np.arange(xlim[0], xlim[1], (xlim[1] - xlim[0]) / 1000.0)
    cdf = n.cdf(xs)
    ax.plot(xs, cdf, label=label)
    ax.set_xlim(xlim)
    ax.set_ylim(ylim)
    ax.set_xlabel(xlabel)
    ax.set_ylabel(ylabel)
    return ax

Plot Gaussian PDF

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)

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

Parameters:

Name	Type	Description	Default
mean	scalar	mean for the normal distribution.	0.
variance	scalar	variance for the normal distribution.	1., optional
std		standard deviation of the normal distribution. Use instead of variance if desired	None
ax	matplotlib axes object	If provided, the axes to draw on, otherwise plt.gca() is used.	None
mean_line	boolean	draws a line at x=mean	False
xlim		specify the limits for the x or y axis as tuple (low,high). If not specified, limits will be automatically chosen to be 'nice'	None
ylim		specify the limits for the x or y axis as tuple (low,high). If not specified, limits will be automatically chosen to be 'nice'	None
xlabel	(str, optional)	label for the x-axis	None
ylabel	str	label for the y-axis	None
label	str	label for the legend	None

Returns:

Type	Description
axis of plot

Source code in bayesian_filters/stats/stats.py

def 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,
):
    """
    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
    """

    import matplotlib.pyplot as plt

    if ax is None:
        ax = plt.gca()

    if variance is not None and std is not None:
        raise ValueError("Specify only one of variance and std")

    if variance is None and std is None:
        raise ValueError("Specify variance or std")

    if variance is not None:
        std = math.sqrt(variance)

    n = norm(mean, std)

    if xlim is None:
        xlim = [n.ppf(0.001), n.ppf(0.999)]

    xs = np.arange(xlim[0], xlim[1], (xlim[1] - xlim[0]) / 1000.0)
    ax.plot(xs, n.pdf(xs), label=label)
    ax.set_xlim(xlim)

    if ylim is not None:
        ax.set_ylim(ylim)

    if mean_line:
        plt.axvline(mean)

    if xlabel is not None:
        ax.set_xlabel(xlabel)
    if ylabel is not None:
        ax.set_ylabel(ylabel)
    return ax

Plot Discrete CDF

plot_discrete_cdf(xs, ys, ax=None, xlabel=None, ylabel=None, label=None)

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

Parameters:

Name	Type	Description	Default
xs	list-like of scalars	x values corresponding to the values in ys. Can be None, in which case range(len(ys)) will be used.	required
ys	list-like of scalars	list of probabilities to be plotted which should sum to 1.	required
ax	matplotlib axes object	If provided, the axes to draw on, otherwise plt.gca() is used.	None
xlim		specify the limits for the x or y axis as tuple (low,high). If not specified, limits will be automatically chosen to be 'nice'	required
ylim		specify the limits for the x or y axis as tuple (low,high). If not specified, limits will be automatically chosen to be 'nice'	required
xlabel	(str, optional)	label for the x-axis	None
ylabel	str	label for the y-axis	None
label	str	label for the legend	None

Returns:

Type	Description
axis of plot

Source code in bayesian_filters/stats/stats.py

def plot_discrete_cdf(xs, ys, ax=None, xlabel=None, ylabel=None, label=None):
    """
    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
    """
    import matplotlib.pyplot as plt

    if ax is None:
        ax = plt.gca()

    if xs is None:
        xs = range(len(ys))
    ys = np.cumsum(ys)
    ax.plot(xs, ys, label=label)
    ax.set_xlabel(xlabel)
    ax.set_ylabel(ylabel)
    return ax

Plot Gaussian

plot_gaussian(mean=0.0, variance=1.0, ax=None, mean_line=False, xlim=None, ylim=None, xlabel=None, ylabel=None, label=None)

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

Source code in bayesian_filters/stats/stats.py

def plot_gaussian(
    mean=0.0,
    variance=1.0,
    ax=None,
    mean_line=False,
    xlim=None,
    ylim=None,
    xlabel=None,
    ylabel=None,
    label=None,
):
    """
    DEPRECATED. Use plot_gaussian_pdf() instead. This is poorly named, as
    there are multiple ways to plot a Gaussian.
    """

    warnings.warn(
        "This function is deprecated. It is poorly named. "
        "A Gaussian can be plotted as a PDF or CDF. This "
        "plots a PDF. Use plot_gaussian_pdf() instead,",
        DeprecationWarning,
    )
    return plot_gaussian_pdf(mean, variance, ax, mean_line, xlim, ylim, xlabel, ylabel, label)

Covariance Ellipse

covariance_ellipse(P, deviations=1)

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

Parameters:

Name	Type	Description	Default
P	nd.array shape (2,2)	covariance matrix	required
deviations	int (optional	of standard deviations. Default is 1.	= 1)
Returns			required

Source code in bayesian_filters/stats/stats.py

def covariance_ellipse(P, deviations=1):
    """
    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)
    """

    U, s, _ = linalg.svd(P)
    orientation = math.atan2(U[1, 0], U[0, 0])
    width = deviations * math.sqrt(s[0])
    height = deviations * math.sqrt(s[1])

    if height > width:
        raise ValueError("width must be greater than height")

    return (orientation, width, height)

Plot Covariance Ellipse

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='none', ec='#004080', alpha=1.0, xlim=None, ylim=None, ls='solid')

Deprecated function to plot a covariance ellipse. Use plot_covariance instead.

See Also

plot_covariance

Source code in bayesian_filters/stats/stats.py

def 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="none",
    ec="#004080",
    alpha=1.0,
    xlim=None,
    ylim=None,
    ls="solid",
):
    """
    Deprecated function to plot a covariance ellipse. Use plot_covariance
    instead.

    See Also
    --------

    plot_covariance
    """

    warnings.warn("deprecated, use plot_covariance instead", DeprecationWarning)
    plot_covariance(
        mean=mean,
        cov=cov,
        variance=variance,
        std=std,
        ellipse=ellipse,
        title=title,
        axis_equal=axis_equal,
        show_semiaxis=show_semiaxis,
        facecolor=facecolor,
        edgecolor=edgecolor,
        fc=fc,
        ec=ec,
        alpha=alpha,
        xlim=xlim,
        ylim=ylim,
        ls=ls,
    )

Normal CDF

norm_cdf(x_range, mu, var=1, std=None)

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

Parameters:

Name	Type	Description	Default
x_range	(float, float)	tuple of range to compute probability for	required
mu	float	mean of the Gaussian	required
var	float	variance of the Gaussian. Ignored if std is provided	1
std	float	standard deviation of the Gaussian. This overrides the var parameter	None

Returns:

Name	Type	Description
probability	float	probability that Gaussian is within x_range. E.g. .1 means 10%.

Source code in bayesian_filters/stats/stats.py

def norm_cdf(x_range, mu, var=1, std=None):
    """
    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%.
    """

    if std is None:
        std = math.sqrt(var)
    return abs(norm.cdf(x_range[0], loc=mu, scale=std) - norm.cdf(x_range[1], loc=mu, scale=std))

Random Student-t

rand_student_t(df, mu=0, std=1)

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

Source code in bayesian_filters/stats/stats.py

def rand_student_t(df, mu=0, std=1):
    """
    return random number distributed by student's t distribution with
    `df` degrees of freedom with the specified mean and standard deviation.
    """

    x = random.gauss(0, std)
    y = 2.0 * random.gammavariate(0.5 * df, 2.0)
    return x / (math.sqrt(y / df)) + mu

NEES

NEES(xs, est_xs, ps)

Computes the normalized estimated error squared (NEES) 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 NEES should be equal to or less than the dimension of x.

Examples:

.. code-block: Python

xs = ground_truth()
est_xs, ps, _, _ = kf.batch_filter(zs)
NEES(xs, est_xs, ps)

Parameters:

Name	Type	Description	Default
xs	list - like	sequence of true values for the state x	required
est_xs	list - like	sequence of estimates from an estimator (such as Kalman filter)	required
ps	list - like	sequence of covariance matrices from the estimator	required

Returns:

Name	Type	Description
errs	list of floats	list of NEES computed for each estimate

Source code in bayesian_filters/stats/stats.py

def NEES(xs, est_xs, ps):
    """
    Computes the normalized estimated error squared (NEES) 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 NEES should be equal to or less than the dimension
    of x.

    Examples
    --------

    .. code-block: Python

        xs = ground_truth()
        est_xs, ps, _, _ = kf.batch_filter(zs)
        NEES(xs, est_xs, ps)

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

    errs : list of floats
        list of NEES computed for each estimate

    """

    est_err = xs - est_xs
    errs = []
    for x, p in zip(est_err, ps):
        errs.append(np.dot(x.T, linalg.inv(p)).dot(x))
    return errs

Mahalanobis Distance

mahalanobis(x, mean, cov)

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:

Name	Type	Description	Default
x	(N,) array_like, or float	Input state vector	required
mean	(N,) array_like, or float	mean of multivariate Gaussian	required
cov	(N, N) array_like or float	covariance of the multivariate Gaussian	required

Returns:

Name	Type	Description
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

Source code in bayesian_filters/stats/stats.py

def mahalanobis(x, mean, cov):
    """
    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
    """

    x = _validate_vector(x)
    mean = _validate_vector(mean)

    if x.shape != mean.shape:
        raise ValueError("length of input vectors must be the same")

    y = x - mean
    S = np.atleast_2d(cov)

    dist = float(np.dot(np.dot(y.T, inv(S)), y))
    return math.sqrt(dist)