procrustes¶

Data alignment — SRM, Procrustes, and state alignment.

Methods:

Classes¶

Methods¶

align¶

align(data, method = 'deterministic_srm', n_features = None, axis = 0, *args, **kwargs)

Align subject data into a common response model.

This function is a convenience wrapper around HyperAlignment and SRM classes.

Can be used to hyperalign source data to target data using Hyperalignment from Dartmouth (i.e., procrustes transformation; see nltools.algorithms.procrustes) or Shared Response Model from Princeton (see nltools.algorithms.srm). (see nltools.data.BrainData.align for aligning a single Brain object to another). Common Model is shared response model or centered target data. Transformed data can be back projected to original data using Tranformation matrix. Inputs must be a list of BrainData instances or numpy arrays (observations by features).

Parameters:

Returns:

Examples:

• Hyperalign using procrustes transform:

  out = align(data, method=‘procrustes’)

• Align using shared response model:

  out = align(data, method=‘probabilistic_srm’, n_features=None)

• Project aligned data into original data:

  original_data = [np.dot(t.data,tm.T) for t,tm in zip(out[‘transformed’], out[‘transformation_matrix’])]

align_states¶

align_states(reference, target, *, metric = 'correlation', return_index = False, replace_zero_variance = False)

Align state weight maps by minimizing pairwise distance between group states.

This function uses the Hungarian algorithm for state alignment, which is different from aligning multiple subjects’ data.

Parameters:

Returns: If return_index=False (default): target[:, remapping], a single ndarray of the target’s columns reordered to match the reference, oriented pattern x state (same shape as target). If return_index=True: the remapping index array (ndarray) that reorders the target’s state columns.

procrustes¶

procrustes(data1, data2)

Perform a Procrustes similarity analysis on two data sets.

For more comprehensive Procrustes-based alignment tasks, use HyperAlignment and align() instead.

Each input matrix is a set of points or vectors (the rows of the matrix). The dimension of the space is the number of columns of each matrix. Given two identically sized matrices, procrustes standardizes both such that:

• $tr(AA^{T}) = 1$.

• Both sets of points are centered around the origin. Procrustes then applies the optimal transform to the second matrix (including scaling/dilation, rotations, and reflections) to minimize $M^{2}=\sum(data1-data2)^{2}$, or the sum of the squares of the pointwise differences between the two input datasets. This function was not designed to handle datasets with different numbers of datapoints (rows). If two data sets have different dimensionality (different number of columns), this function will add columns of zeros to the smaller of the two.

Parameters:

Returns:

procrustes_distance¶

procrustes_distance(mat1, mat2, *, n_permute = 5000, tail = 2, n_jobs = -1, random_state = None)

Test matrix similarity using Procrustes superposition.

Matrices need to match in size on their first dimension only, as the smaller matrix on the second dimension will be padded with zeros. After aligning two matrices using the Procrustes transformation, use the computed disparity between them (sum of squared error of elements) as a similarity metric. Shuffle the rows of one of the matrices and recompute the disparity to perform inference (Peres-Neto & Jackson, 2001).

Parameters:

Returns: