adopy.tasks.psi

../../_images/Psychometricfn.svg

Psychometric function is to figure out whether a subject can perceive a signal with varying levels of magnitude. The function has one design variable for the intensity of a stimulus, \(x\); the model has four model parameters: guess rate \(\gamma\), lapse rate \(\delta\), threshold \(\alpha\), and slope \(\beta\).

Task

class adopy.tasks.psi.Task2AFC

Bases: adopy.base._task.Task

The Task class for a simple 2-Alternative Forced Choice (2AFC) task with a single design variable, the magnitude of a stimulus.

Design variables
  • stimulus (\(x\)) - magnitude of a stimulus

Responses
  • choice (\(y\)) - index of the chosen option

Examples

>>> from adopy.tasks.psi import Task2AFC
>>> task = Task2AFC()
>>> task.designs
['stimulus']
>>> task.responses
[0, 1]

A task object stores information for a specific experimental task, including labels of design variables (designs), possible responses (responses) and its name (name).

Parameters
  • designs – Labels of design variables in the task.

  • responses – Labels of response variables in the task (e.g., choice, rt).

  • name – Name of the task.

Examples

>>> task = Task(name='Task A',
...             designs=['d1', 'd2'],
...             responses=['choice'])
>>> task
Task('Task A', designs=['d1', 'd2'], responses=['choice'])
>>> task.name
'Task A'
>>> task.designs
['d1', 'd2']
>>> task.responses
['choice']

Model

class adopy.tasks.psi.ModelLogistic

Bases: adopy.tasks.psi._ModelPsi

The psychometric function using logistic function.

\[\begin{split}\begin{align} F(x; \alpha, \beta) &= \frac{1}{1 + \exp\left(-\beta (x - \mu) \right)} \\ \Psi \left( x \mid \alpha, \beta, \gamma, \delta \right) &= \gamma + (1 - \gamma - \delta) \cdot F(x; \alpha, \beta) \end{align}\end{split}\]
Model parameters
  • threshold (\(\alpha\)) - indifference point where the probability of a positive response equals to 0.5.

  • slope (\(\beta\)) - slope of a tangent line on the threshold point (\(\beta > 0\))

  • guess_rate (\(\gamma\)) - leftward asymptote of the psychometric function (\(0 < \gamma < 1\))

  • lapse_rate (\(\delta\)) - rightward asymptote of the psychometric function(\(0 < \delta < 1\))

Examples

>>> from adopy.tasks.psi import ModelLogistic
>>> model = ModelLogistic()
>>> model.task
Task('2AFC', designs=['stimulus'], responses=[0, 1])
>>> model.params
['threshold', 'slope', 'guess_rate', 'lapse_rate']
compute(choice, stimulus, guess_rate, lapse_rate, threshold, slope)

Compute log likelihood of obtaining responses with given designs and model parameters. If the likelihood function is not given for the model, it returns a random log probability.

Deprecated since version 0.4.0: As the Model class get modified to contain a function for log likelihood in 0.4.0, we recommend you to use model.compute_log_lik() function instead so to make it clear what the function calculates.

class adopy.tasks.psi.ModelWeibull

Bases: adopy.tasks.psi._ModelPsi

The psychometric function using log Weibull (Gumbel) cumulative distribution function.

\[\begin{split}\begin{align} F(x; \mu, \beta) &= CDF_\text{Gumbel_l} \left( \beta (x - \mu) \right) \\ \Psi \left( x \mid \alpha, \beta, \gamma, \delta \right) &= \gamma + (1 - \gamma - \delta) \cdot F(x; \alpha, \beta) \end{align}\end{split}\]
Model parameters
  • threshold (\(\alpha\)) - indifference point where the probability of a positive response equals to 0.5.

  • slope (\(\beta\)) - slope of a tangent line on the threshold point (\(\beta > 0\))

  • guess_rate (\(\gamma\)) - leftward asymptote of the psychometric function (\(0 < \gamma < 1\))

  • lapse_rate (\(\delta\)) - rightward asymptote of the psychometric function(\(0 < \delta < 1\))

Examples

>>> from adopy.tasks.psi import ModelLogistic
>>> model = ModelLogistic()
>>> model.task
Task('2AFC', designs=['stimulus'], responses=[0, 1])
>>> model.params
['threshold', 'slope', 'guess_rate', 'lapse_rate']
compute(choice, stimulus, guess_rate, lapse_rate, threshold, slope)

Compute log likelihood of obtaining responses with given designs and model parameters. If the likelihood function is not given for the model, it returns a random log probability.

Deprecated since version 0.4.0: As the Model class get modified to contain a function for log likelihood in 0.4.0, we recommend you to use model.compute_log_lik() function instead so to make it clear what the function calculates.

class adopy.tasks.psi.ModelProbit

Bases: adopy.tasks.psi._ModelPsi

The psychometric function using Probit function (Normal cumulative distribution function).

\[\begin{split}\begin{align} F(x; \mu, \beta) &= CDF_\text{Normal} \left( \beta (x - \mu) \right) \\ \Psi \left( x \mid \alpha, \beta, \gamma, \delta \right) &= \gamma + (1 - \gamma - \delta) \cdot F(x; \alpha, \beta) \end{align}\end{split}\]
Model parameters
  • threshold (\(\alpha\)) - indifference point where the probability of a positive response equals to 0.5.

  • slope (\(\beta\)) - slope of a tangent line on the threshold point (\(\beta > 0\))

  • guess_rate (\(\gamma\)) - leftward asymptote of the psychometric function (\(0 < \gamma < 1\))

  • lapse_rate (\(\delta\)) - rightward asymptote of the psychometric function(\(0 < \delta < 1\))

Examples

>>> from adopy.tasks.psi import ModelProbit
>>> model = ModelProbit()
>>> model.task
Task('2AFC', designs=['stimulus'], responses=[0, 1])
>>> model.params
['threshold', 'slope', 'guess_rate', 'lapse_rate']
compute(choice, stimulus, guess_rate, lapse_rate, threshold, slope)

Compute log likelihood of obtaining responses with given designs and model parameters. If the likelihood function is not given for the model, it returns a random log probability.

Deprecated since version 0.4.0: As the Model class get modified to contain a function for log likelihood in 0.4.0, we recommend you to use model.compute_log_lik() function instead so to make it clear what the function calculates.

Engine

class adopy.tasks.psi.EnginePsi(model, grid_design, grid_param, d_step=1)

Bases: adopy.base._engine.Engine

The Engine class for the psychometric function estimation. It can be only used for Task2AFC.

property d_step

Step size on index to compute \(\Delta\) for the staircase method.

get_design(kind='optimal')

Choose a design with a given type.

  • optimal: an optimal design \(d^*\) that maximizes the information for fitting model parameters.

  • staircase: Choose the stimulus \(s\) as below:

    \[\begin{split}x_t = \begin{cases} x_{t-1} - \Delta & \text{if } y_{t-1} = 1 \\ x_{t-1} + 2 \Delta & \text{if } y_{t-1} = 0 \end{cases}\end{split}\]

    where \(\Delta\) is determined by d_step which is the step-size change on the grid index.

  • random: a design randomly chosen.

Parameters

kind ({‘optimal’, ‘staircase’, ‘random’}, optional) – Type of a design to choose

Returns

design – A chosen design vector