Skip to main content

Functional MRI Preprocessing

NOTE

The runnable commands on this page use the packaged demo commands, which demonstrates the pipeline described below. The full preprocessing pipeline as shown is currently for illustration only, not part of 0.0.1a1. Future release will include a real-data bootstrap. See Scope and Limitations.

This page uses a compact BOLD/T1 preprocessing example to show how NIPACT keeps source inputs, selected QC outputs, related files from multi-output steps, trace results, and GUI review connected. The runnable commands use the packaged fmri demo and a small generated dataset, so the focus is workflow inspection rather than neuroimaging conclusions.

The QC walkthrough later in the page shows what a larger preprocessing workflow would inspect: slice timing, motion correction, T1 preprocessing, registration, Schaefer atlas projection, timeseries extraction, and denoising.

Tutorial Overview​

The first section walks through the mechanics with the packaged fmri demo. You initialize and validate a demo project, inspect source mappings and workflow shape, run one selected registration step, and trace a selected QC output back to its BOLD and T1 inputs.

The QC walkthrough then uses documentation examples to show the review targets a larger fMRI preprocessing workflow would expose.

Initialize The Demo​

nipact init \
  --demo fmri \
  --project-dir demos/fmri/project \
  --runtime-dir demos/fmri/runtime

The command writes a project root, a runtime root, and a workspace-local nipact.contexts.yaml entry for the fmri context. The project root contains nipact.yaml, sources.yaml, manifests/init.yaml, step YAML, and workflow YAML. The runtime root contains runtime/database/registry.db and tiny generated .npy source files under data/fmri/.

The selected project root and runtime root must be empty and must not contain each other.

Validate​

nipact validate --context fmri

Validation checks the prepared project structure, manifests, step and workflow YAML, sources.yaml shape and path safety, and registry preflight when runtime/database/registry.db exists.

Source Index​

The init manifest defines the example subject IDs. Source file bindings live in sources.yaml, not in the manifest body.

demos/fmri/project/sources.yaml excerpt
entities:
  sub_001:
    bold: data/fmri/sub_001_bold.npy
    t1: data/fmri/sub_001_t1.npy
  sub_002:
    bold: data/fmri/sub_002_bold.npy
    t1: data/fmri/sub_002_t1.npy

The paths above are recorded as data/... paths. They resolve under runtime_root/data/... when NIPACT builds a run plan and when Snakemake executes the selected jobs.

Workflow Shape​

The packaged workflow is small:

init manifest
  -> fmri_source
  -> fmri_registration

fmri_source brings the subject/session BOLD and T1 files from sources.yaml into the workflow as raw_bold and raw_t1 outputs.

fmri_registration is a subject/session-level transform. It consumes raw_bold and raw_t1 and declares five related outputs:

  • registered_bold
  • forward_transform
  • inverse_transform
  • brain_mask
  • registration_qc

Selecting fmri_registration publishes the selected registration_qc outputs. The related registration files are still recorded, so later inspection can show which transform, mask, or QC file was produced by the same step.

Inspect And Run​

nipact workflow list --context fmri
nipact workflow steps \
  --context fmri \
  --workflow base
nipact workflow plan \
  --context fmri \
  --workflow base \
  --step fmri_registration
nipact workflow graph \
  --context fmri \
  --workflow base \
  --step fmri_registration

Run a dry-run first if you want to inspect Snakemake's planned jobs:

nipact workflow run \
  --context fmri \
  --workflow base \
  --step fmri_registration \
  --cores 1 \
  --dry-run

Then run the selected workflow step:

nipact workflow run \
  --context fmri \
  --workflow base \
  --step fmri_registration \
  --cores 1

The non-dry-run records the source files used for the run, records produced workflow outputs, publishes the selected registration_qc outputs, and records lineage between inputs and outputs.

Trace And GUI​

Trace one selected QC output by workflow coordinate:

nipact trace \
  --context fmri \
  --workflow base \
  --step fmri_registration \
  --output registration_qc \
  --address sub_001

The trace should report provenance_status=complete and include the source BOLD/T1 files used for that subject.

The read-only GUI can inspect the same registry state:

nipact gui --context fmri

The GUI shows the project summary, workflow graph, registered source files, registered workflow outputs, selected output detail, and lineage.

Preprocessing QC Walkthrough​

