#' SARS-CoV-2 Surface Glycoprotein Sequences -- NCBI Demo Sample
#'
#' @description
#' A compressed FASTA file containing a random sample of size 100 of SARS-CoV-2
#' surface glycoprotein (Spike protein) amino acid sequences, drawn from a
#' dataset of 137,132 complete sequences downloaded from the NCBI SARS-CoV-2
#' Data Hub on October 12, 2021. Intended to demonstrate the full
#' \code{ViralEntropR} pipeline on real-world surveillance data.
#'
#' @details
#' The file is accessed at runtime via:
#' \preformatted{
#' path  <- system.file("extdata", "sarscov2_sample.fasta.gz",
#'                      package = "ViralEntropR")
#' fasta <- Biostrings::readAAStringSet(path)
#' }
#'
#' \strong{Sample file contents:}
#' \itemize{
#'   \item \strong{Sample size}: 100 random sequences
#'   \item \strong{Protein}: Surface glycoprotein (Spike, S protein)
#'   \item \strong{Organism}: \emph{Severe acute respiratory syndrome
#'     coronavirus 2} (SARS-CoV-2), NCBI Taxonomy ID: 2697049
#'   \item \strong{Completeness}: Complete sequences only
#'   \item \strong{Format}: Gzip-compressed FASTA (\code{.fasta.gz}),
#'     readable directly by \code{\link[Biostrings]{readAAStringSet}}
#' }
#'
#' \strong{Full dataset:}
#' The complete 137,132-sequence dataset (~181.5 MB, uncompressed FASTA) is
#' archived on Zenodo (DOI: \doi{10.5281/zenodo.19040165});
#' \code{\link[Biostrings]{readAAStringSet}} reads it directly.
#'
#' \strong{Header format:}
#' Sequence headers follow the NCBI Virus export format. Dates and countries
#' can be extracted directly using the package helper functions:
#' \preformatted{
#' dates     <- extract_fasta_dates(fasta, option = 1)
#' countries <- extract_fasta_countries(fasta, position = 2)
#' }
#'
#' \strong{Subsampling:}
#' To keep the package within CRAN size limits, the bundled sample was
#' generated by random sampling of 100 sequences. The full provenance and
#' reproducible sampling script are in \code{data-raw/sarscov2_ncbi.R} in
#' the package source.
#'
#' @section Provenance:
#' Downloaded from the NCBI SARS-CoV-2 Data Hub
#' (\url{https://www.ncbi.nlm.nih.gov/labs/virus/vssi/}) on
#' \strong{October 12, 2021} with the following filters:
#' \enumerate{
#'   \item Virus: Severe acute respiratory syndrome coronavirus 2
#'     (SARS-CoV-2), taxid: 2697049
#'   \item Nucleotide completeness: complete
#'   \item Protein: surface glycoprotein
#' }
#' Result: \strong{n = 137,132 sequences}, file size ~181.5 MB (uncompressed).
#'
#' @section License:
#' NCBI sequence data is a US Government work and is in the public domain
#' within the United States. Data from international contributors is subject
#' to the INSDC open-access policy (Karsch-Mizrachi et al., 2025;
#' \doi{10.1093/nar/gkae1058}). The compiled dataset is released under
#' CC0 1.0 Universal. Individual GenBank accession numbers in the FASTA
#' headers provide full traceability to original submissions.
#'
#' @format A gzip-compressed FASTA file (\code{.fasta.gz}) readable by
#'   \code{\link[Biostrings]{readAAStringSet}}. Each record contains:
#'   \describe{
#'     \item{Header}{NCBI Virus format: accession, country, and collection date 
#'     metadata separated by \code{|}.}
#'     \item{Sequence}{Amino acid sequence using the standard IUPAC one-letter
#'       code. Ambiguous residues (B, X, Z) and gaps (-) may be present and
#'       can be removed with \code{\link{filter_ambiguous_sequences}}.}
#'   }
#'
#' @name sarscov2_sample
#'
#' @source \url{https://www.ncbi.nlm.nih.gov/labs/virus/vssi/}
#'
#' @references
#' Clark K, Karsch-Mizrachi I, Lipman DJ, Ostell J, Sayers EW (2016).
#' GenBank.
#' \emph{Nucleic Acids Research}, 44(D1), D67--D72.
#' \doi{10.1093/nar/gkv1276}
#'
#' Sayers EW, Bolton EE, Brister JR, et al. (2022).
#' Database resources of the National Center for Biotechnology Information.
#' \emph{Nucleic Acids Research}, 50(D1), D20--D26.
#' \doi{10.1093/nar/gkab1112}
#'
#' NCBI Virus \[Internet\]. Bethesda (MD): National Library of Medicine (US),
#' National Center for Biotechnology Information; \[2020\] --
#' \[cited 2021 Oct 12\]. Available from:
#' \url{https://www.ncbi.nlm.nih.gov/labs/virus/vssi/}
#'
#' @examples
#' \donttest{
#' path  <- system.file("extdata", "sarscov2_sample.fasta.gz",
#'                      package = "ViralEntropR")
#' fasta <- Biostrings::readAAStringSet(path)
#'
#' # Number of sequences in the demo sample
#' length(fasta)
#'
#' # Inspect first 3 headers
#' names(fasta)[1:3]
#'
#' # Extract collection dates
#' dates <- extract_fasta_dates(fasta, option = 1)
#' head(dates$corrected_dates)
#'
#' # Extract countries
#' countries <- extract_fasta_countries(fasta, position = 2)
#' table(countries$countries)
#'
#' # Convert to character matrix for pipeline entry
#' char_mat <- fasta_to_char_matrix(fasta)
#' dim(char_mat)
#'
#' # The full 137,132-sequence dataset (~181.5 MB) is available on Zenodo:
#' # https://zenodo.org/records/19040165
#' # Download sequences.fasta manually and load with:
#' # fasta_full <- Biostrings::readAAStringSet("path/to/sequences.fasta")
#' }
NULL


