% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/tools-data.R
\name{forced_choice_data_conversion}
\alias{forced_choice_data_conversion}
\title{Forced-Choice Data Conversion Formats}
\description{
Documents the three data objects used by the forced-choice conversion
helpers: human-readable \code{data}, block definitions
\code{block.items}, and model-ready \code{response} matrices.  This
overview is intended as the starting point before using
\code{\link{get.response.from.data}},
\code{\link{get.data.from.response}}, the TIRT-specific converters, or
the FCDCM-specific converters.
}
\details{
The package uses two layers of forced-choice representation:
\describe{
\item{\code{data}}{An \eqn{N \times B} matrix or data frame that is easy
to read and edit.  Rows are persons and columns are forced-choice
blocks.  A cell records the observed ordering with item labels separated
by \code{">"}.  For example, \code{"3>4>5"} means item 3 was ranked
above item 4, which was ranked above item 5.}
\item{\code{block.items}}{A list of length \eqn{B}.  Element \eqn{b}
gives the item labels appearing in column \eqn{b} of \code{data}.  This
object is the bridge between column order in the data file and item rows
in model parameter matrices such as \code{Q.matrix}.}
\item{\code{response}}{The compact numeric representation consumed by
model fitting code.  Its meaning depends on the model family.  For
FCGGUM, FCMIRT, and FCGDINA, \code{response} is an \eqn{N \times B}
matrix of 1-based pattern indices.  For TIRT, \code{response} is an
\eqn{N \times P} matrix of pairwise binary outcomes.  For FCDCM,
\code{response} is an \eqn{N \times B} binary matrix for two-item
blocks.}
}
}
\section{Choosing a Converter}{

\describe{
\item{FCGGUM, FCMIRT, and FCGDINA}{Use
\code{\link{get.response.from.data}} to convert character strings to
pattern indices, and \code{\link{get.data.from.response}} for the
inverse conversion.}
\item{TIRT}{Use \code{\link{get.response.from.data.TIRT}} and
\code{\link{get.data.from.response.TIRT}}.  TIRT expands each block to
pairwise comparisons, so its \code{response} columns are pairs rather
than block-level pattern numbers.}
\item{FCDCM}{Use \code{\link{get.response.from.data.FCDCM}} and
\code{\link{get.data.from.response.FCDCM}}.  Each block has exactly two
statements, so \code{response = 1} means the first statement in
\code{block.items[[b]]} was preferred and \code{response = 0} means the
second statement was preferred.}
\item{Recovering \code{block.items}}{Use
\code{\link{get.block.items.from.data}} for generic multi-item
forced-choice data and \code{\link{get.block.items.from.data.FCDCM}}
for FCDCM pair data.  Recovery is only possible for item labels that
actually appear in the observed strings.}
}
}

\section{Core Conventions}{

\itemize{
\item The \eqn{b}th element of \code{block.items} always corresponds to
the \eqn{b}th column of \code{data} or \code{response}.
\item \code{fc.type = "RANK"} expects a complete ranking such as
\code{"3>4>5"} for a three-item block.
\item \code{fc.type = "MOLE"} expects a most-least string such as
\code{"3>5"}: item 3 is most preferred and item 5 is least preferred.
\item \code{fc.type = "PICK"} expects a single most-preferred item such
as \code{"3"}.
\item Generic FC pattern-index responses are 1-based.  They are row
numbers in the deterministic pattern matrix generated internally; see
\code{\link{generate_fc_permutation_patterns}} for the public pattern
generator.
\item TIRT data should use consecutive item labels across blocks, for
example \code{list(1:2, 3:5, 6:8)}.  This is the format returned by
\code{\link{sim.data.TIRT}} and expected by the TIRT conversion
routines.
}
}

\examples{
# Generic FC conversion: response is a block-level pattern index.
block.items <- list(1:2, 3:5)
dat <- data.frame(
  block.1 = c("1>2", "2>1"),
  block.2 = c("3>4>5", "5>4>3"),
  stringsAsFactors = FALSE
)
resp <- get.response.from.data(dat, block.items, fc.type = "RANK")
resp
get.data.from.response(resp, block.items, fc.type = "RANK")

# TIRT conversion: response is pairwise 0/1 data.
tirt <- get.response.from.data.TIRT(dat, block.items, fc.type = "RANK")
tirt$response
get.data.from.response.TIRT(
  tirt$response, block.items, fc.type = "RANK",
  pairs.value = tirt$pairs.value
)

# FCDCM conversion: response is binary within each two-item block.
fcdcm.items <- list(c(1L, 3L), c(2L, 4L))
fcdcm.dat <- data.frame(
  block.1 = c("1>3", "3>1"),
  block.2 = c("2>4", "4>2"),
  stringsAsFactors = FALSE
)
fcdcm.resp <- get.response.from.data.FCDCM(fcdcm.dat, fcdcm.items)
fcdcm.resp$response
get.data.from.response.FCDCM(fcdcm.resp$response, fcdcm.items)

}
\seealso{
\code{\link{get.block.items.from.data}},
\code{\link{get.response.from.data}},
\code{\link{get.data.from.response}},
\code{\link{get.response.from.data.TIRT}},
\code{\link{get.data.from.response.TIRT}},
\code{\link{get.response.from.data.FCDCM}},
\code{\link{get.data.from.response.FCDCM}}
}
\keyword{utilities}
