fSTG-Toolkit 1.0.0

Aan Open-Source Software for Spatio-Temporal Graph Analysis of fMRI data.

fSTG Toolkit: an Open-Source Software for Spatio-Temporal Graph Analysis of fMRI data

Overview

fSTG Toolkit is an open-source software dedicated to longitudinal analysis of brain connectivity, modeling data as spatio-temporal graphs. It enables the study of dynamics and reorganization of brain regions, primarily using functional MRI (fMRI) data, but is also compatible with any type of connectivity data.

Current main features:

• Building of spatio-temporal graphs from correlation matrices and region definitions.
• Advanced graph metrics computation.
• Interactive visualization of results.
• Simulation of connectivity patterns and sequences.

Future features in planned updates:

• Frequent patterns detection and analysis in spatio-temporal graphs.
• Web-based server to enhance end-user's interactions with an installation-free service.

Installation

The easiest way to ge started is to create a new environment with the required python and poetry binaries. Using conda, to install the environment and activate it, run:

conda env create -n <env_name> -f environment.yml
conda activate <env_name>

Then in the project's root folder to install the dependencies, run:

poetry install

Usage

The CLI tool provides several commands building, calculating metrics, plotting, simulating and viewing the results. To see the complete list of commands, run:

python -m fstg_toolkit --help

Use the --help option with any command to get specific help. Some examples and explanations are provided in the next section.

Examples

Build one or multiple graphs

Assume the timeseries of correlation matrices are stored in a numpy pickle file (matrices.npz or matrices.npy) and the definitions of the areas and regions are in a CSV file (areas.csv).

The areas/regions definition must be formatted as follows:

Id_Area	Name_Area	Name_Region
1	Area1	Region1
2	Area2	Region1
3	Area3	Region2
4	Area4	Region3

Accordingly, the CSV file should look like this:

Id_Area,Name_Area,Name_Region
1,Area1,Region1
2,Area2,Region1
3,Area3,Region2
4,Area4,Region3

To build a spatio-temporal graph from the inputs and save the graph to the archive file my_graph.zip, use the command:

python -m fstg_toolkit build -o my_graph.zip areas.csv matrices.npz

The build command also works with multiple sequences of matrices. All sequences stored in a single .npz or .npy will be red. To build sequences from multiple file, just input them all:

python -m fstg_toolkit build -o my_graphs.zip areas.csv matrices-1.npz matrices-2.npz matrcices-3.npz

Calculate metrics

Metrics can be calculating using the metrics command. From a dataset of built spatio-temporal graph, run:

python -m fstg_toolkit metrics my_graphs.zip

The calculated metrics will be inserted in the dataset archive.

View the results

To visualize a dashboard to explore the processed data from a dataset with the show command, run:

python -m fstg_toolkit show my_graphs.zip

It will start a local server and open a web browser containing the dashboard, that includes the content of the dataset, the raw matrices, a visualization of the spatio-temporal graphs, etc. An illustration of the dashboard is shown below.

Factors and Subjects Detection

If the names of the matrices are formatted, factors and subjects will be automatically detected and can be used to filter the data and choose the display of the plots. The parts of the names must be separated either by underscores (_) or by slashes (/) or a combination of both. For instance, the following names will be correctly parsed:

• control_time1_T21;
• control/time2_T22;
• group1_time2/T31;
• group1_time1_T11.

The subjects will be matched to the part that has different values between the names, and the factors will be the parts that are common to multiple names. If a part is similar in all names, it will not be considered. In this case, the subjects are T21, T22, T31, and T11, and the factors are control and group1 for first factor, time1 and time2 for the second factor.