@brainpilot/skills 0.0.6

package/skills/03_Cognitive_Psychology/drift-diffusion-model/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: "drift-diffusion-model"
+description: "Expert guidance on selecting, fitting, and evaluating drift-diffusion models for two-choice response time data in cognitive science"
+domain: "computational-cognitive-modeling"
+version: "1.0.0"
+papers:
+ - "Ratcliff, 1978"
+ - "Ratcliff & McKoon, 2008"
+ - "Wagenmakers et al., 2007"
+ - "Voss et al., 2013"
+ - "Wiecki et al., 2013"
+dependencies:
+ required:
+ - research-literacy
+review_status: "ai-generated"
+---
+
+# Drift-Diffusion Model
+
+## Purpose
+
+This skill encodes expert knowledge for applying drift-diffusion models (DDMs) to two-choice reaction time data. DDMs decompose observed accuracy and RT distributions into latent cognitive processes — evidence accumulation rate, response caution, and non-decision time. This skill guides researchers through model variant selection, parameter fitting, and result evaluation, encoding domain-specific judgment that requires specialized training in computational cognitive modeling.
+
+## When to Use This Skill
+
+- Designing a study where two-alternative forced choice (2AFC) RT data will be collected and you want to decompose behavior into latent cognitive components
+- Choosing between DDM variants (classic DDM, full DDM, EZ-diffusion, HDDM, LBA) for a given dataset and research question
+- Setting up model fitting: selecting fitting method, preparing data, configuring software tools
+- Evaluating model fit quality: checking parameter recovery, running posterior predictive checks, comparing nested models
+- Interpreting DDM parameters in terms of cognitive processes (e.g., drift rate as evidence quality, boundary separation as response caution)
+- Troubleshooting fitting problems: convergence failures, implausible parameter estimates, poor fits to RT quantiles
+
+## When NOT to Use This Skill
+
+- Tasks with more than two response options require multi-accumulator models (see Racing Diffusion Model or LBA in `references/model-variants.md`)
+- Go/No-Go tasks violate the two-boundary assumption; use single-boundary models or SSP models instead (Ratcliff et al., 2018)
+- Tasks where speed-accuracy tradeoff is not a meaningful dimension (e.g., pure accuracy tasks with unlimited time)
+- If you only need a coarse summary of RT effects and do not need process-level decomposition, standard ANOVA on mean RT may suffice
+
+## Research Planning Protocol
+
+Before executing the domain-specific steps below, you MUST:
+
+1. **State the research question** — What cognitive process decomposition question is this DDM addressing?
+2. **Justify the method choice** — Why DDM (not simple RT analysis, Bayesian models, etc.)? What alternatives were considered?
+3. **Declare expected outcomes** — Which parameter(s) do you expect to differ across conditions, and in what direction?
+4. **Note assumptions and limitations** — What does the DDM assume (e.g., 2AFC, stationary drift)? 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).
+
+## Core Concepts
+
+### What the DDM Models
+
+The DDM assumes that on each trial, noisy evidence accumulates over time from a starting point toward one of two decision boundaries. The key insight: observed RT = decision time + non-decision time, and accuracy depends on which boundary is reached first (Ratcliff, 1978).
+
+### The Four Core Parameters
+
+| Parameter | Symbol | Cognitive Interpretation | Typical Range | Source |
+|-----------|--------|--------------------------|---------------|--------|
+| Drift rate | v | Quality/strength of evidence accumulation | **0.1 – 5.0** (commonly 0.5–3.0) | Ratcliff & McKoon, 2008; Voss et al., 2004, Table 2 |
+| Boundary separation | a | Response caution (speed-accuracy tradeoff) | **0.5 – 2.5** (commonly 0.8–2.0) | Ratcliff & McKoon, 2008; Voss et al., 2004, Table 2 |
+| Non-decision time | t0 (or Ter) | Encoding + motor execution time | **0.1 – 0.6 s** (commonly 0.2–0.5 s) | Ratcliff & McKoon, 2008; Matzke & Wagenmakers, 2009, Table 1 |
+| Starting point | z | Response bias (relative to boundaries) | **a/2** (unbiased) ± 20% | Ratcliff & McKoon, 2008; Voss et al., 2013 |
+
+### Trial-to-Trial Variability Parameters (Full DDM)
+
+| Parameter | Symbol | Interpretation | Typical Range | Source |
+|-----------|--------|----------------|---------------|--------|
+| Drift rate variability | sv | Cross-trial variation in evidence quality | **0 – 2.0** | Ratcliff & McKoon, 2008 |
+| Starting point variability | sz | Cross-trial variation in bias | **0 – 0.3 × a** | Ratcliff & McKoon, 2008 |
+| Non-decision time variability | st0 | Cross-trial variation in encoding/motor time | **0 – 0.3 s** | Ratcliff & McKoon, 2008 |
+
+## Decision Logic: Choosing a Model Variant
+
+### Step 1: Assess Your Research Question
+
+```
+Is the goal to decompose RT data into cognitive components?
+├── YES → Continue to Step 2
+└── NO → DDM may not be needed; consider simpler analyses
+```
+
+### Step 2: Assess Data Characteristics
+
+```
+How many trials per condition do you have?
+├── < 20 trials → Insufficient for any DDM variant (Ratcliff & Childers, 2015)
+├── 20-40 trials → Use EZ-diffusion only (Wagenmakers et al., 2007)
+├── 40-100 trials → Classic 4-parameter DDM or EZ-diffusion
+├── 100-200 trials → Full DDM possible but fix some variability parameters
+└── > 200 trials → Full DDM with all 7 parameters estimable
+```
+(Trial count thresholds: Ratcliff & Childers, 2015, simulation study)
+
+### Step 3: Choose Variant
+
+```
+Are you comparing groups or conditions at the population level?
+├── YES, with moderate sample size (N > 15 participants)
+│ └── Consider HDDM for hierarchical/Bayesian estimation (Wiecki et al., 2013)
+├── YES, with large trial counts per person
+│ └── Classic or Full DDM per participant, then group-level tests on parameters
+└── Exploratory / individual differences focus
+ └── HDDM or hierarchical Bayesian approach
+```
+
+```
+How many response alternatives?
+├── 2 → Standard DDM variants
+├── > 2 → LBA or Racing Diffusion Model (see references/model-variants.md)
+└── Go/No-Go → Single-boundary model (not covered here)
+```
+
+See `references/model-variants.md` for detailed comparison of all variants.
+
+### Step 4: Select Fitting Method
+
+```
+What variant did you choose?
+├── EZ-diffusion → Closed-form solution, no fitting needed (Wagenmakers et al., 2007)
+├── Classic/Full DDM → Use fast-dm (Voss & Voss, 2007) or PyDDM (Shinn et al., 2020)
+│ ├── MLE: Best for large trial counts (>100 per condition)
+│ ├── Chi-square: Robust for moderate trial counts (Ratcliff & Tuerlinckx, 2002)
+│ └── Quantile-based (QMP): Most robust to outliers (Heathcote et al., 2002)
+└── HDDM → Use HDDM Python package, Bayesian estimation (Wiecki et al., 2013)
+```
+
+See `references/fitting-guide.md` for the complete fitting workflow.
+
+## Fitting Workflow Summary
+
+1. **Data Preparation**: Clean RTs, apply cutoffs (remove < **200 ms** and > **3000-5000 ms**; Ratcliff, 1993; Ratcliff & Tuerlinckx, 2002), code accuracy
+2. **Model Specification**: Choose parameters to estimate vs. fix; decide which parameters vary across conditions
+3. **Parameter Estimation**: Run fitting with chosen method and tool
+4. **Convergence Check**: Verify optimizer converged; run multiple starting points
+5. **Model Comparison**: Use BIC (for MLE-fitted models) or DIC/WAIC (for Bayesian; Spiegelhalter et al., 2002) to compare nested models
+6. **Posterior Predictive Check**: Simulate data from fitted parameters; compare predicted vs. observed RT quantiles (Ratcliff & McKoon, 2008, Fig. 2)
+7. **Parameter Recovery**: Simulate data with known parameters; verify your pipeline can recover them (Heathcote et al., 2015)
+
+See `references/fitting-guide.md` for detailed guidance on each step.
+
+## Interpreting Parameters
+
+### Drift Rate (v)
+
+- Higher v = faster, more accurate decisions
+- Sensitive to: stimulus difficulty, attention, perceptual quality
+- **Manipulations that typically affect v**: stimulus contrast, coherence (motion dots), word frequency (Ratcliff et al., 2004)
+- If v is near 0 for a condition, participants are essentially guessing
+
+### Boundary Separation (a)
+
+- Higher a = more cautious (slower but more accurate)
+- Sensitive to: speed-accuracy instructions, emphasis conditions
+- **Manipulations that typically affect a**: speed vs. accuracy instruction (Ratcliff & McKoon, 2008), reward structure
+- If a changes across stimulus conditions (rather than instruction conditions), reconsider the model specification
+
+### Non-Decision Time (t0)
+
+- Reflects encoding + response execution time
+- Sensitive to: stimulus degradation, response modality (key press vs. voice)
+- **Manipulations that typically affect t0**: stimulus masking, response complexity (Ratcliff & McKoon, 2008)
+- If t0 > **0.5 s**, check for unusually slow motor responses or task-specific encoding demands
+
+### Starting Point (z)
+
+- Reflects a priori bias toward one response
+- Sensitive to: prior probability, payoff asymmetry
+- When z = a/2, no bias; z > a/2 = bias toward upper boundary
+- **Manipulations that typically affect z**: unequal base rates, cue validity (Ratcliff & McKoon, 2008; Voss et al., 2004)
+
+## Common Pitfalls
+
+1. **Fitting too many free parameters with too few trials**: The full 7-parameter DDM requires **>200 trials per condition** for stable estimates (Ratcliff & Childers, 2015). With fewer trials, fix variability parameters or use EZ-diffusion.
+
+2. **Ignoring RT outliers**: Extremely fast (< **200 ms**) or slow (> **3000–5000 ms**) RTs likely reflect non-decision processes (guesses, lapses). Include these and they distort parameter estimates (Ratcliff, 1993; Ratcliff & Tuerlinckx, 2002). Apply cutoffs BEFORE fitting.
+
+3. **Not checking parameter recovery**: Always simulate data with known parameters using your exact pipeline and verify you can recover them. Poor recovery means your results are uninterpretable (Heathcote et al., 2015; White et al., 2018).
+
+4. **Confusing drift rate and boundary effects**: Speed-accuracy tradeoff instructions should primarily affect boundary separation (a), not drift rate (v). If both change, the model may be misspecified or the manipulation has multiple effects (Ratcliff & McKoon, 2008).
+
+5. **Using mean RT instead of full RT distributions**: DDMs leverage the shape of the entire RT distribution. Analyzing only mean RT discards the information DDMs are designed to capture (Ratcliff, 1978; Wagenmakers et al., 2007).
+
+6. **Neglecting error RT distributions**: Correct and error RT distributions are jointly constrained by the DDM. Fitting only correct RTs loses critical information about the generative process (Ratcliff & McKoon, 2008).
+
+7. **Treating HDDM posterior modes as point estimates**: Bayesian models yield posterior distributions. Report and interpret the full posterior, including credible intervals, rather than treating the mode as a frequentist point estimate (Wiecki et al., 2013).
+
+## Key References
+
+- Ratcliff, R. (1978). A theory of memory retrieval. *Psychological Review*, 85(2), 59–108.
+- Ratcliff, R., & McKoon, G. (2008). The diffusion decision model: Theory and data for two-choice decision tasks. *Neural Computation*, 20(4), 873–922.
+- Wagenmakers, E.-J., van der Maas, H. L. J., & Grasman, R. P. P. P. (2007). An EZ-diffusion model for response time and accuracy. *Psychonomic Bulletin & Review*, 14(1), 3–22.
+- Voss, A., Nagler, M., & Lerche, V. (2013). Diffusion models in experimental psychology: A practical introduction. *Experimental Psychology*, 60(6), 385–402.
+- Wiecki, T. V., Sofer, I., & Frank, M. J. (2013). HDDM: Hierarchical Bayesian estimation of the drift-diffusion model in Python. *Frontiers in Neuroinformatics*, 7, 14.
+- See `references/model-variants.md` for DDM family details.
+- See `references/fitting-guide.md` for the complete fitting workflow.