The R6 class underlying all "cm" (cognitive model) objects 'Cm$new(formula, data, parspace)'

The R6 class underlying all "cm" (cognitive model) objects 'Cm$new(formula, data, parspace)'

The R6 class underlying all "cm" (cognitive model) objects 'Cm$new(formula, data, parspace)'

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

parspace. It is optional to define a value that makes the parameter have zero effect in the column called "na" in parspace. For example, a parameter b in b*x, has no-effect when setting b=0. The no-effect value can be NA.

fix Supplying list(alpha=0.5, beta="alpha", gamma=NA) constrains the parameters alpha, beta, and gamma as follows

• alpha=0.5: fix alpha to 0.5.

• beta="alpha": fix beta to the value of alpha; alpha may be a free or fixed model parameter in parspace.

• delta=NA: ignore delta if it can be ignored by setting delta equal to the value in the column "na" of parspace, given that parspace has a value in the column "na" for delta.

You can ignore a model parameter by setting it to NA in 'fix', in this case your 'parspace' needs to contain a value in the column na nullifying the effect of the parameter.

See also

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

Author

Jana B. Jarecki, jj@janajarecki.com

Public fields

call

The call to the model

title

A string, the name of the model

formula

Calling formula, e.g., y ~ x1 + x2 + x3 models one response variable (y) given one three-attribute stimulus, and y ~ x1 + x2 | z1 + z2 models a response given two two-attribute stimuli where attributes are separated by a "+"" and stimuli are separated by a "|".

input

Inputs to the model in a standardized form: three-dimensional matrix based on formula and data with dimensions n(data) x n(attributes) x n(stimuli)

more_input

Additional inputs to the model from variables that are not part of the formula, three-dimensional matrix with dimensions n(data) x n(additional inputs) x n(stimuli)

res

The response variable to be modeled, two-dimensional matrix with dimensions n(data) x n(response variables)

natt

List with the number of attributes per stimulus

nobs

Number of observations in data

nstim

Number of stimuli in model input

nres

Number of response variables

ncon

Number of constraints on the parameter

par

Model parameters, a named list

fix

Fixed model parameters, a named list

parspace

Parameter space, a matrix with one parameter per row, and four columns lb (lower bound), ub (upper bound), start (starting value for fitting) and na (value of the parameter if it has no effect on the model); rownames are parameter names

pred

Model predictions for data

parnames

Parameter names

stimnames

Stimuli names

prednames

Prediction column names if > 1 prediction

mode

A string the modality of the predicted responses "continuous" or "discrete"

choicerule

