Utility modules

Util module

util.correlate(X, Y)

Correlate X and Y numpy arrays after standardizing them

util.file_nii_or_gz(file_path)

Checks if the file exists with .nii or .nii.gz extension and returns the correct path returns None if the file does not exist with either extension

Parameters:

file_path (str) – the file path to check, can end with .nii or .nii.gz

Returns:

str – the file path with the correct extension that exists

util.get_volumes(data, atlas_name='MNISymC2')

Projects CIFTI data from any space (e.g., SUIT3/MNISymC2) back to volume space.

Parameters:

• data (list, np.ndarray) – Input data. Can be a list, NumPy array.

• atlas (str) – Atlas code to specify the projection space (e.g., ‘SUIT3’, ‘MNISymC3’). Default is ‘MNISymC2’.

Returns:

list – A list of NIfTI volume objects projected from the input data.

util.nan_linear_model(X, Y, unknowns_to_nan=True)

Calculates the Nansafe estimates of the regression model Y on design matrix X Y = X @ B If an entire row in Y is missing, the B-estimate will skip that observation If this there is no information in the data about that B anymore, the B’s are set to NaN

Parameters:

• X (ndarray) – N x Q Design matrix

• Y (ndarray) – N x P data matrix

• unknowns_to_nan (bool) – Set regression coefficients without information to Nan (instead of to zero)

Returns:

B (ndarray) – Q x P regression weights - non-estimable weights are set to NaN

util.smooth_fs32k_data(input_file, smooth=1, kernel='gaussian', return_data_only=False)

Smooth cortical data in fs32k space from cifti file, then save as cifti

format using workbench command

Parameters:

• input_file – the input cifti file to be smoothed

• smooth – width of smoothing kernel in mm

• kernel – the type of smoothing kernel, either “gaussian” or “fwhm”

• return_data_only – only return the smoothed data but not store any

Returns:

Write in the cifti file of smoothed data

util.split_string(s)

Split string into integer and string

Parameters:

s – input string to be splitted

Returns:

integer part, and string part

util.sq_eucl_distances(coordA, coordB)

Calculates the squared euclidean distance between two sets of coordinates :param coordA: 3 x N array of coordinates :type coordA: ndarray :param coordB: 3 x M array of coordinates :type coordB: ndarray

Returns:

D (ndarray) – N x M array of squared euclidean distances between each pair of coordinates in A and B

util.surf_from_cifti(ts_cifti, struct_names=['CIFTI_STRUCTURE_CORTEX_LEFT', 'CIFTI_STRUCTURE_CORTEX_RIGHT'], mask_gii=None)

Gets the time series of cortical surface vertices (Left and Right)

Parameters:

• ts_cifti (cifti obj)

• struct_names (list) – the struct name of left and right cortex

• mask_gii –

  (list of Obj.) the mask gifti object for each hemisphere

  if given. Default is None, indicating no mask for return.

  (list of str.) the file path of mask gifti for each

  hemisphere if given. Default is None, indicating no mask for return.

Returns:

cii (cifti object)

util.volume_from_cifti(ts_cifti, struct_names=None)

Gets the 4D nifti object containing the time series for all the subcortical structures

Parameters:

ts_cifti (cifti obj)

Returns:

nii_vol (nifti vol object)

Matrix module

Collection of different utility Matrices

indicator: indicator variable for each unique element in vector pairwise_contrast: All n_unique*(n_unique-1)/2 pairwise contrasts centering: Centering matrix which removes the column or row mean

@author: jdiedrichsen

matrix.centering(size)

generates a centering matrix

Parameters:

size (int) – size of the center matrix

Returns:

centering_matrix (numpy.ndarray) – size * size

matrix.indicator(index_vector, positive=False)

Indicator matrix with one column per unique element in vector

Parameters:

• index_vector (numpy.ndarray) – n_row vector to code - discrete values (one dimensional)

• positive (bool) – should the function ignore zero negative entries in the index_vector? Default: false

Returns:

indicator_matrix (numpy.ndarray) – nrow x nconditions indicator matrix

matrix.pairwise_contrast(index_vector)

Contrast matrix with one row per unqiue pairwise contrast

Parameters:

index_vector (numpy.ndarray) – n_row vector to code discrete values (one dimensional)

Returns:

• numpy.ndarray – indicator_matrix: n_values * (n_values-1)/2 x n_row

• contrast matrix

matrix.pairwise_contrast_sparse(index_vector)

Contrast matrix with one row per unqiue pairwise contrast

Parameters:

index_vector (numpy.ndarray) – n_row vector to code discrete values (one dimensional)

Returns:

scipy.sparse.csr_matrix – indicator_matrix: n_values * (n_values-1)/2 x n_row contrast matrix

matrix.row_col_indicator_G(n_cond)

generates a row and column indicator matrix for a vectorized second moment matrix. The vectorized version has the off-diagonal elements first (like in an RDM), and then appends the diagnoal. You can vectorize a second momement matrix G by np.diag(rowI@G@colI.T) = np.sum(colI*(rowI@G)),axis=1)

Parameters:

n_cond (int) – Number of conditions underlying the second moment

Returns:

• row_indicator (numpy.ndarray) – n_cond (n_cond-1)/2+n_cond * n_cond

• col_indicator (numpy.ndarray) – n_cond (n_cond-1)/2+n_cond * n_cond

matrix.row_col_indicator_RDM(n_cond)

generates a row and column indicator matrix for an RDM vector

Parameters:

n_cond (int) – Number of conditions underlying the RDM

Returns:

• row_indicator (numpy.ndarray) – n_cond (n_cond-1)/2 * n_cond

• col_indicator (numpy.ndarray) – n_cond (n_cond-1)/2 * n_cond