@brainpilot/skills 0.0.6

package/skills/06_fMRI_Neuroimaging/fmri-preprocessing-pipeline-guide/references/step-by-step-pipeline.md

@@ -0,0 +1,380 @@
+# Step-by-Step fMRI Preprocessing Pipeline
+
+This reference document provides detailed parameter tables, software-specific guidance, and processing order diagrams for each preprocessing step. It supplements the core decision logic in `SKILL.md`.
+
+---
+
+## Step 1: DICOM to NIfTI Conversion and BIDS Organization
+
+### Why BIDS?
+
+The Brain Imaging Data Structure (BIDS; Gorgolewski et al., 2016) is essential for reproducible neuroimaging. fMRIPrep, MRIQC, and other automated tools require BIDS-formatted input.
+
+### Expected BIDS Directory Structure
+
+```
+dataset/
+ sub-01/
+ anat/
+ sub-01_T1w.nii.gz
+ sub-01_T1w.json
+ func/
+ sub-01_task-rest_bold.nii.gz
+ sub-01_task-rest_bold.json
+ sub-01_task-rest_events.tsv
+ fmap/
+ sub-01_dir-AP_epi.nii.gz
+ sub-01_dir-PA_epi.nii.gz
+ sub-01_dir-AP_epi.json
+ sub-01_dir-PA_epi.json
+```
+
+### Software-Specific Guidance
+
+| Tool | Command Example | Notes |
+|---|---|---|
+| `dcm2niix` | `dcm2niix -b y -z y -o output_dir input_dir` | Recommended; preserves all metadata in JSON sidecar |
+| `heudiconv` | `heudiconv -d {subject}/* -s 01 -c dcm2niix -o bids_dir -f heuristic.py` | Automates BIDS naming with heuristic files |
+| `BIDScoin` | GUI-based mapping | User-friendly for complex protocols |
+
+### What Happens If You Skip This Step
+
+Without BIDS organization, automated tools like fMRIPrep cannot run. Manual pipelines will lack standardized metadata, making it difficult to detect acquisition parameters (TR, slice timing, phase-encoding direction) automatically.
+
+---
+
+## Step 2: Non-Steady-State Volume Removal
+
+### Detailed Parameters
+
+| Parameter | Value | Source |
+|---|---|---|
+| Volumes to discard | **3-5** (or until signal stabilizes) | Poldrack et al., 2011, Ch. 5 |
+| Time equivalent | ~5-15 seconds depending on TR | Standard practice |
+| Detection method | Signal intensity in first volumes >> subsequent volumes | fMRIPrep automatic detection |
+
+### Software-Specific Guidance
+
+| Tool | Implementation |
+|---|---|
+| **fMRIPrep** | Automatic detection and flagging via `non_steady_state_outlier_XX` columns in confounds TSV |
+| **FSL** | Manual: remove volumes with `fslroi input output 5 -1` (skips first 5) |
+| **SPM** | Set "Images to remove" in the batch editor before any preprocessing |
+| **AFNI** | `3dTcat -prefix output input'[5..$]'` (removes first 5 volumes) |
+
+### What Happens If You Skip This Step
+
+Non-steady-state volumes have artificially high signal intensity. If retained, they bias the mean image (used as motion correction reference), inflate temporal variance, and can introduce artifacts in motion parameter estimates.
+
+---
+
+## Step 3: Slice Timing Correction — Detailed Parameters
+
+### Parameters by Acquisition Type
+
+| Acquisition | Slice Order | STC Reference Slice | Notes |
+|---|---|---|---|
+| Sequential ascending | 1, 2, 3, ... N | Middle slice (N/2) | Simple; less common in modern protocols |
+| Sequential descending | N, N-1, ... 1 | Middle slice (N/2) | Less common |
+| Interleaved (odd first) | 1, 3, 5, ... 2, 4, 6, ... | Middle slice | SPM/FSL default for interleaved |
+| Interleaved (even first) | 2, 4, 6, ... 1, 3, 5, ... | Middle slice | Check scanner documentation |
+| Multiband/SMS | Multiple slices simultaneously | Use slice timings, not slice order | Slice order cannot represent simultaneous slices |
+
+### Software-Specific Guidance
+
+| Tool | Implementation | Key Parameter |
+|---|---|---|
+| **fMRIPrep** | Automatic if BIDS metadata includes `SliceTiming` field | Reads from JSON sidecar |
+| **FSL** (`slicetimer`) | `slicetimer -i input -o output -r TR --tcustom=timings.txt` | Custom timing file for multiband |
+| **SPM** | Slice Timing module in batch editor | Specify slice order and reference slice |
+| **AFNI** (`3dTshift`) | `3dTshift -tpattern alt+z -prefix output input` | Pattern: alt+z (interleaved), seq+z (sequential) |
+
+### When to Definitely Skip STC
+
+- **TR < 0.5 seconds**: Common STC interpolation methods provide negligible benefit (Sladky et al., 2011). Even newer methods (e.g., filter-shift) show minimal improvement at very short TRs
+- **No accurate slice timing information available**: STC with wrong parameters is worse than no STC
+- **Using only temporal derivatives in GLM**: The temporal derivative of the HRF can absorb timing shifts of approximately +/- 1 second (Henson et al., 2002), partially compensating for slice timing differences
+
+### What Happens If You Skip This Step
+
+Without STC, the temporal offset between first and last slices introduces a systematic timing error. For a TR of 2 seconds with interleaved acquisition, the last slice is offset by nearly 2 seconds from the first. This reduces statistical power for event-related designs and can bias estimates of hemodynamic response timing (Sladky et al., 2011).
+
+---
+
+## Step 4: Motion Correction — Detailed Parameters
+
+### MCFLIRT (FSL) Parameters
+
+| Parameter | Default | Recommended | Notes |
+|---|---|---|---|
+| Reference volume | Middle volume | Mean image after initial pass | Mean is more representative (Jenkinson et al., 2002) |
+| Cost function | Normalized correlation | Normalized correlation | Robust for intra-modal EPI-to-EPI |
+| Search stages | 8 mm, then 4 mm (x2) | Default | Three-stage coarse-to-fine optimization |
+| Interpolation (estimation) | Trilinear | Trilinear | Fast; adequate for parameter estimation |
+| Interpolation (final reslice) | Trilinear | **Sinc** (--sinc_final) | Reduces blurring in output images |
+| DOF | 6 (rigid body) | 6 (rigid body) | Never use higher DOF for within-subject motion |
+
+### Software Comparison
+
+| Tool | Algorithm | Key Feature |
+|---|---|---|
+| **FSL MCFLIRT** | Cost-function optimized rigid body | Three-stage optimization; robust to local minima (Jenkinson et al., 2002) |
+| **SPM Realign** | Least squares rigid body | Iterative resampling to mean image |
+| **AFNI 3dvolreg** | Iterated linearized weighted least-squares | Fast; supports multiple cost functions |
+| **ANTs** | Symmetric normalization (rigid) | Used by fMRIPrep for high-quality registration |
+| **fMRIPrep** | MCFLIRT (default) or ANTs | Automatically selects based on data characteristics |
+
+### Output: Motion Parameters
+
+The 6 rigid-body parameters should be saved and used as confound regressors:
+
+| Parameter | Unit | Typical Range (good data) | Concern Threshold |
+|---|---|---|---|
+| Translation X (left/right) | mm | < 1 mm total range | > 3 mm (Poldrack et al., 2011) |
+| Translation Y (anterior/posterior) | mm | < 1 mm total range | > 3 mm |
+| Translation Z (superior/inferior) | mm | < 1 mm total range | > 3 mm |
+| Rotation pitch (around X) | radians | < 0.02 rad (~1 degree) | > 0.05 rad |
+| Rotation roll (around Y) | radians | < 0.02 rad | > 0.05 rad |
+| Rotation yaw (around Z) | radians | < 0.02 rad | > 0.05 rad |
+
+### What Happens If You Skip This Step
+
+Without motion correction, even small head movements (1-2 mm) produce signal changes that are larger than the BOLD effect (~1-3% signal change). Motion artifacts are the single largest source of false positives in fMRI (Power et al., 2012).
+
+---
+
+## Step 5: Distortion Correction — Detailed Parameters
+
+### Method Comparison
+
+| Method | Data Required | Accuracy | Software | When to Use |
+|---|---|---|---|---|
+| **TOPUP** (reverse PE) | Opposite-PE EPI pair (e.g., AP + PA blip-up/blip-down) | **High** | FSL TOPUP | Preferred when opposite-PE data available (Andersson et al., 2003) |
+| **FUGUE** (fieldmap) | Dual-echo gradient-echo magnitude + phase images | **High** | FSL FUGUE | When GRE fieldmap was acquired (Jezzard & Balaban, 1995) |
+| **SyN-SDC** (fieldmapless) | T1-weighted structural only | **Moderate** | ANTs / fMRIPrep | Fallback when no fieldmap data exists |
+| **3dQwarp** | Opposite-PE pair | **High** | AFNI | AFNI pipeline equivalent of TOPUP |
+
+### TOPUP Parameters (FSL)
+
+```
+# Example TOPUP configuration
+topup --imain=AP_PA_blips --datain=acqparams.txt --config=b02b0.cnf --out=topup_results
+applytopup --imain=AP_bold,PA_bold --topup=topup_results --datain=acqparams.txt --method=jac --out=corrected
+```
+
+The `acqparams.txt` file specifies phase-encoding direction and total readout time. These values **must** match the actual acquisition parameters.
+
+### Regions Most Affected by Distortion
+
+| Brain Region | Proximity to Air-Tissue Interface | Typical Displacement | Impact |
+|---|---|---|---|
+| Orbitofrontal cortex | Paranasal sinuses | **Several mm** | Signal loss and mislocalization in reward/decision studies |
+| Anterior temporal lobe | Ear canals, mastoid | **Several mm** | Affects memory and language studies |
+| Inferior temporal lobe | Sphenoid sinus | Moderate | Affects face perception and object recognition studies |
+| Brainstem | Surrounding bone | Moderate | Affects autonomic and arousal studies |
+
+### What Happens If You Skip This Step
+
+Without distortion correction, functional images are geometrically distorted along the phase-encoding direction. This causes: (1) misregistration with the T1 structural image, (2) mislocalization of functional activations after normalization, and (3) signal pileup and signal void in affected regions. The impact is most severe for studies targeting orbitofrontal, temporal, and brainstem regions (Jezzard & Balaban, 1995).
+
+---
+
+## Step 6: Coregistration — Detailed Parameters
+
+### Boundary-Based Registration (BBR)
+
+BBR (Greve & Fischl, 2009) is the recommended method for EPI-to-T1 coregistration:
+
+| Parameter | Value | Notes |
+|---|---|---|
+| Cost function | BBR (boundary-based) | Uses WM boundary; more robust than mutual information for EPI-T1 |
+| Input | Distortion-corrected mean EPI | Apply distortion correction before coregistration |
+| Reference | Skull-stripped T1 | Brain extraction must be accurate |
+| DOF | 6 (rigid body) | EPI and T1 are from the same subject/session |
+| Initialization | FLIRT 6-DOF (schedule=bbr.sch) | BBR refines initial FLIRT alignment |
+
+### Software-Specific Guidance
+
+| Tool | Method | Command |
+|---|---|---|
+| **fMRIPrep** | BBR (via FreeSurfer + FSL) | Automatic |
+| **FSL** | `flirt -cost bbr -wmseg wm_seg -schedule bbr.sch` | Requires WM segmentation |
+| **SPM** | `Coregister: Estimate` with mutual information | Less robust than BBR for EPI |
+| **FreeSurfer** | `bbregister --bold --mov func.nii --s subject --init-fsl` | Excellent for surface-based analyses |
+
+### What Happens If You Skip This Step
+
+Without coregistration, functional and structural images are in different coordinate spaces. Normalization to MNI space via the structural image becomes impossible, and anatomical labeling of functional results is inaccurate.
+
+---
+
+## Step 7: Spatial Normalization — Detailed Parameters
+
+### Normalization Methods
+
+| Method | Software | Quality | Speed | Source |
+|---|---|---|---|---|
+| **ANTs SyN** | ANTs / fMRIPrep | **Excellent** | Slow (~1-2 hr/subject) | Avants et al., 2008 |
+| **Unified Segmentation** | SPM | Good | Moderate | Ashburner & Friston, 2005 |
+| **DARTEL** | SPM | **Excellent** | Slow (study-specific template) | Ashburner, 2007 |
+| **FNIRT** | FSL | Good | Moderate | Andersson et al., 2007 |
+
+### Template Spaces
+
+| Template | Resolution | When to Use | Source |
+|---|---|---|---|
+| **MNI152NLin2009cAsym** | 1 mm | fMRIPrep default; current standard | Fonov et al., 2011 |
+| **MNI152NLin6Asym** | 1 mm | FSL default (MNI152 6th generation) | FSL convention |
+| **MNI152Lin** | 2 mm | Legacy; older SPM analyses | Older convention |
+| **fsaverage** | Surface | Surface-based group analyses (FreeSurfer) | Fischl et al., 1999 |
+| **fsLR** | Surface | HCP-style surface analyses | Van Essen et al., 2012 |
+
+### Output Resolution
+
+| Analysis | Recommended Output Voxel Size | Rationale |
+|---|---|---|
+| Standard group analysis | **2 mm isotropic** | Matches template resolution; balances detail and file size |
+| High-resolution studies | **1-1.5 mm isotropic** | Preserves spatial detail for laminar or columnar analysis |
+| ROI-based analysis | **2 mm isotropic** | Standard; ROIs average over voxels anyway |
+| Connectivity with small ROIs | **2 mm isotropic** | Smaller voxels preserve signal in small subcortical structures |
+
+### What Happens If You Skip This Step
+
+Without normalization, each subject's brain is in its own native space. Group-level analyses (second-level GLM, group connectivity maps) are impossible because there is no common coordinate system. Subject-level analyses in native space are valid but results cannot be reported in standard coordinates.
+
+---
+
+## Step 8: Spatial Smoothing — Detailed Parameters
+
+### Kernel Size Recommendations
+
+| Voxel Size | Analysis Type | FWHM | Result | Source |
+|---|---|---|---|---|
+| 2 mm | Univariate group | **6 mm** | 3x voxel size; good SNR gain | Mikl et al., 2008 |
+| 3 mm | Univariate group | **6-8 mm** | 2-3x voxel size; standard | Poldrack et al., 2011 |
+| 2 mm | Resting-state connectivity | **4-6 mm** | Moderate smoothing | Ciric et al., 2017 |
+| 2 mm | MVPA | **0 mm (none)** | Preserve spatial patterns | Misaki et al., 2013 |
+| 1.5 mm | High-resolution | **3-4 mm** | 2x voxel size; preserve resolution | Matched filter theorem |
+| Any | Searchlight | **0 mm (none)** | Searchlight provides spatial averaging | Etzel et al., 2013 |
+
+### Software-Specific Guidance
+
+| Tool | Command | Notes |
+|---|---|---|
+| **FSL** | `fslmaths input -s 2.548 output` | FSL uses sigma, not FWHM: sigma = FWHM / 2.355 |
+| **SPM** | Smooth module: set FWHM [6 6 6] | Specify FWHM in mm for each axis |
+| **AFNI** | `3dmerge -1blur_fwhm 6 -prefix output input` | Specify FWHM directly |
+| **Nilearn** | `smooth_img(img, fwhm=6)` | Python; can also specify per-axis |
+| **fMRIPrep** | Does NOT smooth | Smoothing is intentionally left to the user |
+
+### Smoothing and Random Field Theory (RFT)
+
+For cluster-based inference using RFT (Worsley et al., 1996), the data must be sufficiently smooth. The smoothness estimation assumes a minimum smoothness of approximately 2-3 voxel FWHM. Applying a kernel of at least 2x voxel size ensures this assumption is met. If data are already smooth (e.g., after normalization and resampling), additional smoothing may not be needed for RFT validity, but this should be verified.
+
+### What Happens If You Skip This Step
+
+Without smoothing for univariate analyses: (1) SNR is lower, reducing power; (2) inter-subject anatomical variability is not compensated, reducing group-level sensitivity; (3) RFT assumptions may be violated, leading to invalid cluster-based inference. However, skipping smoothing is correct and necessary for MVPA.
+
+---
+
+## Complete Pipeline Processing Order Diagram
+
+### Standard Task fMRI Pipeline
+
+```
+Raw DICOM data
+ |
+ v
+[1] DICOM to NIfTI (dcm2niix) + BIDS organization
+ |
+ v
+[2] Remove non-steady-state volumes (first 3-5 TRs)
+ |
+ v
+[3] Slice timing correction (if TR > 1 s)
+ | - Reference: middle slice
+ | - Interpolation: sinc or Fourier
+ |
+ v
+[4] Motion correction (6-DOF rigid body)
+ | - Reference: mean image
+ | - Save 6 motion parameters
+ | - Calculate FD and DVARS
+ |
+ v
+[5] Distortion correction (TOPUP or FUGUE)
+ | - Requires fieldmap or opposite-PE data
+ |
+ v
+[6] Coregistration (EPI to T1)
+ | - Method: BBR (Greve & Fischl, 2009)
+ |
+ v
+[7] Spatial normalization (to MNI space)
+ | - Method: ANTs SyN or SPM unified segmentation
+ | - Output: 2 mm isotropic
+ |
+ v
+[8] Smoothing (FWHM = 2-3x voxel size)
+ | - SKIP for MVPA
+ |
+ v
+Preprocessed BOLD data (ready for GLM)
+ + Confound time series (motion, FD, DVARS, CompCor)
+```
+
+### Resting-State Connectivity Pipeline Additions
+
+After the standard pipeline, resting-state analyses typically add:
+
+```
+Preprocessed BOLD data
+ |
+ v
+[9] Confound regression
+ | - 24-parameter motion model (Friston et al., 1996)
+ | - aCompCor: 5-6 WM/CSF components (Behzadi et al., 2007)
+ | - Optional: global signal regression (Murphy & Fox, 2017)
+ | - Spike regressors for FD > 0.2 mm (Power et al., 2014)
+ |
+ v
+[10] Temporal filtering
+ | - Band-pass: 0.01-0.1 Hz (for connectivity)
+ | - OR high-pass only: 0.01 Hz (if GSR applied)
+ |
+ v
+[11] Scrubbing / censoring
+ | - Remove volumes with FD > 0.2 mm + 1 volume before + 2 after
+ | - Require minimum 5 minutes of clean data (Power et al., 2014)
+ |
+ v
+Cleaned BOLD data (ready for connectivity analysis)
+```
+
+---
+
+## Key References for This Document
+
+- Andersson, J. L. R., Skare, S., & Ashburner, J. (2003). How to correct susceptibility distortions in spin-echo echo-planar images. *NeuroImage*, 20(2), 870-888.
+- Ashburner, J. (2007). A fast diffeomorphic image registration algorithm. *NeuroImage*, 38(1), 95-113.
+- Ashburner, J., & Friston, K. J. (2005). Unified segmentation. *NeuroImage*, 26(3), 839-851.
+- Avants, B. B., Epstein, C. L., Grossman, M., & Gee, J. C. (2008). Symmetric diffeomorphic image registration with cross-correlation. *Medical Image Analysis*, 12(1), 26-41.
+- Behzadi, Y., Restom, K., Liau, J., & Liu, T. T. (2007). A component based noise correction method (CompCor). *NeuroImage*, 37(1), 90-101.
+- Ciric, R., Wolf, D. H., Power, J. D., et al. (2017). Benchmarking confound regression strategies. *NeuroImage*, 154, 174-187.
+- Etzel, J. A., Zacks, J. M., & Braver, T. S. (2013). Searchlight analysis: promise, pitfalls, and potential. *NeuroImage*, 78, 261-269.
+- Fonov, V. S., Evans, A. C., Botteron, K., et al. (2011). Unbiased average age-appropriate atlases for pediatric studies. *NeuroImage*, 54(1), 313-327.
+- Friston, K. J., Williams, S., Howard, R., et al. (1996). Movement-related effects in fMRI time-series. *Magnetic Resonance in Medicine*, 35(3), 346-355.
+- Gorgolewski, K. J., et al. (2016). The brain imaging data structure. *Scientific Data*, 3, 160044.
+- Greve, D. N., & Fischl, B. (2009). Accurate and robust brain image alignment using boundary-based registration. *NeuroImage*, 48(1), 63-72.
+- Henson, R. N. A., et al. (2002). Detecting latency differences in event-related BOLD responses. *NeuroImage*, 15(1), 83-97.
+- Jenkinson, M., Bannister, P., Brady, J. M., & Smith, S. M. (2002). Improved optimization for the robust and accurate linear registration and motion correction of brain images. *NeuroImage*, 17(2), 825-841.
+- Jezzard, P., & Balaban, R. S. (1995). Correction for geometric distortion in echo planar images from B0 field variations. *Magnetic Resonance in Medicine*, 34(1), 65-73.
+- Mikl, M., et al. (2008). Effects of spatial smoothing on fMRI group inferences. *Magnetic Resonance Imaging*, 26(4), 490-503.
+- Misaki, M., Luh, W. M., & Bandettini, P. A. (2013). The effect of spatial smoothing on fMRI decoding. *NeuroImage*, 78, 13-22.
+- Murphy, K., & Fox, M. D. (2017). Towards a consensus regarding global signal regression. *NeuroImage*, 154, 169-173.
+- Parker, D. B., & Razlighi, Q. R. (2019). The benefit of slice timing correction in common fMRI preprocessing pipelines. *Frontiers in Neuroscience*, 13, 821.
+- Poldrack, R. A., Mumford, J. A., & Nichols, T. E. (2011). *Handbook of Functional MRI Data Analysis*. Cambridge University Press.
+- Power, J. D., et al. (2012). Spurious but systematic correlations in functional connectivity MRI networks arise from subject motion. *NeuroImage*, 59(3), 2142-2154.
+- Power, J. D., et al. (2014). Methods to detect, characterize, and remove motion artifact in resting state fMRI. *NeuroImage*, 84, 320-341.
+- Sladky, R., et al. (2011). Slice-timing effects and their correction in functional MRI. *NeuroImage*, 58(2), 588-594.
+- Worsley, K. J., et al. (1996). A unified statistical approach for determining significant signals in images of cerebral activation. *Human Brain Mapping*, 4(1), 58-73.