The figure panels below illustrate how a larger fMRI preprocessing workflow can be reviewed alongside NIPACT workflow structure. The examples use one NIPACT address per subject/session. Each workflow step declares the images, transforms, masks, timeseries, confound tables, and metadata.json files it writes, so downstream inspection can follow which output was selected or used.

The PNG and JSON files in this section are documentation examples for visual explanation. They are separate from local runtime outputs and are not included in nipact trace results.

Source-QC Static Figures​

The first figures summarize the raw BOLD and T1 inputs for a small three-subject example cohort before preprocessing. Use them to compare the selected subject/session's BOLD middle-volume view with the corresponding T1 anatomy and metadata.

Each source-QC subject has:

  • raw_bold_summary.png: a sagittal/coronal/axial mosaic from the middle BOLD volume
  • raw_t1_summary.png: a sagittal/coronal/axial mosaic from the raw T1 image
  • source_metadata.json: address, subject/session ID, image shapes, voxel sizes, and display filenames

The metadata omits source filesystem paths and keeps only the fields needed to interpret the displayed inputs.

Loading figures...

BOLD And Motion QC Static Figures​

The next figures summarize the BOLD preprocessing branch after motion correction and confound preparation. Use them to inspect six MCFLIRT motion traces, outlier markers, and metadata that will later feed denoising.

Each displayed BOLD/motion subject has:

  • motion_summary.png: MCFLIRT motion parameter traces with outlier markers on the same volume axis
  • motion_metadata.json: shape/count metadata, outlier counts, and recorded output references

Loading figures...

These checks catch obvious BOLD-branch issues before the workflow proceeds to T1 registration, atlas projection, and Schaefer timeseries extraction.

BOLD And Motion Workflow Focus

Loading graph...

T1 Registration And Brain Extraction QC Static Figures​

The next figure set shows candidate selection in the T1 branch. It compares T1-to-standard registration candidates against the MNI target and shows which candidate is carried forward into brain extraction.

The T1 branch uses explicit candidate steps instead of hiding the selection inside one large command. Registration candidates are compared in standard space against the MNI target, and the selected registration writes metadata.json with masked correlation plus Jacobian/folding checks where applicable. Brain extraction then uses the selected inverse transform to warp the standard brain mask back into the selected native-T1 reference space before writing the skull-stripped T1 and mask.

The metadata tabs document the candidate metrics, selected registration, and selected mask used by downstream steps.

Loading figures...

Brain-extraction QC checks the selected registration-derived mask. The example evaluates a six-candidate SynthMorph grid spanning raw and robustfov-cropped T1 inputs with affine and joint modes. Downstream steps consume selected_t1_reference so later registration remains tied to the selected geometry rather than a hardcoded T1 file.

Loading figures...

T1 Candidate Selection Workflow Focus

Loading graph...

Registration And Atlas QC Static Figures​

The next QC panel checks the downstream registration branch after T1 candidate selection and brain extraction. It uses the selected T1 reference from t1_to_std_select, the fMRI-to-T1 registration output, tissue masks projected back into native fMRI space, and the Schaefer atlas projected from MNI space into native fMRI space.

This section checks whether the selected T1 geometry is carried into downstream registration, whether tissue masks land on the fMRI reference image, and whether the projected Schaefer atlas preserves expected integer labels.

Loading figures...

The graph below follows the denoising dependency path through the registration and atlas steps that feed signal extraction. The separate registration_atlas_qc_ready metadata target shown in the figure section is a QC join target, not a dependency of denoise_fmri_timeseries.

Registration And Atlas Workflow Focus

Loading graph...

Signal QC Static Figures​

The final QC panel summarizes the signal-processing branch after atlas coverage has passed. The example extracts 480 timepoints by 400 Schaefer parcels for each subject/session, writes finite cleaned timeseries, and preserves all 400 expected Schaefer labels in the projected native-fMRI atlas.

The figures compare raw extracted parcel timeseries with the cleaned parcel timeseries, summarize the confounds passed into denoising, and report simple shape and correlation checks.

Loading figures...

Signal Extraction And Denoising Workflow Focus

Loading graph...

The preprocessing workflow backbone is:

