The R6 class underlying all "cm" (cognitive model) objects 'Cm$new(formula, data, parspace)'
Cm.Rd
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 inparspace
.delta=NA
: ignore delta if it can be ignored by setting delta equal to the value in the column "na" ofparspace
, 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, andy ~ 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
anddata
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
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 onformula
and can bedelta
,x1
,x2
(see details - model parameters).list(x1 = 3.09)
sets parameterx1
equal to 3.09.list(x1 = "x2")
sets parameterx1
equal to parameterx2
(estimatesx2
).list(x2 = "x1", x1 = 3.09)
sets parameterx2
equal to parameterx1
and setsx1
equal to 3.09 (estimates none of the two).list(x1 = NA)
omits the parameterx1
, 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 fitsdiscount
(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, orlist(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
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 thetype
argument in gof...
other arguments
Method predict()
Make predictions for every row in the input data to the model
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
Method set_par()
Set model parameter
Arguments
x
A named list of parameters, their names must be in
parspace
check
(optional, default
TRUE
) A logical value, ifTRUE
the parameter names are checked for validity, ifFALSE
no check is performed.constrain
(optional, default
TRUE
) A logical, whether to newly constrain the parameters when setting a parameter that is constrained.
Method npar()
Number of model parameters
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 gofn
(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 fitsdiscount
(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
Method BIC()
Bayesian Information Criterion of the model predictions given the observed responses
Method AIC()
Akaike Information Criterion of the model predictions given the observed response
Method AICc()
Small-sample corrected Akaike Information Criterion of the model predictions given the responses
Method MSE()
Mean squared error between the model predictions given the observed responses
Method SSE()
Sum of squared errors between the model predictions given the observed responses
Method print()
Prints the model object