---
title: "Using RCMsize for Malaria Research"
output: 
  rmarkdown::html_vignette:
    toc: true
vignette: >
  %\VignetteIndexEntry{Using_RCMsize_for_Malaria_Research}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---


# Introduction
This package is designed primarily to calculate the sample size required for studies where the main outcome measure is the seroconversion rate (`SCR`). It provides tools to compute the probability of an individual being seropositive, given specific parameters such as the seroconversion rate (`SCR`) , the seroreversion rate (`SRR`), and the individual's age, using a reversible catalytic model.
Additionally, the package allows for the calculation of seroprevalence (`SP`) and its corresponding confidence interval. From the confidence interval of seroprevalence, users can back-transform to obtain the confidence interval for the seroconversion rate. Furthermore, the package allows for the calculation of sample size while controlling for the relative length (width) of the confidence interval for the seroconversion rate.

# Installation
To install the RCMsize package from GitHub, use one of the following commands:
```{r, eval=FALSE}
devtools::install_github("https://github.com/marciagraca/RCMsize")
remotes::install_github("https://github.com/marciagraca/RCMsize")
```
After the installation is complete, you can load the RCMsize package into your R session by running:

```{r setup}
library(RCMsize)
```
# Functions
## 1. **`prob_seropositive`** – Calculation of Seropositivity Probability

### Description:
This function calculates the probability of seropositivity for a given age, based on the seroconversion rate (`SCR`) and the seroreversion rate (`SRR`). It uses a reversible catalytic model to calculate the probability that an individual will be seropositive at a specific age.

### Parameters:
- `SCR`: The seroconversion rate.
- `SRR`: The seroreversion rate.
- `t`: The age of the individual.

### Example:


```{r}
prob_seropositive(0.03, 0.01, 45)
```

## **`seroprevalence`** – Seroprevalence Calculation

### Description:
This function calculates the seroprevalence (the proportion of individuals who are seropositive) in a population, considering an age distribution and using a reversible catalytic model. It aggregates the probability of seropositivity across different ages to provide a total estimate of seroprevalence for the population.

### Parameters:
- `ages`: A vector representing the distribution of ages in the population.
- `A_max`: The maximum age in the population.
- `SCR`: The seroconversion rate.
- `SRR`: The seroreversion rate.

### Example:

```{r}
seroprevalence(rep(1 / 80, 80), 80, 0.03, 0.01)
```

## **`IC_SP`** – Confidence Interval for Seroprevalence

### Description:
This function calculates the confidence interval for a seroprevalence estimate using a specified confidence level. It employs binomial confidence interval methods to compute the lower and upper bounds of the interval based on the given seroprevalence estimate and sample size. This function uses some of the methods available in the binom.confint function of the binom package (see the references for a link to the package).

### Parameters:
- `SP`: The estimated seroprevalence value (proportion of seropositive individuals).
- `n`: The sample size used for the estimation.
- `conf.level`: The desired confidence level (default is 0.95, representing 95% confidence).
- `method`: The method to calculate the confidence interval (default is "asymptotic"). Available methods: c("asymptotic","exact","ac","wilson","logit","cloglog")

### Example:

```{r}
IC_SP(0.25, 100, conf.level = 0.95, method = "asymptotic")
```

## **`IC_SP_Waldcc`** – Confidence Interval for Seroprevalence with Continuity Correction (Wald Method)

### Description:
This function calculates the confidence interval for seroprevalence using the Wald method with a continuity correction. The continuity correction is applied by subtracting  from the lower limit and adding to the upper limit 1/(2n).

### Parameters:
- `SP`: The estimated seroprevalence value (proportion of seropositive individuals).
- `n`: The sample size used for the estimation.
- `conf.level`: The desired confidence level (default is 0.95, representing 95% confidence).

### Example:

```{r}
IC_SP_Waldcc(0.25, 100, conf.level = 0.95)
```

## **`IC_SCR`** – Confidence Interval for the Seroconversion Rate (`SCR`)

### Description:
This function calculates the confidence interval for the seroconversion rate (`SCR`) using the confidence interval of seroprevalence. The function uses numerical methods to solve for the SCR that results in the observed seroprevalence.

### Parameters:
- `SP_interval`: A vector containing the lower and upper limits of the confidence interval for the seroprevalence.
- `SRR`: The seroreversion rate.
- `ages`: A vector with the distribution of ages in the population.
- `A_max`: The maximum age in the population.
- `limits`: A vector specifying the lower and upper bounds for the SCR (default is `c(0, 1)`).

### Example:

```{r}
IC_SCR(c(0.1, 0.2), 0.01, rep(1 / 80, 80), 80, limits = c(0, 1))
```
## **`sample_s`** – Sample Size Calculation

### Description:
This function estimates the required sample size so that the relative width of the confidence interval for the seroconversion rate (`SCR`) is equal to a specified value (`RL`). The function calculates the necessary sample size by iteratively adjusting the sample size until the confidence interval for SCR meets the desired width criteria. This calculation is based on the seroprevalence, confidence intervals for seroprevalence, and the seroconversion rate.

### Parameters:
- `SCR`: The seroconversion rate.
- `RL`: The desired relative width for the confidence interval width for the seroconversion rate.
- `SRR`: The seroreversion rate.
- `ages`: A vector representing the distribution of ages in the population.
- `A_max`: The maximum age in the population.
- `limits`: The lower and upper limits for the `SCR`.
- `max_iter`: The maximum number of iterations for adjusting the sample size (default is 10000).
- `conf.level`: The confidence level for the confidence interval (default is 0.95).
- `method`: The method for calculating the confidence interval for seroprevalence, default is `"asymptotic"`.

### Example:

```{r}
A_max <- 80
age_distribution <- rep(1 / A_max, A_max)
sample_s(0.03, 1, 0.01, age_distribution, A_max, limits = c(0, 1))
```

# References

For more information on reversible catalytic models, please refer to the following [article](https://link.springer.com/article/10.1186/s12936-015-0661-z).

For details about the binom package, see the [link](https://CRAN.R-project.org/package=binom).
