neurocaps.analysis.change_dtype#

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

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.

Returns:

dict[str, dict[str, dict[str, np.ndarray]]] -- A nested dictionary containing the converted subject timeseries.

Warning

Floating Point Precision: The minimum recommended floating-point dtype is float32, as lower precision may introduce rounding errors that affect calculations.

On this page