multiDetectR

Authors: Richard A. Erickson, Danelle M. Larson, Kevin D. Lafferty

Point of contact: Richard A. Erickson (rerickson@usgs.gov)

Repository Type: R package

Year of Origin: 2026

Year of Version: 2026

Version: 0.1.0

Digital Object Identifier (DOI): https://doi.org/10.5066/XXXXXXXXXX

USGS Information Product Data System (IPDS) no.: IP-XXXXXXX (internal agency tracking)

---

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.

Installation

if (!require("remotes")) install.packages("remotes")
remotes::install_github("DOI-USGS/multiDetectR")

Quick start

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 frontier

Supply 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.

What the functions compute

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

Repository organization

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/, each as a targets workflow with its own README:

• marine_r12c/ — the marine optimization example (the mixture-model fits, the one-pass allocation rule, the rule-vs-grid validation, and the location curves) on release r12c of the Point Conception data.
• marine/ — the marine cost-and-richness analysis (the Bayesian power-law richness model and the Pareto front) from the precomputed design table.
• carp/ — the freshwater (Burns Harbor) example: two-level occStan occupancy fits, species accumulation, and turnover.

That directory is excluded from the built package by .Rbuildignore, so the installable package stands alone.

Data sources

The two worked examples draw on external data releases, not on data committed to this repository:

• Marine (Point Conception rocky intertidal eDNA). California Intertidal Dryad data package, DOI 10.5061/dryad.1rn8pk1bx.
• Freshwater (Burns Harbor, Lake Michigan eDNA). U.S. Fish and Wildlife Service metabarcoding data, to be released by the USFWS on ScienceBase; DOI pending (this citation will be updated once the release is published).

Obtain the data from the release above and point the analysis pipelines at it with the MULTIDETECTR_DATA environment variable (see the per-analysis READMEs under data-raw/analysis/).

Disclaimer

See DISCLAIMER.md. This software is preliminary or provisional and is subject to revision.

License

CC0 1.0 Universal (public domain dedication). See LICENSE.