lnccbrown / lnccbrown/HSSM

aDDM model cartoon: condition on observed fixations + honor continuation policy (currently generic-SSM re-simulation)

Open
#1,039 1 comment 0 reactions 1 assignee View on GitHub

@AlexanderFengler is already working on this.

Since Jul 8, 2026.

Dominant language
Python
Stars
124
Forks
24
Avg merge
19h 32m
Merged PRs (30d)
60

Description

Summary

hssm.plotting.plot_model_cartoon produces a valid-looking cartoon for the aDDM, but its predictive is decoupled from the aDDM's fixation covariates and continuation policy in three ways. The cartoon reuses the generic-SSM path, which assumes "re-simulate at posterior θ" fully specifies the predictive — true for covariate-free SSMs, but the aDDM adds per-trial fixation covariates (r1, r2, flag, sacc_array, d, sigma) and a posterior-predictive continuation policy that the cartoon has no way to thread.

Follow-up to #1032 (cartoon) and #1035 (fixation continuation). A caveat is documented in the aDDM tutorial §7 + the plot_model_cartoon docstring; this issue tracks the real fix.

The three decouplings

  1. Regenerated predictive uses the default continuation. plot_model_cartoon deep-copies idata, collapses the posterior to its per-trial mean, and _make_idata_mean_posterior deletes the posterior_predictive group (src/hssm/plotting/model_cartoon.py:351-352). _use_traces_or_sample (src/hssm/plotting/utils.py:511-526) then regenerates it via model.sample_posterior_predictive(idata=..., data=..., inplace=True, draws=n_samples) with no continuation_mode/continuation_params → always the config default prolong_last_fixation. A user's per-call sample_continuation is discarded (it lives only in the user's original idata, which the cartoon deep-copies and never reads).

  2. The drawn histogram + trajectories self-sample fixations (Mode 1). plot_func_model re-simulates via simulator(model="addm", theta=θ̄, ...) (model_cartoon.py:901, 938, 968) with no extra_fields, so the aDDM simulator self-samples its own gaze sequence instead of conditioning on each trial's observed fixations. The trajectories are genuine aDDM drift paths (metadata["trajectory"]), but for invented fixations, not the empirical ones. extra_fields never appears anywhere in model_cartoon.py.

  3. No public API to pass either. plot_model_cartoon exposes neither extra_fields nor continuation_mode/continuation_params.

Net: the aDDM cartoon's predictive is neither the observed-fixation-conditioned PPC (model.sample_posterior_predictive, Mode 2) nor steerable by continuation policy — it silently differs from tutorial §6.

Proposed fix

  • Add continuation_mode / continuation_params params to plot_model_cartoonplot_func_model, and pass them to the simulator(...) calls (model_cartoon.py:901/938/968) and the step-1 regeneration.
  • For covariate models (aDDM), thread the observed extra_fields (per-trial covariate rows aligned to the sampled θ rows) into those simulator(...) calls (Mode 2); tile the observed fixation set to n_samples to match the θ tiling.
  • Test: assert the cartoon's predictive differs between prolong_last_fixation and sample_continuation, and that swapping observed r1/r2 changes the drift (stimulus-conditioning holds).

Acceptance

  • plot_model_cartoon(model, idata, continuation_mode="sample_continuation", ...) yields a cartoon whose predictive matches a Mode-2 sample_continuation PPC.
  • The cartoon conditions on the observed fixations by default (Mode 2), matching aDDM tutorial §6.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.