multimodal-mri-publication-pipeline

Multimodal MRI Publication Pipeline

Overview

Use this skill to move a neuroimaging project from raw or partially processed MRI data to defensible, publication-oriented outputs. Prefer it when the task spans more than one stage of the workflow: data intake, BIDS conversion, modality-specific preprocessing, QC, feature extraction, statistics, figure styling, table formatting, or results writing.

Workflow Decision Tree

• Start with references/workflow-blueprint.md when the user has mixed raw DICOM, NIfTI, BIDS, or derivatives and needs the full raw-to-results map.
• Read references/modality-playbooks.md when the main question is modality specific: structural MRI, resting-state fMRI, task fMRI, connectivity, diffusion MRI, tractography, or multimodal fusion.
• Read references/reporting-and-qc.md when the user needs exclusion rules, QC thresholds, software/version reporting, multiple-comparison strategy, or reproducibility language.
• Read references/visual-style.md when figures, brain maps, captions, or three-line tables need a high-impact journal look.
• Read references/results-and-interpretation.md when drafting result paragraphs, explaining effect sizes, or turning statistical outputs into publication-ready prose.

Core Workflow

1. Audit the starting point before analysis

• Identify whether inputs are raw DICOM, converted NIfTI, BIDS, or downstream derivatives such as fmriprep, xcp_d, freesurfer, qsiprep, DPABI, or atlas ROI tables.
• Build a manifest with at least subject_id, session_id, modality, source path, derivative path, key acquisition parameters, and QC state.
• Keep clinical IDs separate from imaging IDs until an explicit mapping table exists.
• If the study folder is messy, run scripts/init_mri_study_layout.py in a clean analysis root to create a reproducible directory layout and manifest templates.

2. Normalize the dataset structure

• Prefer BIDS as the canonical layout whenever raw or near-raw imaging is available.
• For DICOM intake, document scanner vendor, field strength, coil, sequence, TR, TE, flip angle, voxel size, phase-encoding direction, multiband factor, and fieldmap availability before conversion.
• Use dcm2niix plus a heuristic layer such as HeuDiConv or BIDScoin when conversion is part of the task, then validate with the BIDS Validator.
• Do not start main analyses until missing sessions, malformed metadata, and sequence naming ambiguities are resolved.

3. Choose the modality branch deliberately

• Structural MRI: prefer sMRIPrep, FreeSurfer, CAT12, or a similarly defensible structural workflow for cortical thickness, volume, surface area, or deformation analyses.
• Resting-state fMRI: prefer fMRIPrep for preprocessing and XCP-D, Nilearn, CONN, or DPABI for denoising and connectivity derivatives.
• Task fMRI: verify events.tsv, contrast definitions, and first-level design assumptions before fitting second-level models.
• Diffusion MRI and tractography: prefer QSIPrep plus MRtrix3, DIPY, or FSL-based downstream modeling for tensor, connectome, or fiber analyses.
• Mixed-modality projects: finish per-modality QC and feature generation before fusion, prediction, clustering, or normative modeling.

4. Keep statistics publication-oriented

• Define the primary endpoint before exploratory analyses expand.
• Prefer ROI or network-level analyses for modest samples and reserve voxelwise discovery for adequately powered studies with correction for multiplicity.
• Report effect sizes, uncertainty intervals, model covariates, and correction method alongside p or q values.
• Separate confirmatory analyses from sensitivity analyses, subgroup exploration, and machine-learning experiments.
• Guard against circular analysis: do not define ROIs, clusters, or features using the same inferential data without proper cross-validation or independent masks.

5. Produce figures, tables, and result text as part of the workflow

• Use scripts/preview_pub_figure_style.py to generate the bundled publication-style SVG palette preview.
• Use scripts/make_booktabs_table.py to convert CSV or TSV outputs into LaTeX three-line tables with booktabs.
• Match figure type to question: cohort flow, QC attrition, anatomical overlays, violin or raincloud summaries, effect plots with confidence intervals, connectome heatmaps, and tract summaries.
• Report exclusions, sample sizes, contrast direction, correction method, and units directly in figures, captions, or tables.

Working Pattern

• Default to a reproducible folder structure, explicit manifests, and versioned software names.
• Prefer primary-source documentation and official tools for pipeline decisions.
• Start with the smallest defensible feature space that answers the question.
• Escalate when data leakage, site effects, longitudinal dependence, or multiple-comparison inflation could invalidate the study.
• If the user only provides derived tables, still audit how those tables were produced before interpreting them as final evidence.

Bundled Scripts

• scripts/init_mri_study_layout.py: create a clean raw-to-results MRI project scaffold with manifest and plan templates.
• scripts/make_booktabs_table.py: convert CSV or TSV results into a standard LaTeX three-line table.
• scripts/preview_pub_figure_style.py: render an SVG palette sheet for manuscript figure styling.

Source Backbone

Base workflow choices on the official BIDS specification, MRIQC, NiPreps documentation for fMRIPrep, sMRIPrep, XCP-D, and QSIPrep, MRtrix3 documentation, FreeSurfer documentation, and COBIDAS-style reporting expectations. The reference files list concrete source URLs so downstream agents can inspect the underlying documentation when needed.