fSTG-Toolkit 1.3.0__tar.gz → 1.4.0__tar.gz

{fstg_toolkit-1.3.0 → fstg_toolkit-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fSTG-Toolkit
-Version: 1.3.0
+Version: 1.4.0
 Summary: An Open-Source Software for Spatio-Temporal Graph Analysis of fMRI data.
 License-Expression: CECILL-2.1
 License-File: LICENSE
@@ -52,6 +52,7 @@ Description-Content-Type: text/markdown
 ![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/)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22093918.svg)](https://doi.org/10.5281/zenodo.22093918)
 
 </div>
 

{fstg_toolkit-1.3.0 → fstg_toolkit-1.4.0}/README.md

@@ -10,6 +10,7 @@
 ![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/)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22093918.svg)](https://doi.org/10.5281/zenodo.22093918)
 
 </div>
 

{fstg_toolkit-1.3.0 → fstg_toolkit-1.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fSTG-Toolkit"
-version = "1.3.0"
+version = "1.4.0"
 description = "An Open-Source Software for Spatio-Temporal Graph Analysis of fMRI data."
 authors = [
     {name = "Julien PONTABRY", email = "jpontabry@unistra.fr"}

{fstg_toolkit-1.3.0 → fstg_toolkit-1.4.0}/src/fstg_toolkit/__main__.py

@@ -126,6 +126,24 @@ def __load_graph(filepath: Path) -> SpatioTemporalGraph:
     return loader.load_graph(areas, chosen)
 
 
+def __with_zip_suffix(filepath: Path) -> Path:
+    """Add the '.zip' extension to a path of archive, if it is missing.
+
+    Parameters
+    ----------
+    filepath : Path
+        The path of the archive to write.
+
+    Returns
+    -------
+    Path
+        The path ending with the '.zip' extension.
+    """
+    if filepath.suffix.lower() == '.zip':
+        return filepath
+    return filepath.with_name(f'{filepath.name}.zip')
+
+
 ## building and computing #####################################################
 
 
@@ -224,6 +242,7 @@ def build(areas_description_path: Path, correlation_matrices_path: Tuple[Path],
 
     The CSV file for the description of areas and regions should have the columns: `Id_Area`, `Name_Area`, and `Name_Region`.
     """
+    output = __with_zip_suffix(output)
 
     # prepare the data saver
     saver = DataSaver()
@@ -234,6 +253,9 @@ def build(areas_description_path: Path, correlation_matrices_path: Tuple[Path],
             matrices = {}
             for cm in correlation_matrices_path:
                 for name, matrix in __read_load_np(cm):
+                    if name in matrices:
+                        error_console.print(f"Warning: sequence '{name}' from '{cm.name}' "
+                                            f"replaces a previous sequence with the same name.")
                     matrices[name] = matrix
                 console.print(f"- red '{cm.name}'")
         console.print(f"Red {len(correlation_matrices_path)} files.")
@@ -640,7 +662,8 @@ GRAPH_SEQUENCE_DESCRIPTION = GraphSequenceDescription()
 @graph.group()
 @click.option('-o', '--output_path', type=click.Path(writable=True, path_type=Path),
               default="output", show_default="a file named 'output' in the current directory",
-              help="Path where to write the simulated output.")
+              help="Path where to write the simulated output. The extension is added if missing: "
+                   "'.zip' for patterns and sequences, '.npz' for correlations.")
 @click.pass_context
 def simulate(ctx: click.core.Context, output_path: Path):
     """Simulate a spatio-temporal graph."""
@@ -679,7 +702,7 @@ def pattern(ctx: click.core.Context, networks: List[List[Tuple[Tuple[int, int],
     pat = generate_pattern(networks_list=networks,
                            spatial_edges=spatial_edges,
                            temporal_edges=temporal_edges)
-    save_spatio_temporal_graph(pat, ctx.obj)
+    save_spatio_temporal_graph(pat, __with_zip_suffix(ctx.obj))
 
 
 @simulate.command()
@@ -697,7 +720,7 @@ def sequence(ctx: click.core.Context, patterns: Tuple[Path], sequence_descriptio
                       for i, filepath in enumerate(patterns)}
     simulator = SpatioTemporalGraphSimulator(**pattern_graphs)
     graph = simulator.simulate(*sequence_description)
-    save_spatio_temporal_graph(graph, ctx.obj)
+    save_spatio_temporal_graph(graph, __with_zip_suffix(ctx.obj))
 
 
 @simulate.command()
@@ -707,11 +730,16 @@ def sequence(ctx: click.core.Context, patterns: Tuple[Path], sequence_descriptio
               help="The correlation threshold when building graph from matrices.")
 @click.pass_context
 def correlations(ctx: click.core.Context, graph_path: Path, threshold: float):
-    """Simulate correlations matrices from a spatio-temporal graph."""
+    """Simulate correlations matrices from a spatio-temporal graph.
+
+    The sequence of matrices is saved under the name of the output file (without its
+    '.npz' extension), which is the name the command 'build' gives to its graph.
+    """
     graph = __load_graph(graph_path)
     simulator = CorrelationMatrixSequenceSimulator(graph, threshold=threshold)
     matrices = simulator.simulate()
-    np.savez_compressed(ctx.obj, simulated=matrices)
+    name = Path(ctx.obj).name.removesuffix('.npz')
+    np.savez_compressed(ctx.obj, **{name: matrices})
 
 
 ## showing ####################################################################

{fstg_toolkit-1.3.0 → fstg_toolkit-1.4.0}/src/fstg_toolkit/frequent/spminer.py

@@ -33,6 +33,7 @@
 
 import logging
 import re
+from importlib.metadata import version
 from pathlib import Path
 from typing import Optional
 
@@ -73,8 +74,8 @@ class SPMinerService:
         already loaded.
         """
         if self.__docker_image is None:
-            # TODO use an external config file?
-            tag = 'spminer:latest'
+            # tagging by package version rebuilds the image when the bundled code changes
+            tag = f'spminer:{version("fSTG-Toolkit")}'
             build_path = Path(__file__).parent.parent / 'spminer'
             self.__docker_image = self.__docker_helper.load_local_image(tag, build_path)
 

{fstg_toolkit-1.3.0 → fstg_toolkit-1.4.0}/src/fstg_toolkit/io.py

@@ -1279,7 +1279,7 @@ def load_spatio_temporal_graph(filepath: Path | str) -> SpatioTemporalGraph:
         If no graph is found in the zip file.
     """
     logger.debug(f"Loading STG from '{filepath}'.")
-    loader = DataLoader(filepath)
+    loader = DataLoader(Path(filepath))
     filenames = loader.lazy_load_graphs()
 
     if len(filenames) > 0:
@@ -1331,7 +1331,7 @@ def save_spatio_temporal_graph(graph: SpatioTemporalGraph, filepath: Path | str)
     saver = DataSaver()
     saver.add_areas(graph.areas)
     saver.add_graphs({'graph.json': graph})
-    _, gen = saver.save(filepath)
+    _, gen = saver.save(Path(filepath))
     list(gen)
 
 
@@ -1714,8 +1714,10 @@ class GraphsDataset:
         columns = [f'Factor{i+1}' for i in range(n)] + ['Subject', 'Graph']
         subjects = pd.DataFrame(data, columns=columns).set_index(columns[:n+1])
 
-        if len(matrices_filenames) == len(graphs_filenames):
-            subjects['Matrix'] = matrices_filenames
+        # pair matrices with graphs by name, as files are not stored in the same order
+        matrices_by_name = {filename.removesuffix('.npy'): filename for filename in matrices_filenames}
+        if all(name in matrices_by_name for name in filenames_without_ext):
+            subjects['Matrix'] = [matrices_by_name[name] for name in filenames_without_ext]
 
         return GraphsDataset(loader=loader,
                              areas_desc=areas_desc,

{fstg_toolkit-1.3.0 → fstg_toolkit-1.4.0}/src/fstg_toolkit/spminer/Dockerfile

@@ -46,7 +46,7 @@ RUN pip install --no-cache-dir -r requirements.txt
 COPY . .
 
 # 5. Setup the permissionsgp
-RUN mkdir data_preprocessed_batch && chmod 1777 data_preprocessed_batch
+RUN mkdir -p data_preprocessed_batch && chmod 1777 data_preprocessed_batch
 
 ## select either "t" or "st" 
 CMD ["python", "batch_process.py", "t"]

{fstg_toolkit-1.3.0 → fstg_toolkit-1.4.0}/src/fstg_toolkit/spminer/batch_process.py

@@ -57,31 +57,32 @@ OUTPUT_FOLDER = 'results_batch'
 PREPROCESSED_FOLDER = 'data_preprocessed_batch'
 NODE_ANCHORED = True
 
-REGION_ENCODING = {
-    'Prefrontal cortex': 1,
-    'Retrosplenial': 2,
-    'Insula': 3,
-    'Thalamus': 4,
-    'Hippocampe': 5,
-    'hippocampal formation': 6,
-    'Cortical subplate': 7,
-    'Sensory cortex': 8,
-    'Olfactory area': 9,
-    'Striatum': 10,
-    'Pallidum': 11,
-    'Hypothalamus': 12,
-    'Midbrain': 13,
-    'Unknown': 14
-}
-
 TEMPORAL_EDGE_ENCODING = {
     'PP': 0, 'PO': 1, 'EQ': 2, 'DC': 3, 'PPi': 4
 }
 
 SPATIAL_EDGE_TYPE = 5
 
+UNKNOWN_REGION = 'Unknown'
+
 
-def preprocess_graph_temporal(input_json, output_pkl):
+def build_region_encoding(json_files):
+    """Build the region encoding shared by all the graphs of a run.
+
+    Codes start at 1 and follow the sorted order of the region names, so that
+    the encoding does not depend on the order of the files.
+    """
+    regions = set()
+    for json_file in json_files:
+        with open(json_file, 'r') as f:
+            data = json.load(f)
+        for node in data['nodes']:
+            regions.add(node.get('region', UNKNOWN_REGION))
+
+    return {region: code for code, region in enumerate(sorted(regions), 1)}
+
+
+def preprocess_graph_temporal(input_json, output_pkl, region_encoding):
     with open(input_json, 'r') as f:
         data = json.load(f)
     
@@ -89,8 +90,8 @@ def preprocess_graph_temporal(input_json, output_pkl):
     
     for node in data['nodes']:
         node_id = node['id']
-        region = node.get('region', 'Unknown')
-        region_code = REGION_ENCODING.get(region, 14)
+        region = node.get('region', UNKNOWN_REGION)
+        region_code = region_encoding[region]
         G.add_node(node_id, node_feature=region_code)
     
     temporal_count = 0
@@ -109,7 +110,7 @@ def preprocess_graph_temporal(input_json, output_pkl):
     
     return G, temporal_count
 
-def preprocess_graph_spatial(input_json, output_pkl):
+def preprocess_graph_spatial(input_json, output_pkl, region_encoding):
     with open(input_json, 'r') as f:
         data = json.load(f)
     
@@ -121,8 +122,8 @@ def preprocess_graph_spatial(input_json, output_pkl):
     for node in data['nodes']:
         old_id = node['id']
         new_id = id_mapping[old_id]
-        region = node.get('region', 'Unknown')
-        region_code = REGION_ENCODING.get(region, 14)
+        region = node.get('region', UNKNOWN_REGION)
+        region_code = region_encoding[region]
         G.add_node(new_id, node_feature=region_code, original_id=old_id, region=region)
     
     spatial_count = 0
@@ -142,7 +143,7 @@ def preprocess_graph_spatial(input_json, output_pkl):
     
     return G, spatial_count
 
-def preprocess_graph_spatiotemporal(input_json, output_pkl):
+def preprocess_graph_spatiotemporal(input_json, output_pkl, region_encoding):
     with open(input_json, 'r') as f:
         data = json.load(f)
     
@@ -150,8 +151,8 @@ def preprocess_graph_spatiotemporal(input_json, output_pkl):
     
     for node in data['nodes']:
         node_id = node['id']
-        region = node.get('region', 'Unknown')
-        region_code = REGION_ENCODING.get(region, 14)
+        region = node.get('region', UNKNOWN_REGION)
+        region_code = region_encoding[region]
         G.add_node(node_id, node_feature=region_code)
     
     temporal_count = 0
@@ -181,17 +182,17 @@ def preprocess_graph_spatiotemporal(input_json, output_pkl):
     
     return G, temporal_count, spatial_count
 
-def preprocess_graph(input_json, output_pkl, mode):
+def preprocess_graph(input_json, output_pkl, mode, region_encoding):
     print(f'  [1/3] Preprocessing {input_json.name} (mode: {mode})...')
     
     if mode == 't':
-        G, edge_count = preprocess_graph_temporal(input_json, output_pkl)
+        G, edge_count = preprocess_graph_temporal(input_json, output_pkl, region_encoding)
         print(f'         Saved: {G.number_of_nodes()} nodes, {edge_count} temporal edges')
     elif mode == 's':
-        G, edge_count = preprocess_graph_spatial(input_json, output_pkl)
+        G, edge_count = preprocess_graph_spatial(input_json, output_pkl, region_encoding)
         print(f'         Saved: {G.number_of_nodes()} nodes, {edge_count} spatial edges')
     elif mode == 'st':
-        G, temporal_count, spatial_count = preprocess_graph_spatiotemporal(input_json, output_pkl)
+        G, temporal_count, spatial_count = preprocess_graph_spatiotemporal(input_json, output_pkl, region_encoding)
         print(f'         Saved: {G.number_of_nodes()} nodes, {temporal_count} temporal + {spatial_count} spatial edges')
     
     return G
@@ -224,7 +225,7 @@ def run_spminer(pkl_path, json_path, output_dir, mode, node_anchored=True):
     print(f'\n        SPMiner completed successfully')
     return True
 
-def process_single_graph(json_file, relative_path, mode):
+def process_single_graph(json_file, relative_path, mode, region_encoding):
     print(f'\n{"="*70}')
     print(f'Processing: {relative_path.stem} (mode: {mode})')
     print(f'{"="*70}')
@@ -232,7 +233,7 @@ def process_single_graph(json_file, relative_path, mode):
     try:
         pkl_path = Path(PREPROCESSED_FOLDER) / relative_path.with_name(f'{relative_path.stem}_{mode}.pkl')
         pkl_path.parent.mkdir(parents=True, exist_ok=True)
-        _ = preprocess_graph(json_file, pkl_path, mode)
+        _ = preprocess_graph(json_file, pkl_path, mode, region_encoding)
 
         graph_output_dir = Path(OUTPUT_FOLDER) / relative_path.with_suffix('')
         graph_output_dir.mkdir(parents=True, exist_ok=True)
@@ -305,6 +306,11 @@ def main():
     print(f'\n Found {len(json_files)} JSON files:')
     for f in json_files:
         print(f'  - {f.name}')
+
+    region_encoding = build_region_encoding(json_files)
+    print(f'\n Region encoding ({len(region_encoding)} regions):')
+    for region, code in region_encoding.items():
+        print(f'  {code}: {region}')
     
     os.makedirs(OUTPUT_FOLDER, exist_ok=True)
     os.makedirs(PREPROCESSED_FOLDER, exist_ok=True)
@@ -318,7 +324,7 @@ def main():
         for mode in modes:
             task_num += 1
             print(f'\n[{task_num}/{total_tasks}] ', end='')
-            process_single_graph(json_file, relative_path, mode)
+            process_single_graph(json_file, relative_path, mode, region_encoding)
     
     print(f'\n{"="*70}')
     print(' ALL GRAPHS PROCESSED')