% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/tools-data.R
\name{get.response.from.data}
\alias{get.response.from.data}
\title{Convert FC Data Strings to an Integer Response (Pattern-Index) Matrix}
\usage{
get.response.from.data(data, block.items, fc.type = "RANK")
}
\arguments{
\item{data}{An \eqn{N \times B} character matrix or data frame.  Cells
encode within-block item orderings as global indices 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 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{
An \eqn{N \times B} integer matrix.  Each entry is a 1-based
pattern index (row number in the block's pattern matrix).  Column
names are \code{"block.1"}, \dots, \code{"block.B"}.
}
\description{
Parses human-readable forced-choice data strings into integer pattern
indices.  This is the generic converter used by \strong{FCGGUM},
\strong{FCMIRT}, and \strong{FCGDINA}.  Each data cell is matched
against the full set of permutation/observation patterns for that
block, and the resulting row index is stored in the response matrix.
}
\section{Pattern Matching}{

The conversion first generates all possible observation patterns for
each block via the internal permutation helper:
\itemize{
\item \strong{RANK} (\eqn{K} items): all \eqn{K!} full rankings,
ordered lexicographically by within-block position.
\item \strong{MOLE}: \eqn{K(K-1)} most-least observation patterns.
\item \strong{PICK}: \eqn{K} best-only patterns.
}
Each data cell string is parsed into an integer vector of global item
indices, which is then matched (as an ordered sequence) against the
pattern matrix.  The 1-based row index of the match becomes the
response value.  Pattern ordering is deterministic and reproducible.

A non-missing cell that cannot be matched to a valid pattern is returned as
\code{NA_integer_}.  This is useful for data-screening workflows: after
conversion, check \code{anyNA(response)} before passing the response matrix
to a fitting function.
}

\examples{
# 2 persons, 2 RANK blocks.
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, items, fc.type = "RANK")
resp
get.data.from.response(resp, items, fc.type = "RANK")

# Mixed block formats: most-least plus pick.
dat.mixed <- data.frame(
  mole = c("1>3", "3>2"),
  pick = c("4", "6"),
  stringsAsFactors = FALSE
)
mixed.items <- list(1:3, 4:6)
get.response.from.data(
  dat.mixed, mixed.items, fc.type = c("MOLE", "PICK")
)
}
\seealso{
\code{\link{get.data.from.response}} for the reverse conversion.

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

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