Sovereign 8s.is mirror of standardgalactic/MRSI-Metabolic-Connectome
  • Python 96.6%
  • Shell 3.4%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-03-05 11:40:54 +01:00
data Update participants_allsessions.tsv 2026-03-05 11:40:54 +01:00
experiments published pip package 2026-02-12 14:08:07 +01:00
figures metabolic ppath construction 2025-09-15 16:24:53 +02:00
harmonize published pip package 2026-02-12 14:08:07 +01:00
mrsitoolbox published pip package 2026-02-12 14:08:07 +01:00
.gitignore pypi instructions 2026-02-12 18:16:55 +01:00
build_env.sh Initial commit 2025-03-11 17:47:08 +01:00
environment.yaml - cross site VB harmonization 2026-01-29 15:21:49 +01:00
LICENSE added license 2025-03-11 22:50:31 +01:00
MANIFEST.in published pip package 2026-02-12 14:08:07 +01:00
pyproject.toml published pip package 2026-02-12 14:08:07 +01:00
README.md published pip package 2026-02-12 14:08:07 +01:00
requirements.txt Initial commit 2025-03-11 17:47:08 +01:00
set_env_paths.py Initial commit 2025-03-11 17:47:08 +01:00
setup.py pypi instructions 2026-02-12 18:16:55 +01:00

🧠 MRSI Toolbox Kit

This repository provides tools and preprocessing utilites to construct a within-subject Metabolic Similarity Matrix (MetSiM) based on MRSI scans, as detailed in Nature Communications 2025 and preparing files for a voxel-based analysis as detailed in biorxiv

📚 Table of Contents


📜 License

The repository is distributed under the CHUV license LICENSE.


🧑‍💻 Contributors

Name GitHub Profile Email
Federico Lucchetti @fedlucchetti federico.lucchetti@unil.ch
Edgar Céléreau @mrspsy edgar.celereau@unil.ch

📂 Dataset

A demo dataset is available at data/BIDS/Dummy-Project and constructed MetSiMs from the Geneva-Study in data/BIDS/Geneva-Study/derivatives/connectivity.

To access the full dataset, contact the authors with a detailed research proposal explaining your intended use.


⚙️ Installation

Requirements

  • Python 3.x
  • Conda / Miniconda (optional, but recommended)
  • CHIMERA for anatomical parcellation

Setup Instructions

  1. Clone the Repository

    git clone git@github.com:MRSI-Psychosis-UP/MRSI-Metabolic-Connectome.git
    cd MRSI-Metabolic-Connectome
    
  2. Install the Environment

    bash build_env.sh
    
  3. Activate the Environment

    conda activate mrsitooldemo_env
    
  4. Set Environment Paths

    python set_env_paths.py
    

    Use the provided demo BIDS dataset (data/BIDS) if applicable.

Install From PyPI

pip install mrsitoolbox

Python Imports

Use package-prefixed imports:

from mrsitoolbox.tools.datautils import DataUtils
from mrsitoolbox.tools.mridata import MRIData
from mrsitoolbox.registration.registration import Registration
from mrsitoolbox.connectomics.network import NetBasedAnalysis
from mrsitoolbox.graphplot.simmatrix import SimMatrixPlot

🗂️ Inputs

List of Participants/Subject File

  • BIDS directory PROJECT_NAME/ should contain a tab-separated participants_allsessions.tsv file following the BIDS standard subject-id \t session-id.

MRSI Files

  • MRSI files should be placed in:

    PROJECT_NAME/derivatives/mrsi-<space>/sub-<subject_id>/ses-<session>/
    
  • File naming convention:

    sub-<subject_id>_ses-<session>_space-<space>_met-<metabolite>_desc-<description>_mrsi.nii.gz
    
BIDS Prefix Description Choices
subject_id Subject/Participant ID
session Session ID [V1, V2, V3, ...]
space MRI Acquisition space orig, t1w, mni
metabolite MRSI resolved Metabolite B0 = 3T: Ins, CrPCr, GPCPCh, GluGln, NAANAAG, water
B0 = 7T: NAA, NAAG, Ins, GPCPCh, Glu, Gln, CrPCr, GABA, GSH
description MRSI Map Description signal, crlb, fwhm, snr, filtharmonic, brainmask

