---
title: "Getting Started with SampleSizeR"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting Started with SampleSizeR}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
library(SampleSizeR)
```

# Introduction

`SampleSizeR` provides functions for sample size determination in
epidemiological, clinical, and diagnostic studies. The package provides
a consistent interface and returns standardized `SampleSizeR` objects.

# Prevalence Study

The required sample size for estimating a prevalence of 20% with an
absolute precision of 5% can be calculated as follows:

```{r prevalence}
ss_prevalence(
  prevalence = 0.20,
  precision = 0.05
)
```

# Cohort Study

For a cohort study with a baseline risk of 10% and a risk ratio of 2:

```{r cohort}
ss_cohort(
  p0 = 0.10,
  risk.ratio = 2
)
```

# Case-Control Study

For an unmatched case-control study designed to detect an odds ratio
of 2 when the exposure proportion among controls is 15%:

```{r case-control}
ss_case_control(
  odds.ratio = 2.0,
  p0 = 0.15,
  alpha = 0.05,
  power = 0.80,
  ratio = 1
)
```

# Diagnostic Sensitivity

For a diagnostic test with an anticipated sensitivity of 90%, disease
prevalence of 20%, and desired absolute precision of 5%:

```{r diagnostic-sensitivity}
ss_diagnostic_sensitivity(
  sensitivity = 0.90,
  prevalence = 0.20,
  precision = 0.05,
  conf.level = 0.95
)
```

# Diagnostic Specificity

The required sample size for estimating diagnostic specificity can be
calculated similarly:

```{r diagnostic-specificity}
ss_diagnostic_specificity(
  specificity = 0.90,
  prevalence = 0.20,
  precision = 0.05,
  conf.level = 0.95
)
```

# ROC AUC

A precision-based sample size calculation for an anticipated ROC AUC
of 0.80 can be performed as follows:

```{r diagnostic-auc}
ss_diagnostic_auc(
  auc = 0.80,
  prevalence = 0.20,
  precision = 0.05,
  design = "precision",
  method = "obuchowski"
)
```

# Diagnostic Agreement

For a diagnostic agreement study, the Pearson method uses a multinomial
Pearson goodness-of-fit effect size with a non-central chi-square
approximation.

```{r diagnostic-agreement}
ss_diagnostic_agreement(
  kappa1 = 0.70,
  kappa0 = 0.40,
  prevalence = 0.50,
  alpha = 0.05,
  power = 0.80,
  method = "pearson"
)
```

# Working with Results

Functions in `SampleSizeR` return objects of class `SampleSizeR`.
Standard S3 methods can therefore be used to inspect and manipulate
results.

```{r result-methods}
result <- ss_prevalence(
  prevalence = 0.20,
  precision = 0.05
)

print(result)
summary(result)
as.data.frame(result)
```

A graphical representation can also be produced:

```{r plot, eval=FALSE}
plot(result)
```

# Summary

`SampleSizeR` provides a unified interface for sample size determination
across epidemiological, clinical, and diagnostic study designs. Optional
adjustments available across applicable functions include finite
population correction, design effects, anticipated response rates, and
dropout.