neurocaps.analysis.standardize

standardize(subject_timeseries_list, return_dicts=True, output_dir=None, file_names=None)

Perform Participant-wise Timeseries Standardization.

Standardizes the columns/ROIs of each run independently for all subjects in the subject timeseries. This function uses sample standard deviation, meaning Bessel's correction, n-1 is used in the denominator. Note, this function is intended for use when standardization was not performed during timeseries extraction using TimeseriesExtractor.get_bold, as requested by the user.

Parameters:

• subject_timeseries_list (list[dict[str, dict[str, np.ndarray]]] or list[os.PathLike]) --

  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 (os.PathLike 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.

• file_names (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, dict[str, dict[str, np.ndarray]]]