% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/tools-data.R
\name{get.response.from.data.TIRT}
\alias{get.response.from.data.TIRT}
\title{Convert TIRT Forced-Choice Data to Pairwise-Response Matrix}
\usage{
get.response.from.data.TIRT(data, block.items, fc.type = NULL)
}
\arguments{
\item{data}{An \eqn{N \times B} character matrix or data frame of
forced-choice responses.  Each cell encodes the within-block item
ordering using item labels from \code{block.items} separated by \code{">"}
(e.g. \code{"3>1>2"} for RANK, \code{"3>2"} for MOLE, \code{"3"}
for PICK).}

\item{block.items}{A list of length \eqn{B} giving the unique 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"}.}
}
\value{
A list with two components:
\describe{
\item{response}{An \eqn{N \times P} integer matrix of pairwise
binary outcomes (1/0).  For block \eqn{b}, the number of contributed
columns is \eqn{K_b(K_b-1)/2} for RANK, \eqn{2K_b - 3} for MOLE, and
\eqn{K_b - 1} for PICK.}
\item{pairs.value}{A list of length \eqn{N}, each element being
a list of length \eqn{B} of integer pair-definition matrices.
Required as input for
\code{\link{get.data.from.response.TIRT}}.}
}
}
\description{
Parses human-readable forced-choice data strings (full rankings,
most-least choices, or best-only picks) into the Thurstonian IRT
pairwise binary response format.  Each unordered item pair within a
block receives a 1/0 outcome indicating which item was preferred.
}
\details{
This function expands each block column in \code{data} into one or more
pairwise response columns.  Pair columns are grouped by block in the same
order as \code{block.items}.  Within a pair column, the coding is always
1 if the first item in the pair is preferred, and 0 if the second item is
preferred.

Item labels must match the values supplied in \code{block.items}; they do
not need to be consecutive. For example, if
\code{block.items = list(c(2, 7), c(10, 20, 30))}, the second block can
contain \code{"10>20>30"}, \code{"30>10"}, or \code{"20"}, depending on
\code{fc.type}.
}
\section{Pattern Naming and Pair Encoding}{

For a block with \eqn{K} items, the number of pair columns depends on
\code{fc.type}: \eqn{K(K-1)/2} for \code{"RANK"}, \eqn{2K - 3} for
\code{"MOLE"}, and \eqn{K - 1} for \code{"PICK"}.  For each retained pair:
\itemize{
\item \strong{RANK}: the item ranked earlier in the ordering is
preferred.  For \code{block.items[[b]] = 3:5}, pair order is
\code{(3,4)}, \code{(3,5)}, \code{(4,5)}.  The string
\code{"3>4>5"} therefore produces pairwise responses
\code{1, 1, 1}.
\item \strong{MOLE}: only the most- and least-preferred items are
identified (e.g. \code{"3>2"} in a 3-item block).  The
remaining items are treated as tied in the middle, producing
preference relations consistent with the partial ordering.
\item \strong{PICK}: only the most-preferred item is identified
(e.g. \code{"3"} in a 3-item block).  All other items are
treated as equally less preferred.
}
The \code{pairs.value} component records the actual pair matrices used for
each person and block.  It is essential for converting MOLE/PICK responses
back to \code{data}, because the retained pair set can differ across
persons.
}

\examples{
# 2 persons, 2 RANK blocks.
dat <- data.frame(
  block.1 = c("1>2", "2>1"),
  block.2 = c("3>4>5", "5>4>3"),
  stringsAsFactors = FALSE
)
items <- list(1:2, 3:5)
result <- get.response.from.data.TIRT(dat, items, fc.type = "RANK")
result$response
result$pairs.value[[1]]
get.data.from.response.TIRT(
  result$response, items, fc.type = "RANK",
  pairs.value = result$pairs.value
)

# Mixed partial-response blocks.
dat.partial <- data.frame(
  mole = c("1>3", "2>1"),
  pick = c("4", "5"),
  stringsAsFactors = FALSE
)
items.partial <- list(1:3, 4:6)
partial <- get.response.from.data.TIRT(
  dat.partial, items.partial, fc.type = c("MOLE", "PICK")
)
partial$response
get.data.from.response.TIRT(
  partial$response, items.partial, fc.type = c("MOLE", "PICK"),
  pairs.value = partial$pairs.value
)
}
\seealso{
\code{\link{get.data.from.response.TIRT}} for the reverse conversion.

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