hssm.HSSM

Use hssm.HSSM class to construct an HSSM model.

hssm.HSSM

HSSM(
    data: DataFrame,
    model: SupportedModels | str = "ddm",
    choices: list[int] | None = None,
    include: list[dict[str, Any] | Any] | None = None,
    model_config: ModelConfig | dict | None = None,
    loglik: str
    | PathLike
    | Callable
    | Distribution
    | type[Distribution]
    | None = None,
    loglik_kind: LoglikKind | None = None,
    p_outlier: float | dict | Prior | None = 0.05,
    lapse: float | dict | Prior | None = None,
    global_formula: str | None = None,
    link_settings: Literal["log_logit"] | None = None,
    prior_settings: Literal["safe"] | None = "safe",
    extra_namespace: dict[str, Any] | None = None,
    missing_data: bool | float = False,
    deadline: bool | str = False,
    loglik_missing_data: str | PathLike | Callable | None = None,
    process_initvals: bool = True,
    initval_jitter: float = INITVAL_JITTER_SETTINGS["jitter_epsilon"],
    **kwargs: Any,
)

Bases: HSSMBase

The basic Hierarchical Sequential Sampling Model (HSSM) class.

Parameters:

• data (DataFrame) –

  A pandas DataFrame with the minimum requirements of containing the data with the columns "rt" and "response".

• model (SupportedModels | str, default: 'ddm' ) –

  The name of the model to use. Currently supported models are "ddm", "ddm_sdv", "full_ddm", "angle", "levy", "ornstein", "weibull", "race_no_bias_angle_4", "ddm_seq2_no_bias". If any other string is passed, the model will be considered custom, in which case all model_config, loglik, and loglik_kind have to be provided by the user.

• choices (optional, default: None ) –

  When an int, the number of choices that the participants can make. If 2, the choices are [-1, 1] by default. If anything greater than 2, the choices are [0, 1, ..., n_choices - 1] by default. If a list is provided, it should be the list of choices that the participants can make. Defaults to 2. If any value other than the choices provided is found in the "response" column of the data, an error will be raised.

• include (optional, default: None ) –

  A list of dictionaries specifying parameter specifications to include in the model. If left unspecified, defaults will be used for all parameter specifications. Defaults to None.

• model_config (optional, default: None ) –

  A hssm.config.BaseModelConfig / hssm.config.Config instance or a dict with model configuration information. The constructor accepts a typed ModelConfig or a plain dict; when a dict is provided the library will build a typed Config via the factory function. If None is provided, defaults will be used where available. Fields for this config are usually:

  • "list_params": a list of parameters indicating the parameters of the model. The order in which the parameters are specified in this list is important. Values for each parameter will be passed to the likelihood function in this order.
  • "backend": Only used when loglik_kind is approx_differentiable and an onnx file is supplied for the likelihood approximation network (LAN). Valid values are "jax" or "pytensor". It determines whether the LAN in ONNX should be converted to "jax" or "pytensor". If not provided, jax will be used for maximum performance.
  • "default_priors": A dict indicating the default priors for each parameter.
  • "bounds": A dict indicating the boundaries for each parameter. In the case of LAN, these bounds are training boundaries.
  • "rv": Optional. Can be a RandomVariable class containing the user's own rng_fn function for sampling from the distribution that the user is supplying. If not supplied, HSSM will automatically generate a RandomVariable using the simulator identified by model from the ssm_simulators package. If model is not supported in ssm_simulators, a warning will be raised letting the user know that sampling from the RandomVariable will result in errors.
  • "extra_fields": Optional. A list of strings indicating the additional columns in data that will be passed to the likelihood function for calculation. This is helpful if the likelihood function depends on data other than the observed data and the parameter values.
• loglik (optional, default: None ) –

  A likelihood function. Defaults to None. Requirements are:

  1. if loglik_kind is "analytical" or "blackbox", a pm.Distribution, a pytensor Op, or a Python callable can be used. Signatures are:
     • pm.Distribution: needs to have parameters specified exactly as listed in list_params
     • pytensor.graph.Op and Callable: needs to accept the parameters specified exactly as listed in list_params
  2. If loglik_kind is "approx_differentiable", then in addition to the specifications above, a str or Pathlike can also be used to specify a path to an onnx file. If a str is provided, HSSM will first look locally for an onnx file. If that is not successful, HSSM will try to download that onnx file from Hugging Face hub.
  3. It can also be None, in which case a default likelihood function will be used