Anatomical Files

  • Chimera Anatomical Parcellation Files:

    • Example for subjects T1w filenames stores in found in t1s.txt with chimera atlas LFMIHISIFF using the Lausanne cortical parcellation at scale 3 :
      chimera -b data/BIDS/Dummy-Project/ \
              -d data/BIDS/Dummy-Project/derivatives/ \
              --freesurferdir data/BIDS/Dummy-Project/derivatives/freesurfer/ \
              -p LFMIHISIFF -g 2 -s 3 -ids t1s.txt --nthreads 28
      
    • Parcellations saved in PROJECT_NAME/derivatives/chimera-atlases.
  • Partial Volume Correction (PVC) files:

    Replace <N> with the appropriate tissue type index (e.g., 1 for GM, 2 for WM, 3 for CSF):

    PROJECT_NAME/derivatives/<PVCORR_DIR>/sub-<subject_id>/ses-<session>/sub-<subject_id>_ses-<session>_desc-p<N>_T1w.nii.gz
    
    • Minimum required:

      • p1: gray matter
      • p2: white matter
      • p3: CSF
    • Additional tissue files may be included (optional).


🧩 Construct a within-subject MetSiM

Batch mode semantics

  • --batch file requires --participants to point to a .tsv file listing the subject–session pairs to process.
  • --batch off requires both --subject_id and --session and processes one acquisition (a single subject–session pair).
  • --batch all processes all discoverable subject–session pairs in the group.
  1. Create MRSI-to-T1w Transforms

    python experiments/Preprocessing/registration_mrsi_to_t1.py --group Dummy-Project --ref_met CrPCr --subject_id S001 --session V1 --nthreads 16
    
  2. Map Chimera Parcel Image to MRSI Space

    python experiments/MetSiM_pipeline/map_parcel_image_to_mrsi.py --group Dummy-Project --subject_id S001 --session V1 --parc LFMIHIFIS --scale 3
    
  3. Construct within-subject MetSiM

    python experiments/MetSiM_pipeline/construct_MetSiM_subject.py --group Dummy-Project --subject_id S001 --session V1 --parc LFMIHIFIS --scale 3 --npert 50 --show_plot 1 --nthreads 16 --analyze 1
    
  4. Construct within-subject MetSiM (batch)

    python experiments/MetSiM_pipeline/construct_MetSiM_subject.py --group Dummy-Project --parc LFMIHIFIS --scale 3 --npert 50 --show_plot 0 --nthreads 16 --analyze 1 --batch file --participants $PATH2_PARTICIPANT-SESSION_FILE --t1mask acq-memprage_desc-brain_T1w 
    
  5. Construct MetSiM Population Average

    python experiments/MetSiM_pipeline/construct_MetSiM_pop.py --group Geneva-Study --parc LFMIHIFIS --scale 3 --npert 50 --participants $PATH2_PARTICIPANT-SESSION_FILE
    
    
  • Outputs: Transforms, coregistered parcellations, and MetSiMs are saved in the derivatives/ folder.

Input Options Description

Arg Name Description Type Default
--group BIDS project folder name str Dummy-Project
--subject_id Subject ID (e.g., S001). Required when --batch off (processes a single acquisition). str S001
--session Session label (e.g., V1). Required when --batch off (processes a single acquisition). str V1
--parc Chimera parcellation string str LFMIHIFIS
--npert Number of metabolic profile perturbations int 50
--leave_one_out Leave-one-metabolite-out option int (0 or 1) 0
--show_plot Show plots int (0 or 1) 0
--overwrite Overwrite existing results int (0 or 1) 0
--ref_met Reference metabolite for coregistration str CrPCr
--nthreads Number of parallel CPU threads int 4
--t1 Path or pattern to T1-weighted image str None
--t1mask Path or pattern to T1-weighted brain mask str None
--b0 MRI B0 field in Tesla float (choices: 3, 7) 3
--batch Batch mode. file requires --participants; off requires --subject_id and --session (processes a single acquisition); all uses all pairs. str (choices: all,file,off) off
--participants Path to a .tsv listing subject–session pairs to process (required when --batch file; ignored for --batch off and --batch all). path None
  • Note: --participants refers to a BIDS-style participants_allsessions.tsv. Defaults to $BIDSDATAPATH/group if not specified.

