---
title: "Using diagcounts"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Using diagcounts}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

## Motivation

Diagnostic accuracy studies frequently report summary measures such as
sensitivity, specificity, predictive values, and prevalence, but omit the
underlying 2×2 table counts (true positives, false negatives, false positives,
and true negatives). These counts are often required for downstream analyses,
including meta-analysis, decision modeling, and health economic evaluation.

The **diagcounts** package implements a system of linear equations to recover
these unreported counts when a sufficient set of accuracy measures is available.

---

## Basic usage

The primary function is `derive_counts()`. Users supply the total sample size
and any combination of reported diagnostic accuracy measures that uniquely
identify the underlying 2×2 table.

```r
library(diagcounts)

res <- derive_counts(
  n = 105,
  sensitivity = 0.6,
  specificity = 0.893,
  prevalence = 0.733
)

res
```

The function returns integer-valued counts:

```r
as.table(res)
```

---

## Alternative combinations of inputs

Any identifiable combination of accuracy measures may be used. For example,
counts can also be recovered using predictive values:

```r
derive_counts(
  n = 200,
  sensitivity = 0.75,
  ppv = 0.82,
  npv = 0.70
)
```

Internally, the package constructs and solves a system of linear equations
corresponding to the supplied measures.

---

## Infeasible systems

If the supplied measures do not uniquely identify a valid 2×2 table, or if the
resulting system is mathematically inconsistent, `derive_counts()` will stop
with an error:

```r
# Not enough information
# derive_counts(n = 100, sensitivity = 0.8)
```

This behavior is intentional and ensures that returned counts are both
mathematically and epidemiologically valid.

---

## Discussion

The methods implemented in `diagcounts` focus on settings in which the
system of equations is exactly identified and yields a unique integer
solution. Extensions to partially identified systems and bound-based
solutions, as discussed in the accompanying paper, may be considered in
future versions of the package.


## References

Xie X, Wang M, Antony J, Vandersluis S, Kabali CB (2025).
*System of Linear Equations to Derive Unreported Test Accuracy Counts*.
Statistics in Medicine. https://doi.org/10.1002/sim.70336