% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ViralEntropR-package.R
\docType{package}
\name{ViralEntropR-package}
\alias{ViralEntropR}
\alias{ViralEntropR-package}
\title{ViralEntropR: A Computational Pipeline for Entropy-Informed Detection of Emerging Viral Variants}
\description{
A computational pipeline for detecting emerging variants in viral amino
acid sequence data, combining per-site Shannon entropy, Gaussian mixture
model site selection, Gower-distance Partitioning Around Medoids
clustering, Hellinger-distance quantification of distributional shifts,
and multivariate non-parametric change-point detection.
}
\section{Pipeline overview}{

The package supports a four-stage workflow:
\itemize{
\item \strong{Preprocessing.} Parse FASTA headers, filter ambiguous
residues, and convert between integer and character representations
of amino acid sequences under a 25-symbol alphabet. See
\code{\link{extract_fasta_dates}},
\code{\link{extract_fasta_countries}},
\code{\link{fasta_to_char_matrix}},
\code{\link{filter_ambiguous_sequences}},
\code{\link{encode_aa_sequence}}, and
\code{\link{decode_aa_sequence}}.
\item \strong{Site selection.} Compute per-site Shannon entropy across
temporal partitions and cluster sites by entropy via Gaussian
mixture models. See \code{\link{calculate_entropy}},
\code{\link{partition_time_windows}},
\code{\link{cluster_sites_by_entropy}}, and
\code{\link{relabel_entropy_classes}}.
\item \strong{Distributional analysis.} Quantify residue-composition
shifts between time windows using the Hellinger distance. See
\code{\link{calculate_hellinger_matrix}}.
\item \strong{Change-point detection.} Identify temporal change points
non-parametrically using energy statistics or wild binary
segmentation. See \code{\link{detect_changepoints_ecp}} and
\code{\link{detect_changepoints_hdcp}}.
}
}

\section{Visualisation and tabulation}{

\itemize{
\item \code{\link{plot_entropy_trajectories}} — customizable multi-site
Shannon entropy trajectories, summarizing evolutionary dynamics
across time.
\item \code{\link{plot_site_class_trajectory}} — single-site entropy
trajectory with class-change markers for inspecting individual
residues of interest.
\item \code{\link{tabulate_site_evolution}} — per-site amino acid
count and proportion tables across partitions, optionally
rendered as styled HTML.
}
}

\section{Simulation}{

\code{\link{simulate_variant_evolution}} provides a configurable
multi-variant simulation engine with user-specified emergence
schedules, growth rates, mutation-rate variability, and
deleterious-mutation injection. Generates synthetic time-series data
with known ground truth for benchmarking detection pipelines.
}

\section{Bundled data}{

\itemize{
\item \code{\link{sarscov2_variants}} — curated metadata for twelve
SARS-CoV-2 Variants of Concern and Variants of Interest, including
WHO labels, Pango lineages, GISAID and Nextstrain clades, dates
and countries of first detection, defining Spike-protein
mutations and SNP sites, and 21 peer-reviewed references with DOIs.
\item \code{\link{sarscov2_sample}} — a random sample of 100 NCBI Spike
protein sequences for end-to-end testing without external downloads.
}
}

\section{External data}{

The complete preprocessed NCBI Spike protein dataset (137,132
sequences, ~181.5 MB uncompressed FASTA) underlying the package's
real-data pre-processing vignette is archived on Zenodo:
\doi{10.5281/zenodo.19040165}. The dataset can be read directly with
\code{\link[Biostrings]{readAAStringSet}} and processed end-to-end
using the preprocessing toolkit; see
\code{vignette("preprocessing_pipeline", "ViralEntropR")} for the
full workflow.
}

\section{Vignettes}{

Three pre-rendered vignettes walk through the full workflow on real
and simulated data: \code{vignette("preprocessing_pipeline",
"ViralEntropR")}, \code{vignette("detecting_variants_simulation",
"ViralEntropR")}, and \code{vignette("clustering_accuracy",
"ViralEntropR")}.
}

\seealso{
Useful links:
\itemize{
  \item \url{https://github.com/vadimtyuryaev/ViralEntropR}
  \item \doi{10.5281/zenodo.19040165}
  \item \url{https://vadimtyuryaev.github.io/ViralEntropR/}
  \item Report bugs at \url{https://github.com/vadimtyuryaev/ViralEntropR/issues}
}

}
\author{
\strong{Maintainer}: Vadim Tyuryaev \email{vadim.tyuryaev@gmail.com} (\href{https://orcid.org/0009-0008-1361-6265}{ORCID})

Authors:
\itemize{
  \item Jane Heffernan \email{jmheffer@yorku.ca}
  \item Hanna Jankowski \email{hkj@yorku.ca}
}

}
\keyword{internal}
