agentleFS
NeuroAIHubNeuroAIHub/awesome_cognitive_and_neuroscience_skills/skills/drift-diffusion-model/SKILL.md

drift-diffusion-model

Skill39 starsChanged 9 months agoMITView on GitHub

Expert guidance on selecting, fitting, and evaluating drift-diffusion models for two-choice response time data in cognitive science

The file

We split this skill into the rules it gives an agent

11 rules. About 0 are common, 11 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈11

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    If you only need a coarse summary of RT effects and do not need process-level decomposition, standard ANOVA on mean RT may suffice

    line 38
  2. Distinctive:

    Before executing the domain-specific steps below, you MUST:

    line 42
  3. Distinctive:

    Present the plan to the user and WAIT for confirmation: before proceeding.

    line 48
  4. Distinctive:

    Parameter Estimation: Run fitting with chosen method and tool

    line 141
  5. Distinctive:

    Convergence Check: Verify optimizer converged.

    line 142
  6. Distinctive:

    Model Comparison: Use BIC (for MLE-fitted models) or DIC/WAIC (for Bayesian.

    line 143
  7. Distinctive:

    If v is near 0 for a condition, participants are essentially guessing

    line 156
  8. Distinctive:

    If a changes across stimulus conditions (rather than instruction conditions), reconsider the model specification

    line 163
  9. Distinctive:

    If t0 > 0.5 s, check for unusually slow motor responses or task-specific encoding demands

    line 170
  10. Distinctive:

    When z = a/2, no bias; z > a/2 = bias toward upper boundary

    line 176
  11. Distinctive:

    Not checking parameter recovery: Always simulate data with known parameters using your exact pipeline and verify you can recover them.

    line 185

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.

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

ParameterSymbolCognitive InterpretationTypical RangeSource
Drift ratevQuality/strength of evidence accumulation0.1 – 5.0 (commonly 0.5–3.0)Ratcliff & McKoon, 2008; Voss et al., 2004, Table 2
Boundary separationaResponse caution (speed-accuracy tradeoff)0.5 – 2.5 (commonly 0.8–2.0)Ratcliff & McKoon, 2008; Voss et al., 2004, Table 2
Non-decision timet0 (or Ter)Encoding + motor execution time0.1 – 0.6 s (commonly 0.2–0.5 s)Ratcliff & McKoon, 2008; Matzke & Wagenmakers, 2009, Table 1
Starting pointzResponse bias (relative to boundaries)a/2 (unbiased) ± 20%Ratcliff & McKoon, 2008; Voss et al., 2013

Trial-to-Trial Variability Parameters (Full DDM)

ParameterSymbolInterpretationTypical RangeSource
Drift rate variabilitysvCross-trial variation in evidence quality0 – 2.0Ratcliff & McKoon, 2008
Starting point variabilityszCross-trial variation in bias0 – 0.3 × aRatcliff & McKoon, 2008
Non-decision time variabilityst0Cross-trial variation in encoding/motor time0 – 0.3 sRatcliff & 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.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.