SPD module

SPD.Karcher(data, eps=1e-08, max_steps=20)

Karcher mean for given shapes. (Fletcher, Lu, and Joshi 2003)

Calculated Karcher mean for given data by minimizing the sum of squared (Riemannian) distances to all points in the data

Parameters:

  • data – (n_elements, 2, 2) array of given data

  • eps – float number: convergence criterion

  • max_steps – maximum number of iterations to converge

Returns:

(2, 2) array defining Karcher mean

SPD.PGA(mu, data, n_coord=None)

Principal Geodesic Analysis (PGA).

Principal Geodesic Analysis (PGA), a generalization of Principal Component Analysis (PCA) over Riemannian manifolds. PGA is a data-driven approach that determines principal components as elements in a central tangent space, given a data set represented as elements in asmooth manifold.

Parameters:

  • mu – (2, 2) array defining Karcher mean

  • data – (n_points, 2, 2) given data

  • n_coord – dimension of resulting PGA space (if None n_coord=4)

Returns:

Vh is principal basis transposed ((n_coord*2)x(n_coord*2)), t are given elements in principal coordinates, S is corresponding singular values,

SPD.exp(t, P, S)

SPD Exponential. (Fletcher, P. T., & Joshi, S. 2004)

Parameters:

  • t – scalar > 0, how far in given direction to move (if t=0, exp(P, log_map) = P)

  • P – (2, 2) array = starting point in S_++^2

  • S – (2, 2) array = direction in tangent space in T_P S_++^2

Returns:

(2, 2) array = end point

SPD.log(P, D)

SPD Logarithmic mapping (inverse mapping of exponential map). (Fletcher, P. T., & Joshi, S. 2004)

Calculates direction S (tangent vector Delta) from P to D in tangent subspace.

Parameters:

  • P – (2, 2) array = start point in S_++^2

  • D – (2, 2) array = end point in S_++^2

Returns:

(2, 2) array = direction in tangent space (tangent vector Delta) in T_P S_++^2

SPD.perturb_mu(Vh, mu, perturbation)

Given element Karcher mean, perturbs it in given direction by a given amount.

Parameters:

  • Vh – (n_landmarks*2 - 4 , n_landmarks*2 - 4) array of PGA basis vectors transposed

  • mu – (n_landmarks, 2) array of Karcher mean (elenemt on Grassmann)

  • perturbation – (n_modes,) array of amount of perturbations in pga coordinates

Returns:

(n_landmarks, 2) array of perturbed element on Grassmann

SPD.polar_decomposition(X_phys)
Parameters:

X_phys – (n_shapes, n_landmarks, 2) array of physical coordinates defining shapes

Returns:

X_grassmann, P, b, such that X_phys = X_grassmann @ P + b.

SPD.tangent_space(mu, data)

Get tangent directions (SPD Logarithmic mapping) from given point mu to each point of the data and vectorize resulting tangent vectors of shape (n, 2) into shape (2*n) for later SVD decomposition in PGA analysis.

Parameters:

  • mu – starting point for tangent vectors

  • data – nparray of data points (elements of Grassamnnian)

Returns:

nparray of vectorized tangent vectors

SPD.vec(P)

Return vector of the upper-triangle elements

Parameters:

P – (n, n) symmetric matrix

Returns:

(n*(n+1)/2,1) vectorization of unique entries

SPD.vecinv(p)

Return symmetric matrix from vectorized form

Parameters:

p – (n*(n+1)/2,1) vector of symmetric matrix entries returned by consistent vectorization

Returns:

(n,n) corresponding symmetric matrix