ProMisesModel: ProMises model

In angeella/vMFPmodelR: Functional alignment by ProMises (Procrustes von Mises) model

ProMises model

Description

Performs the functional alignment of input data matrices using the ProMises model with unknown reference matrix.

Usage

ProMisesModel(
  data,
  maxIt = 10,
  t = 0.001,
  k = 0,
  Q = NULL,
  ref_ds = NULL,
  scaling = TRUE,
  reflection = TRUE,
  subj = FALSE,
  center = TRUE,
  kCalibrate = FALSE,
  D = NULL,
  p = 0.01,
  ind = 2
)

Arguments

data	data, i.e., array of matrices with dimension time points - voxels or list of matrices with dimension time points - voxels.
maxIt	maximum number of iterations.
t	the threshold value to be reached as the minimum relative reduction between the mean matrices.
k	value of the concentration parameter of the prior distribution of the rotation parameter.
Q	value of the location parameter of the prior distribution of the rotation parameter. It has dimension voxels x voxels, it could be not symmetric. If Q=NULL, it is set equal to a matrix of 0 (i.e. no regularization, classic Generalized Procrustes Analysis).
ref_ds	starting reference matrix to align. If NULL, at the first iteration it is set equal to the element-wise mean of the data matrices.
scaling	Flag to apply scaling transformation.
reflection	Flag to apply reflection transformation.
subj	Flag if each subject has his/her own set of voxel after voxel selection step. If subj=TRUE, then the model considers a different location parameter for the prior distribution of each rotation parameter and Q has to be an array of dimensions voxels x voxels x number of matrices.
center	Flag to apply centering transformation to data prior to alignment step.
kCalibrate	if TRUE, the parameters of the prior distribution are computed with the function kCalibrate.
D	squared euclidean distance matrix between the coordinates of the voxels. Necessary only when kCalibrate = TRUE.
p	distances to compute bandwith value for the kCalibrate function. Default value is 0.01.
ind	(only required in the case with two matrices) the index of the matrix to be used as reference, must be 1 or 2.

Details

Let X_1,\dots, X_N \in \mathbb{R}^{n\times m} be the N matrices to be aligned. The ProMises model assumes that each matrix can be represented as a random perturbation of a common reference matrix plus an error term:

X_i=(M+E_i)R_i^\top,

where

• M \in \mathbb{R}^{n\times m} is the common reference matrix,

• E_i \in \mathbb{R}^{n\times m} is a matrix error term following a matrix normal distribution,

• R_i \in \mathbb{R}^{m\times m} is the rotation parameter and follows a von Mises-Fisher distribution with location parameter Q and concentration parameter k.

The rotation parameters R_i are estimated using the maximum a posteriori estimate, given by \hat{R}_i = U_iV_i^\top, where U_i and V_i are obtained from the singular value decomposition of Q^* = X_i^\top M + kQ.

The common reference matrix M represents the shared structure among all matrices, serving as a baseline for the alignment process. Since it is unknown, it is iteratively updated during the algorithm execution. In particular, the algorithm starts with an initial guess for M as the element-wise mean matrix of the input matrices X_i. Then, in each iteration, M is updated based on the mean of the aligned matrices until convergence (Frobenius distance between two subsequent estimates of M less than t) or until the maximum number of iterations is reached.

If the number of columns m is large or if each matrix has a different number of column, then use the EfficientProMises function.

If there are only two matrices, then one matrix is projected onto the other. The solution is explicit (see Green, 1952) and is equal to \hat{R}=UV^\top, where U and V come from the SVD of X_1^\top X_2.

Value

In the case with more than two matrices, ProMisesModel returns a list with four components:

Xest	an array with the aligned matrices
R	an array with the rotation matrices
dist	a vector with length equal to the number of iterations that contains the distances between a reference matrix and the previous one
count	the number of iterations done by the algorithm

In the case with only two matrices, ProMisesModel returns a list with two components:

Xest	an array with the aligned matrices
R	an array with the rotation matrices (one is the identity)

Author(s)

Angela Andreella and Daniela Corbetta

References

For the theory on the ProMises model and more details on the algorithm see: A. Andreella and L. Finos (2022), Procrustes analysis for high-dimensional data, Psychometrika 87, 1422-1438

For the two matrix case see: B. Green (1952), The orthogonal approximation of an oblique structure in factor analysis, Psychometrika 17, 429-440.

Examples

{
## create a random array of 3 matrices with 24576 time-points and 60 voxels
data<- array(rnorm(24576*60*3), dim = c(24576,60,3))
## Align the three matrices setting the location parameter equal to the 
## identity and the concentration parameter equal to 1
out <- ProMisesModel(data, maxIt = 20, t = 1/100, k = 1, Q = diag(1,60), 
scaling = FALSE, reflection = FALSE, subj = FALSE, center = FALSE)
}

angeella/vMFPmodelR documentation built on March 9, 2024, 4:51 a.m.