neurocaps — neurocaps 1.0.0.post3 documentation (2024)

Custom Key Structure:

• maps: Directory path containing necessary parcellation files. Ensure files are in a supported format (e.g., .nii for NifTI files). For plotting purposes, this key is not required.

• nodes: List of all node labels used in your study, arranged in the exact order they correspond to indices in your parcellation files. Each label should match the parcellation index it represents. For example, if the parcellation label “0” corresponds to the left hemisphere visual cortex area 1, then “LH_Vis1” should occupy the 0th index in this list. This ensures that data extraction and analysis accurately reflect the anatomical regions intended. For timeseries extraction, this key is not required.

• regions: Dictionary defining major brain regions. Each region should list node indices under “lh” and “rh” to specify left and right hemisphere nodes. For timeseries extraction, this key is not required.

Example:

The provided example demonstrates setting up a custom parcellation containing nodes for the visual network (Vis) and hippocampus regions:

parcel_approach = { "Custom": { "maps": "/location/to/parcellation.nii.gz", "nodes": [ "LH_Vis1", "LH_Vis2", "LH_Hippocampus", "RH_Vis1", "RH_Vis2", "RH_Hippocampus" ], "regions": { "Vis": { "lh": [0, 1], "rh": [3, 4] }, "Hippocampus": { "lh": [2], "rh": [5] } } }}

Main features for TimeseriesExtractor includes:

• Timeseries Extraction: Extract timeseries for resting-state or task data, creating a nested dictionary containing the subject ID, run number, and associated timeseries. This serves as input for the get_caps() method in the CAP class.

• Saving Timeseries: Save the nested dictionary containing timeseries as a pickle file.

• Visualization: Visualize the timeseries of a Schaefer, AAL, or Custom parcellation node or region/network in a specific subject’s run, with options to save the plots.

• Parallel Processing: Use parallel processing by specifying the number of CPU cores in the n_cores parameter in the get_bold() method. Testing on an HPC using a loop with TimeseriesExtractor.get_bold() to extract session 1 and 2BOLD timeseries from 105 subjects from resting-state data (single run containing 360 volumes) and two task datasets (three runs containing 200 volumes each and two runs containing 200 volumes) reduced processing time from 5 hours 48 minutes to 1 hour 26 minutes(using 10 cores). Note: If you are using an HPC, remember to allocate the appropriate amount of CPU cores with your workload manager. For instance in slurm use #SBATCH --cpus-per-task=10 if you intend to use 10 cores.

Main features for CAP includes:

• Optimal Cluster Size Identification: Perform the silhouette or elbow method to identify the optimal cluster size, saving the optimal model as an attribute.

