% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/metadata-infer.R
\name{infer_question_prefaces}
\alias{infer_question_prefaces}
\title{Infer Question Prefaces from Variable Labels}
\usage{
infer_question_prefaces(
  x,
  sep = c(" - ", "- ", " – ", ": ", " | "),
  min_vars = 2L,
  lcp_min = 20L,
  overwrite = FALSE,
  verbose = TRUE
)
}
\arguments{
\item{x}{A survey design object (\code{survey_taylor}, \code{survey_replicate}, etc.)
\strong{or} a data frame with haven-style \code{"label"} attributes.}

\item{sep}{Character vector of literal separator strings to try, in
priority order. Default: \code{c(" - ", "- ", " \\u2013 ", ": ", " | ")}.}

\item{min_vars}{Minimum number of variables that must share a candidate
preface to trigger extraction. Default \code{2L}.}

\item{lcp_min}{Minimum character length (after trimming to a word boundary)
for an LCP-derived preface to be accepted. Default \code{20L}.}

\item{overwrite}{If \code{FALSE} (default), variables that already have a
\code{question_preface} are skipped and a warning is emitted. Set \code{TRUE} to
replace existing prefaces without warning.}

\item{verbose}{If \code{TRUE} (default), emits a cli summary for each detected
group.}
}
\value{
The modified \code{x}, invisibly.
}
\description{
Scans variable labels in a survey design object or labelled data frame for
groups of variables sharing a common preface (via separator or longest
common prefix). Detected prefaces are written to \code{question_preface} in the
metadata and the shared text is trimmed from each variable label, leaving
only the unique suffix.
}
\details{
\strong{Detection algorithm (two passes):}
\enumerate{
\item \strong{Separator pass} — for each separator in \code{sep} (tried in order):
\itemize{
\item Variables whose label contains the separator are grouped by their
candidate preface (text before the \emph{first} occurrence of the separator,
trimmed).
\item Any group with \eqn{\geq} \code{min_vars} members is recorded; those
variables are excluded from all subsequent passes.
}
\item \strong{LCP pass} — for remaining labelled variables (\eqn{\geq} 2):
\itemize{
\item The character-level longest common prefix (LCP) of all remaining
labels is computed and trimmed to the last word boundary.
\item If the trimmed LCP is \eqn{\geq} \code{lcp_min} characters, the group
is recorded.
}
}

\strong{Apply step:}
\itemize{
\item Variables with an existing \code{question_preface} are skipped when
\code{overwrite = FALSE} (default); a warning is emitted listing the count
of skipped variables.
\item Variables whose unique suffix would be empty after trimming are always
skipped with a per-variable warning.
}

\strong{Data frame integration:}
When called on a data frame, the detected preface is written to
\code{attr(col, "question_preface")}. Passing the result to \code{\link[=as_survey]{as_survey()}}
automatically picks up both the trimmed label and the preface via the
internal haven metadata extraction step.
}
\examples{
# Data frame with haven-style labels (Qualtrics / SPSS export pattern)
df <- data.frame(
  discrim_a = 1:5,
  discrim_b = 2:6,
  discrim_c = 3:7
)
attr(df$discrim_a, "label") <-
  "Please rate discrimination - Evangelical Christians"
attr(df$discrim_b, "label") <-
  "Please rate discrimination - Muslims"
attr(df$discrim_c, "label") <-
  "Please rate discrimination - Jews"

df <- infer_question_prefaces(df, verbose = FALSE)
attr(df$discrim_a, "label")            # "Evangelical Christians"
attr(df$discrim_a, "question_preface") # "Please rate discrimination"

}
\seealso{
Other metadata: 
\code{\link{classify_question_type}()},
\code{\link{extract_metadata}()},
\code{\link{extract_missing_codes}()},
\code{\link{extract_question_preface}()},
\code{\link{extract_sata}()},
\code{\link{extract_universe}()},
\code{\link{extract_val_labels}()},
\code{\link{extract_var_label}()},
\code{\link{extract_var_note}()},
\code{\link{set_missing_codes}()},
\code{\link{set_question_preface}()},
\code{\link{set_sata}()},
\code{\link{set_universe}()},
\code{\link{set_val_labels}()},
\code{\link{set_var_label}()},
\code{\link{set_var_note}()},
\code{\link{survey_metadata}()},
\code{\link{survey_weighting_history}()}
}
\concept{metadata}
