avicortex 1.0.0

Description:

avicortex 1.0.0

Avicortex - Brain Connectivity Graph Builder
Python functions and classes to build connectivity graphs and datasets from Freesurfer’s brain cortical measurements.

Installation
Avicortex datasets are written in torch-based classes and return torch-geometric Data objects as data samples.
Therefore you need to have a compatible torch-geometric installation along with the torch installation.
$ pip install avicortex


Usage
First, you need to have the output stats table from Freesurfer outputs. A collection of commands can be executed
from fs_utils/stats2table.sh file. We now provide Python utilities to extract these stats tables
as well. You can use our Freesurfer StatsCollector class:
>>> from avicortex.freesurfer.reader import StatsCollector
>>> collector = StatsCollector(subjects_path="/freesurfer/execution/outputs/subjects/dir")
>>> table = collector.collect_all()

StatsCollector’s collect_all function will collect all subjects, hemispheres, measurements of specified atlas into a
pandas dataframe. Then you can save your table to a csv for later use. In later versions, we will provide a better
maintained CLI.
One class is provided for HCP Young Adult dataset but the you need to access data from:
https://www.humanconnectome.org/study/hcp-young-adult
>>> from avicortex.datasets import HCPYoungAdultDataset

After you have the table, you can point the path to your dataset as following:
>>> freesurfer_stat_path = "path/to/hcp/outputs"
>>> hcp_dataset_tr = HCPYoungAdultDataset(hemisphere="left", mode="train", freesurfer_out_path=freesurfer_stat_path)

Note that you can select a hemisphere; ‘right’ or ‘left’ and a mode for dataloading; ‘train’, ‘validation’, ‘test’ or ‘inference’,
where ‘test’ is for loading the unseen data after your training is finished, and use ‘inference’ as an in-production mode when
you do not have the labels but you want to have predictions.
Moreover, you can select a feature set for the source and target graphs that will be returned. Consider graphs in shape:
Data(x=[batch_size, n_nodes, n_features], edge_attr=[batch_size, n_edges, n_features]). After the selection, you will have:
Data(x=[batch_size, n_nodes, selection_idx], edge_attr=[batch_size, n_edges, selection_idx]). You can specify this while initializing:
>>> hcp_dataset_tr = HCPYoungAdultDataset(hemisphere="left", mode="train", freesurfer_out_path=freesurfer_stat_path, src_view_idx=0, tgt_view_idx=3)

Now you can put into a torch_geometric dataloader:
>>> from torch_geometric.loader import DataLoader as PygDataLoader
>>> hcp_dataloader_tr = PygDataLoader(hcp_dataset_tr)

Let’s take a look at the first sample:
>>> input_graph, target_graph = next(iter(hcp_dataloader_tr))

Output input_graph and target_graph will belong to the same patient. And you can also access their medical condition as a classification label:
>>> cls_label = target_graph.y

This class might represent different conditions, such as different diseases, age groups, or gender. For example, in HCP Young Adult dataset, label
represents patient gender.
You can access the subject id of each graph to easily keep track of.
>>> cls_label = target_graph.subject_id

Another use case we cover is to atlas selections for both source and target. You can select different atlases for atlas-to-atlas mapping tasks.
>>> hcp_dataset_tr = HCPYoungAdultDataset(
>>> hemisphere="left",
>>> mode="train",
>>> src_atlas="dktatlas",
>>> tgt_atlas="destrieux",
>>> src_atlas_path="/path/to/dktatlas/freesurfer/table.csv",
>>> tgt_atlas_path="/path/to/destrieux/freesurfer/table.csv"
>>> )

You can further select a device and specify a random seed for reproducibility.
>>> hcp_dataset_tr = HCPYoungAdultDataset(hemisphere="left", mode="train", device="cpu", random_seed=9832)



Contributing
Contributions are welcome and highly appreciated. Feel free to open issues and pull requests.