% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/tools-data.R
\name{get.block.items.from.data}
\alias{get.block.items.from.data}
\title{Extract Block Items from Forced-Choice Data}
\usage{
get.block.items.from.data(data)
}
\arguments{
\item{data}{An \eqn{N \times B} character matrix (or data frame) of
forced-choice responses.  Each entry encodes an item ordering using
integer item indices separated by \code{">"} (e.g. \code{"3>1>2"}).
Missing values (\code{NA}) are permitted and skipped.}
}
\value{
A list of length \eqn{B}.  Each element is an integer vector of
global item indices appearing in that block, sorted in ascending order.
}
\description{
Infers the item composition of each forced-choice block from a character
data matrix.  Each cell should encode the within-block item ordering
(e.g. \code{"2>1>3"} for a rank-3 block).  The function parses all
non-missing cells per block and returns sorted, unique item indices.

This function is the recommended way to recover \code{block.items} when
only character-rank data are available.  It works for all forced-choice
types (\code{"RANK"}, \code{"MOLE"}, \code{"PICK"}) as long as every
item appears at least once across persons.
}
\details{
The returned \code{block.items} list defines the block layout used by the
other converters.  If \code{data} has \eqn{B} columns, the result has
\eqn{B} elements, and result element \eqn{b} belongs to data column
\eqn{b}.  Item labels are treated as global item indices; they are not
recoded to local positions.

The function scans observed strings only.  Therefore, for partial-response
formats, it can only recover items that appear in the observed partial
strings:
\itemize{
\item For \code{"RANK"}, a complete ranking normally contains every item
in the block, so one valid row can be sufficient.
\item For \code{"MOLE"}, only most- and least-preferred items appear in
each cell.  An item that is never chosen as most or least cannot be
recovered from \code{data} alone.
\item For \code{"PICK"}, only picked items appear.  Items that are never
picked cannot be recovered from \code{data} alone.
}
In those partial-response cases, pass a complete user-defined
\code{block.items} list to the fitting or conversion function when the raw
data do not mention every item.
}
\examples{
# 3 persons, 2 blocks.
# Block 1 contains items 1 and 2; block 2 contains items 3, 4, and 5.
dat <- data.frame(
  block.1 = c("1>2", "2>1", "1>2"),
  block.2 = c("3>4>5", "5>4>3", "4>3>5"),
  stringsAsFactors = FALSE
)
get.block.items.from.data(dat)
}
\seealso{
\code{\link{get.block.items.from.data.FCDCM}} for the FCDCM (binary-pair)
variant.

\code{\link{get.response.from.data}} to convert character data to an
integer pattern-index matrix.
}