A string with the choicerule that the model uses (e.g. "softmax"")

pred_types

The types of predictios the model males

discount

A numeric with trials to discount when fitting

constraints

An object with the parameter constraints

fitobj

An object holding the results of the parameter fitting method

options

A list with options

pass_checks

A logical, TRUE means the model passes all internal checks

Methods

Public methods

• Cm$new()

• Cm$fit()

• Cm$coef()

• Cm$predict()

• Cm$simulate()

• Cm$set_data()

• Cm$set_par()

• Cm$get_par()

• Cm$npar()

• Cm$gof()

• Cm$logLik()

• Cm$BIC()

• Cm$AIC()

• Cm$AICc()

• Cm$MSE()

• Cm$SSE()

• Cm$RMSE()

• Cm$set_lb()

• Cm$set_ub()

• Cm$set_start()

• Cm$print()

• Cm$summary()

• Cm$pargrid()

• Cm$getCall()

• Cm$clone()

---

Method new()

Initializes a new model

Usage

Cm$new(
  formula,
  data = NULL,
  parspace = make_parspace(),
  fix = NULL,
  choicerule = if (grepl("^c", mode)) {     "none" } else {     NULL },
  title = NULL,
  discount = NULL,
  mode = NULL,
  options = NULL
)

Arguments

formula

A formula, the variables in data to be modeled. For example, y ~ x1 + x2 models response y as function of one stimulus with features x1, x2.

data

A data frame, the data to be modeled.

parspace

(optional, required to add model parameters) A n x 4 matrix, the parameter space. Use make_parspace to construct it. Column names must be "lb","ub","start","na", row names must be parameter names. Columns contain the lower limit, upper limit, starting value in fitting, and (optional) a value that makes a parameter have zero effect, which can be NA. See details.

fix

(optional) 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 formula and can be delta, x1, x2 (see details - model parameters).

• list(x1 = 3.09) sets parameter x1 equal to 3.09.

• list(x1 = "x2") sets parameter x1 equal to parameter x2 (estimates x2).

• list(x2 = "x1", x1 = 3.09) sets parameter x2 equal to parameter x1 and sets x1 equal to 3.09 (estimates none of the two).

• list(x1 = NA) omits the parameter x1, if possible.

• "start" sets all parameters equal to their initial values (estimates none). Useful for building a first test model.

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.

title

(optional, default is the class name) A string, the model's name.

discount

(optional) A number, e.g. 10 ignores the first ten data rows when fitting parameters and when calculating goodness of fits

discount

(optional) An integer or integer vector (default 0), ddefining which or how many, starting from trial 1, to discount when fitting.

mode

A string, the response mode. Allowed are "discrete", `"continuous". Discrete responses are binary (0 or 1), continuous responses are numbers-

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.

---

Method fit()

Fits the free model parameters to the response data

Usage

Cm$fit(solver = self$options$solver, measure = self$options$fit_measure, ...)

Arguments

solver

(optional) A string with the model solver

measure

(optional) A string with the goodness-of-fit measure that the solver optimizes (e.g. "loglikelihood"). Possible values, see the type argument in gof

...

other arguments

---

Method coef()

Returns the free parameters of the model

Usage

Cm$coef()

---

Method predict()

Make predictions for every row in the input data to the model

Usage

Cm$predict(type = "response", newdata = NULL, ...)

Arguments

type

(optional, default "response") Type of prediction to make. See the respective model.

newdata

(optional) A data frame with new data for which to compute predictions.

...

other arguments (ignored) calls the child model's make_prediction function for every slice of the third dimension of the input matrix

---

Method simulate()

Simulates observable data from the model

Usage

Cm$simulate(newdata = NULL)

Arguments

newdata

(optional) A data frame with inputs (e.g., stimuli) to be used in the simulation

Returns

A matrix with simulated choices or judgment values

---

Method set_data()

New data input for a cogscim

Usage

Cm$set_data(data = NULL)

Arguments

data

A data frame with variables corresponding to the inputs that the model needs

---

Method set_par()

Set model parameter

Usage

Cm$set_par(x, check = TRUE, constrain = TRUE)

Arguments

x

A named list of parameters, their names must be in parspace

check

(optional, default TRUE) A logical value, if TRUE the parameter names are checked for validity, if FALSE no check is performed.

constrain

(optional, default TRUE) A logical, whether to newly constrain the parameters when setting a parameter that is constrained.

---

Method get_par()

Get the model parameter

Usage

Cm$get_par(x = "all")

Arguments

x

(optional) A string, which set of parameters to get, "all" returns all parameter, "free" returns the free parameters, "constrained" returns constrained parameters, "equal" returns parameters equal to another parameter

---

Method npar()

Number of model parameters

Usage

Cm$npar(x = "free")

Arguments

x

A string, which of the parameters to return, allowed are "all", "free", "constrained", "equal"

---

Method gof()

Computes the goodness of model fit

Usage

Cm$gof(
  type = self$options$fit_measure,
  n = self$options$fit_args$n,
  newdata = NULL,
  discount = (length(self$discount) > 0),
  ...
)

Arguments

type

A string, which goodness of fit measure to use, e.g. "loglikelihood"; for the allowed values see gof

n

(optional) When fitting to aggregate data, supply how many raw data points underly each aggregated data point

newdata

(optional) A data frame with new data - experimental!

discount

(optional) A number, e.g. 10 ignores the first ten data rows when fitting parameters and when calculating goodness of fits

discount

(optional) An integer or integer vector (default 0), ddefining which or how many, starting from trial 1, to discount when fitting.

...

other arguments (ignored)

---

Method logLik()

Log likelihood of the observed responses under the model predictions

Usage

Cm$logLik(...)

Arguments

...

other arguments (ignored)

---

Method BIC()

Bayesian Information Criterion of the model predictions given the observed responses

Usage

Cm$BIC(...)

Arguments

...

other arguments (ignored)

---

Method AIC()

Akaike Information Criterion of the model predictions given the observed response

Usage

Cm$AIC(...)

Arguments

...

other arguments (ignored)

---

Method AICc()

Small-sample corrected Akaike Information Criterion of the model predictions given the responses

Usage

Cm$AICc(...)

Arguments

...

other arguments (ignored)

---

Method MSE()

Mean squared error between the model predictions given the observed responses

Usage

Cm$MSE(...)

Arguments

...

other arguments (ignored)

---

Method SSE()

Sum of squared errors between the model predictions given the observed responses

Usage

Cm$SSE(...)

Arguments

...

other arguments (ignored)

---

Method RMSE()

Root mean squared error between the model predictions and the observed responses

Usage

Cm$RMSE(...)

Arguments

...

other arguments (ignored)

---

Method set_lb()

Change the lower limit of parameter values

Usage

Cm$set_lb(...)

Arguments

...

new parameter bound, e.g. alpha = 0 sets the lower bound of the parameter alpha to 0

---

Method set_ub()

Change the upper limit of parameter values

Usage

Cm$set_ub(...)

Arguments

...

new parameter bound, e.g. alpha = 0 sets the lower bound of the parameter alpha to 0

---

Method set_start()

Change the starting values for fitting parameters

Usage

Cm$set_start(...)

Arguments

...

new parameter bound, e.g. alpha = 0 sets the lower bound of the parameter alpha to 0

---

Method print()

Prints the model object

Usage

Cm$print(digits = 2)

Arguments

digits

A number specifying the number of digits to print

---

Method summary()

Summarizes the model, it's parameters, and some fit information

Usage

Cm$summary()

---

Method pargrid()

Produces a parameter grid

Usage

Cm$pargrid(nsteps = NULL, offset = NULL, par = NULL)

Arguments

nsteps

A list with steps for each parameter

offset

A number by which to offset the parameters from their bounds

par

(optional) A vector with parameter names for which to generate the grid.

---

Method getCall()

Retrieves the call Remove choicerule

Usage

Cm$getCall()

---

Method clone()

The objects of this class are cloneable with this method.

Usage

Cm$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Examples

# No examples yet.