FSL Tool

Overview

FSL is a comprehensive library of analysis tools for MRI, fMRI, and diffusion brain imaging. This skill provides a safe, unified interface for the three core modalities in NeuroClaw:

• Structural MRI (T1w, T2w, FLAIR)
• Functional MRI (task-based and resting-state)
• Diffusion MRI (DTI / dMRI)

Workflow:

1. Check if FSL is installed (fslversion).
2. If not installed → call dependency-planner to generate installation plan.
3. Analyze input files and propose concrete shell commands with parameter explanations.
4. Present full numbered plan + estimated time + risks.
5. Wait for explicit user confirmation (“YES”, “execute”, “proceed”).
6. Execute all commands safely via claw-shell.
7. Summarize outputs and suggest next steps.

Research use only.

Core Modalities and Common Shell Commands

1. Structural MRI

# One-click structural preprocessing (strongly recommended)
fsl_anat -i T1w.nii.gz -o T1w_anat --clobber
# -i : input T1w file
# -o : output folder name
# --clobber : overwrite existing files (commonly used)

# Brain extraction (BET)
bet T1w.nii.gz T1w_brain -m -f 0.5
# -m : output brain mask (_mask.nii.gz)
# -f : brain extraction threshold (0.3~0.7; 0.5 is usually stable)

# Tissue segmentation + bias correction
fast -t 1 -n 3 -H 0.1 -I 4 -l 20.0 -o T1w_fast T1w_brain
# -t 1 : T1-weighted image
# -n 3 : 3 tissue classes (GM, WM, CSF)
# -H 0.1 : bias field correction strength

# Linear + nonlinear registration to MNI152
flirt -in T1w_brain -ref $FSLDIR/data/standard/MNI152_T1_2mm_brain -out T1w_to_MNI -omat T1w_to_MNI.mat -dof 12
fnirt --in=T1w_brain --aff=T1w_to_MNI.mat --cout=T1w_to_MNI_warp --config=T1_2_MNI152_2mm

# Subcortical segmentation
first -i T1w_brain -o T1w_first -b

2. Functional MRI

# Motion correction
mcflirt -in bold.nii.gz -out bold_mcf -plots -refvol 0

# Task-based fMRI full analysis (FEAT)
feat design.fsf

# Resting-state ICA
melodic -i bold_mcf.nii.gz -o melodic_output --report --nobet --bgthreshold=10 --tr=2.0 --mmthresh=0.5 --dim=30

# Automatic denoising (FIX)
fix melodic_output -c $FSLDIR/training_files/Standard.RData -m -f 20

3. Diffusion MRI

# Distortion and eddy current correction
topup --imain=AP_PA_b0.nii.gz --datain=acqparams.txt --out=topup_results --fout=field --iout=b0_unwarped
eddy --imain=dwi.nii.gz --mask=dwi_brain_mask.nii.gz --acqp=acqparams.txt --index=index.txt \
     --bvecs=bvecs --bvals=bvals --topup=topup_results --out=eddy_corrected --very_verbose

# Tensor fitting
dtifit -k eddy_corrected.nii.gz -m dwi_brain_mask.nii.gz -r bvecs -b bvals -o dtifit

# Multi-fiber modeling
bedpostx bedpostx_input -n 3 -w 1 -b 1000

# Automated major tract extraction
xtract -bpx bedpostx_input.bedpostX -out xtract_results -str $FSLDIR/data/xtract/tracts.txt

Quick Reference

Modality	Task	Main Command	Typical Time
Structural	Full preprocessing	fsl_anat	10–40 min
Structural	Brain extraction	bet	1–3 min
Structural	Tissue segmentation	fast	5–15 min
Functional	Motion correction	mcflirt	2–10 min
Functional	Task GLM	feat	15–90 min
Functional	Resting-state ICA	melodic	20–120 min
Diffusion	Preprocessing	topup + eddy	30–180 min
Diffusion	Tensor metrics	dtifit	5–20 min
Diffusion	Tractography	probtrackx2 / xtract	30 min – 24 h+

Installation

Use dependency-planner skill with one of the following requests:

• “Install latest FSL on Ubuntu using official installer”
• “Install FSL via conda-forge in a new environment”

After installation, verify with:

fslversion
echo $FSLDIR

Important Notes & Limitations

• All actual execution is routed through claw-shell.
• Long-running commands (bedpostx, probtrackx, group FEAT, etc.) run safely in the claw tmux session.
• Always consider running fsl_anat first for structural data — it handles BET + FAST + registration automatically.
• Input must be NIfTI format. Use dcm2nii skill first if starting from DICOM.
• Monitor progress with tail -f on the log file provided by claw-shell.

When to Call This Skill

• After dcm2nii conversion
• When any FSL preprocessing, registration, segmentation or advanced analysis is needed
• Before feeding quantitative results into paper-writing or experiment-controller

Complementary / Related Skills

• dependency-planner
• claw-shell

More Advanced Features

For less common tools (ASL, FABBER, VBM, PALM, custom scripting, etc.), please refer to the official FSL documentation:

• Official FSL Website: https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/
• Structural tools: https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/Structural
• Functional tools: https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FEAT
• Diffusion tools: https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT
• Full tool list: https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FSL

You may use the multi-search-engine, academic-research-hub, or arxiv-cli-tools skill anytime to find the latest FSL tutorials or example pipelines.

Post-Execution Verification (Harness Integration)

After FSL processing completes, this skill automatically invokes harness-core's VerificationRunner to validate output integrity:

Integrated verification checks:

from skills.harness_core import VerificationRunner, AuditLogger

verifier = VerificationRunner(task_type="fsl_processing")

# 1. Brain extraction quality (BET)
verifier.add_check("brain_extraction",
    checker=lambda: verify_bet_output(output_dir),
    severity="error"
)

# 2. FSL output files existence
verifier.add_check("output_files",
    checker=lambda: verify_output_files(output_dir),
    severity="error"
)

# 3. Data integrity (NaN/Inf checks)
verifier.add_check("data_integrity",
    checker=lambda: verify_no_nan_inf(output_dir),
    severity="error"
)

# 4. Registration quality metrics
verifier.add_check("registration_quality",
    checker=lambda: verify_registration_quality(output_dir),
    severity="warning"
)

# 5. Tensor metrics bounds (for DTI/DWI)
verifier.add_check("tensor_bounds",
    checker=lambda: verify_fa_md_bounds(output_dir),
    severity="warning"
)

report = verifier.run(output_dir)

# Log verification results
logger = AuditLogger(log_file=f"{output_dir}/fsl_verification.jsonl")
logger.log_validation(
    task_name="fsl_processing",
    checks_passed=len([r for r in report.results if r.passed]),
    total_checks=len(report.results),
    output_path=output_dir
)

Output: {output_dir}/fsl_verification.jsonl (structured audit log with JSONL format)

---

Created At: 2026-03-25 00:00 HKT Last Updated At: 2026-04-05 02:03 HKT Author: chengwang96