Quick Start

Installation

pak::pak("gcol33/numdenom")

library(numdenom)

What numdenom Does

numdenom fits Bayesian hierarchical models for ratios, rates, and proportions. Instead of modelling ratios directly (which is statistically problematic), numdenom jointly models the numerator and denominator processes, then derives ratios with full uncertainty propagation.

See vignette("philosophy") for the statistical motivation.

The Three Families

numdenom provides three model families for common ratio types:

Family	Numerator	Denominator	Use Case
`ratiod_negbin_negbin()`	Counts	Counts	Relative abundance, species ratios
`ratiod_binomial()`	Successes	Trials	Detection rates, survival
`ratiod_poisson_gamma()`	Counts	Continuous	CPUE, catch per effort

Basic Example: CPUE Analysis

Catch per unit effort with site-level variation:

library(numdenom)

# Simulated trawl data
set.seed(123)
n_sites <- 20
n_obs <- 200

trawl_data <- data.frame(
  site = factor(rep(1:n_sites, each = n_obs/n_sites)),
  depth = rnorm(n_obs, 50, 15),
  season = factor(sample(c("spring", "summer", "fall"), n_obs, replace = TRUE)),
  catch = rpois(n_obs, lambda = 15),
  effort = rgamma(n_obs, shape = 5, rate = 1)
)

# Fit model
fit <- tratio(
  catch | effort ~ depth + season + (1 | site),
  data = trawl_data,
  family = ratiod_poisson_gamma()
)

# View results
summary(fit)

Extract CPUE Posteriors

# Observation-level CPUE
cpue <- ratio(fit)
summary(cpue)

# Compare CPUE between seasons
ratio_contrast(fit, ~ season)

Formula Syntax

Combined Formula (Recommended)

Use num | denom ~ predictors when both processes share predictors:

fit <- tratio(
  catch | effort ~ depth + season + (1 | site),
  data = df,
  family = ratiod_poisson_gamma()
)

Process-Specific Predictors

Add terms that affect only numerator or denominator:

fit <- tratio(
  catch | effort ~ (1 | site),           # Shared structure
  formula_num = ~ depth + season,         # Catch-specific

  formula_denom = ~ weather,              # Effort-specific
  data = df,
  family = ratiod_poisson_gamma()
)

Random Effects

Random Intercepts

# Single grouping factor
fit <- tratio(y | n ~ x + (1 | site), ...)

# Multiple (crossed) grouping factors
fit <- tratio(y | n ~ x + (1 | site) + (1 | year), ...)

# Nested grouping factors
fit <- tratio(y | n ~ x + (1 | site/plot), ...)

Random Slopes

# Correlated intercept and slope
fit <- tratio(y | n ~ x + (1 + x | site), ...)

# Uncorrelated (independent) intercept and slope
fit <- tratio(y | n ~ x + (1 + x || site), ...)

Model Checking

# Posterior predictive checks
pp_check(fit, type = "dens_overlay")

# Model comparison
loo(fit)
waic(fit)

# Compare models
fit1 <- tratio(y | n ~ x, ...)
fit2 <- tratio(y | n ~ x + z, ...)
ratiod_compare(fit1, fit2)

Quick Reference

Function	Purpose
`tratio()`	Fit model
`ratio()`	Extract ratio posteriors
`ratio_contrast()`	Compare ratios between groups
`pp_check()`	Posterior predictive checks
`loo()`, `waic()`	Model comparison
`ratiod_compare()`	Compare multiple models

Gilles Colling

2026-08-04