
A reproducible field-count lesson with real salamander observations
More than six in ten salamander survey records contain zero animals. Does that mean a zero-inflated statistical model is necessary? The answer depends on how the remaining count variability is modeled, not on the height of the zero bar alone.
Using historical field observations, three comparable mixed models give a clear result: negative binomial AIC 1,672.40, compared with 1,674.40 for zero-inflated negative binomial and 1,962.81 for Poisson. The negative-binomial model also reproduces the observed proportion of zeros in model-based simulations. The additional zero-inflation parameter is estimated near zero and is poorly identified. The lesson is about explaining counts with the fewest justified mechanisms, not declaring some field zeros to be certain biological absences.
The historical field data are observational. Mining status varies between sites; associations cannot establish that mining caused a given count difference. A zero count is a nondetection or absence in the recorded count cell, not proof of a biologically unoccupied stream. The model’s zero-inflation component is a statistical mixture, not a validated occupancy process.
The data: what is being counted?
The response is a nonnegative count for a particular species/life-stage code at a stream site on a survey occasion. There are 23 stream sites, four surveys per site and seven species/life-stage codes. Multiple records from the same site can be correlated, so treating all rows as independent sampling sites is inappropriate.
These historical observations are available through the glmmTMB::Salamanders dataset. They derive from the field work reported by Price and colleagues (2016). The original Dryad deposit provides additional study context. This analysis uses the documented package dataset rather than a separately reconciled copy of the Dryad source files.
1. Prepare R and import the observations
The analysis begins by loading the observations and explicitly setting categorical reference levels. This is not cosmetic: the meaning of a count ratio depends on which group is the baseline. The mining-status contrast is defined relative to mined sites, while species code GP serves as the species reference.
# Run from the ZIP project root. No downloads or installation occur here.
needed <- c("glmmTMB", "ggplot2")
missing_packages <- needed[!vapply(needed, requireNamespace, logical(1), quietly = TRUE)]
if (length(missing_packages)) {
stop("Install required packages first: install.packages(c(\"glmmTMB\", \"ggplot2\"))")
}
library(ggplot2)
input_file <- file.path("01_data", "salamander_counts_glmmTMB.csv")
if (!file.exists(input_file)) stop("Run this script from the project root; CSV not found.")
dir.create("04_outputs/figures", showWarnings = FALSE, recursive = TRUE)
salamanders <- read.csv(input_file, stringsAsFactors = FALSE)
fields <- c("site", "mined", "cover", "sample", "DOP", "Wtemp", "DOY", "spp", "count")
if (!identical(names(salamanders), fields)) stop("Unexpected source columns or their order.")
salamanders$site <- factor(salamanders$site)
salamanders$mined <- factor(salamanders$mined, levels = c("yes", "no"))
salamanders$spp <- factor(salamanders$spp, levels = unique(salamanders$spp))The source has nine fields, including the count, stream site, sampling occasion, species code, mining classification and four scaled environmental measures. Here the model isolates the effect of the count distribution by keeping species and mining status as the same predictors across candidates; environmental and detection covariates are important potential extensions.
2. The counts and the unit of analysis
A valid count analysis begins with the observational unit. Each row is a site–visit–species cell; multiple cells share a stream site. Verification of missingness, nonnegative whole-number responses and unique sampling keys protects against falsely treating an absent measurement as zero or double-counting a visit. Repeated records from one site motivate a random intercept rather than an independence assumption.
if (anyNA(salamanders)) stop("The source contains missing data: inspect before fitting.")
if (nrow(salamanders) != 644L || nlevels(salamanders$site) != 23L ||
nlevels(salamanders$spp) != 7L || anyNA(salamanders$mined)) {
stop("Dataset dimensions or categorical levels differ from the audited source.")
}
if (!all(vapply(salamanders[c("cover", "DOP", "Wtemp", "DOY")],
is.numeric, logical(1)))) stop("A numeric covariate was misread.")
if (any(!is.finite(salamanders$count)) || any(salamanders$count < 0) ||
any(salamanders$count != floor(salamanders$count))) {
stop("Counts must be finite, nonnegative integers.")
}
plot_key <- paste(salamanders$site, salamanders$sample, salamanders$spp, sep = "|")
if (anyDuplicated(plot_key)) stop("Repeated site / visit / species identifiers.")
if (any(vapply(split(salamanders$mined, salamanders$site),
function(x) length(unique(x)) != 1L, logical(1)))) {
stop("Mining status changes within a site; check source data.")
}
zero_share <- mean(salamanders$count == 0)
observed_summary <- data.frame(
records = nrow(salamanders), sites = nlevels(salamanders$site),
total_count = sum(salamanders$count), mean_count = mean(salamanders$count),
sample_variance = var(salamanders$count),
zero_count = sum(salamanders$count == 0), zero_fraction = zero_share
)
print(observed_summary) records sites total_count mean_count sample_variance zero_count zero_fraction
1 644 23 852 1.322981 6.946843 387 0.6009317
observed_groups <- do.call(rbind, lapply(
split(salamanders, list(salamanders$spp, salamanders$mined), drop = TRUE),
function(d) data.frame(spp = as.character(d$spp[1]),
mined = as.character(d$mined[1]), n = nrow(d),
zero_n = sum(d$count == 0),
zero_fraction = mean(d$count == 0),
mean_count = mean(d$count))
))
rownames(observed_groups) <- NULL
print(observed_groups) spp mined n zero_n zero_fraction mean_count
1 GP yes 44 43 0.9772727 0.04545455
2 PR yes 44 41 0.9318182 0.11363636
3 DM yes 44 35 0.7954545 0.43181818
4 EC-A yes 44 41 0.9318182 0.09090909
5 EC-L yes 44 35 0.7954545 0.25000000
6 DES-L yes 44 33 0.7500000 0.56818182
7 DF yes 44 31 0.7045455 0.56818182
8 GP no 48 11 0.2291667 2.20833333
9 PR no 48 37 0.7708333 0.45833333
10 DM no 48 12 0.2500000 2.43750000
11 EC-A no 48 30 0.6250000 0.95833333
12 EC-L no 48 12 0.2500000 3.95833333
13 DES-L no 48 10 0.2083333 3.91666667
14 DF no 48 16 0.3333333 1.91666667
There are 644 cells, 387 of which equal zero (60.1%). The unconditional count mean is 1.323 and the sample variance is 6.947. Because these aggregate data across different species and sites, the marginal variance-versus-mean comparison is a diagnostic motivation, not proof that a conditional Poisson model fails.
3. First visual: what does “many zeros” look like?
For visual clarity, counts of five through nine and ten or more are grouped; the models retain every original integer response. Among 308 records from mined sites, 259 are zero (84.1%). Among 336 records from unmined sites, 128 are zero (38.1%). These descriptive contrasts are between different stream sites, not randomized treatment comparisons.
# Group the long right tail for legibility, without dropping any observation.
salamanders$count_band <- cut(salamanders$count,
breaks = c(-Inf, 0, 1, 2, 3, 4, 9, Inf),
labels = c("0", "1", "2", "3", "4", "5-9", "10+"))
p_counts <- ggplot(salamanders, aes(x = count_band)) +
geom_bar(fill = "#175d75", width = 0.78) +
facet_wrap(~ mined, nrow = 1) +
labs(title = "Recorded salamander counts", subtitle = "Every site-visit-species record is retained",
x = "Count per record", y = "Number of records") +
theme_minimal(base_size = 13) +
theme(panel.grid.minor = element_blank())4. The mechanism: three models for the same field counts
For a Poisson model, the conditional variance equals the conditional mean, written as Var(Y | X)=μ. The log link ensures predicted count means remain positive. A site random intercept represents unobserved baseline differences shared by the repeated records at a stream. The Poisson property concerns counts conditional on the model terms and random effects, not the unadjusted mixture of all observations.
The NB2 model keeps the same log-linear mean relationship but allows Var(Y | X)=μ+μ²/θ. Smaller θ means more extra-Poisson variability; large θ approaches the Poisson. NB2 can naturally generate additional zeros without declaring any zero a special biological state.
The zero-inflated NB2 adds an intercept-only mixture probability π. At the zero count, its probability is
P(Y = 0) = Ï€ + (1 − Ï€) PNB(Y = 0).
At positive counts, the NB2 probabilities are multiplied by 1-π. We use a deliberately simple zero-inflation term so the demonstration does not overfit a separate zero mechanism to each species or mining category. An estimated π near zero can be at the boundary and cause numerical Hessian problems; in that case, do not rank the model as though it fitted reliably. See the official glmmTMB troubleshooting notes.
All three models use count ~ spp + mined + (1 | site). Holding the predictors and repeated-site structure fixed makes the count-family comparison interpretable, although this is not a complete scientific model-selection exercise.
# The site random intercept accounts for clustering of repeated records.
count_formula <- count ~ spp + mined + (1 | site)
m_poisson <- glmmTMB::glmmTMB(count_formula, data = salamanders, family = poisson())
m_negbin <- glmmTMB::glmmTMB(count_formula, data = salamanders,
family = glmmTMB::nbinom2())
m_zinb <- glmmTMB::glmmTMB(count_formula, ziformula = ~ 1,
data = salamanders, family = glmmTMB::nbinom2())
fits <- list(Poisson = m_poisson, Negative_binomial = m_negbin,
Zero_inflated_NB = m_zinb)
# A zero-inflated fit can reach a parameter boundary: never rank a bad fit.
fit_diagnostics <- data.frame(
model = names(fits),
optimizer_converged = vapply(fits,
function(x) isTRUE(x$fit$convergence == 0), logical(1)),
hessian_positive = vapply(fits,
function(x) isTRUE(x$sdr$pdHess), logical(1)),
AIC = vapply(fits, AIC, numeric(1))
)
fit_diagnostics$valid <- with(fit_diagnostics,
optimizer_converged & hessian_positive & is.finite(AIC))
print(fit_diagnostics) model optimizer_converged hessian_positive
Poisson Poisson TRUE TRUE
Negative_binomial Negative_binomial TRUE TRUE
Zero_inflated_NB Zero_inflated_NB TRUE TRUE
AIC valid
Poisson 1962.807 TRUE
Negative_binomial 1672.404 TRUE
Zero_inflated_NB 1674.404 TRUE
if (!all(fit_diagnostics$valid[1:2])) {
stop("Poisson or negative-binomial model failed diagnostics; inspect warnings first.")
}
if (!fit_diagnostics$valid[3]) {
message("Zero-inflated NB is not a valid fitted candidate; it will not be ranked or simulated.")
}All three fitted candidates report successful optimizer convergence, positive-definite Hessians and finite AIC values. A passing numerical checklist is not the same as well-identified model parameters. The zero-inflation intercept is approximately −16.41 (standard error approximately 4,039), translating into an extra-zero probability close to zero. Its enormous uncertainty indicates that the separate zero component adds little information, even though the fit is numerically admissible. This is consistent with official glmmTMB troubleshooting guidance on boundary estimates.
5. Compare well-behaved fits, not just small AIC values
For models fitted by maximum likelihood to the same observations, AIC balances fit and parameter count. Lower AIC is better relative to the alternatives considered; an AIC difference is neither a p-value nor an effect size, and does not demonstrate that a particular biological mechanism exists. In particular, likelihood-ratio tests involving zero-inflation probabilities at a boundary require special care.
model_comparison <- fit_diagnostics
model_comparison$delta_AIC <- NA_real_
good <- model_comparison$valid
model_comparison$delta_AIC[good] <- model_comparison$AIC[good] -
min(model_comparison$AIC[good])
model_comparison <- model_comparison[order(model_comparison$delta_AIC,
na.last = TRUE), ]
rownames(model_comparison) <- NULL
print(model_comparison) model optimizer_converged hessian_positive AIC valid
1 Negative_binomial TRUE TRUE 1672.404 TRUE
2 Zero_inflated_NB TRUE TRUE 1674.404 TRUE
3 Poisson TRUE TRUE 1962.807 TRUE
delta_AIC
1 0.0000
2 2.0000
3 290.4031
# AIC measures relative in-sample fit penalized for complexity, not causal truth.
p_aic <- ggplot(model_comparison[model_comparison$valid, ],
aes(x = reorder(model, delta_AIC), y = delta_AIC)) +
geom_col(fill = "#276b73", width = 0.60) +
coord_flip() +
labs(title = "AIC differences among valid count models",
x = NULL, y = "Delta AIC (smaller is better)") +
theme_minimal(base_size = 13)The negative-binomial model achieves AIC 1672.40, versus 1674.40 for its zero-inflated extension and 1962.81 for Poisson. The zero-inflated model has almost the same log likelihood as ordinary NB2, but incurs an extra complexity penalty. This supports the simpler NB2 specification among the candidates compared, not the biological nonexistence of structural zeros, a new-site predictive guarantee or a causal claim.
6. Can the models reproduce the fraction of zeros?
We now simulate 250 full datasets per valid model, using the fitted model’s mechanism. Importantly, glmmTMB simulations also resample random effects; thus the figure checks the broader model-implied dataset distribution, not a claim about conditional residual independence. The red line shows the actual observed zero fraction, and the bars show fractions from fitted-model simulations. These simulation ranges are not confidence intervals for the mining effect.
# Simulate new datasets from each supported fitted model, including new site effects.
set.seed(20261112)
zero_draws <- do.call(rbind, lapply(
model_comparison$model[model_comparison$valid], function(name) {
simulated <- do.call(cbind, simulate(fits[[name]], nsim = 250))
data.frame(model = name, draw = seq_len(ncol(simulated)),
zero_fraction = colMeans(simulated == 0))
}
))
rownames(zero_draws) <- NULL
zero_check <- do.call(rbind, lapply(split(zero_draws$zero_fraction, zero_draws$model),
function(x) data.frame(observed_zero_fraction = zero_share,
simulated_median = median(x),
simulated_lower_2_5 = unname(quantile(x, 0.025)),
simulated_upper_97_5 = unname(quantile(x, 0.975)))))
zero_check$model <- rownames(zero_check)
rownames(zero_check) <- NULL
zero_check <- zero_check[, c("model", "observed_zero_fraction", "simulated_median",
"simulated_lower_2_5", "simulated_upper_97_5")]
print(zero_check) model observed_zero_fraction simulated_median simulated_lower_2_5
1 Negative_binomial 0.6009317 0.5877329 0.5345109
2 Poisson 0.6009317 0.4968944 0.4472050
3 Zero_inflated_NB 0.6009317 0.5877329 0.5360637
simulated_upper_97_5
1 0.6381988
2 0.5583075
3 0.6381988
p_zeros <- ggplot(zero_draws, aes(x = zero_fraction)) +
geom_histogram(bins = 24, fill = "#468e92", colour = "white") +
geom_vline(xintercept = zero_share, colour = "#c84f3a", linewidth = 0.9) +
facet_wrap(~ model, ncol = 1, scales = "free_y") +
labs(title = "Can each fitted model reproduce the observed zeros?",
subtitle = "Red line = observed zero fraction; bars = 250 model simulations",
x = "Zero fraction in a simulated dataset", y = "Simulation count") +
theme_minimal(base_size = 12)
The observed zero fraction is 60.1%. Poisson simulations have a median zero fraction of 49.7%, with central 95% simulation percentiles 44.7–55.8%; the observed value lies outside this range. NB2 simulations instead have median 58.8% and central percentiles 53.5–63.8%, encompassing the actual result. ZINB2 produces essentially the same pattern as NB2 because its added zero probability is near zero.
Interpretation: NB2 reproduces the overall frequency of zeros without an extra zero-only process. These simulation percentiles are not confidence intervals for the mining effect, and success on one diagnostic does not establish perfect fit across count tails, species, survey dates or sites.
7. Interpret coefficients in count units, and check group means
With a log link, exponentiating a conditional coefficient gives a count rate ratio for a one-unit predictor contrast, holding the other included terms and site random effect fixed. The Wald intervals below rely on the fitted NB model and approximate normality of coefficient estimates; they are not robust causal intervals. Here mined = yes is the reference group, so a term labeled minedno contrasts unmined with mined sites in the fitted model.
# Conditional fixed effects from the NB model; these are associations.
nb_coef <- summary(m_negbin)$coefficients$cond
nb_effects <- data.frame(
term = rownames(nb_coef), estimate_log = nb_coef[, "Estimate"],
std_error = nb_coef[, "Std. Error"],
rate_ratio = exp(nb_coef[, "Estimate"]),
lower_95 = exp(nb_coef[, "Estimate"] - 1.96 * nb_coef[, "Std. Error"]),
upper_95 = exp(nb_coef[, "Estimate"] + 1.96 * nb_coef[, "Std. Error"])
)
rownames(nb_effects) <- NULL
print(nb_effects) term estimate_log std_error rate_ratio lower_95 upper_95
1 (Intercept) -1.6832302 0.2741630 0.1857729 0.1085451 0.3179470
2 sppPR -1.3197389 0.2874900 0.2672051 0.1520996 0.4694195
3 sppDM 0.3685899 0.2234629 1.4456946 0.9329560 2.2402269
4 sppEC-A -0.7098386 0.2529764 0.4917236 0.2994906 0.8073445
5 sppEC-L 0.5714003 0.2190892 1.7707449 1.1525599 2.7204986
6 sppDES-L 0.7929362 0.2166493 2.2098755 1.4452807 3.3789629
7 sppDF 0.3120271 0.2329048 1.3661917 0.8654840 2.1565733
8 minedno 2.2632890 0.2838101 9.6146594 5.5125161 16.7694160
# These are training-site conditional predictions, not new-site forecasts.
rate_rows <- data.frame(spp = salamanders$spp, mined = salamanders$mined,
observed = salamanders$count,
fitted_nb = as.numeric(predict(m_negbin, type = "response")))
group_fit <- aggregate(cbind(observed, fitted_nb) ~ spp + mined,
data = rate_rows, FUN = mean)
print(group_fit) spp mined observed fitted_nb
1 GP yes 0.04545455 0.22794848
2 PR yes 0.11363636 0.06090899
3 DM yes 0.43181818 0.32954389
4 EC-A yes 0.09090909 0.11208764
5 EC-L yes 0.25000000 0.40363861
6 DES-L yes 0.56818182 0.50373777
7 DF yes 0.56818182 0.31142132
8 GP no 2.20833333 1.84308420
9 PR no 0.45833333 0.49248141
10 DM no 2.43750000 2.66453695
11 EC-A no 0.95833333 0.90628793
12 EC-L no 3.95833333 3.26363195
13 DES-L no 3.91666667 4.07298666
14 DF no 1.91666667 2.51800631
group_long <- rbind(
data.frame(spp = group_fit$spp, mined = group_fit$mined,
series = "Recorded", count_mean = group_fit$observed),
data.frame(spp = group_fit$spp, mined = group_fit$mined,
series = "Fitted NB", count_mean = group_fit$fitted_nb))
p_groups <- ggplot(group_long,
aes(x = spp, y = count_mean, colour = series, group = series)) +
geom_point(size = 2.5, position = position_dodge(width = 0.35)) +
facet_wrap(~ mined, nrow = 1) +
labs(title = "Observed and fitted means by species and mining status",
subtitle = "In-sample means; no uncertainty or causal inference implied",
x = "Species / life-stage code", y = "Mean count per record", colour = NULL) +
theme_minimal(base_size = 12) +
theme(axis.text.x = element_text(angle = 35, hjust = 1))The unmined-versus-mined conditional count ratio in the NB2 model is 9.61, with an approximate 95% Wald interval 5.51–16.77. Mining status differs between sites, so this reflects a large model-based association rather than the effect of changing mining status at an otherwise identical site.
The group-mean figure reveals remaining discrepancies. At unmined sites, EC-L has an observed mean near 3.96 but a fitted mean near 3.26; DF shows 1.92 observed versus 2.52 fitted. Such patterns merit attention even when the model is preferred by AIC and reproduces the overall zero fraction. Species-by-mining interactions, survey conditions, environmental covariates and detection processes remain plausible modeling considerations.
8. Reproducible results and interpretation
The analysis retains interpretable data summaries, likelihood comparisons, simulated reference distributions, effect estimates and visual model checks. Together, these provide an inspectable chain of evidence from recorded counts to the choice of a distribution. In reproducible analysis, numerical preferences should always be considered alongside diagnostics and limits of the field sampling design.
write.csv(observed_summary, "04_outputs/01_observed_summary.csv", row.names = FALSE)
write.csv(observed_groups, "04_outputs/02_observed_species_mining.csv", row.names = FALSE)
write.csv(fit_diagnostics, "04_outputs/03_fit_diagnostics.csv", row.names = FALSE)
write.csv(model_comparison, "04_outputs/04_model_comparison.csv", row.names = FALSE)
write.csv(zero_check, "04_outputs/05_simulated_zero_check.csv", row.names = FALSE)
write.csv(nb_effects, "04_outputs/06_nb_rate_ratios.csv", row.names = FALSE)
write.csv(group_fit, "04_outputs/07_observed_vs_fitted.csv", row.names = FALSE)
write.csv(zero_draws, "04_outputs/08_simulated_zero_draws.csv", row.names = FALSE)
ggsave("04_outputs/figures/01_count_distribution.png", p_counts,
width = 9, height = 4.5, dpi = 300, bg = "white")
ggsave("04_outputs/figures/02_model_AIC.png", p_aic,
width = 9, height = 4.5, dpi = 300, bg = "white")
ggsave("04_outputs/figures/03_simulated_zero_check.png", p_zeros,
width = 9, height = 8.5, dpi = 300, bg = "white")
ggsave("04_outputs/figures/04_observed_vs_fitted.png", p_groups,
width = 9, height = 4.5, dpi = 300, bg = "white")
writeLines(capture.output(summary(m_poisson), summary(m_negbin),
summary(m_zinb), sessionInfo()),
"04_outputs/model_summaries_and_session.txt")
if (interactive()) {
print(p_counts)
print(p_aic)
print(p_zeros)
print(p_groups)
}
message("Finished writing 8 tables, 4 figures, and model/session details.")Finished writing 8 tables, 4 figures, and model/session details.
What should a researcher conclude?
- Begin with the sampling process. A count of zero may mean no salamanders recorded on that species-by-visit occasion; it does not automatically certify biological absence.
- Check the conditional model. Extra unconditional variance can arise from covariate heterogeneity and repeated-site variation even when a Poisson count mechanism is plausible conditional on predictors.
- Do not assume zero inflation from a histogram. The NB2 model may already describe the observed zeros. An unidentifiable zero-inflation parameter should not be interpreted as scientifically measured absence.
- Compare what is comparable. AIC is meaningful here because the response, records, count predictors and maximum-likelihood basis are held fixed, but it cannot substitute for fit diagnostics or new-site validation.
- Translate to your research cautiously. Crop pest counts, weed numbers per quadrat or seedlings per plot can use related approaches when the sampling unit, effort/offset, clustering and detection process justify them.
Common errors worth avoiding
- Replacing a real zero count with a missing value simply because it seems extreme.
- Using
glm()without accounting for correlated observations from the same site. - Treating a zero-inflation probability as a directly measured species absence rate.
- Reporting a failed-convergence model’s smallest printed AIC as though it were valid.
- Calling the mined/nonmined association a causal effect.
Data provenance and interpretation limits
The count table is drawn from the published glmmTMB teaching dataset, which is based on historical field work. The underlying Dryad file has not been independently matched row-for-row to this package distribution. Mining status is observational and measured at the site level; recorded zeros do not uniquely identify species absence. The fitted model also omits detection probability, survey timing effects and several available environmental measures. These limitations are relevant when transferring the method to monitoring data or interpreting ecological impacts.
References
- Price, S. J., Muncy, B. L., Bonner, S. J., Drayer, A. N., and Barton, C. D. (2016). Journal of Applied Ecology, 53, 459–468.
- Price et al. (2015). Dryad dataset.
glmmTMBpackage, official troubleshooting guide and simulation documentation.- Quarto HTML / code-copy documentation.
Comments
Post a Comment