% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/tools-data.R
\name{get.data.from.response}
\alias{get.data.from.response}
\title{Convert an Integer Response (Pattern-Index) Matrix to FC Data Strings}
\usage{
get.data.from.response(response, block.items, fc.type = "RANK")
}
\arguments{
\item{response}{An \eqn{N \times B} integer matrix of pattern
indices.  Each entry is an integer between 1 and the number of
observed patterns for that block.}

\item{block.items}{A list of length \eqn{B} giving the global item
indices 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 data frame with \eqn{N} rows and \eqn{B} columns.  Column
names are \code{"block.1"}, \dots, \code{"block.B"}.  Cell values
are character strings: full rankings (\code{"2>5>8"}) for
\code{"RANK"}, \code{"best>worst"} pairs for \code{"MOLE"}, and
single integers for \code{"PICK"}.
}
\description{
Converts an integer matrix of pattern indices back to human-readable
forced-choice data strings.  This is the generic converter used by
\strong{FCGGUM}, \strong{FCMIRT}, and \strong{FCGDINA} where each
column of the response matrix is an index into the block's observed
permutation-pattern list.
}
\section{Pattern Generation and Numbering}{

For a block with \eqn{K} items, the set of possible response patterns
depends on the forced-choice type:
\describe{
\item{RANK}{All \eqn{K!} full permutations of the \eqn{K} items
are generated.  The patterns are listed in lexicographic order
of the within-block item positions.  For example, a 3-item
block with items \code{c(2,5,8)} produces \eqn{3! = 6} patterns:
\code{(2,5,8)}, \code{(2,8,5)}, \code{(5,2,8)}, \code{(5,8,2)},
\code{(8,2,5)}, \code{(8,5,2)}.  Pattern index 1 means the
first pattern was observed.}
\item{MOLE}{For a \eqn{K}-item block, \eqn{K(K-1)} most-least
observation patterns are possible: \eqn{K} choices for the most
preferred item times \eqn{K-1} choices for the least preferred
item.  Pattern \eqn{(a,b)} means item \eqn{a} was most
preferred and item \eqn{b} was least preferred.}
\item{PICK}{For a \eqn{K}-item block, exactly \eqn{K} patterns
exist: one for each possible most-preferred item.}
}
In all cases the pattern index (an integer from 1 to the number of
observed patterns) is the row number in the matrix returned by
the internal permutation helper for that block. The same deterministic
pattern construction is exposed by
\code{\link{generate_fc_permutation_patterns}}.

This format is a compact block-level encoding.  One response column equals
one forced-choice block, even when the block contains more than two items.
This is the representation expected by the generic forced-choice model
families FCGGUM, FCMIRT, and FCGDINA.  It should not be confused with the
TIRT pairwise format, where one block usually expands to several pair
columns.
}

\examples{
# 2 persons, 2 RANK blocks.
items <- list(1:2, 3:5)
resp <- cbind(c(1, 2), c(1, 6))
get.data.from.response(resp, items, fc.type = "RANK")

# Mixed block formats: first block is most-least, second block is pick.
mixed.items <- list(1:3, 4:6)
mixed.resp <- cbind(c(1, 6), c(1, 3))
get.data.from.response(
  mixed.resp, mixed.items, fc.type = c("MOLE", "PICK")
)
}
\seealso{
\code{\link{get.response.from.data}} for the reverse conversion.

\code{\link{generate_fc_permutation_patterns}} for pattern generation.

\code{\link{get.data.from.response.TIRT}} for the TIRT-specific
converter.
}
