% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/read_responses.R
\name{read_responses}
\alias{read_responses}
\title{Read and validate survey responses}
\usage{
read_responses(
  x,
  instrument,
  respondent_id = NULL,
  submitted_at = NULL,
  meta_cols = NULL,
  strict = TRUE
)
}
\arguments{
\item{x}{A file path to a CSV file, a \code{data.frame}, or a \code{tibble}.}

\item{instrument}{An \code{sframe} object created by \code{\link[=sf_instrument]{sf_instrument()}}.}

\item{respondent_id}{Character or NULL. The name of the column containing
unique respondent identifiers. If NULL, no respondent ID column is
expected.}

\item{submitted_at}{Character or NULL. The name of the column containing
submission timestamps.}

\item{meta_cols}{Character vector or NULL. Additional column names that are
not item IDs but should be retained (for example, condition assignment or
source URL).}

\item{strict}{Logical. When \code{TRUE} (default), columns in the response data
outside the declared item IDs and metadata columns raise an error.
When \code{FALSE}, undeclared columns are retained with a warning.}
}
\value{
A \code{data.frame} with columns ordered as: metadata columns first, then
item columns in instrument order. Unrecognised columns are dropped when
\code{strict = TRUE} or appended with a warning when \code{strict = FALSE}.
}
\description{
Loads survey response data and checks that it conforms to the instrument
specification. Column names in the response file must match item IDs defined
in the instrument. Non-item columns are allowed only when declared through
\code{respondent_id}, \code{submitted_at}, or \code{meta_cols}.
}
\examples{
responses <- read_responses(
  x = system.file("extdata", "tourism_services_responses.csv",
                  package = "surveyframe"),
  instrument = read_sframe(
    system.file("extdata", "tourism_services_demo.sframe",
                package = "surveyframe")
  ),
  respondent_id = "respondent_id",
  submitted_at = "submitted_at",
  meta_cols = "started_at"
)
head(responses[, c("respondent_id", "visit_type", "dm_1")])
}
\seealso{
\code{\link[=quality_report]{quality_report()}}, \code{\link[=score_scales]{score_scales()}}
}
