neurocaps.analysis.merge_dicts

merge_dicts(subject_timeseries_list, return_merged_dict=True, return_reduced_dicts=False, output_dir=None, filenames=None, save_reduced_dicts=False)[source]

Merge Participant Timeseries Across Multiple Sessions or Tasks.

Merge subject timeseries data across dictionaries, concatenating matching run IDs. Only subjects present across all input dictionaries are included in the merged output.

For example, if three dictionaries are provided contain subject 1 with:

  • dict 1: run-1 (resting-state)

  • dict 2: run-1 and run-2 (stroop)

  • dict 3: run-3 (n-back)

Then subject 1 in the final merged dictionary will contain:

  • run-1: concatenated timeseries from dict 1 and dict 2 (resting-state + stroop)

  • run-2: timeseries from dict 2 (stroop)

  • run-3: timeseries from dict 3 (n-back)

This function supports workflows for identifying similar CAPs across tasks or sessions. Specifically, using the merged dictionary as input for CAP.get_caps and the filtered input dictionaries, containing only subjects present in the merged dictionary, as inputs for CAP.calculate_metrics to compute participant-wise CAP metrics for each task.

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_merged_dict (bool, default=True) -- If True, returns a single dictionary containing the merged dictionary under a key named "merged".

  • return_reduced_dicts (bool, default=False) -- If True, returns a single dictionary containing the input dictionaries filtered to only include subjects present in the merged dictionary. 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 merged or reduced dictionaries as pickle files. The directory will be created if it does not exist. For the reduced dictionaries to be saved, save_reduced_dicts must be set to True. If save_reduced_dicts is False and output_dir is provided, only the merged dictionary will be saved. Dictionaries will not be saved if None.

  • filenames (list[str] or None, default=None) --

    A list of file names for saving dictionaries when output_dir is provided.

    If save_reduced_dicts is False:

    • Provide a single name, which will be used to save the merged dictionary.

    If save_reduced_dicts is True:

    • Provide N+1 names (where N is the length of subject_timeseries_list) - N names for individual reduced dictionaries followed by one name for the merged dictionary. Names are assigned by input position order.

    Note: Full paths are handled using basename and extensions are ignored. If None, uses default names - "subject_timeseries_{0}_reduced.pkl" (where {0} indicates the original input order) and "merged_subject_timeseries.pkl" for the merged dictionary.

    Changed in version 0.19.0: file_names to filenames

  • save_reduced_dicts (bool or None, default=False) -- If True and the output_dir is provided, then the reduced dictionaries are saved as pickle files.

Returns:

dict[str, dict[str, dict[str, np.ndarray]]] -- A nested dictionary containing the merged subject timeseries and reduced subject timeseries if specified.

References

Kupis, L., Romero, C., Dirks, B., Hoang, S., Parladé, M. V., Beaumont, A. L., Cardona, S. M., Alessandri, M., Chang, C., Nomi, J. S., & Uddin, L. Q. (2020). Evoked and intrinsic brain network dynamics in children with autism spectrum disorder. NeuroImage: Clinical, 28, 102396. https://doi.org/10.1016/j.nicl.2020.102396