cpm.generators

`cpm.generators.Value(value=None, lower=0, upper=1, prior=None, args=None, **kwargs)`

The Value class is a wrapper around a float value, with additional details such as the prior distribution, lower and upper bounds. It supports all basic mathematical operations and can be used as a regular float with the parameter value as operand.

Parameters:

Name	Type	Description	Default
`value`	`float`	The value of the parameter.	`None`
`lower`	`float, optional`	The lower bound of the parameter.	`0`
`upper`	`float, optional`	The upper bound of the parameter.	`1`
`prior`	`string or object, optional`	If a string, it should be one of continuous distributions from `scipy.stats`. See the scipy documentation for more details. The default is None. If an object, it should be or contain a callable function representing the prior distribution of the parameter with methods similar to `scipy.stats` distributions. See Notes for more details.	`None`
`args`	`dict, optional`	A dictionary of arguments for the prior distribution function.	`None`

Notes

We currently implement the following continuous distributions from scipy.stats corresponding to the prior argument:

'uniform'
'truncated_normal'
'beta'
'gamma'
'truncated_exponential'
'norm'

Because these distributions are inherited from scipy.stats, see the scipy documentation for more details on how to update variables of the distribution.

Returns:

Type	Description
`Value`	A Value object, where each attribute is one of the arguments provided for the function. It support all basic mathematical operations and can be used as a regular float with the parameter value as operand.

`PDF(log=False)`

Return the prior distribution of the parameter.

Returns:

Type	Description
`float`	The probability of the parameter value under the prior distribution. If `log` is True, the log probability is returned.

`copy()`

Return a copy of the parameter.

Returns:

Type	Description
`Value`	A copy of the parameter.

`fill(value)`

Replace the value of the parameter with a new value.

Parameters:

Name	Type	Description	Default
`value`	`float or array_like`	The new value of the parameter.	required

Notes

If the parameter is an array, it should be a list of values. If the parameter is an array, and the new value is a single value, it will be broadcasted to the shape of the array.

`sample(size=1, jump=False)`

Sample and update the parameter value from its prior distribution.

Returns:

Name	Type	Description
`sample`	`float`	A sample from the prior distribution of the parameter.

`update_prior(**kwargs)`

Update the prior distribution of the parameter. Currently it is only implemented for truncated normal distributions.

Parameters:

Name	Type	Description	Default
`**kwargs`	`dict`	Keyword arguments representing the parameters of the prior distribution. If you are unsure what the names are for the parameters of the prior distribution, you can check the `scipy.stats` documentation or the `prior.kwds` attribute.	`{}`

`cpm.generators.Parameters(**kwargs)`

A class representing a set of parameters. It takes keyword arguments representing the parameters with their values and wraps them into a python object.

Parameters:

Name	Type	Description	Default
`**kwargs`	`dict`	Keyword arguments representing the parameters.	`{}`

Returns:

Type	Description
`Parameters`	A Parameters object, where each attributes is one of the keyword arguments provided for the function wrapped by the Value class.

Examples:

>>> from cpm.generators import Parameters
>>> parameters = Parameters(a=0.5, b=0.5, c=0.5)
>>> parameters['a']
0.1
>>> parameters.a
0.1
>>> parameters()
{'a': 0.1, 'b': 0.2, 'c': 0.5}

The Parameters class can also provide a prior.

>>> x = Parameters(
>>>    a=Value(value=0.1, lower=0, upper=1, prior="normal", args={"mean": 0.5, "sd": 0.1}),
>>>    b=0.5,
>>>    weights=Value(value=[0.1, 0.2, 0.3], lower=0, upper=1, prior=None),
>>> )

>>> x.prior(log=True)
-6.5854290732499186

We can also sample new parameter values from the prior distributions.

>>> x.sample()
{'a': 0.4670755733417274, 'b': 0.30116207009111917}

`PDF(log=False)`

Return the prior probability density of the parameter values.

Returns:

Type	Description
`float`	The summed probability density of the parameter set under the prior distribution for each parameter. If `log` is True, the log probability is returned. When the PDF is 0, it returns the smallest positive float value. If `log` is True and the log probability is negative infinity, it returns the most negative float value.

`bounds()`

Returns a tuple with lower (first element) and upper (second element) bounds for parameters with defined priors.