• Parallel Processing: Use parallel processing, when using the silhouette or elbow method, by specifying the number of CPU cores in the n_cores parameter in the `get_caps() method.Note: If you are using an HPC, remember to allocate the appropriate amount of CPU cores with your workload manager. For instance in slurm use #SBATCH --cpus-per-task=10 if you intend to use 10 cores.

• Grouping: Perform CAPs analysis for entire sample or groups of subject IDs (using the groups parameter when initializing the CAP class). K-means clustering, silhouette and elbow methods, and plotting are done for each group when specified.

• CAP Visualization: Visualize the CAPs as outer products or heatmaps, with options to use subplots to reduce the number of individual plots, as well as save.Refer to the documentation for the caps2plot() method in the CAP class for available **kwargs arguments and parameters to modify plots.

• Save CAPs as NifTIs: Convert the atlas used for parcellation to a stat map and saves them (caps2niftis).

• Surface Plot Visualization: Convert the atlas used for parcellation to a stat map projected onto a surface plot with options to customize and save plots.Refer to the documentation for the caps2surf() method in the CAP class for available **kwargs arguments and parameters to modify plots.Also includes the option to save the NifTIs. There is also another a parameter in caps2surf, fslr_giftis_dict, which can be used if the CAPs NifTI files were converted to GifTI files using a tool such as Connectome Workbench, which may work better forconverting your atlas to fslr space. This parameter allows plotting without re-running the analysis and only initializing the CAP class and using the caps2surf method is needed.

• Correlation Matrix Creation: Create a correlation matrix from CAPs with options to customize and save plots. Refer to the documentationfor the caps2corr() method in the CAP class for available **kwargs arguments and parameters to modify plots.

• CAP Metrics Calculation: Calculate CAP metrics (calculate_metrics()) as described in Liu et al., 2018 [1] and Yang et al., 2021 [2]:

  • Temporal Fraction: The proportion of total volumes spent in a single CAP over all volumes in a run.

    predicted_subject_timeseries = [1, 2, 1, 1, 1, 3]target = 1temporal_fraction = 4/6

  • Persistence: The average time spent in a single CAP before transitioning to another CAP (average consecutive/uninterrupted time).

    predicted_subject_timeseries = [1, 2, 1, 1, 1, 3]target = 1# Sequences for 1 are [1] and [1,1,1]persistence = (1 + 3)/2 # Average number of framestr = 2if tr: persistence = ((1 + 3) * 2)/2 # Turns average frames into average time

  • Counts: The frequency of each CAP observed in a run.

    predicted_subject_timeseries = [1, 2, 1, 1, 1, 3]target = 1counts = 4

  • Transition Frequency: The number of switches between different CAPs across the entire run.

    predicted_subject_timeseries = [1, 2, 1, 1, 1, 3]# Transitions between unique CAPs occur at indices 0 -> 1, 1 -> 2, and 4 -> 5transition_frequency = 3

• Cosine Similarity Radar Plots: Create radar plots showing the cosine similarity between CAPs and networks/regions. Especially useful as a quantitative method to categorize CAPs by determining the regions containing the most nodes demonstratingincreased co-activation or decreased co-deactivation [3]. Refer to the documentation in caps2radar in the CAP class for a moredetailed explanation as well as available **kwargs arguments and parameters to modify plots. Note, the “Low Amplitude”are negative cosine similarity values. The absolute value of those cosine similarities are taken so that the radar plot starts at 0 and magnitudecomparisons between the “High Amplitude” and “Low Amplitude” groups are easier to see. Below is an example of how the cosine similarity is calculated for this function.

  import numpy as np# Nodes in order of their label ID, "LH_Vis1" is the 0th index in the parcellation# but has a label ID of 1, and RH_SomSot2 is in the 7th index but has a label ID# of 8 in the parcellation.nodes = ["LH_Vis1", "LH_Vis2", "LH_SomSot1", "LH_SomSot2", "RH_Vis1", "RH_Vis2", "RH_SomSot1", "RH_SomSot2"]# Binary representation of the nodes in Vis, essentially acts as# a mask isolating the modes for for Visbinary_vector = [1,1,0,0,1,1,0,0]# Cluster centroid for CAP 1cap_1_cluster_centroid = [-0.3, 1.5, 2, -0.2, 0.7, 1.3, -0.5, 0.4]# Dot product is the sum of all the values here [-0.3, 1.5, 0, 0, 0.7, 1.3, 0, 0]dot_product = np.dot(cap_1_cluster_centroid, binary_vector)norm_cap_1_cluster_centroid = np.linalg.norm(cap_1_cluster_centroid)norm_binary_vector = np.linalg.norm(binary_vector)# Cosine similarity between CAP 1 and the visual networkcosine_similarity = dot_product/(norm_cap_1_cluster_centroid * norm_binary_vector)

Additionally, the `neurocaps.analysis` submodule contains two additional functions:

• merge_dicts: Merge the subject_timeseries dictionaries for overlapping subjects across tasks to identify similar CAPs across different tasks. The merged dictionary can be saved as a pickle file.

• standardize: Standardizes each run independently for all subjects in the subject timeseries.

Please refer to demo.ipynb for a more extensive demonstration of the features included in this package.

Contents