From awesome-cognitive-and-neuroscience-skills
Guides fMRI General Linear Model specification: HRF modeling, design matrix construction, contrasts, confound regression, and statistical inference for task-based analysis.
npx claudepluginhub neuroaihub/awesome_cognitive_and_neuroscience_skills --plugin awesome-cognitive-and-neuroscience-skillsThis skill uses the workspace's default tool permissions.
The General Linear Model (GLM) is the standard statistical framework for task-based fMRI analysis. It models the observed BOLD time series as a linear combination of expected signal components (task regressors convolved with the hemodynamic response function) plus confound regressors plus noise (Poline & Brett, 2012; Poldrack et al., 2011, Ch. 4).
Guides fMRI task design: block, event-related, mixed paradigms; jittering; contrasts; power for BOLD detection. For planning cognitive neuroscience experiments.
Provides UI/UX resources: 50+ styles, color palettes, font pairings, guidelines, charts for web/mobile across React, Next.js, Vue, Svelte, Tailwind, React Native, Flutter. Aids planning, building, reviewing interfaces.
Fetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.
Share bugs, ideas, or general feedback.
The General Linear Model (GLM) is the standard statistical framework for task-based fMRI analysis. It models the observed BOLD time series as a linear combination of expected signal components (task regressors convolved with the hemodynamic response function) plus confound regressors plus noise (Poline & Brett, 2012; Poldrack et al., 2011, Ch. 4).
This skill encodes the domain-specific judgment needed to correctly specify a GLM for fMRI data. A competent programmer without neuroimaging training would get many of these decisions wrong -- choosing the wrong HRF model, setting an inappropriate high-pass filter cutoff, omitting critical confound regressors, or applying invalid statistical thresholds. Each decision described here requires understanding the biophysics of BOLD signal, the noise characteristics of fMRI data, and the statistical assumptions of the model.
Before executing the domain-specific steps below, you MUST:
For detailed methodology guidance, see the research-literacy skill.
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.
The hemodynamic response function (HRF) models the neurovascular coupling delay between neural activity and the measured BOLD signal. The canonical HRF peaks at approximately 5-6 seconds post-stimulus (Glover, 1999).
| HRF Model | When to Use | Trade-off |
|---|---|---|
| Canonical (double-gamma) | Default for most task designs when timing is well-established | Assumes fixed HRF shape; highest statistical power (1 parameter per condition) (Lindquist et al., 2009) |
| Canonical + temporal derivative | When peak latency may vary by ~1 s across conditions or regions | Captures timing shifts; 2 parameters per condition (Friston et al., 1998; Henson et al., 2002) |
| Canonical + temporal + dispersion derivatives | When both latency and width of HRF may vary | Maximum flexibility with basis functions; 3 parameters per condition, reduced power (Henson et al., 2002) |
| Finite Impulse Response (FIR) | When HRF shape is unknown or expected to deviate substantially from canonical form | No shape assumption; many parameters (one per time bin); requires many trials for stable estimation (Glover, 1999; Dale, 1999) |
Decision logic:
Is the HRF shape well-established for your task and population?
|
+-- YES --> Is timing precision critical to your hypothesis?
| |
| +-- YES --> Canonical + temporal derivative
| |
| +-- NO --> Canonical HRF (default)
|
+-- NO --> Do you have enough trials (>40 per condition) for stable estimation?
|
+-- YES --> FIR model (exploratory) or canonical + derivatives
|
+-- NO --> Canonical + temporal derivative (safest compromise)
Domain warning: When using derivative basis functions, the contrast for the main condition should weight only the canonical regressor (not the derivatives). An F-test across all basis functions tests whether any component differs from zero (Calhoun et al., 2004). See references/design-matrix-guide.md for details.
Low-frequency drifts from scanner instability, subject physiology, and slow head motion must be removed. This is implemented as a discrete cosine transform (DCT) basis set added to the design matrix (Poldrack et al., 2011, Ch. 5).
Domain warning: Setting the cutoff too low (long period) leaves drift in the data, inflating noise. Setting it too high (short period) attenuates your experimental signal. Always verify that your design's fundamental frequency is preserved by the filter.
Confound regressors model variance from non-neural sources. Omitting them inflates false positive rates; including too many reduces statistical power.
Head motion is the single largest source of structured artifact in fMRI (Power et al., 2012).
| Model | Parameters | When to Use | Source |
|---|---|---|---|
| Standard 6-parameter | 3 translation + 3 rotation | Minimum acceptable model | Friston et al., 1996 |
| 24-parameter (Friston) | 6 current + 6 prior timepoint + 12 squared terms | Recommended default for task fMRI | Friston et al., 1996 |
| 6-parameter + derivatives | 6 current + 6 temporal derivatives | Intermediate model | Satterthwaite et al., 2013 |
Domain insight: The 24-parameter model (Friston et al., 1996) captures both linear and nonlinear motion effects, including spin-history artifacts from previous-timepoint head positions. The squared terms model the nonlinear relationship between motion and BOLD signal changes.
When physiological recordings (pulse, respiration) are unavailable:
Domain warning -- global signal regression: Regressing out the global mean signal is controversial. It improves motion artifact removal but introduces artifactual anticorrelations in functional connectivity analyses (Murphy & Fox, 2017). For task-based GLM, global signal regression is generally not recommended unless specifically justified.
fMRI time series exhibit temporal autocorrelation due to hemodynamic smoothing and physiological noise. Ignoring this inflates t-statistics and false positive rates (Woolrich et al., 2001).
| Method | Implementation | Software |
|---|---|---|
| AR(1) prewhitening | Models autocorrelation as first-order autoregressive process | SPM (default), Nilearn |
| ARMA(1,1) | Autoregressive moving-average; more flexible | AFNI (3dREMLfit) |
| Tukey taper prewhitening | Nonparametric spectral smoothing of autocorrelation | FSL FILM (Woolrich et al., 2001) |
Domain insight: Recent work has shown that AR(1) may be insufficient for modern multiband acquisitions with short TRs (< 1 s), where higher-order autocorrelation structure is present (Olszowy et al., 2019). For short-TR data, consider ARMA(1,1) or FSL's FILM approach.
Before fitting the model:
See references/design-matrix-guide.md for detailed guidance on design matrix construction.
Contrasts define the specific hypotheses you test within the fitted GLM.
A t-contrast is a single row vector of weights applied to the parameter estimates. It tests a directional hypothesis.
| Contrast Type | Weight Vector Example | Tests |
|---|---|---|
| Activation vs. baseline | [1 0 0 ...] | Is condition A > 0? |
| Condition difference | [1 -1 0 ...] | Is condition A > condition B? |
| Linear trend | [-1 0 1 ...] | Does activation increase linearly across 3 levels? |
| Interaction (2x2) | [1 -1 -1 1 ...] | Does the difference A1-A2 differ from B1-B2? |
Rules for valid t-contrasts (Poline & Brett, 2012):
An F-contrast tests whether any of several effects are non-zero. It is specified as a matrix (multiple rows).
| Use Case | When to Use |
|---|---|
| Main effect of factor | Testing whether any level of a factor differs from any other |
| HRF model with derivatives | Testing whether the canonical + derivative basis set captures any response |
| Any-difference test | Testing whether any condition differs from baseline |
Domain insight: An F-test for the full basis set (canonical + derivatives) tests whether there is any evoked response, regardless of its exact timing or shape. This is more sensitive than a t-test on the canonical regressor alone when the true HRF deviates from canonical form (Calhoun et al., 2004).
First-level contrast maps (one per subject) serve as input to the group model.
| Approach | Models | Generalizability | When to Use | Source |
|---|---|---|---|---|
| Fixed effects (FFX) | Within-subject variance only | Only to the scanned subjects | Multiple runs within one subject | Poldrack et al., 2011, Ch. 8 |
| Mixed effects (MFX) | Within- + between-subject variance | To the population | Group inference across subjects | Mumford & Nichols, 2009 |
| OLS (summary statistics) | Between-subject variance only | To the population (if homogeneity holds) | Standard group analysis; valid and near-optimal under moderate variance heterogeneity | Mumford & Nichols, 2009 |
Decision logic:
Are you combining runs within one subject?
|
+-- YES --> Fixed effects (concatenation or run-by-run with FFX)
|
+-- NO --> Are you making group-level inferences?
|
+-- YES --> Mixed effects (FLAME in FSL) or OLS summary statistics
OLS is valid and near-optimal for balanced designs
(Mumford & Nichols, 2009)
Domain warning: Using a fixed-effects analysis for group inference treats between-subject variability as zero, dramatically inflating false positive rates. Results would apply only to the specific subjects scanned, not to the population (Friston et al., 2005; Mumford & Nichols, 2009).
With approximately 100,000 voxels tested simultaneously, correction for multiple comparisons is essential. See references/statistical-inference.md for detailed guidance.
| Method | Controls | Recommended Threshold | When to Use |
|---|---|---|---|
| Voxelwise FWE (RFT) | Family-wise error | p < 0.05 FWE | Highly localized effects expected (Worsley et al., 1996) |
| FDR (Benjamini-Hochberg) | False discovery rate | q < 0.05 | Distributed effects; moderate correction (Genovese et al., 2002) |
| Cluster-based (RFT) | Cluster-level FWE | CDT p < 0.001, then cluster p < 0.05 FWE | Standard approach; use CDT of p < 0.001 (Eklund et al., 2016) |
| TFCE | Voxelwise FWE via permutation | p < 0.05 FWE-corrected | No arbitrary CDT; good sensitivity (Smith & Nichols, 2009) |
| Permutation testing | FWE (nonparametric) | p < 0.05 FWE | Gold standard; no distributional assumptions (Nichols & Holmes, 2002) |
Critical domain knowledge: Cluster-based inference with a cluster-defining threshold (CDT) of p < 0.01 produces inflated false positive rates (up to 70% instead of the nominal 5%). Always use CDT of p < 0.001 or stricter (Eklund et al., 2016). For permutation tests, use at least 5,000-10,000 permutations for publication-quality results (Nichols & Holmes, 2002).
Based on the OHBM COBIDAS guidelines (Nichols et al., 2017) and Poldrack et al. (2008):
See references/ for detailed design matrix construction guide and statistical inference methods.