PTSM2025#

class PTSM2025(data=None, parameters_settings=None, utility_curve=None, variant='alpha')[source]#

Bases: Application

An Prospect Theory Softmax Model loosely based on Chew et al. (2019), incorporating a bias term (phi_gain / phi_loss) in the softmax function for risks and gains, a utility curvature parameter (alpha) for non-linear utility transformations, and an ambiguity aversion parameter (eta).

Parameters:
datapd.DataFrame, optional

Data containing the trials to be modeled, where each row represents a trial in the experiment (a state), and each column represents a variable (e.g., safe_magnitudes, risky_magnitudes, risky_probability, ambiguity, observed variable).

parameters_settingsdict, optional

A dictionary containing the initial values and bounds for the model parameters. Each key must correspond to the name of the parameter, and contain a list in the form of [initial, lower_bound, upper_bound]. If not provided, default values are used. See Notes.

utility_curvecallable(), optional

A callable function that defines the utility curve. If provided, it overrides the default power function used for utility transformations. Its first argument should be the magnitude, and the second argument should be the curvature parameter (alpha). If None, a power function is used, see Notes.

variantstr, optional

The variant of the model to use. Options are “alpha” for the full model with a non-linear curvature or “standard” for a simplified version without curvature. Default is “alpha”.

Returns:
cpm.generators.Wrapper

An instance of the PTSM2025 model, which can be used to fit data and generate predictions.

Notes

The model parameters are initialized with the following default values if not specified (values are in the form [initial, lower_bound, upper_bound]):

  • eta: [0.0, -0.49, 0.49] (ambiguity aversion)

  • phi_gain: [0.0, -10.0, 10.0] (gain sensitivity)

  • phi_loss: [0.0, -10.0, 10.0] (loss sensitivity)

  • temperature: [5.0, 0.001, 20.0] (temperature parameter)

  • alpha: [1.0, 0.001, 5.0] (utility curvature parameter)

The priors for the parameters are set as follows:

  • eta: truncated normal with mean 0.0 and standard deviation 0.25.

  • phi_gain: truncated normal with mean 0.0 and standard deviation 2.5.

  • phi_loss: truncated normal with mean 0.0 and standard deviation 2.5.

  • temperature: truncated normal with mean 10.0 and standard deviation 5.

  • alpha: truncated normal with mean 1.0 and standard deviation 1.

Model Description

In what follows, we briefly describe the model’s operations. First, the model calculates the subjective probability of the risky option, adjusting for ambiguity aversion using the parameter eta, denoted with \(\eta\). The subjective probability is computed as:

\[p_{subjective} = p_{risky} - \eta \cdot ambiguity\]

where \(p_{risky}\) is the original probability of the risky choice and \(ambiguity\) is the ambiguity associated with the risky option, either 0 for non-ambiguous or 1 for ambiguous cases. The utility of the safe and risky options is then computed using a utility function, which can be either a power function or a user-defined utility curve. If a utility curve is not provided, the model uses the following power function with curvature parameter alpha, denoted with \(\alpha\):

\[\begin{split}u(x) = \begin{cases} x^\alpha & \text{if } x \geq 0 \\ -|x|^\alpha & \text{if } x < 0 \end{cases}\end{split}\]

The model then applies loss aversion and gain sensitivity adjustments based on the sign of the risky choice magnitude. Here, the gain sensitivity phi_gain, denoted as \(\phi_{gain}\), is applied when the risky choice is positive, and the loss sensitivity phi_loss, denoted as \(\phi_{loss}\), is applied when the risky choice is negative. The adjusted probability of choosing the risky option, \(p(A_{risky})\), is computed using a softmax function:

\[p(A_{risky}) = \frac{e^{\beta (u_{risky} + \phi_{t})}}{e^{\beta (u_{risky} + \phi_{t})} + e^{\beta u_{safe}}}\]

where denoted with \(\beta\) is the temperature parameter, \(u_{risky}\) is the utility of the risky option, \(u_{safe}\) is the utility of the safe option, and \(\phi_{t}\) is either \(\phi_{gain}\) or \(\phi_{loss}\) depending on the sign of the risky choice magnitude. Note that in Chew et al. (2019), the model only has a gambling bias term for the gain loss, that is then added to the difference between the safe and risky utilities, and only then transformed to a probability via a sigmoid function.

Furthermore, the model generates a response based on the computed probabilities, where the choice is sampled from a Bernoulli distribution with the computed policy as the probability of choosing the risky option.

Model Output

For each trial, the model outputs the following variables:

  • policy: The computed probabilities for the risky options.

  • model_choice: The model’s predicted choice (0 for safe, 1 for risky).

  • real_choice: The observed (participant’s) choice from the data.

  • u_safe: The utility of the safe option.

  • u_risk: The utility of the risky option.

  • dependent: The computed probability of a risky choice according to the model, which can be used for further analysis or fitting

Details for fitting the model to data

The model uses a softmax function to map the computed utilities to choice probabilities, with a temperature parameter that controls the stochasticity of the choices. Exponential functions, depending on the temperature parameter, can get out of hand quickly, so it is advisable to keep the temperature parameter within reasonable bounds (e.g., between 0.001 and 20.0).

If you get overflow warnings during fitting, consider lowering the upper bound of the temperature parameter. Another possible reason for these overflow warnings is that the computed utilities are very large in magnitude. Ensure that the magnitudes in your dataset are within a reasonable range (e.g., between 0 and 1, or -1 and 1). Another option is to z-score the utilities before passing them to the softmax function, which can help stabilize the exponentials.

Computation

The model computes all trials of a participant in one call, compiled with numba if numba is installed (pip install cpm-toolbox[numba]) and as plain Python otherwise, with the same results. model is the model function for a single trial, model(parameters, trial), which returns the outputs of that trial.

References

Chew, B., Hauser, T. U., Papoutsi, M., Magerkurth, J., Dolan, R. J., & Rutledge, R. B. (2019). Endogenous fluctuations in the dopaminergic midbrain drive behavioral choice variability. Proceedings of the National Academy of Sciences, 116(37), 18732–18737. https://doi.org/10.1073/pnas.1900872116

On this page