Point of contact: Richard A. Erickson (rerickson@usgs.gov)
Digital Object Identifier (DOI): https://doi.org/10.5066/XXXXXXXXXX
Suggested Citation:
Erickson, RA; Larson, DM; Lafferty, KD. 2026. multiDetectR. Version 0.1.0. U.S. Geological Survey software release. Reston, Va. https://doi.org/10.5066/XXXXXXXX
Authors' ORCID nos.:
- Richard A. Erickson 0000-0003-4649-482X
- Danelle M. Larson 0000-0001-6349-6267
- Kevin D. Lafferty 0000-0001-7583-4593
Repository: github.com/DOI-USGS/multiDetectR
Exact allocation of detection effort across the levels of a nested survey, at any depth.
A survey that looks for a target (a species, an infectious agent, a
contaminant) often nests its sampling: sites hold samples, samples hold
replicates, and so on. Each level has its own cost and its own detectability,
and a fixed budget must be split among them. multiDetectR implements the
closed-form rule that solves this allocation exactly, for any number of levels,
and reproduces the paper's own numerical checks as unit tests.
The package models a nested survey as a cascade of conditional Bernoulli trials and measures detection on a log (nat) scale, so the design problem separates into a chain of one-variable problems solved from the innermost level outward. Function and argument names mirror the equations of the accompanying manuscript.
if (!require("remotes")) install.packages("remotes")
remotes::install_github("DOI-USGS/multiDetectR")library(multiDetectR)
## Allocate a budget across a three-level eDNA survey
## (sites -> samples -> PCR replicates).
des <- allocate(
theta = c(0.3, 0.5, 0.6), # per-level conditional detectabilities
cost = c(200, 20, 2), # per-level unit costs
goal = "detection",
budget = 5000
)
des
summary(des)
plot(des) # the budget-detection frontierSupply P_target instead of budget to find the cheapest design that reaches a
required detection probability. Use goal = "count" for the count goal,
enumerate_designs() for the exact integer optimum at small budgets,
optimality_identity() to audit a costed design, and allocate_branches() to
choose among methods or places.
See vignette("multiDetectR") for a walkthrough.
| Function | What it does | Manuscript |
|---|---|---|
detection_recursion() |
detection probability of a nested design | eqs 1-2 |
total_cost(), unit_cost_full() |
cost of a design | eqs 3, 8 |
nats(), prob() |
detection <-> hazard (nats) | log scale |
solve_level() |
optimal effort at one level | eqs 14, 15 |
allocate() |
the exact innermost-outward pass | eqs 4-6, 10-13 |
enumerate_designs() |
exact integer optimum | Supplement S2 |
optimality_identity() |
audit a design (A = B) | Supplement S1.8 |
allocate_branches() |
concentrate vs spread | Supplement S1.5 |
This repository contains the code for an R package and the standard R repository files (see the official R documentation Writing R Extensions or R Packages). In addition to the R package source files, the main level of the repository contains:
README.md, which is this file..gitignore, a Git ignore file for the repository..Rbuildignore, the list of files ignored when building the R package.LICENSE, the license for the software (CC0 1.0 Universal, public domain dedication).CONTRIBUTING.md, which describes how to contribute to this project.DISCLAIMER.md, the standard USGS disclaimer.code.json, the required machine-readable metadata about the code.
The reproducible analyses that feed the manuscript, the vignettes, and the Shiny app live under data-raw/analysis/.
That directory is excluded from the built package by .Rbuildignore, so the installable package stands alone.
See DISCLAIMER.md. This software is preliminary or provisional and is subject
to revision.
CC0 1.0 Universal (public domain dedication). See LICENSE.