% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sf_check.R
\name{sf_check}
\alias{sf_check}
\title{Define a design-time survey check}
\usage{
sf_check(
  id,
  item_id,
  type = c("attention", "instructional", "trap"),
  pass_values = NULL,
  fail_action = c("flag", "exclude"),
  label = NULL,
  notes = NULL
)
}
\arguments{
\item{id}{Character. A unique identifier for this check.}

\item{item_id}{Character. The \code{id} of the item used as the check. The item
must be defined separately with \code{\link[=sf_item]{sf_item()}} and included in the same
instrument.}

\item{type}{Character. The check type. One of:
\itemize{
\item \code{"attention"}: the item has a stated correct answer and flags
respondents who answer incorrectly.
\item \code{"instructional"}: a manipulation check item used to test whether
instructions were followed.
\item \code{"trap"}: an item designed to be selected only by inattentive
respondents (e.g. "Please select Strongly agree for this item.").
}}

\item{pass_values}{Vector or NULL. The response value or values that
constitute a pass. For \code{"attention"} and \code{"instructional"} types, at
least one value should be supplied. For \code{"trap"} types, this is the
value that should NOT be selected.}

\item{fail_action}{Character. What \code{\link[=quality_report]{quality_report()}} does with respondents
who fail this check. Either \code{"flag"} (mark in the report but retain) or
\code{"exclude"} (mark for exclusion).}

\item{label}{Character or NULL. An optional human-readable label for the
check, used in the quality report.}

\item{notes}{Character or NULL. Optional free-text notes about the purpose
or rationale of this check.}
}
\value{
An object of class \code{sf_check} (a named list).
}
\description{
Specifies an attention, instructional, or trap check item at instrument
design time. The check is stored in the instrument object and evaluated
against collected response data by \code{\link[=quality_report]{quality_report()}}. This function only
defines the check. Evaluation happens later in \code{\link[=quality_report]{quality_report()}}.
}
\examples{
# An attention check: respondent must select 4
chk <- sf_check(
  id          = "attn_1",
  item_id     = "attention_check_q",
  type        = "attention",
  pass_values = 4,
  fail_action = "flag",
  label       = "Attention check 1"
)
}
\seealso{
\code{\link[=sf_item]{sf_item()}}, \code{\link[=sf_instrument]{sf_instrument()}}, \code{\link[=quality_report]{quality_report()}}
}
