cpm.models#

The components that models are built from. Combine them inside a model function and pass that to Wrapper. Their formulas are in cpm.models.kernels, as functions that the classes compute with and that loops compiled with numba can call.

Learning rules#

`learning.DeltaRule`	DeltaRule class computes the prediction error for a given input and target value.
`learning.SeparableRule`	A class representing a learning rule based on the separable error-term of Bush and Mosteller (1951).
`learning.QLearningRule`	Q-learning rule (Watkins, 1989) for a one-dimensional array of Q-values.
`learning.HumbleTeacher`	A humble teacher learning rule (Kruschke, 1992; Love, Gureckis, and Medin, 2004) for multi-dimensional outcome learning.
`learning.SARSATrace`	SARSA learning rule with an eligibility trace for a two-stage Markov decision task (Sutton & Barto, 2018; Kool et al., 2016).

Decision rules#

`decision.Softmax`	Softmax class for computing policies based on activations and temperature (Bridle, 1990).
`decision.Sigmoid`	A class representing a sigmoid function that takes an n by m array of activations and returns an n array of outputs, where n is the number of output and m is the number of inputs.
`decision.GreedyRule`	A class representing an ε-greedy rule based on Daw et al. (2006).
`decision.ChoiceKernel`	A class representing a choice kernel based on a softmax function that incorporates the frequency of choosing an action.

Activation functions#

`activation.SigmoidActivation`	Represents a sigmoid activation function.
`activation.CompetitiveGating`	A competitive attentional gating function, an attentional activation function, that incorporates stimulus salience in addition to the stimulus vector to modulate the weights.
`activation.ProspectUtility`	A class for computing choice utilities based on prospect theory.
`activation.Offset`	A class for adding a scalar to one element of an input array.

Attention#

attention.RapidAttentionShift

RapidAttentionShift implements the rapid attention shift from models such as EXIT (Kruschke, 2001) and its simplified version (Paskewitz & Jones, 2020).

Utilities#

utils.Nominal

Converts a target value to a binary representation using a specified number of bits.

Kernels for compiled models#

The computations of the building blocks in cpm.models, as functions.

The classes in cpm.models.decision, cpm.models.learning, cpm.models.activation and cpm.models.attention compute one step of a model and are convenient to write per-trial models with. Their formulas live here, once, as functions on numpy arrays and numbers, and the classes compute with them: each class converts and checks its input, calls the function it is named after, and keeps the result in its attributes.

The functions are written with numpy operations that numba can also compile, so that loops over trials that are compiled as a whole, such as the models of the built-in applications (see cpm.generators.SessionWrapper), can call them too. With numba installed, the functions of this module are compiled on first use (and cached on disk); the classes use a plain-Python copy of them (see cpm.core._jit.kernels), which never needs numba. Both give the same results.

logistic, p_second, log_softmax and choose have no class counterpart: they are for compiled loops. The softmax switches to an equivalent form that cannot overflow where the largest scaled activation is beyond ±700; logistic and p_second cannot overflow.

Functions that update values in place say so; all others return new arrays.

Examples#

A Rescorla-Wagner learner with a softmax policy, compiled as a whole:

>>> import numpy as np
>>> from numba import njit
>>> from cpm.models import kernels
>>> @njit
... def session(alpha, beta, rewards, choices):
...     values = np.zeros(2)
...     p_right = np.empty(len(choices))
...     for t in range(len(choices)):
...         p_right[t] = kernels.p_second(beta, values[0], values[1])
...         values[choices[t]] += alpha * (rewards[t] - values[choices[t]])
...     return p_right
>>> session(0.3, 2.0, np.array([1.0, 0.0, 1.0]), np.array([1, 1, 0]))
array([0.5       , 0.64565631, 0.60348325])

`softmax`	The softmax policy, \(e^{\beta x_i} / \sum_j e^{\beta x_j}\), of `cpm.models.decision.Softmax`.
`log_softmax`	The logarithm of `softmax`, computed without forming the probabilities.
`p_second`	The probability of the second of two options under a softmax.
`logistic`	The logistic function, 1 / (1 + exp(-x)), without overflow.
`irreducible_noise`	A policy with irreducible noise `xi`, as `Softmax.irreducible_noise` computes it.
`softmax_noise`	The softmax with irreducible noise, as `Softmax.irreducible_noise`.
`sigmoid`	The policy of `cpm.models.decision.Sigmoid` (`Sigmoid(temperature, activations, beta=bias)`).
`greedy`	The policy of `cpm.models.decision.GreedyRule`.
`choice_kernel`	The policy of `cpm.models.decision.ChoiceKernel`.
`choose`	Sample an option from a policy, given a uniform random number in [0, 1).
`delta_rule`	The change in the weights and the prediction errors of `cpm.models.learning.DeltaRule`.
`separable_rule`	The change in the weights and the prediction errors of `cpm.models.learning.SeparableRule`.
`q_learning`	The updated values of `cpm.models.learning.QLearningRule`.
`humble_teacher_change`	The change in the weights of `cpm.models.learning.HumbleTeacher`.
`humble_teacher`	The updated weights (a new array) of `cpm.models.learning.HumbleTeacher`.
`sarsa_trace`	The prediction errors and value changes of `cpm.models.learning.SARSATrace`.
`sarsa_trace_update`	`sarsa_trace`, applied to the values in place.
`sigmoid_activation`	The activations of `cpm.models.activation.SigmoidActivation`.
`gating_gain`	The normalised attentional gain of `cpm.models.activation.CompetitiveGating`.
`gate`	The values of each stimulus scaled by its attentional gain (a new array).
`competitive_gating`	The gated values (a new array) of `cpm.models.activation.CompetitiveGating`.
`prospect_utility`	The power utility of `ProspectUtility`: \(x^\alpha\) for gains, \(-\lambda (-x)^\beta\) for losses.
`prospect_weight`	The decision weights of outcomes, as `ProspectUtility` computes them.
`weight_tk`	The Tversky & Kahneman (1992) weighting function with curvature `power`.
`weight_power`	The power weighting function, p^gamma.
`weight_prelec`	The Prelec (1998) weighting function.
`weight_gw`	The Gonzalez & Wu (1999) weighting function.
`expected_utility`	The expected utility of each option: the sum of its weighted utilities.
`add_offset`	Add `offset` to element `index` of `array`, in place, as `cpm.models.activation.Offset` does.
`offset`	The output of `cpm.models.activation.Offset`: a copy of `input` with `offset` added to element `index`.
`rapid_attention_shift`	The change in the attention gain of `cpm.models.attention.RapidAttentionShift`.