comet.utils
- comet.utils.clean(time_series, detrend=False, confounds=None, standardize=False, standardize_confounds=True, filter='butterworth', low_pass=None, high_pass=None, t_r=None, ensure_finite=False)[source]
Wrapper function for nilearn.clean() for cleaning time series data
- Parameters:
time_series (TxP np.ndarray) – time series data
detrend (bool, optional) – Detrend the data. Default is False.
confounds (np.ndarray, str, pathlib.Path, pandas.DataFrame, or list of confounds) – Confounds to be regressed out from the data. Default is None.
standardize (bool, optional) – Z-score the data. Default is False.
standardize_confounds (bool, optional) – Z-score the confounds. Default is True.
filter (str {butterworth, cosine, False}) – Filtering method. Default is ‘butterworth’.
low_pass (float, optional) – Low cutoff frequency in Hertz. Default is None.
high_pass (float, optional) – High cutoff frequency in Hertz. Default is None.
t_r (float, optional) – Repetition time, in seconds (sampling period). Default is None
ensure_finite (bool, optional) – Check if the data contains only finite numbers. Default is False.
- Returns:
data – cleaned time series data
- Return type:
TxP np.ndarray
- comet.utils.dwell_times(labels: ndarray, K: int) ndarray[source]
Mean dwell time (average contiguous run length) per state. Returns 0 for states never visited.
- comet.utils.fractional_occupancy(labels: ndarray, K: int) ndarray[source]
Fraction of time spent in each state.
- comet.utils.kmeans_cluster(dfc, num_states: int = 5, strategy: str = 'pooled', subject_clusters: int = 5, standardise_features: bool = False, diag_value: float = 0.0, random_state: int | None = None, n_init: int = 50)[source]
Cluster continuously varying dFC into K discrete states using k-means.
- Parameters:
dfc (np.ndarray) – (P,P,T) single-subject or (S,P,P,T) multi-subject dynamic FC.
num_states (int) – Number of group states (K).
strategy ({"pooled", "two_level"}) –
“pooled”: cluster all timepoints across subjects together.
”two_level”: per-subject k-means to obtain subject-level centroids, then cluster all centroids to define group states; finally assign each time point to the nearest group state.
subject_clusters (int) – First-level k for “two_level”.
standardise_features (bool) – Z-score each edge across all samples before k-means.
diag_value (float) – Main diagonal values for state connectivity matrices.
random_state (int or None) – Reproducibility for KMeans.
- Returns:
state_tc ((S,T) int array) – State label per time point per subject (S=1 for single-subject).
states ((P,P,K) float array) – State connectivity matrices reconstructed from centroids (same units as input).
inertia (float) – Inertia of the final (group) k-means.
- comet.utils.load_example(fname='time_series')[source]
Load example data.
- Parameters:
fname (str, optional) – File name for any of the included data - ‘time_series’: Parcellated BOLD time series data (default) - ‘simulation’: Simulated time series data for the tutorial - ‘hurricane’: Hurricane data from https://osf.io/9rvps/ (cleaned columns)
- Returns:
data – Data corresponding to the selected file
- Return type:
np.ndarray or pd.DataFrame
- comet.utils.load_timeseries(path=None)[source]
Load time series data from a file. Supported file formats are: .pkl, .txt, .npy, .mat, and .tsv
- Parameters:
path (string) – path to the time series data file.
- Returns:
data – time series data
- Return type:
TxP np.ndarray
- comet.utils.num_transitions(labels: ndarray) int[source]
Number of state changes (i.e., i_t != i_{t-1}).
- comet.utils.save_universe_results(data)[source]
This saves the results of a universe.
If it is a single value, it will be saved in the summary .csv file. In any other case the results will be saved in a universe specific .pkl file.
- Parameters:
data (any) – Data to save as .pkl file
- comet.utils.state_plots(states=None, state_tc=None, summary=None, sub_ids=None, figsize=None)[source]
- comet.utils.summarise_state_tc(state_tc: ndarray) dict[source]
Summarise dwell times, occupancies, transitions, and switching behaviour across subjects.
- Parameters:
state_tc ((S, T) int array) – State time courses for S subjects, each of length T. Each entry represents the active state label at a given time point.
- Returns:
- ‘dwell_times’(S, K)
Mean contiguous dwell length per state and subject (in time points).
- ’fractional_occupancy’(S, K)
Fraction of total time spent in each state per subject.
- ’transitions’(S, K, K)
Row-stochastic transition probability matrices per subject (P[j|i]).
- ’transition_counts’(S, K, K)
Raw transition count matrices per subject.
- ’transitions_sum’(S,)
Total number of state changes (switches) per subject.
- ’switch_rate’(S,)
Fraction of time points involving a switch, i.e. transitions_sum / (T-1).
- Return type:
dict with
- comet.utils.switch_rate(labels: ndarray) float[source]
Proportion of steps that are transitions: num_transitions / (T-1).