correlation module

Functions for Cross-block correlation estimation as laid out in Diedrichsen et al. 2026

correlation.calc_corr_cbe(Y, rem_mpat=False, rem_mval=False, single_eps=True, negvar=0)

Calculates corrected correlation coefficient

Parameters:

• Y (list) – List of PCM datasets

• rem_mpat (bool) – Remove mean pattern in condition (False)

• rem_mval (bool) – Remove mean value (corr or cosang). Defaults to False.

• single_eps (bool) – Use single epsilon estimate all conditions. Defaults to True.

• negvar (float) – Value to replace negative variance estimates. Defaults to 0.

Returns:

• r_adj – Adjusted correlation coefficient (r/sqrt(rel1*rel2))

• sig_s – Signal variance estimate

• sig_e – Noise variance estimate

correlation.calc_corr_raw(Y, rem_mpat=False, rem_mval=False)

Calculates the uncorrected correlation estimate :param Y: List of PCM datasets :type Y: list :param rem_mpat: Remove mean pattern in condition (False) :type rem_mpat: bool :param rem_mval: Remove mean value (corr or cosang). Defaults to False. :type rem_mval: bool

Returns:

r_unc – Uncorrected correlation estimate

correlation.calc_sufficient_stats(Y, rem_mpat=False, rem_mval=False)

returns Sufficient statistics for correlation analysis

Parameters:

• Y (list) – List of PCM datasets

• rem_mpat (bool) – Remove mean pattern in condition (False)

• rem_mval (bool) – Remove mean value (corr or cosang). Defaults to False.

Returns:

• var – Variance of X and Y mean pattern

• var_cr – Variance estimate for X and Y estimated from cross-block

• cov – Covariance between X and Y mean pattern

• cov_cr – Covariance between X and Y estimated only from cross-block

• n_part – Number of partitions

correlation.combine_epsilon(var, var_cr, n_part)

Combines the epsilon estimates across two conditions for noise and recomputes signal variances

Parameters:

• var (_type_) – Variances from sufficient stats

• var_cr (_type_) – Cross-variances from sufficient stats

• n_part (_type_) – Number of partitions

Returns:

• sig_s – Signal variance estimate

• sig_e – Noise variance estimate

correlation.cond_to_item(cond_vec)

Takes a cond_vec and assigns the first half to condition1, and the second half to condition 2 cond can be any integer number - sorted by size and unique Example: cond_vec = [1,2,3,4,5,6] con_vec = [0,0,0,1,1,1] item_vec = [0,1,2,0,1,2]

Parameters:

cond_vec (ndarray) – original condition vector

Returns:

• con_vec (ndarray) – Condition [0,1] vector

• item_vec (ndarray) – Item vector

correlation.get_corr_cbe(var, var_cr, cov, n_part, single_eps=True, negvar=0)

Calculates the cross-block correlation estimate from sufficient stats uses the combined epsilon estimate if single_eps is True.

Parameters:

• var – Variance of X and Y mean pattern

• var_cr – Variance estimate for X and Y estimated from cross-block

• cov – Covariance between X and Y mean pattern

• negvar – What to do when variance estimates are negative? np.nan: exclude, 0: sign of covariance

Returns:

• r_adj – cov/sqrt(var(x) * var(y))

• sig_s – Signal variance estimate

• sig_e – Noise variance estimate

correlation.get_corr_cbe_group(var, var_cr, cov, n_part, negvar=0)

Calculates the cross-block group correlation estimate individual sufficient stats

Parameters:

• var – Variance of X and Y mean pattern

• var_cr – Variance estimate for X and Y estimated from cross-block

• cov – Covariance between X and Y mean pattern

• n_part – Number of partitions

• negvar – What to do when variance estimates are negative? np.nan: exclude, 0: sign of covariance

Returns:

• r_adj – cov/sqrt(var(x) * var(y))

• sig_s – Signal variance estimate

• sig_e – Noise variance estimate

correlation.get_corr_raw(var, cov)

Calculates the uncorrected correlation estimate from sufficient stats

Parameters:

• var – Variance of X and Y mean pattern

• cov – Covariance between X and Y mean pattern

Returns:

r_unc – cov/sqrt(var(x) * var(y))

correlation.multi_to_uni_item(Y, cond_vec, part_vec, rem_mval=False, rem_mpat=False)

Takes correlation patterns with multi-item

then for correlation analysis by stretching them out

paramters:

Y (ndarray): NxP data matrix (N observations, P voxels) cond_vec (ndarray): N-vector condition vector part_vec (ndarray): original partition vector rem_mval (bool): Remove the mean value (across voxel). False. rem_mpat (bool): Remove the mean pattern for each condition. False.

Returns:

X (ndarray) – 2(conditions) x n_part x n_item*n_vox tensor