A toolbox for exploring network correspondence across atlases
Project description
cbig_network_correspondence
Documentation: https://rubykong.github.io/cbig_network_correspondence
Source Code: https://github.com/rubykong/cbig_network_correspondence
PyPI: https://pypi.org/project/cbig_network_correspondence/
This toolbox was used to explore the network correspondence between networks across different atlases.
Installation
Python installation
Check here for how to install python: https://realpython.com/installing-python/
Conda environment
We provide NCT python environment here: NCT_env. You can create a conda environment using the following command:
conda env create -f NCT_env.yml
To use this environment, activate the environment using the following command:
conda activate NCT_env
NCT installation
To install:
pip install cbig_network_correspondence
To upgrade:
pip install --upgrade cbig_network_correspondence
If you don't have pip installed, this pip installation can guide you through the process.
Usage
Quick Example!
Test the toolbox quickly using the example data! Check the last section in Usage.ipynb for the results.
import cbig_network_correspondence as cnc
atlas_names_list = ["EG17","MG360J12"]
example = cnc.load_example
# the example config file
print(example.example_config)
# the path to the example data
print(example.example_nii)
ref_params = cnc.compute_overlap_with_atlases.DataParams(example.example_config, example.example_nii)
cnc.compute_overlap_with_atlases.network_correspondence(ref_params, atlas_names_list,"~/NCTexample/example_results")
Tutorial
We provide a tutorial for how to use this toolbox. The tutorial is available in the Usage.ipynb notebook:
Atlases we included
Check this list for the atlases we have included. We use abbreviations for the atlases. Here we provide the decription for each atlas. If you want us to include your atlas, please contact me (roo.cone@gmail.com).
Abbreviation | Source | Description |
---|---|---|
MG360J12 | Glasser2016; Ji2019 | Mattew Glasser2016 360-ROI with Ji2019 12 Cole-Anticevic networks |
HCPICA | Smith2009; Smith2013 | HCP 25-node ICA maps |
AL20 | Laird2011 | Angela Laird2011 20-node ICA maps |
AS200K17 | Schaefer2018; Kong2021 | Alex Schaefer2018 200-ROI with Kong2021 17 networks |
AS200Y17 | Schaefer2018; Yeo2011 | Alex Schaefer2018 200-ROI with Yeo2011 17 networks |
AS400K17 | Schaefer2018; Kong2021 | Alex Schaefer2018 400-ROI with Kong2021 17 networks |
AS400Y17 | Schaefer2018; Yeo2011 | Alex Schaefer2018 400-ROI with Yeo2011 17 networks |
XS268_8 | Shen2013 | Xilin Shen2013 268-ROI with 8 networks |
XS368_8 | Shen2013 | Xilin Shen2013 368-ROI with 8 networks |
WS90_14 | Shirer2012 | William Shirer2012 90-ROI 14 networks |
UKBICA | Smith2009; Alfaro-Almagro2018 | UKBiobank 25-node ICA maps |
EG286_12 | Power2011; Gordon2016 | Evan Gordon2016 286-ROI with 12 networks |
TL12 | Power2011; Laumann2015 | Tim Laumann2015 12 networks (Power2011) |
EG17 | Power2011; Gordon2017 | Evan Gordon2017 17 networks |
TY7 | Yeo2011 | Thomas Yeo 7 networks |
TY17 | Yeo2011 | Thomas Yeo 17 networks |
XY200K17 | Yan2023; Kong2021 | Xiaoxuan Yan2023 200-ROI with Kong2021 17 networks |
XY200Y17 | Yan2023; Yeo2011 | Xiaoxuan Yan2023 200-ROI with Yeo2011 17 networks |
XY400K17 | Yan2023; Kong2021 | Xiaoxuan Yan2023 400-ROI with Kong2021 17 networks |
XY400Y17 | Yan2023; Yeo2011 | Xiaoxuan Yan2023 400-ROI with Yeo2011 17 networks |
EG5 | Gordon2023 | Evan Gordon2023 5 networks |
TW_TASK_NETS | Woodward2024 | Todd Woodward 2024 12 Task-based Networks |
DU15NET | Du2024 | Jingnan Du2024 15 networks |
These atlases should be automatically downloaded when you install the toolbox. If you want to download the atlases manually, you can find the atlases here: https://github.com/rubykong/cbig_network_correspondence_data. The atlas data will be automatically downloaded in your python package directory: cbig_network_correspondence/src/cbig_network_correspondence/data
.
Input data
The toolbox can also explore the network correspondence of your own input data. The input data can be different format. We support input data in fs_LR_32k, fsaverage6, and FSLMNI2mm.
Format
Here are the formats we support:
For data in fs_LR_32k or fsaverage6 space:
-
.mat
file: The file should contain two variables starting withlh
andrh
. For example, the variable names could belh_data
,rh_data
orlh_labels
,rh_labels
. Each variable should be a 32492x1 vector forfs_LR_32k
space or a 40962x1 vector forfsaverage6
space. -
.npy
file: The file should contain a numpy array with shape (64984, 1) forfs_LR_32k
space or (81924, 1) forfsaverage6
space.
For data in FSLMNI2mm space:
.nii
or.nii.gz
file: The file should be a nifti file with the same dimension as the FSL MNI152 2mm template.
Pass in the data as ...
-
A single path to a single file
/data_dir/my_task_contrast_map.mat
/data_dir/my_task_contrast_map.npy
/data_dir/my_task_contrast_map.nii.gz
-
A list of paths to multiple files
['/data_dir/my_task_contrast_map1.mat', '/data_dir/my_task_contrast_map2.mat']
['/data_dir/my_task_contrast_map1.npy', '/data_dir/my_task_contrast_map2.npy']
['/data_dir/my_task_contrast_map1.nii.gz', '/data_dir/my_task_contrast_map2.nii.gz']
-
A directory contains the input files
/data_dir
under this directory, the toolbox will search for the files containing theData_Name
in the config file (see the Config file section for more details). For example, if theData_Name
ismy_task_contrast_map
, the toolbox will search for the files containingmy_task_contrast_map
in the file name
-
A string indicating the name of a existing atlas
AS400Y17
EG17
TY17
Reference data space
To explore the network correspondence between a given input data and existing atlases, the toolbox will use the input data as the reference data. The toolbox will use existing atlases in the same space as the input data. For example, if the input data is in fs_LR_32k
space, the toolbox will use the existing atlases in fs_LR_32k
space. If the input data is in FSLMNI2mm
space, the toolbox will use the existing atlases in FSLMNI2mm
space.
Reference data names
User can specify the name for the given input data, if not, the toolbox will use the Data_Name
in the config file as the reference data name.
Reference data names could be important for a multi-dimension input data. For example, if the input data is a set of task contrast maps, the user might want to specify the reference data names for each task contrast map. Otherwise, the toolbox will name each task contrast map as <Data_Name>1
, <Data_Name>2
, etc.
If the input data is the user's own atlas with K networks, the user should specify the reference data names for each network. Otherwise the toolbox will name each network as <Data_Name>1
, <Data_Name>2
, etc.
Config file
In this toolbox, the information for each atlas or input data is constructed as a config file. We have included the config files for existing atlases. The config files will be automatically downloaded when you install the toolbox. If you want to check the config files manually, you can find the config files in your python package directory: cbig_network_correspondence/src/cbig_network_correspondence/data/atlas_config
. If you want to explore network correspondence of your own input data/atlas, you can create your own config file, check next sections for how to create a config file.
The config file should be a text file.
Here is an example of the config file for the Schaefer 400-ROI atlas with Yeo 17-network network assignemnt AS400Y17
:
[data_info]
Data_Category: YeoLab
Data_Name: AS400Y17
Data_Space: fsaverage6
Data_Type: Hard
Data_NetworkAssignment: 1
Here is an example of the config file for a example metric data Example
:
[data_info]
Data_Name: Example
Data_Space: FSLMNI2mm
Data_Type: Metric
Data_Threshold: [5,Inf]
Here is the decription for the config file:
-
Data_Category
[optional]We included it for existing atlases because some atlases were from the same lab. In this case, we put the some atlases into the same category. This is not necessary for your own atlas or your own metric data.
-
Data_Name
The name of the atlas or metric data. If the input data is a set of files instead of a single file, user can pass in the directory to the files. The toolbox will search for the files containing the
Data_Name
in the file name. For example, if theData_Name
ismy_task_contrast_map
, the toolbox will search for the files containingmy_task_contrast_map
in the file name. -
Data_Space
The space name of the space where the atlas/data is in. It can be a surface name or a volumetric space name. We currenly have atlases in the following spaces:
fs_LR_32k
surface space,fsaverage6
surface space,FSLMNI2mm
volumetric space,LairdColin2mm
volumetric space,ShenColin1mm
volumetric space. If the user wants to explore the network correspondence of their own data, the data should be infs_LR_32k
,fsaverage6
, orFSLMNI2mm
space. -
Data_Type
The type of the atlas/data. We have two types of atlas:
Hard
andSoft
. TheHard
atlas is the atlas that each ROI is assigned to a specific network. TheSoft
atlas is the atlas that each ROI is assigned to a probability of belonging to each network. We also allow for a metric data such as task contrast maps or probability maps, in this caseData_Type
should beMetric
. -
Data_NetworkAssignment
[optional]Sometimes the atlas has fine-grained ROIs and these ROIs were assigned to large-scale networks. For example, the Schaefer2018 400 ROIs were assigned to the Yeo 17-network atlas. In this case the user can provide a mapping between ROIs to networks, here you can find the mapping for some of the existing atlases: https://github.com/rubykong/cbig_network_correspondence_data/tree/master/network_assignment
-
Data_Threshold
[optional]For soft parcellation and metric data, we will need to apply a threshold to binarize the data. The threshold should be set as
[lower bound, upper bound]
. If the upper bound isInf
, then the threshold will be applied as>= lower bound
. If the lower bound is-Inf
, then the threshold will be applied as<= upper bound
. If theData_Type
isSoft
orMetric
, but theData_Threshold
is not provided, the toolbox will use a default threshold[0, Inf]
.Data_Threshold
is not necessary forHard
atlas.
After importing the toolbox, here are the relevant commands. After decribing the commands, we provide examples for how to use this toolbox. We also provided a jupyter notebook for the usage examples: Usage.ipynb.
Usage scenarios
This toolbox has two main usage scenarios:
- Use this toolbox to explore network correspondence between existing atlases.
- Provide users' own input data, and explore the network correspondence between the input data and existing atlases.
We have provided detailed examples for each usage scenario in the Usage.ipynb notebook. Here we provide brief descriptions for inputs.
1. Explore network correspondence between existing atlases
import cbig_network_correspondence as cnc
cnc.compute_overlap_with_atlases.network_correspondence(reference_atlas, atlas_names_list, output_dir)
reference_atlas
: str- The name of the reference atlas. The reference atlas should be one of the existing atlases. The toolbox will use the reference atlas to explore the network correspondence between the reference atlas and other atlases in the
atlas_names_list
.
- The name of the reference atlas. The reference atlas should be one of the existing atlases. The toolbox will use the reference atlas to explore the network correspondence between the reference atlas and other atlases in the
atlas_names_list
: list- A list of the names of the atlases. The toolbox will explore the network correspondence between the reference atlas and the atlases in the
atlas_names_list
.
- A list of the names of the atlases. The toolbox will explore the network correspondence between the reference atlas and the atlases in the
output_dir
: str- The directory to save the output figures and csv files.
Note: network name should be the abbreviation of the atlas. For example, AS400Y17
for the Schaefer 400-ROI atlas with Yeo 17-network network assignemnt.
2. Explore network correspondence between input data and existing atlases
import cbig_network_correspondence as cnc
# construct DataParams object based on the data file path and config
ref_params = cnc.compute_overlap_with_atlases.DataParams(config, file_path)
# compute the overlap with atlases and save the results
cnc.compute_overlap_with_atlases.network_correspondence(ref_params, atlas_names_list,output_dir,ref_data_names)
config
: str- The path to the config file for the input data.
file_path
: str/list- The path to a single input data file
- A list of paths to multiple input data files
- A directory contains the input data files
atlas_names_list
: list- A list of the names of the atlases. The toolbox will explore the network correspondence between the input data and the atlases in the
atlas_names_list
.
- A list of the names of the atlases. The toolbox will explore the network correspondence between the input data and the atlases in the
output_dir
: str- The directory to save the output figures and csv files.
ref_data_names
: str/list- The name of the input data. If
ref_data_names
is not provided, the toolbox will use theData_Name
in the config file as the reference data name. If the input data is multi-dimension, each dimension will be named as<Data_Name>1
,<Data_Name>2
,... if theref_data_names
is not provided.
- The name of the input data. If
Significance test
The toolbox provides a significance test to test the significance of the network correspondence between the given input data and an existing atlas. The toolbox will use the spin-test (Gordon2017;Alexander-Bloch2018)to test the significance of the network correspondence. Specically, SpinPermutations from BrainSpace python package is used here. For data in FSLMNI2mm space, we project the data to the fsaverage6 space for the spin-test.
Results
NCT provides different types of plots to help the user explore/visualize the network correspondences.
-
Overlap Heatmap
- If input data has multiple dimensions, e.g., a atlas with K networks, a set of task contrast maps. For a specified list of existing atlases, the toolbox will provide heatmaps to show the overlap between the input data and the existing atlases. Each atlas will have a heatmap. If input data has K dimension, and the other atlas has N networks, the heatmap will be a KxN heatmap. Each row represents the overlap between the input data and an existing atlas. Each column represents the overlap between the input data and a network in the existing atlas. The color represents the overlap value. The asterisk indicates the significance of the overlap.
-
Network Clock
- If input data is single dimension, e.g., a task contrast map, a probability map. For a specified list of existing atlases, the toolbox will provide a network clock to show the overlap between the input data and the existing atlases. The network clock will show the overlap between the input data and all networks. Networks from the same atlas are grouped together and colored by the same color. Only the networks with significant overlap will be indicated by network name in the network clock. The clock ring represents the overlap value. The network font size represents the overlap value.
-
Network Radar
- If input data is single dimension, e.g., a task contrast map, a probability map. For a specified list of existing atlases, the toolbox will provide a network radar to show the overlap between the input data and the existing atlases. Each atlas will have a radar map. The asterisk indicates the significance of the overlap.
-
Summary Table
- The toolbox will provide a summary table to show the exact overlap values and p-values of the overlap between the input data and the existing atlases. Summary tables will be saved as figures and csv files.
Development
- Clone this repository
- Requirements:
- Poetry
- Python 3.9+
- Create a virtual environment and install the dependencies
poetry install
- Activate the virtual environment
poetry shell
This project was generated using the wolt-python-package-cookiecutter template.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file cbig_network_correspondence-0.3.1.tar.gz
.
File metadata
- Download URL: cbig_network_correspondence-0.3.1.tar.gz
- Upload date:
- Size: 27.3 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: poetry/1.8.3 CPython/3.10.15 Linux/6.5.0-1025-azure
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | df696ba29d3ea9eeabab233b33b836a0b4a01fa9528fc1f7a47ad6a4e8e97150 |
|
MD5 | 51672084da11a1fbad609e27672d1efe |
|
BLAKE2b-256 | 4fb5cadc1b235b25b102c30dbda7533f50dc93115d21994a586149b43e48c02c |
File details
Details for the file cbig_network_correspondence-0.3.1-py3-none-any.whl
.
File metadata
- Download URL: cbig_network_correspondence-0.3.1-py3-none-any.whl
- Upload date:
- Size: 25.1 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: poetry/1.8.3 CPython/3.10.15 Linux/6.5.0-1025-azure
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 2ddf67849b0e1c891aee3bdaccc903046939c9e601616ef453f8564456820397 |
|
MD5 | e7812625bb81d0ee0dae6d87ac098f3e |
|
BLAKE2b-256 | 3cce3a9beda9dc10991a384445f850952e4cbfe639558bc1868206f79b30dcae |