fMRI preprocessing workflow structure
init manifest
  -> fmri_source.{raw_bold, raw_t1}
  -> BOLD branch
       fmri_slice_timing_correction.slice_corrected
       fmri_middle_volume_extraction.middle_volume
       fmri_motion_correction.{motion_corrected, motion_parameters}
       fmri_motion_outliers.motion_outliers
       fmri_motion_confounds.{confounds_orig, confounds_deriv, confounds_orig_squared, confounds_deriv_squared}
  -> T1 branch
       t1_robustfov.cropped_t1
       t1_to_std_synthmorph_raw_joint_r030.warped_t1
       t1_to_std_select.{selected_t1_reference, selected_warped_t1, selected_inverse_transform}
       t1_brain_extraction_select.{selected_t1_brain, selected_t1_mask}
       t1_tissue_segmentation.{pve_csf, pve_gm, pve_wm}
       t1_tissue_mask_erosion.{wm_eroded_mask, csf_eroded_mask}
  -> registration and signal branch
       registration_fmri_to_t1.{registered_to_t1, transform_lta, inverse_transform_lta}
       registration_t1_tissuemasks_to_fmri.{gm_mask_in_fmri, wm_mask_in_fmri, csf_mask_in_fmri}
       registration_atlas_schaefer_to_fmri.atlas_in_fmri
       registration_atlas_qc_ready.metadata
       extract_fmri_timeseries.timeseries
       fmri_acompcor_confounds.{confounds_wm, confounds_csf}
       denoise_fmri_timeseries.{clean_timeseries, confounds_used}

The key workflow outputs are:

OutputScopeMeaning
raw_bold, raw_t1subject/sessionSource-imported raw BOLD and T1 NIfTI files.
slice_corrected, middle_volume, motion_correctedsubject/sessionBOLD preprocessing outputs used by later registration and signal steps.
motion_parameters, motion_outliers, confounds_*subject/sessionMotion and derived confound tables used by denoising.
warped_t1, forward_transform, inverse_transformsubject/sessionSynthMorph T1-to-standard candidate outputs.
selected_t1_reference, selected_warped_t1, selected_inverse_transformsubject/sessionCanonical selected T1 reference image, standard-space T1 result, and inverse transform for downstream steps.
selected_t1_brain, selected_t1_masksubject/sessionRegistration-derived skull-stripped T1 and native-T1 brain mask.
pve_csf, pve_gm, pve_wm, wm_eroded_mask, csf_eroded_masksubject/sessionTissue maps and eroded masks used for aCompCor-style confounds.
registered_to_t1, transform_lta, inverse_transform_ltasubject/sessionSynthMorph affine fMRI-to-T1 registration output, fMRI-to-T1 LTA transform, and T1-to-fMRI inverse LTA transform.
gm_mask_in_fmri, wm_mask_in_fmri, csf_mask_in_fmrisubject/sessionT1 tissue masks projected into fMRI space.
atlas_in_fmrisubject/sessionSchaefer atlas projected into native fMRI space.
registration_atlas_qc_ready.metadatasubject/sessionJoin-target metadata confirming that downstream registration and atlas QC inputs have compatible geometries.
timeseriessubject/sessionExtracted Schaefer parcel timeseries.
confounds_wm, confounds_csf, confounds_usedsubject/sessionaCompCor and final denoising confound tables.
clean_timeseriessubject/sessionFinal cleaned Schaefer timeseries for downstream analysis.
metadata.jsonstep-specificStep parameters, external commands, QC metrics, array shapes, selected candidates, or label counts recorded by the step that produced it.

The workflow also demonstrates multi-output provenance. NIPACT records selected images, transforms, masks, confound tables, and metadata files under their workflow coordinates. When a later step consumes one of those outputs, trace and lineage can show whether the result depended on a motion-corrected image, a registration transform, a tissue mask, a confound table, or candidate-selection metadata.

The candidate-selection steps are explicit because they are scientifically meaningful. T1-to-standard selection records registration QC metrics such as masked correlation and Jacobian/folding checks where applicable. Brain extraction records how the selected registration-derived brain mask was warped, cleaned, and applied. These metadata.json outputs are part of the audit trail for why a registration was selected and how the skull-stripped T1 was produced.

The atlas projection remains a hard QC boundary. If the projected Schaefer atlas is missing expected labels, timeseries extraction should fail instead of silently filling missing parcels with zeros or NaNs.

Scope​

This page covers NIPACT workflow inspection, QC interpretation, and provenance for the synthetic demo. See Scope and Limitations for what is out of scope in this release.