fSTG-Toolkit 1.0.0__tar.gz → 1.2.0__tar.gz

fstg_toolkit-1.2.0/PKG-INFO

@@ -0,0 +1,131 @@
+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)
+

fstg_toolkit-1.2.0/README.md

@@ -0,0 +1,89 @@
+<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)

{fstg_toolkit-1.0.0 → fstg_toolkit-1.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fSTG-Toolkit"
-version = "1.0.0"
+version = "1.2.0"
 description = "Aan Open-Source Software for Spatio-Temporal Graph Analysis of fMRI data."
 authors = [
     {name = "Julien PONTABRY",email = "jpontabry@unistra.fr"}
@@ -8,7 +8,7 @@ authors = [
 readme = "README.md"
 license = "CECILL-B"
 license-files = ["LICENSE"]
-requires-python = ">=3.12,<4.0"
+requires-python = ">=3.12,<=3.13"
 dependencies = [
     "networkx (>=3.4.2,<4.0.0)",
     "pandas (>=2.2.3,<3.0.0)",
@@ -38,6 +38,13 @@ dev = [
     "coverage (>=7.13.4,<8.0.0)",
     "pip-audit (>=2.10.0,<3.0.0)",
 ]
+docs = [
+    "sphinx (>=8.0.0,<9.0.0)",
+    "furo (>=2024.8.6,<2025.0.0)",
+    "myst-parser (>=4.0.0,<5.0.0)",
+    "sphinx-click (>=6.0.0,<7.0.0)",
+    "sphinx-copybutton (>=0.5.2,<0.6.0)",
+]
 
 [tool.setuptools.package-data]
 fstg_toolkit = ["logging.yml"]

{fstg_toolkit-1.0.0 → fstg_toolkit-1.2.0}/src/fstg_toolkit/__init__.py

@@ -31,18 +31,13 @@
 # The fact that you are presently reading this means that you have had
 # knowledge of the CeCILL-B license and that you accept its terms.
 
+from importlib.metadata import version
+
 from .factory import spatio_temporal_graph_from_corr_matrices
 from .graph import SpatioTemporalGraph
 from .io import load_spatio_temporal_graph, save_spatio_temporal_graph
 from .simulation import CorrelationMatrixSequenceSimulator, generate_pattern, SpatioTemporalGraphSimulator
 
-try:
-    from .visualization import multipartite_plot, spatial_plot, temporal_plot
-except ImportError:
-    pass
-
-from importlib.metadata import version
-
 __version__ = version(__package__)
 
 __all__ = [
@@ -54,3 +49,13 @@ __all__ = [
     'generate_pattern',
     'SpatioTemporalGraphSimulator'
 ]
+
+try:
+    from .visualization import multipartite_plot, spatial_plot, temporal_plot
+    __all__ += [
+        'multipartite_plot',
+        'spatial_plot',
+        'temporal_plot',
+    ]
+except ImportError:
+    pass

{fstg_toolkit-1.0.0 → fstg_toolkit-1.2.0}/src/fstg_toolkit/__main__.py

@@ -32,6 +32,7 @@
 # knowledge of the CeCILL-B license and that you accept its terms.
 
 __help_epilog = []
+__graph_help_epilog = []
 
 import multiprocessing
 import re
@@ -78,7 +79,9 @@ try:
     from .frequent import SPMinerService
 except ImportError as e:
     SPMinerService = None
-    __help_epilog.append(f"⚠️  Install '{__package__}[frequent]' to unlock the frequent patterns analysis command.")
+    epilog_tip = f"⚠️  Install '{__package__}[frequent]' to unlock the frequent patterns analysis command."
+    __help_epilog.append(epilog_tip)
+    __graph_help_epilog.append(epilog_tip)
 
 
 console = Console()
@@ -126,7 +129,7 @@ def __load_graph(filepath: Path) -> SpatioTemporalGraph:
 ## building and computing #####################################################
 
 
-@click.group()
+@click.group(epilog="\n\n".join(__graph_help_epilog))
 def graph():
     """Build, calculate metrics and simulate graphs."""
     pass
@@ -772,16 +775,16 @@ def serve(data_path: Path, upload_path: Path, debug: bool, port: int, db_path: P
 
 ## main entry point ###########################################################
 
-if __name__ == '__main__':
-    cli.add_command(graph)
+cli.add_command(graph)
 
-    if plt is not None:
-        cli.add_command(plot)
+if plt is not None:
+    cli.add_command(plot)
 
-    if app_config is not None:
-        cli.add_command(dashboard)
+if app_config is not None:
+    cli.add_command(dashboard)
 
-    if SPMinerService is not None:
-        graph.add_command(frequent)
+if SPMinerService is not None:
+    graph.add_command(frequent)
 
+if __name__ == '__main__':
     cli()

fstg_toolkit-1.2.0/src/fstg_toolkit/app/assets/common.js

@@ -0,0 +1,93 @@
+// Copyright 2025 ICube (University of Strasbourg - CNRS)
+// author: Julien PONTABRY (ICube)
+//
+// This software is a computer program whose purpose is to provide a toolkit
+// to model, process and analyze the longitudinal reorganization of brain
+// connectivity data, as functional MRI for instance.
+//
+// This software is governed by the CeCILL-B license under French law and
+// abiding by the rules of distribution of free software. You can use,
+// modify and/or redistribute the software under the terms of the CeCILL-B
+// license as circulated by CEA, CNRS and INRIA at the following URL
+// "http://www.cecill.info".
+//
+// As a counterpart to the access to the source code and rights to copy,
+// modify and redistribute granted by the license, users are provided only
+// with a limited warranty and the software's author, the holder of the
+// economic rights, and the successive licensors have only limited
+// liability.
+//
+// In this respect, the user's attention is drawn to the risks associated
+// with loading, using, modifying and/or developing or reproducing the
+// software by the user in light of its specific status of free software,
+// that may mean that it is complicated to manipulate, and that also
+// therefore means that it is reserved for developers and experienced
+// professionals having in-depth computer knowledge. Users are therefore
+// encouraged to load and test the software's suitability as regards their
+// requirements in conditions enabling the security of their systems and/or
+// data to be ensured and, more generally, to use and operate it in the
+// same conditions as regards security.
+//
+// The fact that you are presently reading this means that you have had
+// knowledge of the CeCILL-B license and that you accept its terms.
+
+let _hoverDebounceTimer = null;
+
+window.dash_clientside = Object.assign({}, window.dash_clientside, {
+    clientside: {
+        subject_node_hover: function(hoverData, storeHoverGraph) {
+            if (!hoverData || !hoverData.points || hoverData.points.length === 0 || !storeHoverGraph) {
+                return window.dash_clientside.no_update;
+            }
+
+            clearTimeout(_hoverDebounceTimer);
+            _hoverDebounceTimer = setTimeout(() => {
+                const graphDiv = document.getElementById('st-graph');
+                const figure = graphDiv && graphDiv.querySelector('.js-plotly-plot');
+                if (!figure || !figure.data) return;
+
+                const point = hoverData.points[0];
+                const props = storeHoverGraph[point.x] && storeHoverGraph[point.x][point.y];
+                if (!props || props.length !== 2) return;
+
+                const size = 10, min_size = 1, max_size = size * 2 - 1;
+                const ys = [point.y, ...props[0]];
+                const ws = [size, ...props[1].map(w => Math.abs(w) * max_size + min_size)];
+                const xs = Array(ys.length).fill(point.x);
+                const colors = ['black', ...props[1].map(w =>
+                    `hsl(${w < 0 ? 240 : 0}, ${Math.abs(w) * 100}%, 50%)`
+                )];
+
+                Plotly.restyle(figure, {
+                    x: [xs], y: [ys],
+                    'marker.color': [colors],
+                    'marker.size': [ws],
+                }, figure.data.length - 1);
+            }, 16);  // ~60 fps cap
+
+            return window.dash_clientside.no_update;
+        },
+
+        subject_clear_out: function(id) {
+            setTimeout(() => {
+                const graph = document.querySelector(`#${id} > .js-plotly-plot`);
+
+                graph.on('plotly_unhover', (eventData) => {
+                    if (!eventData || !eventData.event || eventData.event.type !== 'mouseout') return;
+
+                    const graphDiv = document.getElementById('st-graph');
+                    const figure = graphDiv && graphDiv.querySelector('.js-plotly-plot');
+                    if (!figure || !figure.data) return;
+
+                    const n = figure.data.length;
+                    if (figure.data[n-1].name === 'hover-spatial-connections') {
+                        Plotly.restyle(figure, { x: [[]], y: [[]], 'marker.size': [[]], 'marker.color': [[]] }, n-1);
+                    }
+                });
+            }, 300);
+
+            return window.dash_clientside.no_update;
+        }
+    }
+});
+

fstg_toolkit-1.2.0/src/fstg_toolkit/app/figures/common.py

@@ -0,0 +1,73 @@
+# Copyright 2025 ICube (University of Strasbourg - CNRS)
+# author: Julien PONTABRY (ICube)
+#
+# This software is a computer program whose purpose is to provide a toolkit
+# to model, process and analyze the longitudinal reorganization of brain
+# connectivity data, as functional MRI for instance.
+#
+# This software is governed by the CeCILL-B license under French law and
+# abiding by the rules of distribution of free software. You can use,
+# modify and/or redistribute the software under the terms of the CeCILL-B
+# license as circulated by CEA, CNRS and INRIA at the following URL
+# "http://www.cecill.info".
+#
+# As a counterpart to the access to the source code and rights to copy,
+# modify and redistribute granted by the license, users are provided only
+# with a limited warranty and the software's author, the holder of the
+# economic rights, and the successive licensors have only limited
+# liability.
+#
+# In this respect, the user's attention is drawn to the risks associated
+# with loading, using, modifying and/or developing or reproducing the
+# software by the user in light of its specific status of free software,
+# that may mean that it is complicated to manipulate, and that also
+# therefore means that it is reserved for developers and experienced
+# professionals having in-depth computer knowledge. Users are therefore
+# encouraged to load and test the software's suitability as regards their
+# requirements in conditions enabling the security of their systems and/or
+# data to be ensured and, more generally, to use and operate it in the
+# same conditions as regards security.
+#
+# The fact that you are presently reading this means that you have had
+# knowledge of the CeCILL-B license and that you accept its terms.
+
+import numpy as np
+
+
+def integer_tick_step(max_val: int, max_range: int = 5) -> int:
+    """Return a tick step so that ticks land only on integers.
+
+    For small ranges (≤ `max_range`) every integer is shown.  For larger ranges the step
+    is chosen so that roughly 8 ticks appear, avoiding float tick values.
+    """
+    if max_val <= max_range:
+        return 1
+    return max(1, round(max_val / 8))
+
+
+def hex_to_rgba(hex_color: str, alpha: float) -> str:
+    """Convert a hex colour string to an RGBA CSS string.
+
+    Parameters
+    ----------
+    hex_color : str
+        Colour in ``#RRGGBB`` format (e.g. ``'#636EFA'``).
+    alpha : float
+        Opacity in the range [0, 1].
+
+    Returns
+    -------
+    str
+        Colour in ``rgba(R, G, B, alpha)`` format suitable for Plotly.
+    """
+    r = int(hex_color[1:3], 16)
+    g = int(hex_color[3:5], 16)
+    b = int(hex_color[5:7], 16)
+    return f'rgba({r},{g},{b},{alpha})'
+
+
+def norm_min_max_size(s: list[float], new_min: float = 0, new_max: float = 1) -> list[float]:
+    s_min = np.min(s)
+    s_max = np.max(s)
+    scale = s_max - s_min
+    return ((new_max - new_min) * np.subtract(s, s_min) / scale + new_min).tolist()