Basic Tutorial: Simulate and Inspect Sequential Sampling Models¶

This tutorial introduces the main ssm-simulators workflow: create a simulator, generate reaction times and choices, inspect the result, and build a small training-data example.

The notebook runs locally after installing ssm-simulators and can also be opened in Google Colab.

Install¶

For a local environment, install the package from PyPI before starting Jupyter:

python -m pip install ssm-simulators

The next cell installs the package only when the notebook is running in Colab. It is skipped in a local Jupyter session where the package is already installed.

In [1]:

import os

if "COLAB_RELEASE_TAG" in os.environ:
    %pip install -q ssm-simulators

import os if "COLAB_RELEASE_TAG" in os.environ: %pip install -q ssm-simulators

Imports¶

ssm-simulators provides fast simulators for sequential sampling models. We will use NumPy for checks, pandas for a compact tabular view, and Matplotlib for one basic diagnostic plot.

In [2]:

import matplotlib.pyplot as plt
import numpy as np
import pandas as pd
import ssms

from ssms import Simulator

import matplotlib.pyplot as plt import numpy as np import pandas as pd import ssms from ssms import Simulator

Create a Simulator¶

The class-based interface is the recommended starting point. Pass a model name to Simulator and inspect the stable parts of its configuration before simulating data.

In [3]:

ddm_sim = Simulator("ddm")

print("Model:", ddm_sim.config["name"])
print("Parameters:", ddm_sim.config["params"])
print("Choices:", ddm_sim.config["nchoices"])

ddm_sim = Simulator("ddm") print("Model:", ddm_sim.config["name"]) print("Parameters:", ddm_sim.config["params"]) print("Choices:", ddm_sim.config["nchoices"])

Model: ddm
Parameters: ['v', 'a', 'z', 't']
Choices: 2

Simulate Reaction Times and Choices¶

A parameter dictionary supplies one value for each model parameter. The result is a dictionary containing arrays such as rts and choices. random_state makes the example reproducible across notebook runs.

In [4]:

theta = {"v": 0.0, "a": 1.0, "z": 0.5, "t": 0.5}
sim_out = ddm_sim.simulate(theta=theta, n_samples=1000, random_state=42)

rts = sim_out["rts"].ravel()
choices = sim_out["choices"].ravel()

print("Output keys:", sorted(sim_out))
print("RT shape:", sim_out["rts"].shape)
print("Choice shape:", sim_out["choices"].shape)

theta = {"v": 0.0, "a": 1.0, "z": 0.5, "t": 0.5} sim_out = ddm_sim.simulate(theta=theta, n_samples=1000, random_state=42) rts = sim_out["rts"].ravel() choices = sim_out["choices"].ravel() print("Output keys:", sorted(sim_out)) print("RT shape:", sim_out["rts"].shape) print("Choice shape:", sim_out["choices"].shape)

Output keys: ['choices', 'metadata', 'rts']
RT shape: (1000, 1)
Choice shape: (1000, 1)

In [5]:

simulated_data = pd.DataFrame({"rt": rts, "choice": choices})
simulated_data.head()

simulated_data = pd.DataFrame({"rt": rts, "choice": choices}) simulated_data.head()

Out[5]:

	rt	choice
0	1.254133	1
1	1.214967	-1
2	1.950749	1
3	1.389157	-1
4	1.270219	1

Reproducibility¶

Passing the same seed to the same simulator produces the same arrays. This is useful for examples, tests, and debugging.

In [6]:

repeat_out = ddm_sim.simulate(theta=theta, n_samples=1000, random_state=42)
print("RTs match:", np.array_equal(sim_out["rts"], repeat_out["rts"]))
print("Choices match:", np.array_equal(sim_out["choices"], repeat_out["choices"]))

repeat_out = ddm_sim.simulate(theta=theta, n_samples=1000, random_state=42) print("RTs match:", np.array_equal(sim_out["rts"], repeat_out["rts"])) print("Choices match:", np.array_equal(sim_out["choices"], repeat_out["choices"]))

RTs match: True
Choices match: True

A Basic Diagnostic¶

Reaction-time distributions and choice proportions are quick checks that a simulation has the expected scale and response structure.

In [7]:

fig, axes = plt.subplots(1, 2, figsize=(10, 4))

axes[0].hist(rts, bins=30, color="C0", alpha=0.85)
axes[0].set_title("Reaction times")
axes[0].set_xlabel("RT")
axes[0].set_ylabel("Count")

labels, counts = np.unique(choices, return_counts=True)
axes[1].bar(labels.astype(str), counts / counts.sum(), color="C1")
axes[1].set_title("Choice proportions")
axes[1].set_xlabel("Choice")
axes[1].set_ylabel("Proportion")

fig.tight_layout()

