% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/get_variants.R
\name{get_variants}
\alias{get_variants}
\title{Parse SARS-CoV-2 VOC/VOI Variant Metadata from Excel}
\usage{
get_variants(tibble, check = FALSE)
}
\arguments{
\item{tibble}{A \code{tibble} or \code{data.frame} produced by
\code{\link[readxl]{read_excel}} from \code{SARS_CoV_2_VOC_VOI.xlsx}.
Column 1 must be the \code{Variant} field column; columns 2 onward are
one column per variant in the order listed above.}

\item{check}{Logical. If \code{TRUE}, validates that all internal vectors
have equal length and stops with an informative message on mismatch.
Default \code{FALSE}.}
}
\value{
A named list with 13 elements; see Details for full descriptions.
}
\description{
Reads a structured Excel workbook of SARS-CoV-2 Variants of
Concern (VOC) and Variants of Interest (VOI) and returns a named list
containing mutation profiles, nomenclature, temporal detection metadata,
defining SNPs, and a fully citable reference table with interactive
display support.
}
\details{
Intended to be called once during data preparation via
\code{data-raw/sarscov2_variants.R}:

\preformatted{
  variants_dat  <- readxl::read_excel("SARS_CoV_2_VOC_VOI.xlsx")
  variants_list <- get_variants(variants_dat)
  saveRDS(variants_list,
          file = "inst/extdata/sarscov2_variants.rds")
}

The saved object can then be loaded anywhere in the package or vignettes:

\preformatted{
  voc_data <- readRDS(system.file("extdata", "sarscov2_variants.rds",
                                  package = "ViralEntropR"))
}

\strong{Column order of variants in the Excel workbook:}
Alpha, Beta, Epsilon, Eta, Iota, Kappa, Delta, Lambda, Gamma, Zeta,
Theta, Omicron.

\strong{Returned list elements:}
\describe{
\item{\code{WHO_Label}}{List. WHO variant label strings (e.g. \code{"Alpha"}).}
\item{\code{Pango_Lineage}}{List. Pango lineage designations.}
\item{\code{GISAID_Clade}}{Character vector. GISAID clade strings.}
\item{\code{Nextstrain_Clade}}{Character vector. Nextstrain clade strings.}
\item{\code{Country_First_Detected}}{List. Country of first documented
detection per variant.}
\item{\code{Date_Earliest_Sample}}{Character vector. Month-Year of the
earliest documented sample per variant.}
\item{\code{Date_First_Detected}}{Character vector. Month-Year of
world-level first detection.}
\item{\code{Date_First_Detected_US}}{Character vector. Month-Year of
first US detection.}
\item{\code{Spike_Mutations}}{List. Spike protein mutation strings read
from the Excel workbook.}
\item{\code{Mutation_Sites}}{List. Integer site positions extracted from
\code{Spike_Mutations}.}
\item{\code{Defining_SNPs}}{List. Canonical defining SNP strings per
variant (\code{NA} where not characterised).}
\item{\code{Defining_SNP_Sites}}{List. Integer positions extracted from
\code{Defining_SNPs}.}
\item{\code{References}}{Named list with three elements:
\code{$data} — data frame of 21 verified references;
\code{$display(variant = NULL)} — interactive \code{\link[DT]{datatable}},
optionally filtered by WHO label;
\code{$cite(variant)} — character vector of formatted citation strings
suitable for manuscript use.}
}
}
\keyword{internal}
