% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/lr_test.grt_wind_fit.R
\name{lr_test}
\alias{lr_test}
\title{Run likelihood ratio tests of separability and independence}
\usage{
lr_test(fitted_model, cmats, n_reps=20, test=c("PS(A)", "PS(B)", "PI", "DS(A)", "DS(B)"))
}
\arguments{
\item{fitted_model}{An object returned by \code{\link{grt_wind_fit}} or 
\code{\link{grt_wind_fit_parallel}}}

\item{cmats}{List of confusion matrices. Each entry in the list should contain
the 4x4 confusion matrix from one individual. For a detailed description of
how to create this list, see \code{\link{grt_wind_fit}}}

\item{n_reps}{Number of times the optimization algorithm should be run when
a restricted model is fitted to the data (see Details).}

\item{test}{A string array indicating the test(s) to be performed. "PS(A)" and
"PS(B)" indicate to test perceptual separability of A and B, respectively. "PI"
indicates to test perceptual independence. "DS(A)" and "DS(B)" indicate to test
decisional separability of A and B, respectively. The default is test=c("PS(A)",
"PS(B)", "PI", "DS(A)", "DS(B)"), which includes all tests.}
}
\value{
An object of class "\code{grt_wind_fit}," including information about
likelihood ratio tests.

The function \code{summary} is used to obtain a summary of the model fit to 
data and the results of likelihood ratio tests.
}
\description{
Run likelihood ratio tests of perceptual separability, decisional separability,
and perceptual independence (see Ashby & Soto, 2015), using the
maximum likelihood parameter estimates stored in a \code{grt_wind_fit}
object. The method considers any restrictions placed in the original model
and stored in \code{grt_wind_fit$restrictions}.
}
\details{
Each likelihood ratio test involves fitting a restricted model to the
  data (e.g., a model in which parameters are fixed to reflect PS) and then 
  statistically comparing the fit of the restricted model against that of the
  full model (for details, see Ashby & Soto, 2015). The \code{lr_test} function
  calls \code{\link{grt_wind_fit_parallel}} to fit a restricted model several
  times (determined by parameter \code{n_reps}; set to 20 by default). Each time,
  the starting parameter values are the values previously found by fitting the 
  full model, with small random values added or subtracted (for details about
  the fitting procedure, see \code{\link{grt_wind_fit}}). The best-fitting model
  is chosen and used in the likelihood ratio test.
  
  Because likelihood ratio tests require fitting a GRT-wIND model many times,
  you should expect the analysis to take considerable time to finish. We recommend
  you to run only the tests that interest you, and not all the tests included by
  default.
}
\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)

#' # run the likelihood ratio tests
fitted_model <- lr_test(fitted_model, cmats)

# see the results
summary(fitted_model)

}
\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.
}
