Skip to content

meld_graph.md

Latest commit

 

History

History
216 lines (161 loc) · 6.99 KB

meld_graph.md

File metadata and controls

216 lines (161 loc) · 6.99 KB
Raw

MELD Graph

MELD Graph performs automated FCD (Focal Cortical Dysplasia) lesion detection using FreeSurfer surfaces and deep learning.

Default Values

  • Version: v2.2.3
  • Data directory: ~/derivatives/{dataset}-derivatives/meld_graph_v2.2.3/
  • Config directory: ~/code/{dataset}-code/meld_graph_v2.2.3/config/
  • Output location: ~/derivatives/{dataset}-derivatives/meld_graph_v2.2.3/data/output/predictions_reports/
  • Container: meldproject/meld_graph:v2.2.3
  • FreeSurfer version: 7.2.0 (default input - required)

⚠️ Compatibility Note: MELD Graph requires FreeSurfer 7.2.0 or earlier. It does not work with FreeSurfer 7.3 and above. The default FreeSurfer version for MELD Graph is set to 7.2.0.

⚠️ Recommendation: MELD works best with T1w scans only. If using T1w+FLAIR, interpret results with caution as FLAIR may introduce more false positives.

MELD Workflow Overview

MELD Graph has a unique three-step workflow:

  1. Download Weights (one-time setup): Download pretrained model weights
  2. Harmonization (optional but recommended): Compute scanner-specific harmonization parameters using 20+ subjects
  3. Prediction: Run lesion detection on individual subjects

Directory Structure

MELD uses a specific directory structure with data in derivatives and config in code:

~/derivatives/{dataset}-derivatives/
└── meld_graph_v2.2.3/
    └── data/
        ├── input/
        │   └── sub-{id}/
        │       ├── T1/T1.nii.gz
        │       └── FLAIR/FLAIR.nii.gz (optional)
        └── output/
            ├── predictions_reports/
            ├── fs_outputs/
            └── preprocessed_surf_data/

~/code/{dataset}-code/
└── meld_graph_v2.2.3/
    └── config/
        ├── meld_bids_config.json
        └── dataset_description.json

Step 1: Download Model Weights (One-time Setup)

Before first use, download the MELD Graph pretrained model weights:

ln2t_tools meld_graph --dataset mydataset --download-weights

This downloads ~2GB of model weights into the MELD data directory.

Step 2: Harmonization (Optional but Recommended)

Harmonization adjusts for scanner/sequence differences and improves prediction accuracy.

Requirements:

  • At least 20 subjects from the same scanner/protocol
  • Harmonization code (e.g., H1, H2) to identify this scanner
  • BIDS participants.tsv file with demographic data (see below)

Demographics Data:

ln2t_tools automatically creates the MELD-compatible demographics file from your BIDS dataset's participants.tsv. The participants.tsv file should contain:

Required columns:

  • participant_id: Subject ID (e.g., sub-001)
  • age (or Age): Numeric age value
  • sex (or Sex, gender, Gender): M/F or male/female

Optional columns:

  • group: patient or control (defaults to 'patient' if missing)

Example participants.tsv:

participant_id	age	sex	group
sub-001	25	M	patient
sub-002	28	F	control
sub-003	32	M	patient

Compute harmonization parameters (demographics file auto-generated):

ln2t_tools meld_graph --dataset mydataset \
  --participant-label 01 02 03 ... 20 \
  --harmonize \
  --harmo-code H1

The demographics CSV is automatically generated from participants.tsv. If you need to inspect or customize it, it will be created at:

~/derivatives/{dataset}-derivatives/meld_graph_v2.2.3/demographics_H1.csv

The demographics CSV format:

ID,Harmo code,Group,Age at preoperative,Sex
sub-001,H1,patient,25,male
sub-002,H1,control,28,female
sub-003,H1,patient,32,male

This runs FreeSurfer segmentation, extracts features, and computes harmonization parameters. Results saved in preprocessed_surf_data/.

Note: This step needs to be run only once per scanner. You can reuse the harmonization parameters for all future subjects from the same scanner.

Step 3: Prediction - Run Lesion Detection

Once setup is complete, run predictions on individual subjects.

Basic Prediction (without harmonization)

# Single subject
ln2t_tools meld_graph --dataset mydataset --participant-label 01

# Multiple subjects
ln2t_tools meld_graph --dataset mydataset --participant-label 01 02 03

Prediction with Harmonization

ln2t_tools meld_graph --dataset mydataset \
  --participant-label 01 \
  --harmo-code H1

Using Precomputed FreeSurfer Outputs

If you already have FreeSurfer recon-all outputs:

ln2t_tools meld_graph --dataset mydataset \
  --participant-label 01 \
  --use-precomputed-fs \
  --fs-version 7.2.0

This will:

  • Look for FreeSurfer outputs in ~/derivatives/{dataset}-derivatives/freesurfer_7.2.0/
  • Bind them to /data/output/fs_outputs in the container
  • Automatically skip the FreeSurfer segmentation step
  • Use the existing FreeSurfer surfaces for feature extraction

Skip Feature Extraction (Use Existing MELD Features)

If MELD features (.sm3.mgh files) are already extracted from a previous MELD run and you only want to rerun prediction:

ln2t_tools meld_graph --dataset mydataset \
  --participant-label 01 \
  --skip-feature-extraction

Important: --skip-feature-extraction tells MELD to skip computing surface features (.sm3.mgh files). Use this only when those files already exist from a previous MELD run.

Note: When using --use-precomputed-fs, MELD automatically detects existing FreeSurfer outputs and skips recon-all, but still runs feature extraction to create .sm3.mgh files. Don't use --skip-feature-extraction unless those feature files already exist.

Complete Example Workflow

# 1. Download weights (one-time)
ln2t_tools meld_graph --dataset epilepsy_study --download-weights

# 2. Compute harmonization with 25 subjects (one-time per scanner)
#    Demographics automatically created from participants.tsv
ln2t_tools meld_graph --dataset epilepsy_study \
  --participant-label 01 02 03 04 05 06 07 08 09 10 \
                        11 12 13 14 15 16 17 18 19 20 \
                        21 22 23 24 25 \
  --harmonize \
  --harmo-code H1

# 3. Run prediction on new patient with harmonization
ln2t_tools meld_graph --dataset epilepsy_study \
  --participant-label 26 \
  --harmo-code H1

# 4. Run prediction using precomputed FreeSurfer
ln2t_tools meld_graph --dataset epilepsy_study \
  --participant-label 27 \
  --use-precomputed-fs \
  --fs-version 7.2.0 \
  --harmo-code H1

Output Files

Results are saved in:

~/derivatives/{dataset}-derivatives/meld_graph_v2.2.3/data/output/predictions_reports/sub-{id}/
├── predictions/
│   ├── predictions.nii.gz           # Lesion probability map in native space
│   └── reports/
│       ├── {id}_prediction.pdf      # Visual report with inflated brain
│       ├── {id}_saliency.pdf        # Model attention maps
│       └── {id}_mri_slices.pdf      # Predictions on MRI slices
└── features/
    └── {id}.hdf5                    # Extracted surface features