avicortex 1.0.0

Python functions and classes to build connectivity graphs and datasets from Freesurfer's brain cortical measurements.

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.