% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/decode.R
\name{decode_values}
\alias{decode_values}
\title{Decode UKB categorical column values using Showcase metadata}
\usage{
decode_values(data, metadata_dir = "data/metadata/")
}
\arguments{
\item{data}{(data.frame or data.table) Data from \code{extract_pheno()},
with column names in \code{participant.pXXXX} or \code{pXXXX_iX} format.}

\item{metadata_dir}{(character) Directory containing \code{field.tsv} and
\code{esimpint.tsv}. Default: \code{"data/metadata/"}.}
}
\value{
The input \code{data} with categorical columns replaced by character
labels. Returns a \code{data.table} if the input is a \code{data.table}.
}
\description{
Converts raw integer codes produced by \code{\link{extract_pheno}} into
human-readable labels for all categorical fields
(\code{value_type} 21 and 22), using the UKB Showcase encoding tables.
Continuous, text, date, and already-decoded columns are left unchanged.
}
\details{
This function requires two metadata files downloaded from the UKB Research
Analysis Platform:
\itemize{
\item \code{field.tsv} - maps field IDs to encoding IDs and value types.
\item \code{esimpint.tsv} - maps encoding ID + integer code to label.
}
Download them once with:
\preformatted{
fetch_metadata(dest_dir = "data/metadata")
}
Both files are cached in the session after the first read.

\strong{Call order}: use \code{decode_values()} \emph{before}
\code{\link{decode_names}}, so that column names still contain the numeric
field ID needed to look up the encoding.
}
\examples{
\dontrun{
# Download metadata once
fetch_metadata(dest_dir = "data/metadata")

# Recommended call order
df <- extract_pheno(c(31, 54, 20116, 21000))
df <- decode_values(df)                  # 0/1 → "Female"/"Male", etc.
df <- decode_names(df)                   # participant.p31 → sex
}
}