Figure 1


📊 MetSiM Analysis

  1. Construct Metabolic Similarity Map (Single Subject)

    python experiments/MetSiM_analysis/construct_MSI-map_subj.py --group Geneva-Study --parc LFMIHIFIS --scale 3 --npert 50 --dimalg pca_tsne
    
  2. Construct Metabolic Similarity Map (Population)

    python experiments/MetSiM_analysis/construct_MSI-map_pop.py --group Geneva-Study --parc LFMIHIFIS --scale 3 --npert 50 --dimalg pca_tsne --msiscale -255.0
    
  3. Inverse Map MSI to MRSI Signal (Population)

    python experiments/MetSiM_analysis/construct_MSI-map_pop.py --group Geneva-Study --parc LFMIHIFIS --scale 3 --npert 50 --dimalg pca_tsne
    
  4. Derive all GM constrained networtk paths

    python experiments/MetSiM_analysis/find_all_network_paths.py --group Geneva-Study --parc LFMIHIFIS --scale 3
    --lobe LOBE --hemi HEMI --lpath 13
    
  5. Construct Metabolic Principal Curve (Population)

    python experiments/MetSiM_analysis/construct_metabolic_principal_path.py --group Geneva-Study --parc LFMIHIFIS --scale 3 --diag group --lpath 13 --lobe ctx --nperm 100 --lobe ctx
    
  • Note:
    • Run first find_all_network_paths.py for both hemispheres lh and rh to construct all possible network paths then select the one which maximizes metabolic entropy and minimizes local metabolic heterogeneity with construct_metabolic_principal_path.py followed by comparison with a random geometric network and results figure generation.
    • --dimalg specifies the manifold-discovery algorithm used to construct the metabolic fibre.
    • --hemi chooses the hemisphere in which the fibre is built (lh or rh).
    • --lpath sets the maximum path length.
    • --nperm defines the size of the null distribution, generated from random-geometric networks.
    • --start and --stop indicate the start and stop nodes.
      • If not provided, they default to the occipital region (start) and frontal/anterior cingulate regions (stop), which maximise the inter-node MS-mode difference.
      • The script then runs find_all_network_paths.py from scratch with these adjusted end-node labels.
    • --lobe restricts the path search to either the neocortex (ctx) or the subcortex (subc).

Metabolic Fibre

🔧 Pre-Processing Pipeline for Voxel-Based Analysis

experiments/Preprocessing/preprocess.py now runs the full voxel-wise chain end-to-end: preflight checks, optional orientation correction, spike filtering, optional partial volume correction, and MRSI exports to MNI or T1w space. Missing transforms are generated where supported; overwrite flags force regeneration.

What it does

  • Checks required inputs (T1w, MRSI signals/CRLB/SNR/FWHM, CAT12 p1–p3 where available) and batches subject–session pairs from participants_allsessions.tsv or a custom TSV/CSV.
  • Prints a preflight availability table per subject/session: existing files are marked with a green check, missing ones with a red X, and items marked PROC (orange) are auto-generated during preprocessing (e.g., transforms or masks).
  • Optional oblique FOV correction (--corr_orient).
  • Filters MRSI spikes (--filtoption, --spikepc) and builds brain masks if present.
  • Runs/refreshes T1w→MNI registration when needed (--overwrite_mni_reg) and exports MRSI to T1w or MNI space at native-MRSI or T1w resolution via --transform.
  • Partial volume correction runs when --overwrite_pve is set and p1/p2/p3 maps are present; otherwise PVC is skipped (or explicitly bypassed with --no_pvc).

Batch mode semantics

  • --batch file requires --participants to point to a .tsv/.csv listing the subject–session pairs to process.
  • --batch off requires both --sub and --ses and processes one acquisition.
  • --batch all processes all discoverable subject–session pairs in the group.

