Statistics

Manifolds.GeodesicInterpolationType
GeodesicInterpolation <: AbstractEstimationMethod

Repeated weighted geodesic interpolation method for estimating the Riemannian center of mass.

The algorithm proceeds with the following simple online update:

\[\begin{aligned} μ_1 &= x_1\\ t_k &= \frac{w_k}{\sum_{i=1}^k w_i}\\ μ_{k} &= γ_{μ_{k-1}}(x_k; t_k), \end{aligned}\]

where $x_k$ are points, $w_k$ are weights, $μ_k$ is the $k$th estimate of the mean, and $γ_x(y; t)$ is the point at time $t$ along the shortest_geodesic between points $x,y ∈ \mathcal M$. The algorithm terminates when all $x_k$ have been considered. In the Euclidean case, this exactly computes the weighted mean.

The algorithm has been shown to converge asymptotically with the sample size for the following manifolds equipped with their default metrics when all sampled points are in an open geodesic ball about the mean with corresponding radius (see GeodesicInterpolationWithinRadius):

For online variance computation, the algorithm additionally uses an analogous recursion to the weighted Welford algorithm [West1979].

source
Statistics.covMethod
Statistics.cov(
    M::AbstractManifold,
    x::AbstractVector;
    basis::AbstractBasis=DefaultOrthonormalBasis(),
    tangent_space_covariance_estimator::CovarianceEstimator=SimpleCovariance(;
        corrected=true,
    ),
    mean_estimation_method::AbstractEstimationMethod=GradientDescentEstimation(),
    inverse_retraction_method::AbstractInverseRetractionMethod=default_inverse_retraction_method(
        M,
    ),
)

Estimate the covariance matrix of a set of points x on manifold M. Since the covariance matrix on a manifold is a rank 2 tensor, the function returns its coefficients in basis induced by the given tangent space basis. See Section 5 of [Pennec2006] for details.

