cubnm.utils

Utility functions

cdf_2d_2d_right(A_sorted, x_values, out)	CUDA kernel for calculating CDF of matching rows in 2D arrays.
avail_gpus()	Get the number of available GPUs
is_jupyter()	This function checks if the current environment is a Jupyter notebook.
get_bw_params(src)	Get Balloon-Windkessel model parameters
calculate_fc(bold[, exc_interhemispheric, return_tril])	Calculates functional connectivity matrix
calculate_fcd(bold, window_size, window_step[, ...])	Calculates functional connectivity dynamics matrix
fcd_ks_device(sim_fcd_trils, emp_fcd_tril[, usable_mem])	Calculates Kolmogorov-Smirnov distance of provided simulated FCDs
fc_corr_device(sim_fc_trils, emp_fc_tril[, usable_mem])	Calculates Pearson correlation between simulated FCs and empirical FCs

has_cupy

cubnm.utils.has_cupy = True

cubnm.utils.cdf_2d_2d_right(A_sorted, x_values, out)

CUDA kernel for calculating CDF of matching rows in 2D arrays. For each row i, performs searchsorted (right-sided) of x_values[i] in A_sorted[i] divided by the length of A_sorted[i] resulting in empirical CDF of A_sorted[i] at x_values[i]. Each row of A_sorted[i] must be sorted in ascending order.

Parameters

A_sortedobj:cp.ndarray

2D array of sorted values. Shape: (n_rows, m)

x_valuesobj:cp.ndarray

2D array of values to calculate CDF for. Shape: (n_rows, k)

outobj:cp.ndarray

2D array to store the CDF values. Shape: (n_rows, k)

cubnm.utils.avail_gpus()

Get the number of available GPUs

Returns

int

Number of available GPUs

cubnm.utils.is_jupyter()

This function checks if the current environment is a Jupyter notebook.

Returns:

bool: True if the current environment is a Jupyter notebook, False otherwise.

cubnm.utils.get_bw_params(src)

Get Balloon-Windkessel model parameters

Parameters

src: {‘friston2003’, ‘heinzle2016-3T’}

• ‘friston2003’: Friston et al. 2003

• ‘heinzle2016-3T’: Heinzle et al. 2016, 3T parameters

Returns

dict

Balloon-Windkessel model parameters

cubnm.utils.calculate_fc(bold, exc_interhemispheric=False, return_tril=True)

Calculates functional connectivity matrix

Parameters

bold: np.ndarray

cleaned and parcellated empirical BOLD time series. Shape: (nodes, volumes) Motion outliers should either be excluded or replaced with zeros.

exc_interhemispheric: bool, optional

exclude interhemispheric connections

return_tril: bool, optional

return only the lower triangular part of the FCD matrix

Returns

fc: np.ndarray

FC dynamics matrix. Shape: (nodes, nodes) or (n_node_pairs,) if return_tril is True

cubnm.utils.calculate_fcd(bold, window_size, window_step, drop_edges=True, outlier_threshold=0.5, exc_interhemispheric=False, return_tril=True, return_dfc=False)

Calculates functional connectivity dynamics matrix and dynamic functional connectivity matrices

Parameters

bold: np.ndarray

cleaned and parcellated empirical BOLD time series. Shape: (nodes, volumes) Motion outliers should either be excluded (not recommended as it disrupts the temporal structure) or replaced with zeros.

window_size: int, optional

dynamic FC window size (in TR) Must be even. The actual window size is +1 (including center).

window_step: int, optional

dynamic FC window step (in TR)

drop_edges: bool, optional

drop edge windows which have less than window_size volumes

outlier_threshold: float, optional

threshold for the proportion of motion outliers in a window that would lead to discarding the window

exc_interhemispheric: bool, optional

exclude interhemispheric connections

return_tril: bool, optional

return only the lower triangular part of the FCD matrix

return_dfc: bool, optional

return dynamic FCs as well

Returns

fcd_matrix: np.ndarray

FC dynamics matrix. Shape: (n_windows, n_windows) or (n_window_pairs,) if return_tril is True

window_fcs: np.ndarray

dynamic FCs. Shape: (nodes, nodes, n_windows) Returned only if return_dfc is True

cubnm.utils.fcd_ks_device(sim_fcd_trils, emp_fcd_tril, usable_mem=None)

Calculates Kolmogorov-Smirnov distance of provided simulated FCDs to the empirical FCD on GPU. The calculation will be done in batches depending on the available GPU memory (usable_mem) and the memory required for each simulation.

Parameters

sim_fcd_trilscp.ndarray

2D array of simulated FCDs. Shape: (n_simulations, m1)

emp_fcd_trilcp.ndarray

1D array of empirical FCD. Shape: (m2)

usable_memint, optional

available GPU memory in bytes If not provided, 80% of the free GPU memory will be used.

Returns

ksnp.ndarray

Kolmogorov-Smirnov distances. Shape: (n_simulations,)

cubnm.utils.fc_corr_device(sim_fc_trils, emp_fc_tril, usable_mem=None)

Calculates Pearson correlation between simulated FCs and empirical FCs on GPU. The calculation will be done in batches depending on the available GPU memory (usable_mem) and the memory required for each simulation.

Parameters

sim_fc_trilscp.ndarray

2D array of simulated FCs. Shape: (n_simulations, n_pairs)

emp_fc_trilcp.ndarray

1D array of empirical FC. Shape: (n_pairs)

usable_memint, optional

available GPU memory in bytes If not provided, 80% of the free GPU memory will be used.

Returns

fc_corrnp.ndarray

Pearson correlation coefficients. Shape: (n_simulations,)