`neurocaps.analysis`.standardize#

class standardize(subject_timeseries_list, return_dicts=True, output_dir=None, filenames=None)[source]#

Perform Participant-wise Timeseries Standardization Within Runs.

Standardizes the columns/ROIs of each run independently for all subjects in the subject timeseries. Uses sample standard deviation with Bessel’s correction (n-1 in denominator).

This function serves two main purposes:

When standardizing was not done in TimeseriesExtractor
When re-standardizing is needed because all of the following occurred in TimeseriesExtractor:
- High-motion volumes were removed using fd_threshold without setting the “use_sample_mask” key to True.
- standardize was not set to False.

Parameters:

subject_timeseries_list (list[SubjectTimeseries] or list[str]) –

A list where each element consist of a dictionary mapping subject IDs to their run IDs and associated timeseries (TRs x ROIs) as a NumPy array. Can also be a list consisting of paths to pickle files containing this same structure. The expected structure of each dictionary is as follows:

subject_timeseries = {
        "101": {
            "run-0": np.array([...]), # Shape: TRs x ROIs
            "run-1": np.array([...]), # Shape: TRs x ROIs
            "run-2": np.array([...]), # Shape: TRs x ROIs
        },
        "102": {
            "run-0": np.array([...]), # Shape: TRs x ROIs
            "run-1": np.array([...]), # Shape: TRs x ROIs
        }
    }

return_dicts (bool, default=True) – If True, returns a single dictionary containing the standardized input dictionaries. Keys are named “dict_{0}” where {0} corresponds to the dictionary’s position in the input list.
output_dir (str or None, default=None) – Directory to save the standardized dictionaries as pickle files. The directory will be created if it does not exist. Dictionaries will not be saved if None.
filenames (list[str] or None, default=None) – A list of names to save the standardized dictionaries as. Names are matched to dictionaries by position (e.g., a file name in the 0th position will be the file name for the dictionary in the 0th position of subject_timeseries_list). If None and output_dir is specified, uses default file names - “subject_timeseries_{0}_standardized.pkl” (where {0} indicates the original input order).

Returns:

dict[str, SubjectTimeseries] – A nested dictionary containing the standardized subject timeseries if return_dicts is True.

neurocaps.analysis.standardize#

`neurocaps.analysis`.standardize#