Flexyphy Reconstruction and Analysis Code

This repository contains the code used for the Flexyphy data acquisition support, image reconstruction, motion correction, metric extraction, plotting, and statistical analysis. For a good explanation of the data processing in this project, check our standard operating procedures.

Repository Structure

.
├── acquisition
│   ├── pulseq_files
│   └── stimulation
├── code
│   └── HPC
├── plotting
├── requirements.txt
└── README.md

• acquisition/pulseq_files: Pulseq sequence files used for acquisition.
• acquisition/stimulation: PsychoPy stimulation scripts for the experimental tasks.
• code/HPC: MATLAB reconstruction pipeline intended to run on an HPC system.
• plotting: notebooks used for plotting image-quality metrics and running statistical tests.

Data Layout

Raw data are not included in this repository. Place the study data in a separate folder, referred to below as study_root, with the following structure:

study_root
├── sub-01
│   ├── raw
│   │   ├── gre
│   │   │   ├── original
│   │   │   ├── uniform
│   │   │   ├── flexiphy
│   │   │   └── prescans
│   │   └── libre
│   │       ├── original
│   │       ├── uniform
│   │       ├── flexiphy
│   │       └── prescans
│   └── derivatives
└── sub-02
    └── ...

Each main-scan trajectory folder should contain exactly one Siemens TWIX .dat file and the matching Pulseq .seq file. Each prescans folder should contain one prescan .seq file plus one body-coil .dat file with BC in the filename and one head-coil .dat file with HC in the filename.

MATLAB Reconstruction Pipeline

The reconstruction pipeline is in:

code/HPC

The intended subject-level pipeline is:

step0_check_orientation(rootDir, subject);
step1_coil_sens(rootDir, subject);
step2_recon_mathilda(rootDir, subject);
step3_recon_sequential(rootDir, subject, 3.5);
step4_estimate_motion(rootDir, subject);
step5_recon_mathilda_moco(rootDir, subject);

After all subjects have been reconstructed, run:

step6_group_metrics(rootDir);

This produces:

derivatives/group_analysis/recon_metrics/metrics_all_long.csv

HPC Execution

The pipeline is designed to run in an Apptainer/Singularity container with MATLAB, Monalisa, Pulseq, and SPM available.

Typical bind mounts are:

./data/study      -> /data
./code/HPC        -> /code
./external/pulseq -> /pulseq
./external/spm    -> /spm

Submit one subject with:

sbatch code/HPC/flexiphy_jobfile.sh sub-01

Adapt the SLURM partition, memory, wall time, container path, and bind paths to the local HPC environment before running.

Python Plotting and Statistics

Create a Python environment and install the required packages:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

The main plotting and statistical-testing notebook is:

plotting/plots_metrics_and_stats.ipynb

The notebook reads metrics_all_long.csv, keeps motion-corrected reconstructions, averages metrics across temporal bins at the subject/trajectory/sequence level, and runs paired t-tests with Bonferroni correction across the trajectory comparisons.

External Dependencies

The MATLAB reconstruction requires:

• Monalisa reconstruction framework;
• SPM;
• Pulseq;
• MATLAB;
• Apptainer or Singularity for HPC execution.

The Python analysis requires the packages listed in requirements.txt.