package/skills/06_fMRI_Neuroimaging/fmri-task-design-guide/SKILL.md

@@ -0,0 +1,264 @@
+---
+name: "fmri-task-design-guide"
+description: "Guides fMRI task design: block vs. event-related vs. mixed; jittering; contrasts; power for BOLD detection"
+domain: "cognitive-neuroscience"
+version: "1.0.0"
+authors:
+ - "awesome_cognitive_and_neuroscience_skills contributors"
+papers:
+ - "Friston et al., 1999"
+ - "Petersen & Dubis, 2012"
+ - "Dale, 1999"
+ - "Bandettini et al., 1993"
+ - "Glover, 1999"
+ - "Desmond & Glover, 2002"
+ - "Wager & Nichols, 2003"
+dependencies:
+ required:
+ - research-literacy
+ recommended:
+ - fmri-glm-analysis-guide
+ - fmri-preprocessing-pipeline-guide
+review_status: "ai-generated"
+---
+
+# fMRI Task Design Guide
+
+## Purpose
+
+The experimental design is the single most important determinant of an fMRI study's statistical power, interpretability, and scientific value. Choosing between block, event-related, and mixed designs involves trade-offs between detection power and estimation efficiency that depend on the research question. Similarly, the choice of inter-stimulus interval (ISI), jittering strategy, condition ordering, and trial count directly determines whether the BOLD signal of interest can be reliably detected.
+
+A competent programmer without neuroimaging training would not know that block designs provide higher detection power but cannot estimate HRF shape, that exponentially distributed jitter is more efficient than uniform jitter, or that the BOLD response takes 12-16 seconds to return to baseline. This skill encodes those domain-specific design decisions.
+
+## When to Use This Skill
+
+- Planning a new task-based fMRI experiment
+- Choosing between block, event-related, or mixed designs
+- Optimizing inter-stimulus interval and jittering strategy
+- Calculating design efficiency for contrast detection
+- Determining minimum trial counts per condition
+- Integrating behavioral task constraints with fMRI timing requirements
+- Reviewing or troubleshooting an existing fMRI task design
+
+## Research Planning Protocol
+
+Before executing the domain-specific steps below, you MUST:
+
+1. **State the research question** — What specific question is this analysis/paradigm addressing?
+2. **Justify the method choice** — Why is this approach appropriate? What alternatives were considered?
+3. **Declare expected outcomes** — What results would support vs. refute the hypothesis?
+4. **Note assumptions and limitations** — What does this method assume? Where could it mislead?
+5. **Present the plan to the user and WAIT for confirmation** before proceeding.
+
+For detailed methodology guidance, see the `research-literacy` skill.
+
+
+## ⚠️ Verification Notice
+
+This skill was generated by AI from academic literature. All parameters, thresholds, and citations require independent verification before use in research. If you find errors, please [open an issue](https://github.com/HaoxuanLiTHUAI/awesome_cognitive_and_neuroscience_skills/issues).
+
+## Design Type Selection
+
+### Comparison of Design Types
+
+| Design Type | Detection Power | Estimation Efficiency | Trial-Level Analysis | Best For | Source |
+|---|---|---|---|---|---|
+| Block | **High** | Low | No | Detecting whether a region is active | Friston et al., 1999; Petersen & Dubis, 2012 |
+| Event-related (slow) | Moderate | **High** | Yes | Estimating HRF shape | Dale, 1999 |
+| Rapid event-related | Moderate-High | Moderate-High | Yes | Flexible trial-by-trial analysis with good power | Dale, 1999; Friston et al., 1999 |
+| Mixed (hybrid) | High (sustained) + Moderate (transient) | Moderate | Yes (transient component) | Separating sustained and transient effects | Petersen & Dubis, 2012 |
+
+### Decision Tree
+
+```
+What is the primary goal?
+ |
+ +-- Detect presence/absence of activation (localization)
+ | |
+ | +-- Is HRF shape estimation needed?
+ | |
+ | +-- NO --> Block design (maximum detection power)
+ | |
+ | +-- YES --> Mixed design (blocks + events within blocks)
+ |
+ +-- Estimate trial-by-trial neural responses
+ | |
+ | +-- Are there enough trials (>40 per condition)?
+ | |
+ | +-- YES --> Rapid event-related design (jittered ISI)
+ | |
+ | +-- NO --> Slow event-related design (ISI > 12 s)
+ |
+ +-- Separate sustained state vs. transient item effects
+ --> Mixed design (Petersen & Dubis, 2012)
+```
+
+## Block Design Parameters
+
+- **Optimal block duration**: **15-20 seconds** for maximum detection power (Maus et al., 2010; Bandettini et al., 1993). Shorter blocks (< 12 s) reduce sensitivity because the BOLD response does not reach steady state. Longer blocks (> 30 s) increase habituation and strategy effects (Poldrack et al., 2011, Ch. 3)
+- **Minimum block duration**: **12 seconds** to allow the BOLD signal to reach near-plateau (Bandettini et al., 1993)
+- **Number of blocks per condition**: At least **4-6 blocks** per condition per run for stable estimates (Poldrack et al., 2011, Ch. 3)
+- **Condition alternation**: Alternate conditions (ABAB or ABCABC) rather than grouping (AAABBB), which confounds condition with time (Poldrack et al., 2011, Ch. 3)
+- **Rest blocks**: Include rest/fixation blocks of at least **12-16 seconds** between active blocks to allow BOLD signal return to baseline (Glover, 1999)
+
+## Event-Related Design Parameters
+
+### Inter-Stimulus Interval (ISI) and Jittering
+
+The ISI between events is critical for statistical efficiency and BOLD signal separability.
+
+| Parameter | Recommendation | Source |
+|---|---|---|
+| Minimum ISI | **2-4 seconds** (for partial BOLD recovery) | Dale, 1999; Glover, 1999 |
+| Mean ISI for rapid designs | **4-6 seconds** | Dale, 1999 |
+| ISI range for jittered designs | **2-8 seconds** | Dale, 1999; Wager & Nichols, 2003 |
+| Null/fixation trials | **20-33%** of total events | Friston et al., 1999 |
+
+**Jittering strategies** (from most to least recommended):
+
+1. **Optimized sequences**: Use design optimization tools (optseq2, NeuroDesign) to maximize efficiency for specific contrasts (Dale, 1999; Durnez et al., 2017)
+2. **Truncated exponential distribution**: More short ISIs, fewer long ISIs; near-optimal efficiency (Hagberg et al., 2001)
+3. **Uniform random**: Equal probability across ISI range; acceptable but suboptimal
+4. **Fixed ISI**: Avoid for rapid event-related designs; severely reduces design efficiency
+
+**Domain warning**: Jittered designs can be over **10x more efficient** than fixed-ISI designs with the same mean interval (Dale, 1999). Always jitter for event-related fMRI.
+
+### HRF Timing Constraints
+
+The BOLD hemodynamic response imposes hard constraints on fMRI design timing:
+
+- **HRF peak**: **4-6 seconds** after neural event onset (Glover, 1999)
+- **Return to baseline**: **12-16 seconds** after a brief event (Glover, 1999)
+- **BOLD nonlinearity**: Responses to stimuli separated by < **2 seconds** sum nonlinearly (reduced amplitude), making them harder to separate (Glover, 1999; Wager & Nichols, 2003)
+
+### Trial Count Requirements
+
+| Design Type | Minimum Trials per Condition | Recommended Trials | Source |
+|---|---|---|---|
+| Event-related (detection) | **20** | 30-50 | Desmond & Glover, 2002 |
+| Event-related (HRF estimation) | **30** | 50+ | Murphy & Garavan, 2005 |
+| Rapid event-related | **30** | 40-60 | Desmond & Glover, 2002 |
+| FIR/deconvolution | **40+** | 60+ | Glover, 1999 |
+
+**Domain insight**: These are per-condition minimums. If comparing conditions (A vs. B), each condition needs this many trials. More conditions require longer scan sessions or fewer trials per condition, creating a power trade-off.
+
+## Design Efficiency
+
+### Efficiency Calculation
+
+Design efficiency quantifies how well a given design matrix allows detection of specific contrasts:
+
+```
+Detection efficiency = 1 / trace(c' * inv(X'X) * c)
+```
+
+where **c** is the contrast vector and **X** is the design matrix (Dale, 1999; Liu et al., 2001).
+
+### Detection vs. Estimation Trade-off
+
+- **Detection power**: Ability to detect whether an effect exists. Maximized by block designs and rapid event-related designs with high event density (Liu et al., 2001)
+- **Estimation efficiency**: Ability to accurately characterize the HRF shape. Maximized by jittered designs with sufficient ISI variability (Liu et al., 2001)
+- These are inherently in tension: block designs maximize detection but cannot estimate HRF shape
+
+### Design Optimization Tools
+
+- **optseq2** (FreeSurfer): Optimizes event ordering and null events for maximum efficiency (Dale, 1999)
+- **NeuroDesign** (Python): Genetic algorithm-based optimization (Durnez et al., 2017)
+- **fMRIpower**: Power calculations accounting for design and temporal autocorrelation (Mumford & Nichols, 2008)
+
+## Mixed Design Specification
+
+Mixed designs combine sustained (block-level) and transient (event-level) components (Petersen & Dubis, 2012):
+
+1. **Sustained regressor**: Models the tonic task state (e.g., "task block on" vs. "rest"), boxcar convolved with HRF
+2. **Transient regressors**: Model individual trial onsets within each block, convolved with HRF
+3. These regressors are separable because they operate at different temporal frequencies
+
+**Key parameters**:
+- Block duration: **20-40 seconds** to provide enough events within each block (Petersen & Dubis, 2012)
+- Events per block: At least **4-6** for stable transient estimates
+- Inter-block rest: **16-20 seconds** minimum for BOLD signal recovery (Glover, 1999)
+
+## Scanner-Related Timing Constraints
+
+| Constraint | Guideline | Rationale |
+|---|---|---|
+| TR synchronization | Stimulus onsets need not align with TR boundaries for event-related designs | Jittered onsets relative to TR improve temporal sampling of HRF |
+| Trigger pulses | Start experiment on scanner trigger pulse (TTL signal) | Ensures precise alignment between stimulus and acquisition timing |
+| Total scan duration | **5-15 minutes per run** | Longer runs increase motion and fatigue; shorter runs waste setup time (Poldrack et al., 2011, Ch. 3) |
+| Number of runs | **2-4 runs** typical; split conditions across runs if needed | Allows rest between runs; run-level effects can be modeled |
+| Dummy scans | First **3-5 TRs** (5-10 s) are T1 equilibration artifacts | Discard or model as confounds (Poldrack et al., 2011, Ch. 5) |
+
+## Rest/Fixation Baseline
+
+- Allocate **25-30%** of total scan time to rest/fixation baseline (Friston et al., 1999)
+- Rest periods serve dual purpose: allow BOLD signal recovery and provide baseline estimate
+- For block designs, rest blocks of **12-16 seconds** between active blocks (Glover, 1999)
+- For event-related designs, null trials (fixation) distributed throughout the sequence (Friston et al., 1999)
+
+## Condition Ordering
+
+- **m-sequences**: Pseudo-random sequences with optimal counterbalancing properties (Buracas & Boynton, 2002)
+- **Optimized pseudo-random**: Generated by optimization algorithms (optseq2, NeuroDesign) to maximize design efficiency while controlling trial-order effects (Dale, 1999)
+- **Avoid**: Simple alternation (ABABAB) which confounds condition with time, or purely random sequences which may produce long runs of the same condition
+
+## Behavioral Task Constraints
+
+| Constraint | Guideline | Source |
+|---|---|---|
+| Response mapping | Counterbalance button assignments across subjects | Prevents lateralized motor confound |
+| Practice effects | Include out-of-scanner practice until performance plateaus | Reduces learning-related activation changes during scanning |
+| Task difficulty | Aim for **70-85% accuracy** | Floor/ceiling effects eliminate behavioral variance (Poldrack et al., 2011, Ch. 3) |
+| Response window | Allow **1.5-3 seconds** for speeded responses | Accommodate scanner environment slowing (~200 ms; Haatveit et al., 2010) |
+| Stimulus duration | **0.5-4 seconds** typical for visual stimuli | Long enough for perceptual processing, short enough for event separation |
+
+## Common Pitfalls
+
+1. **Fixed ISI in event-related designs**: Dramatically reduces design efficiency compared to jittered designs. Always jitter ISI for event-related fMRI (Dale, 1999)
+2. **Too few trials per condition**: Fewer than 20 events per condition yields unreliable single-subject estimates (Desmond & Glover, 2002). Plan for at least 30 per condition
+3. **Ignoring HRF recovery time**: Events separated by < 2 seconds produce nonlinear BOLD summation, making responses difficult to separate (Glover, 1999)
+4. **No baseline/rest periods**: Without rest periods, the model cannot estimate absolute activation levels and efficiency drops substantially (Friston et al., 1999)
+5. **Confounding condition with time**: Presenting all trials of one condition before another confounds the effect with scanner drift and fatigue
+6. **Not counterbalancing response mappings**: Lateralized motor responses (left vs. right hand) produce motor cortex activation that confounds task effects
+7. **Ceiling/floor performance**: If accuracy is near 100% or chance, there is no behavioral variance to correlate with brain activity
+8. **Not optimizing the design matrix**: Using arbitrary event timing instead of optimized sequences wastes statistical power that could be gained at no additional cost
+
+## Minimum Reporting Checklist
+
+Based on COBIDAS guidelines (Nichols et al., 2017) and Poldrack et al. (2008):
+
+- [ ] Design type (block, event-related, mixed, rapid event-related)
+- [ ] Block duration (for block designs) or ISI distribution parameters (for event-related)
+- [ ] Number of conditions and number of trials per condition
+- [ ] Stimulus duration and response window
+- [ ] Jittering strategy and ISI range (min, max, mean, distribution)
+- [ ] Null trial proportion and distribution
+- [ ] Condition ordering method (optimized, m-sequence, pseudo-random)
+- [ ] Total scan duration per run and number of runs
+- [ ] Design optimization tool used (if any) and efficiency metric
+- [ ] Response mapping and counterbalancing scheme
+- [ ] Practice procedure (in-scanner or out-of-scanner, duration)
+- [ ] TR and its relationship to stimulus timing
+
+## References
+
+- Bandettini, P. A., Jesmanowicz, A., Wong, E. C., & Hyde, J. S. (1993). Processing strategies for time-course data sets in functional MRI of the human brain. *Magnetic Resonance in Medicine*, 30(2), 161-173.
+- Buracas, G. T., & Boynton, G. M. (2002). Efficient design of event-related fMRI experiments using m-sequences. *NeuroImage*, 16(3), 801-813.
+- Dale, A. M. (1999). Optimal experimental design for event-related fMRI. *Human Brain Mapping*, 8(2-3), 109-114.
+- Desmond, J. E., & Glover, G. H. (2002). Estimating sample size in functional MRI (fMRI) neuroimaging studies: Statistical power analyses. *Journal of Neuroscience Methods*, 118(2), 115-128.
+- Durnez, J., Blair, R., & Poldrack, R. A. (2017). NeuroDesign: Optimal experimental designs for task fMRI. *bioRxiv*, 119594.
+- Friston, K. J., Zarahn, E., Josephs, O., Henson, R. N. A., & Dale, A. M. (1999). Stochastic designs in event-related fMRI. *NeuroImage*, 10(5), 607-619.
+- Glover, G. H. (1999). Deconvolution of impulse response in event-related BOLD fMRI. *NeuroImage*, 9(4), 416-429.
+- Haatveit, B. C., Sundet, K., Hugdahl, K., et al. (2010). The validity of d prime as a working memory index. *Neuropsychology*, 24(5), 629-640.
+- Hagberg, G. E., Zito, G., Patria, F., & Sanes, J. N. (2001). Improved detection of event-related functional MRI signals using probability functions. *NeuroImage*, 14(5), 1193-1205.
+- Liu, T. T., Frank, L. R., Wong, E. C., & Buxton, R. B. (2001). Detection power, estimation efficiency, and predictability in event-related fMRI. *NeuroImage*, 13(4), 759-773.
+- Maus, B., van Breukelen, G. J. P., Goebel, R., & Berger, M. P. F. (2010). Optimal design of multi-subject blocked fMRI experiments. *NeuroImage*, 51(3), 1338-1348.
+- Mumford, J. A., & Nichols, T. E. (2008). Power calculation for group fMRI studies accounting for arbitrary design and temporal autocorrelation. *NeuroImage*, 39(1), 261-268.
+- Murphy, K., & Garavan, H. (2005). Deriving the optimal number of events for an event-related fMRI study based on the spatial extent of activation. *NeuroImage*, 27(4), 771-777.
+- Nichols, T. E., Das, S., Eickhoff, S. B., et al. (2017). Best practices in data analysis and sharing in neuroimaging using MRI (COBIDAS). *Nature Neuroscience*, 20(3), 299-303.
+- Petersen, S. E., & Dubis, J. W. (2012). The mixed block/event-related design. *NeuroImage*, 62(2), 1177-1184.
+- Poldrack, R. A., Fletcher, P. C., Henson, R. N., et al. (2008). Guidelines for reporting an fMRI study. *NeuroImage*, 40(2), 409-414.
+- Poldrack, R. A., Mumford, J. A., & Nichols, T. E. (2011). *Handbook of Functional MRI Data Analysis*. Cambridge University Press.
+- Wager, T. D., & Nichols, T. E. (2003). Optimization of experimental design in fMRI: A general framework using a genetic algorithm. *NeuroImage*, 18(2), 293-309.
+
+See `references/` for detailed design optimization examples and parameter lookup tables.