Quick start

  • Single subject (filtering → PVC → export to MNI @ native MRSI res)
    python experiments/Preprocessing/preprocess.py \
      --group Dummy-Project --sub S001 --ses V1 \
      --t1 acq-memprage_desc-brain_T1w --b0 3 --nthreads 16 \
      --transform mni-origres --overwrite_pve
    
  • Batch (participants TSV/CSV)
    python experiments/Preprocessing/preprocess.py \
      --group Dummy-Project --b0 3 --nthreads 16 \
      --batch file --participants $PATH2_PARTICIPANT-SESSION_FILE \
      --t1 acq-memprage_desc-brain_T1w \
      --transform mni-t1wres --overwrite_pve
    
  • Optional add-ons: --corr_orient to fix oblique FOV; --no_pvc to skip partial volume correction; --overwrite_filt/--overwrite_transform/--overwrite_mni_reg to recompute stages; --proc_mnilong (+ --overwrite_mnilong) for MNI152-long outputs; --checksum to print a pre-run output validity summary; --v 1 for verbose logs.

Key preprocess.py options

Argument Default Purpose
--group Mindfulness-Project BIDS project under $BIDSDATAPATH.
--sub S002 Subject ID used when --batch off.
--ses V3 Session ID used when --batch off.
--batch off (all/file/off) Process all pairs, a TSV/CSV list (--participants), or a single pair.
--participants None TSV/CSV path used when --batch file (columns like participant_id/sub and ses/session_id).
--t1 desc-brain_T1w T1w path or pattern (resolved per subject/session).
--b0 3 (3/7) Sets metabolite list (3T vs 7T).
--nthreads 4 CPU threads for filtering, PVC, and transforms.
--filtoption filtbiharmonic Spike filtering strategy.
--spikepc 99 Percentile for spike removal.
--transform mni-origres (mni-t1wres/t1w-origres/t1w-t1wres) Export MRSI to MNI or T1w space at native MRSI vs T1w resolution.
--overwrite_transform off Recompute transforms/exports for the selected space+resolution (flag).
--no_pvc off Skip PVC exports (transform filtered signals only; flag).
--overwrite_pve off Run/refresh partial volume correction before transforms (flag).
--overwrite_filt off Recompute spike filtering outputs (flag).
--overwrite_t1_reg off Force regeneration of MRSI→T1w transforms (flag).
--overwrite_mni_reg off Force regeneration of T1w→MNI transforms (flag).
--proc_mnilong off Generate MNI152-longitudinal outputs (flag).
--overwrite_mnilong off Rerun MNI152-longitudinal exports (flag).
--corr_orient off Correct oblique FOV orientation for MRSI and masks (flag).
--checksum off Display the output validity summary before processing (flag).
--v 0 Verbose flag (1 to print more detail).

Input notes: --participants can be TSV/CSV (subject column such as participant_id/sub/id and session column such as ses/session_id); default is $BIDSDATAPATH/<group>/participants_allsessions.tsv (V2BIS rows are skipped). --t1 is required (defaults to the desc-brain_T1w pattern). Boolean options are flags (no 0/1 values); include them to enable. PVC needs CAT12 p1/p2/p3 maps; if absent or --no_pvc is set, PVC is skipped and logged.

Population quality mask

python experiments/Preprocessing/compute_pop_qmask.py \
  --group Dummy-Project --participants $PATH2_PARTICIPANT-SESSION_FILE \
  --snr 4 --crlb 20 --fwhm 0.1 --alpha 0.68 --b0 3

Registration helpers (optional)
All registration is triggered automatically by preprocess.py. Run these directly only for debugging or bespoke registration:

  • MRSI→T1w (batch capable)
    python experiments/Preprocessing/registration_mrsi_to_t1.py \
      --group Dummy-Project --ref_met CrPCr --nthreads 16 \
      --batch file --participants $PATH2_PARTICIPANT-SESSION_FILE \
      --t1 acq-memprage_desc-brain_T1w
    
  • T1w→MNI (batch capable)
    python experiments/Preprocessing/registration_t1_to_MNI.py \
      --group Dummy-Project --nthreads 16 \
      --batch file --participants $PATH2_PARTICIPANT-SESSION_FILE
    

Figure 1