Wrapper#

class Wrapper(model=None, data=None, parameters=None)[source]#

Bases: object

A Wrapper class for a model function in the CPM toolbox. It is designed to run a model for a single experiment (participant) and store the output in a format that can be used for further analysis.

Parameters:
modelfunction

The model function that calculates the output(s) of the model for a single trial. See Notes for more information. See Notes for more information.

datapandas.DataFrame or dict

If a pandas.DataFrame, it must contain information about each trial in the experiment that serves as an input to the model. Each trial is a complete row. If a dictionary, it must contains information about the each state in the environment or each trial in the experiment - all input to the model that are not parameters.

parametersParameters object

The parameters object for the model that contains all parameters (and initial states) for the model. See Notes on how it is updated internally.

Returns:
Wrapperobject

A Wrapper object.

Notes

The model function should take two arguments: parameters and trial. The parameters argument should be a Parameter object specifying the model parameters. The trial argument should be a dictionary or pd.Series containing all input to the model on a single trial. The model function should return a dictionary containing the model output for the trial. If the model is intended to be fitted to data, its output should contain the following keys:

  • ‘dependent’: Any dependent variables calculated by the model that will be used for the loss function.

If a model output contains any keys that are also present in parameters, it updates those in the parameters based on the model output.

run()[source]#

Run the model.

Returns:
None
reset(parameters=None, data=None)[source]#

Reset the model.

Parameters:
parametersdict, array_like, pd.Series or Parameters, optional

The parameters to reset the model with.

Returns:
None

Notes

When resetting the model, and parameters is None, reset model to initial state. After a run, resetting restores the values of all parameters and initial states to the ones the model was created with. The prior distributions and bounds are kept as they currently are, so that priors updated with Parameters.update_prior, for example by cpm.hierarchical, stay in effect. If parameter is array_like, it resets only the freely-varying parameters (those with a prior), matching elements to parameters in the order returned by Parameters.free(), so non-free attributes such as initial states can be declared in any order.

Examples

>>> x = Wrapper(model = mine, data = data, parameters = params)
>>> x.run()
>>> x.reset(parameters = [0.1, 1])
>>> x.run()
>>> x.reset(parameters = {'alpha': 0.1, 'temperature': 1})
>>> x.run()
>>> x.reset(parameters = np.array([0.1, 1, 0.5]))
>>> x.run()
export()[source]#

Export the trial-level simulation details.

Returns:
pandas.DataFrame

A dataframe containing the model output for each participant and trial. If the output variable is organised as an array with more than one dimension, the output will be flattened.

save(filename=None)[source]#

Save the model.

Parameters:
filenamestr

The name of the file to save the results to.

Returns:
None

Examples

>>> x = Wrapper(model = mine, data = data, parameters = params)
>>> x.run()
>>> x.save('simulation')

If you wish to save a file in a specific folder, provide the relative path.

>>> x.save('results/simulation')
>>> x.save('../archives/results/simulation')
connector(loss=None, prior=False)[source]#

A method to connect the model to an objective function. This method is used to create a parser function that can be used in third-party optimisation routine (e.g., scipy, pybads, genetic algorithms).

Parameters:
lossfunction

The loss function that is used to calculate the metric value.

priorbool, optional

If True, the prior distribution of the parameters is added to the metric value. Default is False.

Returns:
parserfunction

A function that takes a single argument pars, which is a one-dimensional array of parameters, where each element corresponds to the parameters as they were defined in the cpm.generators.Parameters.

Notes

The loss function should take the following named arguments:

  • predicted: The predicted values from the model.

  • observed: The observed values from the data.

It should return a single numeric value representing the loss.

See also