% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/derive.R
\name{derive_selfreport}
\alias{derive_selfreport}
\title{Define a self-reported phenotype from UKB touchscreen data}
\usage{
derive_selfreport(
  data,
  name,
  regex,
  field = c("noncancer", "cancer"),
  ignore_case = TRUE,
  disease_cols = NULL,
  date_cols = NULL,
  visit_cols = NULL
)
}
\arguments{
\item{data}{(data.frame or data.table) UKB data containing self-report
fields.}

\item{name}{(character) Output column name prefix, e.g. \code{"disease"} or
\code{"outcome"}.}

\item{regex}{(character) Regular expression matched against disease text
values (after \code{tolower()}), e.g. \code{"^diabetes$"}.}

\item{field}{(character) Self-report field type: \code{"noncancer"}
(p20002 / p20008) or \code{"cancer"} (p20001 / p20006).}

\item{ignore_case}{(logical) Should regex matching ignore case?
Default: \code{TRUE}.}

\item{disease_cols}{(character or NULL) Column name(s) containing disease
text (p20002 or p20001). \code{NULL} = auto-detect via
\code{extract_ls()} cache.}

\item{date_cols}{(character or NULL) Column name(s) containing the
self-report year-month date (p20008 or p20006). \code{NULL} =
auto-detect.}

\item{visit_cols}{(character or NULL) Column name(s) containing the
baseline assessment date (p53). \code{NULL} = auto-detect.}
}
\value{
The input \code{data} with two new columns appended in-place:
\code{{name}_selfreport} (logical) and
\code{{name}_selfreport_date} (IDate). Always returns a
\code{data.table}.
}
\description{
Searches UKB self-reported illness fields across all instances and arrays,
matches records against a user-supplied regex, parses the associated
year-month date, and appends two columns to the data:
\code{{name}_selfreport} (logical) and \code{{name}_selfreport_date}
(\code{IDate}, earliest matching instance).
}
\details{
The function auto-detects the relevant columns using the
\code{extract_ls()} field dictionary cache (populated by
\code{extract_ls()} or \code{extract_pheno()}). The three \code{_cols}
parameters let you override auto-detection when column names have been
customised (e.g. after \code{decode_names()}).

\strong{Field mapping by \code{field}:}
\itemize{
\item \code{"noncancer"}: disease text = p20002, date = p20008.
\item \code{"cancer"}:    disease text = p20001, date = p20006.
}
Baseline visit date (p53) is used as a fallback when no specific
diagnosis date is recorded.

\strong{data.table pass-by-reference}: new columns are added in-place.
Pass \code{data.table::copy(data)} to preserve the original.
}
\examples{
\donttest{
dt <- ops_toy(n = 100)
# disease_cols / date_cols / visit_cols can be omitted — auto-detected from
# column names matching p20002_* / p20008_* / p53_* respectively
derive_selfreport(dt, name = "htn", regex = "hypertension",
                  field = "noncancer")
}
}