Returns:

Type	Description
`lower, upper`	A tuple of lower and upper parameter bounds

`free()`

Return a dictionary of all parameters with a prior distribution.

Returns:

Name	Type	Description
`free`	`dict`	A dictionary of all parameters with a prior distribution.

`keys()`

Return a list of all the keys in the parameters dictionary.

Returns:

Name	Type	Description
`keys`	`list`	A list of all the keys in the parameters dictionary.

`sample(size=1, jump=False)`

Sample and update parameter values from their prior distribution.

Returns:

Name	Type	Description
`sample`	`dict`	A dictionary of the sampled parameters.

`update(**kwargs)`

Update the parameters with new values.

Parameters:

Name	Type	Description	Default
`**kwargs`	`dict`	Keyword arguments representing the parameters.	`{}`

`update_prior(**kwargs)`

Update the prior distribution of all parameters.

Parameters:

Name	Type	Description	Default
`**kwargs`	`dict`	Keyword arguments representing the parameters of the prior distribution. For each parameter, the keyword should be the name of the parameter and the value should be a dictionary of the parameters of the prior distribution. If you are unsure what the names are for the parameters of the prior distribution, you can check the `scipy.stats` documentation or the `prior.kwds` attribute.	`{}`

`cpm.generators.Wrapper(model=None, data=None, parameters=None)`

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:

Name	Type	Description	Default
`model`	`function`	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.	`None`
`data`	`pandas.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.	`None`
`parameters`	`Parameters 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.	`None`

Returns:

Name	Type	Description
`Wrapper`	`object`	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.

Information on how to compile the model can be found in the [Tutorials - Build your model][/tutorials/defining-model] module.

`export()`

Export the trial-level simulation details.

Returns:

Type	Description
`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.

`reset(parameters=None, data=None)`

Reset the model.

Parameters:

Name	Type	Description	Default
`parameters`	`dict, array_like, pd.Series or Parameters, optional`	The parameters to reset the model with.	`None`

Notes

When resetting the model, and parameters is None, reset model to initial state. If parameter is array_like, it resets the only the parameters in the order they are provided, where the last parameter updated is the element in parameters corresponding to len(parameters).

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()

Returns:

Type	Description
`None`

`run()`

Run the model.

Returns:

Type	Description
`None`

`save(filename=None)`

Save the model.

Parameters:

Name	Type	Description	Default
`filename`	`str`	The name of the file to save the results to.	`None`

Returns:

Type	Description
`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')

`cpm.generators.Simulator(wrapper=None, data=None, parameters=None)`

A Simulator class for a model in the CPM toolbox. It is designed to run a model for multiple participants and store the output in a format that can be used for further analysis.

Parameters:

Name	Type	Description	Default
`wrapper`	`Wrapper`	An initialised Wrapper object for the model.	`None`
`data`	`pandas.core.groupby.generic.DataFrameGroupBy or list of dictionaries`	The data required for the simulation. If it is a pandas.core.groupby.generic.DataFrameGroupBy, as returned by `pandas.DataFrame.groupby()`, each group must contain the data (or environment) for a single participant. If it is a list of dictionaries, each dictionary must contain the data (or environment) for a single participant.	`None`
`parameters`	`Parameters, pd.DataFrame, pd.Series or list`	The parameters required for the simulation. It can be a Parameters object or a list of dictionaries whose length is equal to data. If it is a Parameters object, Simulator will use the same parameters for all simulations. It is a list of dictionaries, it will use match the parameters with data, so that for example parameters[6] will be used for the simulation of data[6].	`None`

Returns:

Name	Type	Description
`simulator`	`Simulator`	A Simulator object.

`export()`

Return the trial- and participant-level information about the simulation.

Returns:

Type	Description
`pandas.DataFrame`	A dataframe containing the 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.

`generate(variable='dependent')`

Generate data for parameter recovery, etc.

Parameters:

Name	Type	Description	Default
`variable`		Name of the variable to pull out from model output.	`'dependent'`

`reset()`

Resets the simulation.

`run()`

Runs the simulation.

`save(filename=None)`

Saves the simulation results.

Parameters:

Name	Type	Description	Default
`filename`	`str`	The name of the file to save the results to.	`None`

`update(parameters=None)`

Updates the parameters of the simulation.