---
title: "Choosing Sample Size for Evaluating a Diagnostic Test"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Choosing Sample Size for Evaluating a Diagnostic Test}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

## Introduction

The `SampleSizeDiagnostics` package provides a function for calculating the sample size needed for evaluating a diagnostic test based on sensitivity, specificity, prevalence, and desired precision.

In this vignette, we will demonstrate how to use the `SampleSizeDiagnostics` function to calculate the necessary sample size for different scenarios.

## Example Usage

Load the package:

```r
library(SampleSizeDiagnostics)
```

## Basic Example

Let's calculate the sample size needed for a diagnostic test with the following parameters:

    Sensitivity: 0.9
    Specificity: 0.85
    Prevalence: 0.2
    Desired half-width (margin of error) of the confidence interval: 0.1
      (This creates a total CI width of 0.2: estimate ±0.1)
    Confidence interval level: 0.95
    
```r
result <- SampleSizeDiagnostics(sn = 0.9, sp = 0.85, p = 0.2, w = 0.1, CI = 0.95)
print(result)
```

## Varying the Confidence Interval

You can also calculate the sample size with a different confidence interval level, for example, 0.9:

```r
result <- SampleSizeDiagnostics(sn = 0.9, sp = 0.85, p = 0.2, w = 0.1, CI = 0.9)
print(result)
```

## Interpretation of Results

The function returns a data frame containing the calculated sample sizes and input parameters. Here is a breakdown of the output:

    Precision: Desired half-width of the CI (margin of error). Total width = 2 × Precision
    Sensitivity: Sensitivity of the diagnostic test
    Specificity: Specificity of the diagnostic test
    Prevalence: Prevalence of the disease
    N1: Sample size for sensitivity
    N2: Sample size for specificity
    Total_Subjects: Total sample size needed (maximum of N1 and N2)
    CI: Confidence interval level

## Understanding the Width Parameter

**IMPORTANT:** The parameter `w` represents the **half-width** or **margin of error** 
of the confidence interval, NOT the total width. This follows Buderer (1996).

### Example Interpretation

If you set `w = 0.1` with expected sensitivity = 0.9:
- **Point estimate:** 0.90
- **Margin of error (w):** ±0.1
- **95% CI:** [0.80, 1.00]
- **Half-width:** 0.1
- **Total CI width:** 0.20

### Common Mistake ⚠️

❌ **Wrong:** "I want a CI spanning 0.10 total, so I'll use w = 0.1"  
✅ **Correct:** "I want a CI spanning 0.10 total, so I'll use w = 0.05"

### Reference

From Buderer (1996), page 896:
> "The width of a 95% CI, where the width is given by 1.96 × (SE), gives the precision 
> in the estimates... **(the total length of the CI is 2 × width).**"