README.qmd

---
format: gfm
---

<!-- README.md is generated from README.qmd. Please edit that file -->

```{r}
#| label: setup
#| echo: false
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# varicella <img src="man/figures/logo.png" width="200px" alt="epiworld logo" align="right">

<!-- badges: start -->
```{=markdown}
[![ForeSITE Group](https://github.com/EpiForeSITE/software/raw/e82ed88f75e0fe5c0a1a3b38c2b94509f122019c/docs/assets/foresite-software-badge.svg)](https://github.com/EpiForeSITE)
[![CRAN status](https://www.r-pkg.org/badges/version/varicella)](https://CRAN.R-project.org/package=varicella)
[![R-CMD-check](https://github.com/UofUEpiBio/varicella/actions/workflows/r.yml/badge.svg)](https://github.com/UofUEpiBio/varicella/actions/workflows/r.yml)
[![CRANlogs downloads](https://cranlogs.r-pkg.org/badges/grand-total/varicella)](https://cran.r-project.org/package=varicella)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/UofUEpiBio/varicella/blob/master/LICENSE.md)
[![codecov](https://codecov.io/gh/UofUEpiBio/varicella/graph/badge.svg?token=ZB8FVLI7GN)](https://app.codecov.io/gh/UofUEpiBio/varicella)
[![status](https://tinyverse.netlify.app/badge/varicella)](https://CRAN.R-project.org/package=varicella)
```
<!-- badges: end -->

## Overview

The **varicella** package is a specialized spinoff from [epiworldR](https://github.com/UofUEpiBio/epiworldR), focusing exclusively on varicella epidemiological models. This package provides fast, agent-based models (ABMs) for studying varicella transmission dynamics, vaccination strategies, and intervention policies.

Built on the powerful [epiworld](https://github.com/UofUEpiBio/epiworld) C++ library, these models leverage the speed and flexibility of epiworldR while providing specialized functionality for varicella outbreak modeling.

## Features

- **Fast simulation**: Leverages the high-performance C++ backend from epiworld
- **Specialized varicella models**: Three distinct models tailored for different scenarios
- **Flexible interventions**: Support for vaccination, quarantine, isolation, and contact tracing
- **Population mixing**: Models can account for different population groups with varying contact patterns
- **Risk-based strategies**: Advanced models support risk-stratified quarantine policies

## Models Included

Currently, the package includes three a single model:

1. **ModelVaricellaSchool**: A SLIHR (Susceptible-Latent-Infectious-Hospitalized-Recovered) model designed for school settings with isolation and quarantine policies.

## Installation

You can install the varicella package from GitHub:

```r
# install.packages("devtools")
devtools::install_github("UofUEpiBio/varicella")
```

Or from <a href="https://uofuepibio.r-universe.dev/"
target="_blank">R-universe</a> (recommended for the latest development
version):

``` r
install.packages(
  'varicella',
  repos = c(
    'https://uofuepibio.r-universe.dev',
    'https://cloud.r-project.org'
  )
)
```

## Quick Example

Here's a simple example using the ModelVaricellaSchool:

```{r}
#| label: example
library(varicella)

# Create a varicella model for a school with 500 students
model_school <- ModelVaricellaSchool(
  n = 500,
  contact_rate = 10 / .9 / 4, # R0 of 10
  prevalence = 1,
  prop_vaccinated = 0.70,
  quarantine_period = -1,
  vax_efficacy = 0.97
)

# Run the simulation
run_multiple(
  model_school,
  ndays = 200,
  seed = 1912,
  nsims = 400,
  saver = make_saver("outbreak_size"),
  nthreads = 4L
)
```

We can take a quick look at the last run using the `summary()` function:

```{r}
# View results
summary(model_school)
```

And we can extract the results (outbreak size in this case), using the function `run_multiple_get_results()`:

```{r}
#| label: plot-outcome
ans <- run_multiple_get_results(model_school)[[1]]
ans <- subset(ans, date == max(date))$outbreak_size
table(ans) |>
  prop.table() |>
  knitr::kable(
    col.names = c("Outbreak Size", "Proportion of Simulations"),
    digits = 3,
    caption = "Distribution of outbreak sizes across 400 simulations"
  )
```


## Relationship to epiworldR

This package is a spinoff from epiworldR, which provides a comprehensive framework for agent-based epidemiological models. While epiworldR includes many different disease models (SIR, SEIR, SIS, etc.), the varicella package focuses specifically on varicella-related models with specialized features for:

- Varicella-specific disease progression (incubation, prodromal, and rash periods)
- School-based outbreak scenarios
- Vaccination coverage and efficacy
- Quarantine and isolation policies
- Contact tracing strategies
- Risk-stratified interventions

For general-purpose epidemiological modeling or other disease types, please see the [epiworldR package](https://github.com/UofUEpiBio/epiworldR).

## Citation

If you use the varicella package in your research, please cite both this package and epiworldR:

```r
citation("varicella")
citation("epiworldR")
```


## Contributing

Contributions are welcome! Please see the [`varicella` development guidelines](https://github.com/UofUEpiBio/varicella/blob/main/DEVELOPMENT.md) for information on how to contribute.

## Acknowledgments

This project was made possible by cooperative agreement
CDC-RFA-FT-23-0069 from the CDC’s Center for Forecasting and Outbreak
Analytics. Its contents are solely the responsibility of the authors and
do not necessarily represent the official views of the Centers for
Disease Control and Prevention.