neurocaps.analysis.change_dtype

change_dtype(subject_timeseries_list, dtype, return_dicts=True, output_dir=None, filenames=None)

Perform Participant-wise Dtype Conversion.

Changes the dtypes of each participants numpy array. This function uses the .astype() method from numpy. This function can help reduce memory usage. For example, converting a numpy array from "float64" to "float32" can halve the memory required, which is particularly useful when analyzing large datasets on a local machine.

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
          }
      }
  

• dtype (bool or np.floating) -- Target data type (e.g "float32" or np.float32) to convert each participant's numpy arrays into.

• return_dicts (bool, default=True) -- If True, returns a single dictionary containing the converted 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 converted subject_timeseries 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 dictionaries with changed dtypes 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}_float{1}.pkl" (where {0} indicates the original input order and {1} is the dtype.

  Changed in version 0.19.0: file_names to filenames

Returns:

dict[str, dict[str, dict[str, np.ndarray]]]

Warning

Floating Point Precision: While this function allows conversion to any valid numpy dtype, it is recommended to use floating-point dtypes. Reducing the dtype could introduce rounding errors that may lower the precision of subsequent analyses as decimal digits are reduced when lower dtypes are requested. Thus, the lowest recommended floating-point dtype would be "float32", since it allows for memory usage reduction while limiting rounding errors that could significantly alter calculations.