• loglik_kind (optional, default: None ) –

  A string that specifies the kind of log-likelihood function specified with loglik. Defaults to None. Can be one of the following:

  • "analytical": an analytical (approximation) likelihood function. It is differentiable and can be used with samplers that requires differentiation.
  • "approx_differentiable": a likelihood approximation network (LAN) likelihood function. It is differentiable and can be used with samplers that requires differentiation.
  • "blackbox": a black box likelihood function. It is typically NOT differentiable.
  • None, in which a default will be used. For ddm type of models, the default will be analytical. For other models supported, it will be approx_differentiable. If the model is a custom one, a ValueError will be raised.
• p_outlier (optional, default: 0.05 ) –

  The fixed lapse probability or the prior distribution of the lapse probability. Defaults to a fixed value of 0.05. When None, the lapse probability will not be included in estimation.

• lapse (optional, default: None ) –

  The lapse distribution. This argument is required only if p_outlier is not None. Defaults to Uniform(0.0, 10.0).

• global_formula (optional, default: None ) –

  A string that specifies a regressions formula which will be used for all model parameters. If you specify parameter-wise regressions in addition, these will override the global regression for the respective parameter.

• link_settings (optional, default: None ) –

  An optional string literal that indicates the link functions to use for each parameter. Helpful for hierarchical models where sampling might get stuck/ very slow. Can be one of the following:

  • "log_logit": applies log link functions to positive parameters and generalized logit link functions to parameters that have explicit bounds.
  • None: unless otherwise specified, the "identity" link functions will be used. The default value is None.
• prior_settings (optional, default: 'safe' ) –

  An optional string literal that indicates the prior distributions to use for each parameter. Helpful for hierarchical models where sampling might get stuck/ very slow. Can be one of the following:

  • "safe": HSSM will scan all parameters in the model and apply safe priors to all parameters that do not have explicit bounds.
  • None: HSSM will use bambi to provide default priors for all parameters. Not recommended when you are using hierarchical models. The default value is "safe".
• extra_namespace (optional, default: None ) –

  Additional user supplied variables with transformations or data to include in the environment where the formula is evaluated. Defaults to None.

• missing_data (optional, default: False ) –

  Specifies whether the model should handle missing data. Can be a bool or a float. If False, and if the rt column contains in the data -999.0, the model will drop these rows and produce a warning. If True, the model will treat code -999.0 as missing data. If a float is provided, the model will treat this value as the missing data value. Defaults to False.

• deadline (optional, default: False ) –

  Specifies whether the model should handle deadline data. Can be a bool or a str. If False, the model will not do nothing even if a deadline column is provided. If True, the model will treat the deadline column as deadline data. If a str is provided, the model will treat this value as the name of the deadline column. Defaults to False.

• loglik_missing_data (optional, default: None ) –

  A likelihood function for missing data. Please see the loglik parameter to see how to specify the likelihood function this parameter. If nothing is provided, a default likelihood function will be used. This parameter is required only if either missing_data or deadline is not False. Defaults to None.

• process_initvals (optional, default: True ) –

  If True, the model will process the initial values. Defaults to True.

• initval_jitter (optional, default: INITVAL_JITTER_SETTINGS['jitter_epsilon'] ) –

  The jitter value for the initial values. Defaults to 0.01.

• noncentered (optional) –

  Controls the centered vs. non-centered parameterization of group-specific (hierarchical) terms. True (bambi's default) uses the non-centered parameterization everywhere, False uses centered. A dict keyed by HSSM parameter name (e.g. {"v": False, "a": True}) sets it per parameter; an unknown key raises at construction. A per-prior noncentered field (inside a prior dict or on an hssm.Prior) overrides the model-level value for that term (precedence: per-prior > model-level dict > default True). Only affects parameters that have a group-specific term (e.g. ... + (1|participant_id)); setting it for a non-hierarchical parameter is a silent no-op. Passed to bmb.Model.

• **kwargs (Any, default: {} ) –

  Additional arguments passed to the bmb.Model object.