% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/grt_wind_fit.R
\name{grt_wind_fit}
\alias{grt_wind_fit}
\title{Fit a GRT-wIND model to identification data}
\usage{
grt_wind_fit(cmats, start_params = c(), model = "full",
  rand_pert = 0.3, control = list())
}
\arguments{
\item{cmats}{List of confusion matrices. Each entry in the list should contain
the 4x4 confusion matrix from one individual (see Details).}

\item{start_params}{An optional vector of parameters to start the
optimization algorithm. You can provide either the group parameters or both
group and individual parameters. It will be created automatically if not
provided (see Details).}

\item{model}{A string or vector of strings indicating what GRT-wIND model to run. 
By default is the full model ("full"), but restricted models can be obtained by 
combination of several string values. "PS(A)" and "PS(B)" are models that assume 
PS for dimension A and dimension B, respectively. "PI" is a model that assumes 
perceptual independence.  "DS(A)" and "DS(B)" are models that assume DS for dimension 
A and dimension B, respectively. "1-VAR" is a model that assumes that all variances 
are equal to one. A model assuming PS for dimension A and that all variances are 
equal to one would require setting model=c("PS(A)", "1-VAR").}

\item{rand_pert}{Maximum value of a random perturbation added to the starting
parameters. With a value of zero, the algorithm is started exactly at
\code{start_params}. As the value of \code{rand_pert} is increased, the starting
parameters become closer to be "truly random."}

\item{control}{A list of control parameters for the \code{optim} function. See
\code{\link[stats]{optim}}.}
}
\value{
An object of class "\code{grt_wind_fit}."

The function \code{\link{wald}} is used to obtain the
results of Wald tests of perceptual separability, decisional separability and
perceptual independence, using the maximum likelihood parameters estimated
through \code{grt_wind_fit}.

The function \code{summary} is used to obtain a summary of the model fit to 
data and the results of Wald tests (if available). The function
\code{\link[=plot.grt_wind_fit]{plot}} is used to print a graphical
representation of the fitted model.
}
\description{
Uses the BFGS optimization method to fit a full GRT-wIND model to data from a
2x2 identification experiment (see Soto et al., 2015).
}
\details{
We recommend that you fit GRT-wIND to your data repeated times, each time 
with a different value for the starting parameters, and keep the solution
with the smallest negative log-likelihood. This facilitates finding the true 
maximum likelihood estimates of the model's parameters, which is necessary to
make valid conclusions about dimensional separability and independence. The 
function \code{\link{grt_wind_fit_parallel}} does exactly this, taking 
advantage of multiple CPUs in your computer to speed up the process. For most
applications, you should use \code{\link{grt_wind_fit_parallel}} instead of
the current function.

A 2x2 identification experiment involves two dimensions, A and B, each with
two levels, 1 and 2. Stimuli are represented by their level in each dimension
(A1B1, A1B2, A2B1, and A2B2) and so are their corresponding correct
identification responses (a1b1, a1b2, a2b1, and a2b2).

The data from a single participant in the experiment should be ordered in a
4x4 confusion matrix with rows representing stimuli and columns representing
responses. Each cell has the frequency of responses for the stimulus/response
pair. Rows and columns should be ordered in the following way:

\itemize{ \item{Row 1: Stimulus A1B1} \item{Row 2: Stimulus A2B1} 
\item{Row 3: Stimulus A1B2} \item{Row 4: Stimulus A2B2} \item{Column
1: Response a1b1} \item{Column 2: Response a2b1} \item{Column 3: Response a1b2} 
\item{Column 4: Response a2b2} }

The argument \code{cmats} is a list with all individual confusion matrices
from an experimental group.

If the value of \code{start_params} is not provided, the starting parameters
for the optimization algorithm are the following: 
\itemize{ 
\item{Means:}{ A1B1=(0,0), A2B1=(1,0), A1B2=(1,0), A2B1=(1,1)} 
\item{Variances:}{ All set to one} 
\item{Correlations:}{ All set to zero} 
\item{Decision bounds:}{ All orthogonal to their corresponding dimension} 
\item{Attention parameters:}{ No differences in global attention (kappa=2) and no 
selective attention (lambda=0.5)}
}

Note that a random value will be added to these parameters if
\code{rand_pert} is given a value higher than zero.
}
\examples{
# Create list with confusion matrices # In this example, we enter data from
# an experiment with 5 participants. For each participant, inside the c(...),
# enter the data from row 1 in the matrix, then from row 2, etc.
cmats <- list(matrix(c(161,41,66,32,24,147,64,65,37,41,179,43,14,62,22,202),nrow=4,ncol=4,byrow=TRUE))
cmats[[2]] <- matrix(c(126,82,67,25,8,188,54,50,34,75,172,19,7,103,14,176),nrow=4,ncol=4,byrow=TRUE)
cmats[[3]] <- matrix(c(117,64,89,30,11,186,69,34,21,81,176,22,10,98,30,162),nrow=4,ncol=4,byrow=TRUE)
cmats[[4]] <- matrix(c(168,57,47,28,15,203,33,49,58,54,156,32,9,96,9,186),nrow=4,ncol=4,byrow=TRUE)
cmats[[5]] <- matrix(c(169,53,53,25,34,168,69,29,38,48,180,34,19,44,60,177),nrow=4,ncol=4,byrow=TRUE)

# fit the model to data
fitted_model <- grt_wind_fit(cmats)

# plot a graphical representation of the fitted model
plot(fitted_model)

# optionally, you can run likelihood ratio tests of separability and independence
# (recommended method, but very slow)
fitted_model <- lr_test(fitted_model, cmats)

# alternatively, you can run a Wald test of separability and independence 
# (less recommended method, due to common problems with numerical estimation, but faster)
fitted_model <- wald(fitted_model, cmats)

# print a summary of the fitted model and tests to screen
summary(fitted_model)

# a data frame with the values of all individual parameters is available in
# in fitted_model$indpar
fitted_model$indpar

}
\references{
Soto, F. A., Musgrave, R., Vucovich, L., & Ashby, F. G. (2015).
  General recognition theory with individual differences: A new method for
  examining perceptual and decisional interactions with an application to
  face perception. \emph{Psychonomic Bulletin & Review, 22}(1), 88-111.
}
