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()	Check 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

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_sorted: cp.ndarray

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

x_values: cp.ndarray

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

out: 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()

Check if the current environment is a Jupyter notebook

Returns

bool

cubnm.utils.get_bw_params(src)

Get Balloon-Windkessel model parameters

Parameters

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

Source of the Balloon-Windkessel model parameters. - '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

exclude interhemispheric connections

return_tril: bool

return only the lower triangular part of the FCD matrix

Returns

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

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

window_step: int

dynamic FC window step (in TR)

drop_edges: bool

drop edge windows which have less than window_size volumes

outlier_threshold: float

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

exc_interhemispheric: bool

exclude interhemispheric connections

return_tril: bool

return only the lower triangular part of the FCD matrix

return_dfc: bool

return dynamic FCs as well

Returns

np.ndarray

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

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_trils: cp.ndarray

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

emp_fcd_tril: cp.ndarray

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

usable_mem: int

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

Returns

np.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_trils: cp.ndarray

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

emp_fc_tril: cp.ndarray

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

usable_mem: int

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

Returns

np.ndarray

Pearson correlation coefficients. Shape: (n_simulations,)