Skip to contents

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

hm1988.Rd

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.

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).

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.

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

Author

Jana B. Jarecki, jj@janajarecki.com

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
#> Optimal RSFT Model (Houston & McNamara, 1988) | choice rule: argmax
#> Call:
#> hm1988(formula = ~x1 + px11 + x2 + px12 + x3 + px13 | x1 + px21 +  ...
#> 
#> 
#> ---
#> Note:  No free parameters. No fixed parameter. 
predict(M)                 # Predict choice probability of 1st option (arg-max)
#>  [1] 0.5 0.0 1.0 1.0 0.0 1.0 1.0 1.0 1.0 1.0 1.0 1.0
predict(M, type="values")  # Predict expected values
#>        x1px1  x1px2
#>  [1,] 0.0000 0.0000
#>  [2,] 0.4100 0.4400
#>  [3,] 0.8310 0.7440
#>  [4,] 0.9654 0.9276
#>  [5,] 0.1000 0.4000
#>  [6,] 0.8600 0.7400
#>  [7,] 0.9780 0.9420
#>  [8,] 0.9970 0.9910
#>  [9,] 0.9000 0.6000
#> [10,] 0.9900 0.9600
#> [11,] 0.9990 0.9960
#> [12,] 0.9999 0.9996