hm1988: Dynamic optimization model for risk-sensitive foraging...

In JanaJarecki/cogscimodels: Cognitive Models - Estimation, Prediction, and Development of Models for Cognitive Scientists

Dynamic optimization model for risk-sensitive foraging problems in discrete time

Description

hm1988() generates Houston & McNamara's (1988) optimal model for risk-sensitive foraging with discrete choices.

Usage

hm1988(
  formula,
  trials,
  states,
  budget,
  ntrials,
  initstate = 0,
  data = NULL,
  choicerule = "argmax",
  fix = list(),
  options = NULL,
  fitnessfun = NULL
)

Arguments

formula	A formula, the variables in data to be modeled. For example, y ~ x1 + p2 + x3 + p4 | x5 + p6 + x7 + p8 models response y as function of two stimuli with features x1, p2, x3, p4 and x5, p6, x7, p8, alternating outcomes x and probabilities p (respectively). Lines | separate stimuli.
trials	The variable in data with the decision trial, can be a number, numeric vector, string, formula, or ".ALL". Vectors must have length nrow(data). If ".ALL" the model predicts for all possible trials and states.
states	The variable in data with the states/accumulated resources, can be a number, numeric vector, string, formula, or ".ALL". Vectors must have length nrow(data). If ".ALL" the model predicts for all possible trials and states.
budget	A number; the goal/requirement/critical state, that matters in the terminal payout function. Can also be a numeric vector of length nrow(data), or a right-side formula that refers to a variable in data.
ntrials	A number; the total number of trials available. Can also be a numeric vector of length nrow(data), or a right-side formula that refers to a variable in data.
initstate	(default 0) A number; the starting state in the first trial. Can also be a numeric vector of length nrow(data), or a right-side formula that refers to a variable in data.
data	A data frame, the data to be modeled.
choicerule	A string, the choice rule. Allowed values, see cm_choicerules(): "none" is no choice rule, "softmax" is soft-maximum, "luce" is Luce's axiom.
fix	(optional, only for choicerule softmax, epsilon) A list with parameter-value pairs of fixed parameters. If missing all free parameters are estimated. If set to "start" all parameters are fixed to their start values. Model parameter names depend on choicerule and can be tau, eps (see details - model parameters). list(tau = 6.16) sets parameter tau equal to 6.16. "start" sets all parameters equal to their initial values (estimates none). Useful for building a first test model.
options	(optional) A list, list entries change the modeling procedure. For example, list(lb = c(k=0)) changes the lower bound of parameter k to 0, or list(fit_measure = "mse") changes the goodness of fit measure in parameter estimation to mean-squared error, for all options, see cm_options.
fitnessfun	(optional) A function, the terminal fitness function, needs two arguments, budget and state.
discount	A number, how many initial trials to not use during parameter fitting.
...	other arguments, ignored.

Details

Risk-sensitive foraging means you have, for instance, four choices between the same two risky lotteries and after the four choices you need to have accumulated at least 12 points to get a reward. The optimal solution to this choice problem relies on dynamic programming. The function creates all possible future states given the possible remaining trials, and predicts the optimal choice polica or the expected value of chosing either option given a certain state and a certain time horizon.

Model Parameters

The model has no free parameters. If choicerule is specified, it can estimate 1 free parameter: If choicerule = "softmax": tau is the temperature or choice softness, higher values cause more equiprobable choices. If choicerule = "epsilon": eps is the error proportion, higher values cause more errors from maximizing.

Value

Returns a cognitive model object, which is an object of class cm. A model, that has been assigned to m, can be summarized with summary(m) or anova(m). The parameter space can be viewed using pa. rspace(m), constraints can be viewed using constraints(m).

Author(s)

Jana B. Jarecki, [e-mail]

References

Houston, A. I., & McNamara, J. M. (1988). A framework for the functional analysis of behaviour. Behavioural and Brain Science, 11, 117-163. doi:10.1017/S0140525X00053061

See Also

Other cognitive models: baseline_const_c(), bayes(), choicerules, cpt, ebm(), shift(), shortfall, threshold(), utility

Examples

## Make fake data -----------------------------------------------------
D <- data.frame(
  x1 = 0, x2 = 1, x3 = 2,
  px11 = 0.1, px12 = 0.8, px13 = 0.1,
  px21 = 0.4, px22 = 0.2, px23 = 0.4,
  s = rep(9:11, each = 4),
  init = rep(9:11, each = 4), t = 4:1)

## Setup the model --------------------------------------------------
M <- hm1988(~ x1+px11+x2+px12+x3+px13 | x1+px21+x2+px22+x3+px23,
             trials = ~t, states = ~s, budget = 12, ntrials = 4,
             initstate = ~init, data = D, choicerule = "argmax")

M                          # View model
predict(M)                 # Predict choice probability of 1st option (arg-max)
predict(M, type="values")  # Predict expected values

JanaJarecki/cogscimodels documentation built on Nov. 4, 2022, 5:33 p.m.