Metadata-Version: 2.4
Name: fSTG-Toolkit
Version: 1.2.0
Summary: Aan Open-Source Software for Spatio-Temporal Graph Analysis of fMRI data.
License-Expression: CECILL-B
License-File: LICENSE
Author: Julien PONTABRY
Author-email: jpontabry@unistra.fr
Requires-Python: >=3.12,<=3.13
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Provides-Extra: dashboard
Provides-Extra: dev
Provides-Extra: docs
Provides-Extra: frequent
Provides-Extra: plot
Requires-Dist: click (>=8.1.8,<9.0.0)
Requires-Dist: coverage (>=7.13.4,<8.0.0) ; extra == "dev"
Requires-Dist: dash (>=3.0.2,<4.0.0) ; extra == "dashboard"
Requires-Dist: dash-bootstrap-components (>=2.0.0,<3.0.0) ; extra == "dashboard"
Requires-Dist: dash-breakpoints (>=0.1.0,<0.2.0) ; extra == "dashboard"
Requires-Dist: dash-daq (>=0.6.0,<0.7.0) ; extra == "dashboard"
Requires-Dist: dash-uploader (==0.7.0a2) ; extra == "dashboard"
Requires-Dist: docker (>=7.1.0,<8.0.0) ; extra == "frequent"
Requires-Dist: furo (>=2024.8.6,<2025.0.0) ; extra == "docs"
Requires-Dist: matplotlib (>=3.10.1,<4.0.0) ; extra == "plot"
Requires-Dist: myst-parser (>=4.0.0,<5.0.0) ; extra == "docs"
Requires-Dist: networkx (>=3.4.2,<4.0.0)
Requires-Dist: numpy (>=2.2.3,<3.0.0)
Requires-Dist: orjson (>=3.10.16,<4.0.0) ; extra == "dashboard"
Requires-Dist: pandas (>=2.2.3,<3.0.0)
Requires-Dist: pip-audit (>=2.10.0,<3.0.0) ; extra == "dev"
Requires-Dist: pyyaml (>=6.0.3,<7.0.0)
Requires-Dist: rich-click (>=1.9.7,<2.0.0)
Requires-Dist: screeninfo (>=0.8.1,<0.9.0)
Requires-Dist: sphinx (>=8.0.0,<9.0.0) ; extra == "docs"
Requires-Dist: sphinx-click (>=6.0.0,<7.0.0) ; extra == "docs"
Requires-Dist: sphinx-copybutton (>=0.5.2,<0.6.0) ; extra == "docs"
Description-Content-Type: text/markdown

<div style="text-align: center">
  <img src="docs/_static/images/fSTG_logo_large.svg" alt="fSTG Toolkit" width="480"/>
</div>

<div style="text-align: center">

![PyPI - Python Version](https://img.shields.io/pypi/pyversions/fSTG-Toolkit)
[![CI](https://github.com/julienpontabry/fstg_toolkit/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/julienpontabry/fstg_toolkit/actions/workflows/ci.yml)
![PyPI - Version](https://img.shields.io/pypi/v/fSTG-Toolkit)
![PyPI - License](https://img.shields.io/pypi/l/fSTG-Toolkit)
[![Read the Docs](https://img.shields.io/readthedocs/fSTG-Toolkit)](https://fstg-toolkit.readthedocs.io/)

</div>

# 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 via a web dashboard.
- Simulation of connectivity patterns and sequences.
- Frequent subgraph pattern mining via SPMiner integration.

## Installation

### Installation from PyPI

The easiest way to get started is to install the package from PyPI. Make sure you have a Python environment ready with a supported version (see the badge above), then run:
```shell
pip install fSTG-Toolkit
```

To install optional feature sets:
```shell
pip install "fSTG-Toolkit[dashboard]"   # web dashboard
pip install "fSTG-Toolkit[plot]"        # matplotlib plots
pip install "fSTG-Toolkit[frequent]"    # frequent pattern mining (requires Docker)
pip install "fSTG-Toolkit[dashboard,plot,frequent]"  # everything
```

### Installation from Source

To install from source, create a new environment with the required Python and Poetry binaries. Using conda:
```shell
conda env create -n <env_name> -f environment.yml
conda activate <env_name>
```

Then in the project's root folder, install the dependencies:
```shell
poetry install
```

To install optional feature sets:
```shell
poetry install --extras dashboard   # web dashboard
poetry install --extras plot        # matplotlib plots
poetry install --extras frequent    # frequent pattern mining (requires Docker)
poetry install --all-extras         # everything
```

## Quick Start

```shell
# Build graphs from a correlation matrix file and an areas CSV
python -m fstg_toolkit graph build -o my_graphs.zip areas.csv matrices.npz

# Compute graph metrics
python -m fstg_toolkit graph metrics my_graphs.zip

# Open the interactive dashboard
python -m fstg_toolkit dashboard show my_graphs.zip
```

The areas CSV must contain `Id_Area`, `Name_Area`, and `Name_Region` columns. Correlation matrices must be NumPy files (`.npz` or `.npy`) with shape `(T, N, N)`.

Use `--help` on any command for full options:
```shell
python -m fstg_toolkit --help
python -m fstg_toolkit graph build --help
```

Full usage documentation, tutorials, and API reference are available at **[fstg-toolkit.readthedocs.io](https://fstg-toolkit.readthedocs.io/)**.

![Illustration of the dashboard.](docs/_static/images/illustration_web-viewer.png)

