SessionWrapper

class SessionWrapper(model=None, data=None, parameters=None, prepare=None)

Bases: Wrapper

A Wrapper for a model function that computes all trials of a participant at once.

SessionWrapper works like Wrapper, and can be used wherever a Wrapper can (the optimisers, Simulator and cpm.hierarchical), but its model function is called once per run instead of once per trial. Loops over trials can then be written in plain Python on numpy arrays, or compiled with numba, and the cost of calling a Python function and copying the parameters on every trial is gone. This is typically 10 to 100 times faster than a per-trial Wrapper.

Use it instead of a Wrapper when fitting your own model is too slow; the built-in models in cpm.applications already compute all trials at once. See Speed up your own model for how to rewrite a per-trial model.

Parameters:

modelfunction

The model function, which computes the outputs of the model on all trials of a participant. See Notes.

datapandas.DataFrame or dict

The data of a single participant (or the environment of a simulation), as for Wrapper: a pandas.DataFrame with one row per trial, or a dictionary with one entry per variable, each holding the values on all trials.

parametersParameters

The parameters of the model, including its initial states.

preparefunction, optional

A function that turns the data into the form the model function takes. It is called once, when the data are first needed (and again after reset with new data or without parameters), not on every run. The default is session_data(), which returns a dictionary of contiguous numpy arrays, one per column.

Notes

The model function takes two arguments, parameters and data. parameters is the Parameters object of the model, and data is the output of prepare. The model function returns a dictionary of outputs, each an array with one row per trial (or a scalar, repeated on every trial). If the model is to be fitted, the outputs include

• ‘dependent’: the dependent variables for the loss function, with shape (trials,) or (trials, k).

After a run, dependent has shape (trials, k), as for a Wrapper, and each output whose name is also a parameter (such as a state) sets that parameter to its value on the last trial, the state a per-trial Wrapper ends a run with. Otherwise the model function should not change parameters.

export() returns one row per trial, laid out as the export of a per-trial Wrapper, see session_export(). The outputs of the last run are in session_output, one array per output, and in simulation, one dictionary per trial, as for a Wrapper. The model function should not change data, which is reused on every run.

Examples

A Rescorla-Wagner model of a single cue, written for all trials at once:

>>> import numpy as np
>>> import pandas as pd
>>> from cpm.generators import SessionWrapper, Parameters, Value
>>> def model(parameters, data):
...     alpha = parameters.alpha.value
...     value = float(parameters.value.value)
...     predictions = np.empty(len(data["reward"]))
...     for t, reward in enumerate(data["reward"]):
...         predictions[t] = value
...         value += alpha * (reward - value)
...     return {"prediction": predictions, "dependent": predictions}
>>> parameters = Parameters(
...     alpha=Value(value=0.3, lower=0, upper=1, prior="uniform"),
...     value=0.0,
... )
>>> data = pd.DataFrame({"reward": [1, 1, 0, 1], "observed": [0.2, 0.5, 0.6, 0.4]})
>>> wrapper = SessionWrapper(model=model, data=data, parameters=parameters)
>>> wrapper.run()
>>> wrapper.dependent.ravel()
array([0.   , 0.3  , 0.51 , 0.357])

property session

The data as the model function takes them: the output of prepare, computed once.

property simulation

The outputs of each trial of the last run, as a list of dictionaries, as for a Wrapper.

run()

Run the model on all trials.

Returns:

None

reset(parameters=None, data=None)

Reset the model.

Parameters:

parametersdict, array_like, pd.Series or Parameters, optional

The parameters to reset the model with.

datapandas.DataFrame or dict, optional

New data for the model, which are passed through prepare once, when they are first needed.

Returns:

None

Notes

See Wrapper.reset.

export()

Export the trial-level output of the last run.

Returns:

pandas.DataFrame

One row per trial. An output with more than one value per trial is split into columns <key>_0, <key>_1, and so on.