fig, axes = plt.subplots(1, 2, figsize=(10, 4)) axes[0].hist(rts, bins=30, color="C0", alpha=0.85) axes[0].set_title("Reaction times") axes[0].set_xlabel("RT") axes[0].set_ylabel("Count") labels, counts = np.unique(choices, return_counts=True) axes[1].bar(labels.astype(str), counts / counts.sum(), color="C1") axes[1].set_title("Choice proportions") axes[1].set_xlabel("Choice") axes[1].set_ylabel("Proportion") fig.tight_layout()

Functional API¶

The original functional API remains available for short, one-off calls. The class-based API above is more convenient when you will reuse a model configuration or call the simulator repeatedly.

In [8]:

from ssms.basic_simulators.simulator import simulator

functional_out = simulator(
    model="ddm", theta=theta, n_samples=1000, random_state=42
)
print("Functional API keys:", sorted(functional_out))

from ssms.basic_simulators.simulator import simulator functional_out = simulator( model="ddm", theta=theta, n_samples=1000, random_state=42 ) print("Functional API keys:", sorted(functional_out))

Functional API keys: ['binned_128', 'binned_256', 'choice_p', 'choice_p_no_omission', 'choices', 'go_p', 'metadata', 'nogo_p', 'omission_p', 'rts']

Try Another Model¶

Other built-in models use the same simulator interface. The Angle model below has an additional theta parameter for its collapsing boundary.

In [9]:

angle_sim = Simulator("angle")
angle_theta = {
    "v": 0.0,
    "a": 1.0,
    "z": 0.5,
    "t": 0.5,
    "theta": 0.3,
}
angle_out = angle_sim.simulate(
    theta=angle_theta, n_samples=500, random_state=42
)
print("Model:", angle_sim.config["name"])
print("RT shape:", angle_out["rts"].shape)
print("Choice shape:", angle_out["choices"].shape)

angle_sim = Simulator("angle") angle_theta = { "v": 0.0, "a": 1.0, "z": 0.5, "t": 0.5, "theta": 0.3, } angle_out = angle_sim.simulate( theta=angle_theta, n_samples=500, random_state=42 ) print("Model:", angle_sim.config["name"]) print("RT shape:", angle_out["rts"].shape) print("Choice shape:", angle_out["choices"].shape)

Model: angle
RT shape: (500, 1)
Choice shape: (500, 1)

Generate a Small Training Dataset¶

TrainingDataGenerator combines parameter sampling and simulation into the arrays used by likelihood approximation networks. The compact setup below is designed to run quickly as a tutorial smoke test; increase the sample counts for real training data.

For the full configuration and production-oriented workflow, see the training data generator tutorial.

In [10]:

from ssms.config import get_default_generator_config, model_config
from ssms.dataset_generators.lan_mlp import TrainingDataGenerator

generator_config = get_default_generator_config(model="ddm")
generator_config["pipeline"].update(
    {
        "n_parameter_sets": 2,
        "n_parameter_sets_rejected": 0,
        "n_subruns": 1,
        "n_cpus": 1,
    }
)
generator_config["training"]["n_samples_per_param"] = 50
generator_config["simulator"]["n_samples"] = 500

generator = TrainingDataGenerator(
    config=generator_config,
    model_config=model_config["ddm"],
)
training_data = generator.generate_data_training(save=False)

print("Output keys:", sorted(training_data))
print("LAN data shape:", training_data["lan_data"].shape)
print("LAN labels shape:", training_data["lan_labels"].shape)

from ssms.config import get_default_generator_config, model_config from ssms.dataset_generators.lan_mlp import TrainingDataGenerator generator_config = get_default_generator_config(model="ddm") generator_config["pipeline"].update( { "n_parameter_sets": 2, "n_parameter_sets_rejected": 0, "n_subruns": 1, "n_cpus": 1, } ) generator_config["training"]["n_samples_per_param"] = 50 generator_config["simulator"]["n_samples"] = 500 generator = TrainingDataGenerator( config=generator_config, model_config=model_config["ddm"], ) training_data = generator.generate_data_training(save=False) print("Output keys:", sorted(training_data)) print("LAN data shape:", training_data["lan_data"].shape) print("LAN labels shape:", training_data["lan_labels"].shape)

Output keys: ['binned_128', 'binned_256', 'cpn_data', 'cpn_labels', 'cpn_no_omission_data', 'cpn_no_omission_labels', 'generator_config', 'gonogo_data', 'gonogo_labels', 'lan_data', 'lan_labels', 'model_config', 'opn_data', 'opn_labels', 'theta']
LAN data shape: (100, 6)
LAN labels shape: (100,)

The returned dictionary also includes the sampled parameters and the generator/model configurations. Set save=True and provide the output settings from the full tutorial when you want to persist a dataset.

Next Steps¶

• Browse the simulator API for available models and simulator arguments.
• Inspect the configuration API for model and generator configuration helpers.
• Learn how to add a custom model.
• Use the training data generator tutorial for larger datasets and persistence options.