EfficientProMises: Efficient ProMises model

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

Efficient ProMises model

Description

Performs the functional alignment of input data matrices using the Efficient ProMises model. This model has a reduced computational load compared to the full ProMises model and it allows input matrices to have different number of columns.

Usage

EfficientProMises(
  data,
  maxIt = 10,
  t = 0.001,
  k = 0,
  Q = NULL,
  ref_ds = NULL,
  scaling = TRUE,
  reflection = TRUE,
  center = TRUE,
  subj = FALSE,
  coord = NULL,
  version = "M",
  l = NULL
)

Arguments

data	data, i.e., list or array of matrices with dimension time points - voxels. Matrices can have different number of columns but must have the same numbers of rows.
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 time-points x time-points, it could be not symmetric.
ref_ds	starting reference matrix to align. If NULL, it is set to the element-wise arithmetic mean of the reduced matrices.
scaling	Flag to apply scaling transformation.
reflection	Flag to apply reflection transformation.
center	Flag to apply centering transformation to reduced data prior to alignment step.
subj	Flag if each subject has his/her own set of voxel after voxel selection step. If TRUE, then coord has to be a list with each subjects' coordinates and the model will assume a different location parameter for the prior distribution of the rotation parameters.
coord	list with 3-dim or 2-dim coordinates of the voxels of dimensions voxels x 2/3. Matrices can have different coordinates. If the location parameter Q = NULL, then coord is used to compute it (see Details).
version	which version of the Efficient ProMises model to use. If version = "M", then it decomposes the element-wise mean matrix (default), if version = "X", it decomposes the single input matrices. See Details for the description of the two versions.
l	number of singular vectors required to obtained the reduced transformation of the matrices. If NULL, it is set equal to the number of rows.

Details

Let X_1,\dots, X_N \in \mathbb{R}^{n\times m} be the N matrices to be aligned. The Efficient ProMises model computes a low dimensional representation of the X_i prior to the alignment step, achieving computational efficacy without loss of information (see Andreella and Finos, 2022 for details).

The function allows for two versions of dimensionality reduction:

• version = "M": If all the matrices have the same dimensions, compute \hat{M}=\sum_{i=1}^N X_i / N, derive the thin-SVD of \hat{M}=UDV^\top, with V \in \mathbb{R}^{m\times n}, and multiply each matrix by V. Then apply the ProMises model to X_i^*=X_iV. This version is the default since it saves time.

• version = "X": If the matrices have a different number of columns, compute the thin-SVD of each X_i=U_iD_iV_i^\top and multiply each X_i by V_i. Then apply the ProMises model to X_i^*=X_iV_i.

In both cases, at the end of the alignment step, the aligned matrices are projected back to the original space with the inverse transformation V^\top (or V_i^\top).

Prior location parameter calculation:

If Q=NULL and coord=NULL, then Q is set to a matrix of zeros (i.e. no regularization, standard Generalized Procrustes Analysis). If Q=NULL but coord is not null, then Q is calculated as follows when version="X":

• For each input matrix X_i \in \mathbb{R^{n\times m}}, compute the thin-SVD X_i=U_iD_iV_i^\top, with V_i\in \mathbb{R}^{m\times n};

• pre-multiply each coordinates matrix C_i (same coordinates matrix for all the matrices if subj=F) by V_i^\top: C_i^*=V_i^\top C_i;

• compute the euclidean distance matrix D_i among points using the coordinates in C_i^*;

• set Q_i=\exp\{-D_i\}.

If version="M", the coordinates matrix are multiplied by V that comes from the thin-SVD of \hat{M}.

Value

EfficientProMisesSubj returns a list with five components:

Xest	a list 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
M	the element-wise mean matrix of the reduced aligned matrices

Author(s)

Angela Andreella and Daniela Corbetta

References

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

Examples

{
## Create random list of matrices with different number of columns
X <- list(matrix(rnorm(100*4000), nrow=100),
          matrix(rnorm(100*3669), nrow=100),
          matrix(rnorm(100*3500), nrow=100))
## Align the matrices with the Efficient ProMises model. 
## Since subj = F and Q is a single matrix, all the rotation parameters 
## will have the same location parameter
out <- EfficientProMises(data = X, maxIt = 10, t = 1, k = 1,
                         Q = diag(1,100), subj = FALSE, scaling = FALSE,
                         center = FALSE, reflection = FALSE, 
                         ref_ds = NULL, coord = NULL, version="X", 
                         l = NULL)
                             
## create random coordinates
C <- list(cbind(sample(1:4000), sample(1:4000)),
          cbind(sample(1:3669), sample(1:3669)),
          cbind(sample(1:3500), sample(1:3500)))

## Align matrices considering a different location parameter for every 
## matrix, calculated from the coordinates as specified in details
out1 <- EfficientProMises(data = X, maxIt = 10, t = 1, k = 1,
                          Q = NULL, subj = TRUE, scaling = FALSE, 
                          center = FALSE, reflection = FALSE, 
                          ref_ds = NULL, coord = C, 
                          version="X", l = NULL)   
                              
## Extract only the first 15 singular vectors to compute the low-dimensional
## representation of the matrices
out2 <- EfficientProMises(data = X, maxIt = 10, t = 1, k = 1,
                          Q = NULL, subj = TRUE, scaling = FALSE, 
                          center = FALSE, reflection = FALSE, 
                          ref_ds = NULL, coord = C, 
                          version="X", l = 15)                         
}

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