% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/grt_hm_fit.R
\name{grt_hm_fit}
\alias{grt_hm_fit}
\title{Fit a hierarchy of traditional GRT models to identification data}
\usage{
grt_hm_fit(cmat, rand_pert = 0.3, n_reps = 10, control = list())
}
\arguments{
\item{cmat}{A 4x4 confusion matrix (see Details).}

\item{rand_pert}{Maximum value of a random perturbation added to the starting
parameters. Defaults to 0.3. With a value of zero, the optimization is started exactly at the 
default starting parameters (see Details). As the value of \code{rand_pert} is 
increased, the starting parameters become closer to be "truly random."}

\item{n_reps}{Number of times the optimization algorithm should be run, each time
with a different value for the starting parameters. The function will return the
model with a highest log-likelihood from all the runs. The value of \code{n_reps}
defaults to ten.}

\item{control}{A list of optional control parameters for the \code{optim} function. See 
\code{\link[stats]{optim}}. Note that the parameter \code{ndeps} entered 
here should be a single number instead of the vector that is usually passed 
to \code{optim}. This single value is repeated inside \code{grt_hm_fit} to 
create the appropriate vectors.}
}
\value{
An object of class "\code{grt_hm_fit}."
  
  The function \code{summary} is used to obtain a summary of results from the
  model fit and selection process, including the best-fitting model and
  conclusions about perceptual separability and perceptual independence
  (decisional separability is assumed by all models)
  
  The function \code{\link[=plot.grt_hm_fit]{plot}} is used to print a
  graphical representation of the best-fitting model.
}
\description{
Fits a hierarchy of traditional GRT models to data from a 2x2 identification 
experiment, using the BFGS optimization method (See Ashby & Soto, 2015). It
then selects the best-fitting model using the AIC.
}
\details{
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 default 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} }

Decisional separability is assumed for all models (i.e., decision bounds are
fixed and orthogonal to the dimension they divide)

Note that a random value will be added to the default starting parameters if 
\code{rand_pert} is given a value higher than zero.
}
\examples{
# Create a confusion matrix
# Inside the c(...) below, we enter the data from row 1 in the 
# matrix, then from row 2, etc.
cmat <- matrix(c(140, 36, 34, 40,
                 89, 91, 4, 66,
                 85, 5, 90, 70,
                 20, 59, 8, 163),
                 nrow=4, ncol=4, byrow=TRUE)

# Perform model fit and selection
hm_fit_results <- grt_hm_fit(cmat)

# See a summary of the fitting and selection results
summary(hm_fit_results)

# plot a graphical representation of the best-fitting model
plot(hm_fit_results)

}
\references{
Ashby, F. G., & Soto, F. A. (2015). Multidimensional signal
  detection theory. In J. R. Busemeyer, J. T. Townsend, Z. J. Wang, & A.
  Eidels (Eds.), \emph{Oxford handbook of computational and mathematical
  psychology} (pp. 13-34). Oxford University Press: New York, NY.
}