The mean is calculated using the specified mean_estimation_method using [mean](@ref Statistics.mean(::AbstractManifold, ::AbstractVector, ::AbstractEstimationMethod), and tangent vectors at this mean are calculated using the provided inverse_retraction_method. Finally, the covariance matrix in the tangent plane is estimated using the Euclidean space estimator tangent_space_covariance_estimator. The type CovarianceEstimator is defined in StatsBase.jl and examples of covariance estimation methods can be found in CovarianceEstimation.jl.

source
Statistics.mean!Method
mean!(M::AbstractManifold, y, x::AbstractVector[, w::AbstractWeights]; kwargs...)
mean!(
    M::AbstractManifold,
    y,
    x::AbstractVector,
    [w::AbstractWeights,]
    method::AbstractEstimationMethod;
    kwargs...,
)

Compute the mean in-place in y.

source
Statistics.meanMethod
mean(
    M::AbstractManifold,
    x::AbstractVector,
    [w::AbstractWeights,]
    method::ExtrinsicEstimation;
    kwargs...,
)

Estimate the Riemannian center of mass of x using ExtrinsicEstimation, i.e. by computing the mean in the embedding and projecting the result back. You can specify an extrinsic_method to specify which mean estimation method to use in the embedding, which defaults to GeodesicInterpolation.

See mean for a description of the remaining kwargs.

source
Statistics.meanMethod
mean(
    M::AbstractManifold,
    x::AbstractVector,
    [w::AbstractWeights,]
    method::GeodesicInterpolation;
    shuffle_rng=nothing,
    retraction::AbstractRetractionMethod = ExponentialRetraction(),
    inverse_retraction::AbstractInverseRetractionMethod = LogarithmicInverseRetraction(),
    kwargs...,
)

Estimate the Riemannian center of mass of x in an online fashion using repeated weighted geodesic interpolation. See GeodesicInterpolation for details.

If shuffle_rng is provided, it is used to shuffle the order in which the points are considered for computing the mean.

Optionally, pass retraction and inverse_retraction method types to specify the (inverse) retraction.

source
Statistics.meanMethod
mean(M::AbstractManifold, x::AbstractVector[, w::AbstractWeights]; kwargs...)

Compute the (optionally weighted) Riemannian center of mass also known as Karcher mean of the vector x of points on the AbstractManifold M, defined as the point that satisfies the minimizer

\[\argmin_{y ∈ \mathcal M} \frac{1}{2 \sum_{i=1}^n w_i} \sum_{i=1}^n w_i\mathrm{d}_{\mathcal M}^2(y,x_i),\]

where $\mathrm{d}_{\mathcal M}$ denotes the Riemannian distance.

In the general case, the GradientDescentEstimation is used to compute the mean. mean( M::AbstractManifold, x::AbstractVector, [w::AbstractWeights,] method::AbstractEstimationMethod; kwargs..., )

Compute the mean using the specified method.

mean(
    M::AbstractManifold,
    x::AbstractVector,
    [w::AbstractWeights,]
    method::GradientDescentEstimation;
    p0=x[1],
    stop_iter=100,
    retraction::AbstractRetractionMethod = ExponentialRetraction(),
    inverse_retraction::AbstractInverseRetractionMethod = LogarithmicInverseRetraction(),
    kwargs...,
)

Compute the mean using the gradient descent scheme GradientDescentEstimation.

Optionally, provide p0, the starting point (by default set to the first data point). stop_iter denotes the maximal number of iterations to perform and the kwargs... are passed to isapprox to stop, when the minimal change between two iterates is small. For more stopping criteria check the Manopt.jl package and use a solver therefrom.

Optionally, pass retraction and inverse_retraction method types to specify the (inverse) retraction.

The Theory stems from[Karcher1977] and is also described in[PennecArsigny2013] as the exponential barycenter. The algorithm is further described in[Afsari2013].

source
Statistics.median!Method
median!(M::AbstractManifold, y, x::AbstractVector[, w::AbstractWeights]; kwargs...)
median!(
    M::AbstractManifold,
    y,
    x::AbstractVector,
    [w::AbstractWeights,]
    method::AbstractEstimationMethod;
    kwargs...,
)

computes the median in-place in y.

source
Statistics.medianMethod
median(
    M::AbstractManifold,
    x::AbstractVector,
    [w::AbstractWeights,]
    method::CyclicProximalPointEstimation;
    p0=x[1],
    stop_iter=1000000,
    retraction::AbstractRetractionMethod = ExponentialRetraction(),
    inverse_retraction::AbstractInverseRetractionMethod = LogarithmicInverseRetraction(),
    kwargs...,
)

Compute the median using CyclicProximalPointEstimation.

Optionally, provide p0, the starting point (by default set to the first data point). stop_iter denotes the maximal number of iterations to perform and the kwargs... are passed to isapprox to stop, when the minimal change between two iterates is small. For more stopping criteria check the Manopt.jl package and use a solver therefrom.

Optionally, pass retraction and inverse_retraction method types to specify the (inverse) retraction.

The algorithm is further described in [Bačák2014].

source
Statistics.medianMethod
median(
    M::AbstractManifold,
    x::AbstractVector,
    [w::AbstractWeights,]
    method::ExtrinsicEstimation;
    extrinsic_method = CyclicProximalPointEstimation(),
    kwargs...,
)

Estimate the median of x using ExtrinsicEstimation, i.e. by computing the median in the embedding and projecting the result back. You can specify an extrinsic_method to specify which median estimation method to use in the embedding, which defaults to CyclicProximalPointEstimation.

See median for a description of kwargs.

source
Statistics.medianMethod
median(
    M::AbstractManifold,
    x::AbstractVector,
    [w::AbstractWeights,]
    method::WeiszfeldEstimation;
    α = 1.0,
    p0=x[1],
    stop_iter=2000,
    retraction::AbstractRetractionMethod = ExponentialRetraction(),
    inverse_retraction::AbstractInverseRetractionMethod = LogarithmicInverseRetraction(),
    kwargs...,
)

Compute the median using WeiszfeldEstimation.

Optionally, provide p0, the starting point (by default set to the first data point). stop_iter denotes the maximal number of iterations to perform and the kwargs... are passed to isapprox to stop, when the minimal change between two iterates is small. For more stopping criteria check the Manopt.jl package and use a solver therefrom.

The parameter $α\in (0,2]$ is a step size.

The algorithm is further described in [FletcherVenkatasubramanianJoshi2008], especially the update rule in Eq. (6), i.e. Let $q_{k}$ denote the current iterate, $n$ the number of points $x_1,\ldots,x_n$, and

\[I_k = \bigl\{ i \in \{1,\ldots,n\} \big| x_i \neq q_k \bigr\}\]

all indices of points that are not equal to the current iterate. Then the update reads $q_{k+1} = \exp_{q_k}(αX)$, where

\[X = \frac{1}{s}\sum_{i\in I_k} \frac{w_i}{d_{\mathcal M}(q_k,x_i)}\log_{q_k}x_i \quad \text{ with } \quad s = \sum_{i\in I_k} \frac{w_i}{d_{\mathcal M}(q_k,x_i)},\]

and where $\mathrm{d}_{\mathcal M}$ denotes the Riemannian distance.

Optionally, pass retraction and inverse_retraction method types to specify the (inverse) retraction, which by default use the exponential and logarithmic map, respectively.

source
Statistics.medianMethod
median(M::AbstractManifold, x::AbstractVector[, w::AbstractWeights]; kwargs...)
median(
    M::AbstractManifold,
    x::AbstractVector,
    [w::AbstractWeights,]
    method::AbstractEstimationMethod;
    kwargs...,
)

Compute the (optionally weighted) Riemannian median of the vector x of points on the AbstractManifold M, defined as the point that satisfies the minimizer

\[\argmin_{y ∈ \mathcal M} \frac{1}{\sum_{i=1}^n w_i} \sum_{i=1}^n w_i\mathrm{d}_{\mathcal M}(y,x_i),\]

where $\mathrm{d}_{\mathcal M}$ denotes the Riemannian distance. This function is nonsmooth (i.e nondifferentiable).

In the general case, the CyclicProximalPointEstimation is used to compute the median. However, this default may be overloaded for specific manifolds.

Compute the median using the specified method.

source
Statistics.stdMethod
std(M, x, m=mean(M, x); corrected=true, kwargs...)
std(M, x, w::AbstractWeights, m=mean(M, x, w); corrected=false, kwargs...)

compute the optionally weighted standard deviation of a Vector x of n data points on the AbstractManifold M, i.e.

\[\sqrt{\frac{1}{c} \sum_{i=1}^n w_i d_{\mathcal M}^2 (x_i,m)},\]

where c is a correction term, see Statistics.std. The mean of x can be specified as m, and the corrected variance can be activated by setting corrected=true.

source
Statistics.varMethod
var(M, x, m=mean(M, x); corrected=true)
var(M, x, w::AbstractWeights, m=mean(M, x, w); corrected=false)

compute the (optionally weighted) variance of a Vector x of n data points on the AbstractManifold M, i.e.

\[\frac{1}{c} \sum_{i=1}^n w_i d_{\mathcal M}^2 (x_i,m),\]

where c is a correction term, see Statistics.var. The mean of x can be specified as m, and the corrected variance can be activated by setting corrected=true. All further kwargs... are passed to the computation of the mean (if that is not provided).

source
StatsBase.kurtosisMethod
kurtosis(M::AbstractManifold, x::AbstractVector, k::Int[, w::AbstractWeights], m=mean(M, x[, w]))

Compute the excess kurtosis of points in x on manifold M. Optionally provide weights w and/or a precomputed mean m.

source
StatsBase.mean_and_stdMethod
mean_and_std(M::AbstractManifold, x::AbstractVector[, w::AbstractWeights]; kwargs...) -> (mean, std)

Compute the mean and the standard deviation std simultaneously.

mean_and_std(
    M::AbstractManifold,
    x::AbstractVector
    [w::AbstractWeights,]
    method::AbstractEstimationMethod;
    kwargs...,
) -> (mean, var)

Use the method for simultaneously computing the mean and standard deviation. To use a mean-specific method, call mean and then std.

source
StatsBase.mean_and_varMethod
mean_and_var(
    M::AbstractManifold,
    x::AbstractVector
    [w::AbstractWeights,]
    method::GeodesicInterpolationWithinRadius;
    kwargs...,
) -> (mean, var)

Use repeated weighted geodesic interpolation to estimate the mean. Simultaneously, use a Welford-like recursion to estimate the variance.

See GeodesicInterpolationWithinRadius and mean_and_var for more information.

source
StatsBase.mean_and_varMethod
mean_and_var(
    M::AbstractManifold,
    x::AbstractVector
    [w::AbstractWeights,]
    method::GeodesicInterpolation;
    shuffle_rng::Union{AbstractRNG,Nothing} = nothing,
    retraction::AbstractRetractionMethod = ExponentialRetraction(),
    inverse_retraction::AbstractInverseRetractionMethod = LogarithmicInverseRetraction(),
    kwargs...,
) -> (mean, var)

Use the repeated weighted geodesic interpolation to estimate the mean. Simultaneously, use a Welford-like recursion to estimate the variance.

If shuffle_rng is provided, it is used to shuffle the order in which the points are considered. Optionally, pass retraction and inverse_retraction method types to specify the (inverse) retraction.

See GeodesicInterpolation for details on the geodesic interpolation method.

Note

The Welford algorithm for the variance is experimental and is not guaranteed to give accurate results except on Euclidean.

source
StatsBase.mean_and_varMethod
mean_and_var(M::AbstractManifold, x::AbstractVector[, w::AbstractWeights]; kwargs...) -> (mean, var)

Compute the mean and the variance simultaneously. See those functions for a description of the arguments.

mean_and_var(
    M::AbstractManifold,
    x::AbstractVector
    [w::AbstractWeights,]
    method::AbstractEstimationMethod;
    kwargs...,
) -> (mean, var)

Use the method for simultaneously computing the mean and variance. To use a mean-specific method, call mean and then var.

source
StatsBase.momentFunction
moment(M::AbstractManifold, x::AbstractVector, k::Int[, w::AbstractWeights], m=mean(M, x[, w]))

Compute the kth central moment of points in x on manifold M. Optionally provide weights w and/or a precomputed mean.

source
StatsBase.skewnessMethod
skewness(M::AbstractManifold, x::AbstractVector, k::Int[, w::AbstractWeights], m=mean(M, x[, w]))

Compute the standardized skewness of points in x on manifold M. Optionally provide weights w and/or a precomputed mean m.

source

Literature

  • Ho2013

    Ho J.; Cheng G.; Salehian H.; Vemuri B. C.; Recursive Karcher expectation estimators and geometric law of large numbers. Proceedings of the 16th International Conference on Artificial Intelligence and Statistics (2013), pp. 325–332. pdf.

  • Salehian2015

    Salehian H.; Chakraborty R.; Ofori E.; Vaillancourt D.; An efficient recursive estimator of the Fréchet mean on a hypersphere with applications to Medical Image Analysis. Mathematical Foundations of Computational Anatomy (2015). pdf.

  • Chakraborty2015

    Chakraborty R.; Vemuri B. C.; Recursive Fréchet Mean Computation on the Grassmannian and Its Applications to Computer Vision. Proceedings of the IEEE International Conference on Computer Vision (ICCV) (2015), pp. 4229-4237. doi: 10.1109/ICCV.2015.481, link.

  • Cheng2016

    Cheng G.; Ho J.; Salehian H.; Vemuri B. C.; Recursive Computation of the Fréchet Mean on Non-positively Curved Riemannian Manifolds with Applications. Riemannian Computing in Computer Vision. Springer, Cham (2016), pp. 21-43. doi: 10.1007/978-3-319-22957-7_2, pdf.

  • Chakraborty2019

    Chakraborty R.; Vemuri B. C.; Statistics on the (compact) Stiefel manifold: Theory and Applications. The Annals of Statistics (2019), 47(1), pp. 415-438. doi: 10.1214/18-AOS1692, arxiv: 1708.00045.

  • West1979

    West D. H. D.; Updating Mean and Variance Estimates: An Improved Method. Communications of the ACM (1979), 22(9), pp. 532–535. doi: 10.1145/359146.359153.

  • Pennec2006

    X. Pennec, “Intrinsic Statistics on Riemannian Manifolds: Basic Tools for Geometric Measurements,” J Math Imaging Vis, vol. 25, no. 1, p. 127, Jul. 2006, doi: 10.1007/s10851-006-6228-4.

  • Afsari2013

    Afsari, B; Tron, R.; Vidal, R.: On the Convergence of Gradient Descent for Finding the Riemannian Center of Mass, SIAM Journal on Control and Optimization (2013), 51(3), pp. 2230–2260, doi: 10.1137/12086282X, arxiv: 1201.0925

  • PennecArsigny2013

    Pennec X., Arsigny V.: Exponential Barycenters of the Canonical Cartan Connection and Invariant Means on Lie Groups. In: Nielsen F., Bhatia R. (eds) Matrix Information Geometry, (2013), pp. 123-166. doi: 10.1007/978-3-642-30232-9_7, hal: https://hal.inria.fr/hal-00699361/document

  • Karcher1977

    Karcher, H.: Riemannian center of mass and mollifier smoothing. Communications on Pure Applied Mathematics (1977), 30, pp. 509–541. doi 10.1002/cpa.3160300502

  • Bačák2014

    Bačák, M: Computing Medians and Means in Hadamard Spaces. SIAM Journal on Optimization (2014), 24(3), pp. 1542–1566, doi: 10.1137/140953393, arxiv: 1210.2145

  • FletcherVenkatasubramanianJoshi2008

    Fletcher, T., Venkatasubramanian, S., Joshi, S: Robust statistics on Riemannian manifolds via the geometric median 2008 IEEE Conference on Computer Vision and Pattern Recognition, doi: 10.1109/CVPR.2008.4587747,