Attentional drift-diffusion models¶

`hssm.aDDM`¶

hssm.aDDM ¶

aDDM(
    data: DataFrame,
    model_config: aDDMConfig | None = None,
    include: list[dict[str, Any] | Any] | None = None,
    p_outlier: float | dict | Prior | None = 0.05,
    lapse: dict | Prior | None = bmb.Prior("Uniform", lower=0.0, upper=20.0),
    prior_settings: Literal["safe"] | None = "safe",
    missing_data: bool | float = False,
    deadline: bool | str = False,
    **kwargs: Any,
)

Bases: HSSMBase

Attentional Drift Diffusion Model.

Parameters:

data (DataFrame) –

A pandas DataFrame with the response columns (rt, response) and the per-trial covariate columns r1, r2, flag, sacc_array, d, sigma. sacc_array is per-row a sequence of fixation onset times.
model_config (aDDMConfig | None, default: None ) –

An :class:aDDMConfig. Defaults to aDDMConfig() (the complete default config) when omitted.
include (list[dict[str, Any] | Any] | None, default: None ) –

Optional list of regression/parameter specifications (HSSM's standard include=[...] machinery), e.g. a hierarchical regression on eta.
prior_settings (Literal['safe'] | None, default: 'safe' ) –

Generated regression-term prior preset. "safe" uses HSSM defaults; None delegates missing regression-term priors to Bambi. Parameters without regressions retain their explicit, model-config, or bounds-derived priors. Defaults to "safe".
p_outlier (float | dict | Prior | None, default: 0.05 ) –

Forwarded to :class:hssm.base.HSSMBase.
lapse (float | dict | Prior | None, default: 0.05 ) –

Forwarded to :class:hssm.base.HSSMBase.
missing_data (float | dict | Prior | None, default: 0.05 ) –

Forwarded to :class:hssm.base.HSSMBase.
deadline (float | dict | Prior | None, default: 0.05 ) –

Forwarded to :class:hssm.base.HSSMBase.
**kwargs (Any, default: {} ) –

Additional keyword arguments forwarded to :class:hssm.base.HSSMBase, including link_settings. That link-function preset accepts "log_logit" or None and defaults to None.

Methods:

sample_posterior_predictive –

Posterior-predictive draws with a per-call fixation-continuation policy.

hssm.aDDM.sample_posterior_predictive ¶

sample_posterior_predictive(
    dt: DataTree | None = None,
    data: DataFrame | None = None,
    inplace: bool = True,
    include_group_specific: bool = True,
    kind: Literal["response", "response_params"] = "response",
    draws: int | float | list[int] | ndarray | None = None,
    safe_mode: bool = True,
    continuation_mode: str | None = None,
    continuation_params: dict | None = None,
) -> DataTree | None

Posterior-predictive draws with a per-call fixation-continuation policy.

continuation_mode / continuation_params (default: the aDDMConfig values) select how fixations continue past the observed ones, for THIS call only (see ssms.basic_simulators.fixation_continuation for the modes). They rewrite the RV class attr the generative rng_fn reads at draw time, so one fitted model can be swept across policies with no rebuild/re-fit; each call sets them explicitly, so calls never leak. Other args match the base method.

`hssm.aDDMConfig`¶

hssm.aDDMConfig `dataclass` ¶

aDDMConfig(
    model_name: str = "addm",
    description: str | None = "Attentional Drift Diffusion Model",
    response: list[str] = (lambda: ["rt", "response"])(),
    choices: tuple[int, ...] = (-1, 1),
    list_params: list[str] = (lambda: ["eta", "kappa", "a", "b", "x0", "t"])(),
    bounds: dict[str, tuple[float, float]] = (
        lambda: {
            "eta": (0.0, 1.0),
            "kappa": (0.0, 5.0),
            "a": (0.1, 3.0),
            "b": (0.0, 3.0),
            "x0": (-1.0, 1.0),
            "t": (0.0, 2.0),
        }
    )(),
    loglik: LogLik | None = None,
    loglik_kind: LoglikKind | None = "approx_differentiable",
    backend: Literal["jax", "pytensor"] | None = None,
    extra_fields: list[str] | None = (
        lambda: ["r1", "r2", "flag", "sacc_array", "d", "sigma"]
    )(),
    rv: Any | None = None,
    params_default: list[float] = (lambda: [0.3, 1.0, 1.0, 2.0, 0.0, 0.0])(),
    attention_process: str | Callable = "standard_alternating",
    continuation_mode: str = "prolong_last_fixation",
    continuation_params: dict | None = None,
)

Bases: BaseModelConfig

Config for the attentional DDM (subclass formulation).

Parameters (sampled) are [eta, kappa, a, b, x0, t], where t is the non-decision time (default 0.0, i.e. the stock model sits on the exact t=0 identity path); the per-trial covariates [r1, r2, flag, sacc_array, d, sigma] are supplied as extra_fields (not sampled), ordered to match the kernel's positional covariate slots.

Methods:

from_addm_dict –

Build an aDDMConfig from a dict, ignoring unknown keys.
get_defaults –

Return (prior, bounds) for param (no prior; bounds from config).
validate –

Validate the configuration (mirrors RLSSMConfig.validate).

hssm.aDDMConfig.from_addm_dict `classmethod` ¶

from_addm_dict(config_dict: dict[str, Any]) -> aDDMConfig

Build an aDDMConfig from a dict, ignoring unknown keys.

hssm.aDDMConfig.get_defaults ¶

get_defaults(param: str) -> tuple[None, tuple[float, float] | None]

Return (prior, bounds) for param (no prior; bounds from config).

Implements the abstract BaseModelConfig.get_defaults with the same contract as RLSSMConfig: params_default holds initialisation values, not priors, so the prior slot is None.

hssm.aDDMConfig.validate ¶

validate() -> None

Validate the configuration (mirrors RLSSMConfig.validate).

Attentional drift-diffusion models¶

hssm.aDDM¶