#' SARS-CoV-2 VOC/VOI Curated Variant Metadata
#'
#' @description
#' A pre-built named list containing curated biological and epidemiological
#' metadata for 12 SARS-CoV-2 Variants of Concern (VOC) and Variants of
#' Interest (VOI): Alpha, Beta, Delta, Epsilon, Eta, Gamma, Iota, Kappa, Lambda, 
#' Omicron, Theta, Zeta. Includes mutation profiles, nomenclature,
#' temporal detection records, defining SNPs, and a fully citable reference
#' table with 21 verified references.
#'
#' @details
#' The object is available automatically after \code{library(ViralEntropR)}
#' via lazy loading. It is produced by \code{\link{get_variants}} from the
#' curated Excel workbook \code{SARS_CoV_2_VOC_VOI.xlsx} (not bundled with
#' the package; see \code{data-raw/sarscov2_variants.R} for the reproducible
#' build script).
#'
#' \strong{List elements:}
#' \describe{
#'   \item{\code{WHO_Label}}{List of 12. WHO variant label strings
#'     (e.g. \code{"Alpha"}, \code{"Omicron"}).}
#'   \item{\code{Pango_Lineage}}{List of 12. Pango lineage designations
#'     (e.g. \code{"B.1.1.7"}).}
#'   \item{\code{GISAID_Clade}}{Character(12). GISAID clade strings
#'     (e.g. \code{"GRY"}, \code{"GR/484A"}).}
#'   \item{\code{Nextstrain_Clade}}{Character(12). Nextstrain clade strings
#'     (e.g. \code{"20I/501Y.V1"}).}
#'   \item{\code{Country_First_Detected}}{List of 12. Country of first
#'     documented detection per variant.}
#'   \item{\code{Date_Earliest_Sample}}{Character(12). Month-Year of earliest
#'     documented sample (e.g. \code{"Sep-2020"}).}
#'   \item{\code{Date_First_Detected}}{Character(12). Month-Year of
#'     world-level first detection.}
#'   \item{\code{Date_First_Detected_US}}{Character(12). Month-Year of first
#'     US detection.}
#'   \item{\code{Spike_Mutations}}{List of 12. Character vectors of Spike
#'     protein mutations per variant, read from the Excel workbook.}
#'   \item{\code{Mutation_Sites}}{List of 12. Integer vectors of amino acid
#'     positions extracted from \code{Spike_Mutations}.}
#'   \item{\code{Defining_SNPs}}{List of 12. Canonical defining SNP strings
#'     (\code{NA} for variants not characterised in the reference set).}
#'   \item{\code{Defining_SNP_Sites}}{List of 12. Integer positions extracted
#'     from \code{Defining_SNPs}.}
#'   \item{\code{References}}{Named list with three elements:
#'     \code{$data} -- data frame of 21 verified references (columns: ID,
#'     Authors, Year, Title, Journal_Source, Volume_Issue_Pages, DOI, URL,
#'     Type, Variants_Covered, Data_Field, Citation);
#'     \code{$display(variant = NULL)} -- renders an interactive
#'     \code{\link[DT]{datatable}}, optionally filtered by WHO label
#'     (requires the \pkg{DT} package);
#'     \code{$cite(variant)} -- returns formatted citation strings for a
#'     given WHO label, suitable for manuscript use.}
#' }
#'
#' @section References:
#' The 21 curated references cover peer-reviewed articles, CDC MMWR government
#' reports, and outbreak.info surveillance database records. Full provenance
#' is available via \code{sarscov2_variants$References$data} or the
#' interactive display.
#'
#' @format A named list of 13 elements (12 metadata fields plus a structured 
#' References object). See Details for per-element descriptions.
#'
#' @docType data
#'
#' @usage data(sarscov2_variants)
#'
#' @source
#' Compiled from 21 peer-reviewed and surveillance sources; see
#' \code{sarscov2_variants$References$data} for the full reference table
#' with DOIs and URLs. Built from \code{SARS_CoV_2_VOC_VOI.xlsx} via
#' \code{\link{get_variants}}.
#'
#' @examples
#' # Object is available immediately after library(ViralEntropR)
#'
#' # --- Basic access ---------------------------------------------------------
#'
#' # All 12 WHO labels
#' unlist(sarscov2_variants$WHO_Label)
#'
#' # Pango lineage for Alpha
#' sarscov2_variants$Pango_Lineage[[
#'   which(unlist(sarscov2_variants$WHO_Label) == "Alpha")
#' ]]
#'
#' # World detection dates for all variants
#' data.frame(
#'   Variant  = unlist(sarscov2_variants$WHO_Label),
#'   Detected = sarscov2_variants$Date_First_Detected,
#'   Country  = unlist(sarscov2_variants$Country_First_Detected)
#' )
#'
#' # --- Mutation sites -------------------------------------------------------
#'
#' # Defining SNPs and sites for Delta
#' idx <- which(unlist(sarscov2_variants$WHO_Label) == "Delta")
#' sarscov2_variants$Defining_SNPs[[idx]]
#' sarscov2_variants$Defining_SNP_Sites[[idx]]
#'
#' # All Spike mutation sites for Omicron
#' sarscov2_variants$Mutation_Sites[[
#'   which(unlist(sarscov2_variants$WHO_Label) == "Omicron")
#' ]]
#'
#' # --- Nomenclature ---------------------------------------------------------
#'
#' data.frame(
#'   WHO        = unlist(sarscov2_variants$WHO_Label),
#'   PANGO      = unlist(sarscov2_variants$Pango_Lineage),
#'   GISAID     = sarscov2_variants$GISAID_Clade,
#'   Nextstrain = sarscov2_variants$Nextstrain_Clade
#' )
#'
#' # --- References -----------------------------------------------------------
#'
#' # Full reference data frame (21 rows)
#' sarscov2_variants$References$data[,
#'   c("ID", "Authors", "Year", "Journal_Source")
#' ]
#'
#' # Formatted citation strings for Gamma
#' sarscov2_variants$References$cite("Gamma")
#'
#' if (interactive() && requireNamespace("DT", quietly = TRUE)) {
#'   # Interactive DT table of all references
#'   sarscov2_variants$References$display()
#'
#'   # Filtered to Omicron references only
#'   sarscov2_variants$References$display(variant = "Omicron")
#' }
"sarscov2_variants"

