% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sumstats_macro.R
\name{sumstats_macro}
\alias{sumstats_macro}
\title{Perform a summary statistics macroanalysis of identification data}
\usage{
sumstats_macro(cmat, use_kadlec = T)
}
\arguments{
\item{cmat}{A 4x4 confusion matrix (see Details).}

\item{use_kadlec}{If TRUE (default), uses a definition of the decision bound
parameter c from Kadlec (1999). If FALSE, it uses the definition from
MacMillan and Creelman (2005).}
}
\value{
An object of class "\code{sumstats_macro}"

The function \code{summary} is used to obtain a summary of conclusions from 
the analysis about perceptual and decisional separability (see Table 1 in
Kadlec, 1995).
}
\description{
Performs a summary statistics (i.e., MSDA) macroanalysis (see Kadlec, 1995;
Kadlec & Townsend, 1992) of data from a 2x2 identification experiment. This
analysis should be performed together with the microanalysis implemented by
the function \code{\link{sumstats_micro}}
}
\details{
For an introductory tutorial on the summary statistics macroanalyses, see
Ashby & Soto (2005), particularly pages 22-28. 

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} }
}
\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 the summary statistics macroanalysis
macro_results <- sumstats_macro(cmat)

# See a summary of the results
summary(macro_results)

# Print to screen the details of each test
macro_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.

Kadlec, H. (1995). Multidimensional signal detection analyses (MSDA)
for testing separability and independence: A Pascal program. \emph{Behavior
Research Methods, Instruments, & Computers, 27}(4), 442-458.

Kadlec, H., & Townsend, J. T. (1992). Signal detection analyses of
multidimensional interactions. In F. G. Ashby (Ed.), \emph{Multidimensional
models of perception and cognition} (pp. 181–231). Hillsdale, NJ: Erlbaum.

Macmillan, N. A., & Creelman, D. (2005). \emph{Detection theory: A user’s
guide (2nd ed.)}. Mahwah, NJ: Erlbaum.
}
\seealso{
\code{\link{sumstats_micro}}
}

