PTSM#

class PTSM(data=None, parameters_settings=None, generate=False, utility_curve=None, weighting='tk')[source]#

Bases: Application

A simplified version of the Prospect Theory-based Softmax Model (PTSM) for decision-making tasks based on Tversky & Kahneman (1992), similar to the initial publication of the theory in Kahneman & Tversky (1979). It differs from cpm.applications.decision_making.PTSM2025 and cpm.applications.decision_making.PTSM1992 in that it does not use use different utility and weight curvature parameters for gains and losses.

Parameters:
datapd.DataFrame

The data, where each row is a trial and each column is an input to the model. Expected to have columns: ‘safe_magnitudes’, ‘risky_magnitudes’, ‘risky_probability’, ‘observed’.

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.

weightingstr

The probability weighting function to use. Options include:

  • “power”: use a simple power function (p^gamma)

  • “tk”: use the Tversky–Kahneman (1992) weighting function.

See cpm.models.activation.ProspectUtility for explanation and alternatives.

Returns:
cpm.generators.Wrapper

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

See also

cpm.models.decision.Softmax

for mapping utilities to choice probabilities.

cpm.models.activation.ProspectUtility

for the Prospect Utility class that computes subjective utilities and weighted probabilities.

Notes

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

  • alpha: [1.0, 1e-2, 5.0] (utility curvature for both gains and losses)

  • lambda_loss: [1.0, 1e-2, 5.0] (loss sensitivity)

  • gamma: [0.5, 1e-2, 5.0] (curvature for the weighting function for both gains and losses)

  • temperature: [5.0, 1e-2, 15.0] (temperature parameter for softmax)

The priors for the parameters are set as follows:

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

  • lambda_loss: truncated normal with mean 2.5 and standard deviation 1.0.

  • gamma: truncated normal with mean 2.5 and standard deviation 1.0.

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

Model Specification

The model computes the subjective utility of the safe and risky options 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\) after Tversky & Kahneman (1992):

\[\mathcal{U}(o) = \sum_{i=1}^{n} w(p_i) \cdot u(x_i)\]

where \(w\) is a weighting function of the probability p of a potential outcome, and \(u\) is the utility function of the magnitude x of a potential outcome. The choice options is denoted with \(o\). The utility function \(u\) is defined as a power function for both gains and losses. It is implemented after Equation 5 in Tversky & Kahneman (1992):

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

where \(\alpha\) is the utility curvature parameter for both gains and losses, and \(\lambda\) is the loss aversion parameter. The weighting function is implemented after Equation 6 in Tversky & Kahneman (1992):

\[w(p) = \frac{p^\gamma}{(p^\gamma + (1 - p)^\gamma)^{1/\gamma}}\]

where gamma, denoted via \(\gamma\), is the discriminability parameter of the weighting function for both gains and losses. The model then applies the softmax function to compute the choice probabilities:

\[p(o_i) = \frac{e^{\beta \cdot \mathcal{U}(o_i)}}{\sum_{j=1}^{n} e^{\beta \cdot \mathcal{U}(o_j)}}\]

Model output

The model outputs the following trial-level information:

  • policy: the softmax probabilities for each option.

  • dependent: the probability of choosing the risky option.

  • observed: the observed (participant’s) choice (0 for safe, 1 for risky).

  • chosen: the chosen option based on the softmax probabilities.

  • is_optimal: whether the chosen option is optimal (1 if chosen option is objectively better, 0 otherwise).

  • objective_best: the objectively better option (1 for risky, 0 for safe) determined by the objective evidence for each.

  • ev_safe: the expected value of the safe option.

  • ev_risk: the expected value of the risky option.

  • u_safe: the utility of the safe option.

  • u_risk: the utility of the risky option.

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

Kahneman, D., & Tversky, A. (1979). Prospect theory: An analysis of decision under risk. Econometrica, 47(2), 263–291.

Tversky, A., & Kahneman, D. (1992). Advances in prospect theory: Cumulative representation of uncertainty. Journal of Risk and uncertainty, 5, 297-323.

On this page