% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/tools-data.R
\name{get.data.from.response.TIRT}
\alias{get.data.from.response.TIRT}
\title{Convert TIRT Pairwise-Response Matrix to Forced-Choice Data Strings}
\usage{
get.data.from.response.TIRT(
  response,
  block.items,
  fc.type = NULL,
  pairs.value = NULL
)
}
\arguments{
\item{response}{An \eqn{N \times P} integer matrix of pairwise binary
responses.  Entries must be 1 (first item in the pair preferred) or 0
(second item in the pair preferred).}

\item{block.items}{A list of length \eqn{B} giving the consecutive item
labels in each forced-choice block.}

\item{fc.type}{Character vector of length \eqn{B} (or a scalar recycled
to all blocks): \code{"RANK"}, \code{"MOLE"}, or \code{"PICK"}.}

\item{pairs.value}{A list of length \eqn{N}, where each element is itself
a list of length \eqn{B} giving the pair-definition matrix for each
block.  Required when any block uses \code{"MOLE"} or \code{"PICK"}.
For all-\code{"RANK"} data this argument may be omitted because the pair
definitions are fixed by \code{block.items}.}
}
\value{
A data frame with \eqn{N} rows and \eqn{B} columns.  Column names
are \code{"block.1"}, \code{"block.2"}, etc.  Cell values are character
strings encoding the within-block ordering: full rankings for
\code{"RANK"}, \code{"best>worst"} for \code{"MOLE"}, and single
integers for \code{"PICK"}.
}
\description{
Converts a Thurstonian IRT pairwise-response matrix back to the
human-readable forced-choice strings used in \code{data}.  This is the
inverse of \code{\link{get.response.from.data.TIRT}}.
}
\details{
TIRT differs from the generic FC converters because the model is expressed
through pairwise comparisons.  The input \code{response} is therefore not a
block-level pattern-index matrix.  It is an \eqn{N \times P} binary matrix,
where each column is one observed item pair and each entry is coded:
\itemize{
\item 1: the first item in that pair was preferred;
\item 0: the second item in that pair was preferred.
}

The number of response columns contributed by a block with \eqn{K} items is
determined by \code{fc.type}:
\describe{
\item{RANK}{All \eqn{K(K-1)/2} unordered pairs are observed.  Pair columns
are generated in the order \eqn{(1,2), (1,3), \dots, (K-1,K)} using the
item labels in \code{block.items[[b]]}.}
\item{MOLE}{Only the pairs needed to identify the most- and least-preferred
items are retained.  The block contributes \eqn{2K - 3} response columns
per person.}
\item{PICK}{Only the pairs involving the picked item are retained.  The
block contributes \eqn{K - 1} response columns per person.}
}

For \code{"MOLE"} and \code{"PICK"}, the identities of the retained pairs
can vary by person.  The \code{pairs.value} object records those
person-specific pair definitions and is required to reconstruct data
strings without ambiguity.  It is normally copied directly from the
\code{pairs.value} component returned by
\code{\link{get.response.from.data.TIRT}}.

TIRT conversion assumes consecutive item labels across blocks, for example
\code{list(1:2, 3:5)}.  This is the layout returned by
\code{\link{sim.data.TIRT}}.
}
\examples{
# 2 RANK blocks: block 1 has items 1,2; block 2 has items 3,4,5.
items <- list(1:2, 3:5)
resp <- cbind(
  c(1, 0),            # block 1 pair: 1 vs 2
  c(1, 0),            # block 2 pair: 3 vs 4
  c(1, 0),            # block 2 pair: 3 vs 5
  c(1, 0)             # block 2 pair: 4 vs 5
)
get.data.from.response.TIRT(resp, items, fc.type = "RANK")
}
\seealso{
\code{\link{get.response.from.data.TIRT}} for the reverse conversion.

\code{\link{get.data.from.response}} for the generic (non-TIRT) converter
used by FCGGUM and FCMIRT.
}
