Package {birp}

Testing for Population Trends Using Low-Cost Ecological Count Data

Description

A Bayesian tool to test for population trends and changes in trends under arbitrary designs, including before-after (BA), control-intervention (CI) and before-after-control-intervention (BACI) designs commonly used to assess conservation impact. It infers changes in trends jointly from data obtained with multiple survey methods, as well as from limited and noisy data not necessarily collected in standardized ecological surveys. Observed counts can be modeled as following either a Poisson or a negative binomial model, and both deterministic and stochastic trend models are available. For more details on the model see Singer et al. (2025) <doi:10.1101/2025.01.08.631844>, and the file 'AUTHORS' for a list of copyright holders and contributors.

Package Content

Index of help topics:

assess_NB               Assess whether a Poisson model can replace the
                        Negative Binomial model
birp                    Create a 'birp' Object
birp-package            Testing for Population Trends Using Low-Cost
                        Ecological Count Data
birp_data               Create a birp_data Object from Count and Effort
                        Matrices
birp_data_from_data_frame
                        Create a 'birp_data' Object from a Data Frame
                        or List of Data Frames
birp_data_from_file     Create a birp_data Object from File(s)
birp_from_command_line
                        Create a birp Object from Command-Line Output
                        Files
plot.birp               Plot posterior distributions of rate and/or
                        step change parameters
plot.birp_data          Plot a birp_data Object
plot_epoch_pair         Plot joint posterior of two gamma parameters
plot_mcmc               Plot MCMC Traces and Posterior Densities
plot_trend              Plot Posterior Trend Estimates
print.birp              Print a birp object
print.birp_data         Print a birp_data object Prints a summary of a
                        'birp_data' object, including the number of
                        methods, locations, control-intervention (CI)
                        groups, and timepoints, as well as the names or
                        identifiers for each.
prob_step               Posterior probability of a step change
prob_trend              Posterior probability of a population trend
prob_trend_diff         Pairwise posterior comparisons of population
                        trends
simulate_birp           Simulate Data for BIRP Models Generates
                        simulated count data using the BIRP model
                        framework with user-defined parameters.
simulate_birp_from_results
                        This function simulates a birp_data object
                        using all parameter estimates, dimensionality
                        (methods, locations, timepoints) and the total
                        number of counts nu_ij of a birp object
summary.birp            Summary method for birp objects
summary.birp_data       Summarize a birp_data object

Maintainer

Andreas Füglistaler <andreas.fueglistaler@unifr.ch>

Author(s)

Madleina Caduff [aut], Andreas Füglistaler [aut, cre], Daniel Wegmann [aut], Liam Singer [aut], Raphael Eckel [ctb]

Function to add legend to plot denoting gammas

Description

Function to add legend to plot denoting gammas

Usage

.addLegendMultiGamma.birp(num, legend, dens, xlim, col, lwd, lty, ...)

Arguments

Value

No return value, called for side effects.

Function to add text box to plot denoting P(gamma > 0 | n) or P(gamma < 0 | n) for single gammas (same for Delta)

Description

Function to add text box to plot denoting P(gamma > 0 | n) or P(gamma < 0 | n) for single gammas (same for Delta)

Usage

.addTextSingleGammaDelta.birp(post, param_name = "gamma")

Arguments

Value

No return value, called for side effects.

Function to convert an argument to a string and add it to a list if necessary

Description

Function to convert an argument to a string and add it to a list if necessary

Usage

.addToList.birp(options, name, x)

Arguments

Value

An updated list options

Compute step-change indicator matrix for Delta

Description

For a set of evaluation times and a set of step-change times, computes a matrix where entry [i, m] is 1 if observation time i is greater than or equal to step-change time m, and 0 otherwise. Used to accumulate the step-change contributions \sum_m \mathbb{1}_{t_k \geq T_m} \Delta(g, m).

Usage

.calculatePsi.birp(eval_times, times_of_change)

Arguments

Value

A matrix with length(eval_times) rows and length(times_of_change) columns.

Function to calculate rho

Description

Function to calculate rho

Usage

.calculateRho.birp(times, times_of_change)

Arguments

Value

A numeric matrix containing rho for each time point and epoch

Function to check if a file exists and generate error message if it was not found

Description

Function to check if a file exists and generate error message if it was not found

Usage

.checkFile.birp(
  path,
  files,
  patterns,
  allowMultiMatch = FALSE,
  sep = "\t",
  mustExist = TRUE
)

Arguments

Value

A string denoting the filename(s)

Function to create an object of type birp

Description

Function to create an object of type birp

Usage

.createObjBirp.birp(
  data,
  meanVar,
  trace,
  gamma,
  Delta,
  timepoints,
  timesOfChange,
  rate_design,
  step_design,
  CI_groups,
  state
)

Arguments

Details

The 'rate_design' and 'step_design' matrices define a Before-After Control-Impact experimental design for the rates of change (gamma) and the step changes (Delta), respectively, with the following format: - Each **row** represents a group (e.g., Control or Intervention). The **first column** specifies the group name (e.g. 'Control' or 'Intervention'). - Each **column after the first** represents a different epoch. The numbers in these columns indicate which change parameter (\gamma or \Delta) to assign for each group and epoch. For example, BACI = matrix(c("A", "B", 1, 1, 1, 2), nrow = 2) corresponds to a canonical BACI design where the first row represents the control group (A) and the second row represents the intervention group (B). Please see the vignette for more examples.

Value

An object of type birp

This function reads data for all methods into a list

Description

This function reads data for all methods into a list

Usage

.getDataAllMethods.birp_data(out, what, res)

Arguments

Value

An instance of birp_data

Function to get the start of each epoch, including for a hypothetical epoch after the last epoch

Description

Function to get the start of each epoch, including for a hypothetical epoch after the last epoch

Usage

.getEpochStarts.birp(times, times_of_change)

Arguments

Value

An integer or numeric vector with starting points for each epoch

Function to generate a nice axis label with greek gamma and subscript

Description

Function to generate a nice axis label with greek gamma and subscript

Usage

.getLabelGamma.birp(x, index)

Arguments

Value

A string

Function to open a file and generate error message if it was not found

Description

Function to open a file and generate error message if it was not found

Usage

.openFile.birp(
  path,
  files,
  patterns,
  sep = "\t",
  header = TRUE,
  mustExist = TRUE
)

Arguments

Value

A file connection.

Function to open an empty plot for plotting the posterior probabilities

Description

Function to open an empty plot for plotting the posterior probabilities

Usage

.openPosteriorPlot.birp(
  xlim,
  ylim,
  xlab,
  ylab,
  shadingIncrease,
  shadingDecrease,
  lineAtZero,
  ...
)

Arguments

Value

No return value, called for side effects.

Function to parse posterior results of gamma and Delta

Description

Function to parse posterior results of gamma and Delta

Usage

.parsePosteriorGammaDelta.birp(param_name, meanVar, trace, posterior_summary)

Arguments

Value

A list with relevant posterior statistics

Function to add a hatched polygon to a plot

Description

Function to add a hatched polygon to a plot

Usage

.plotShadingPolygon.birp(shading, left, right)

Arguments

Value

No return value, called for side effects.

Function to print posterior summaries

Description

Function to print posterior summaries

Usage

.printPostSummary.birp(x, param_name)

Arguments

Value

No return value, called for side effects.

This function check if a birp_data object is valid

Description

This function check if a birp_data object is valid

Usage

.validate.birp_data(data)

Arguments

Value

No return value, called for side effects.

Assess whether a Poisson model can replace the Negative Binomial model

Description

This function tests if the Poisson model is appropriate by simulating replicate datasets under the Poisson assumption and comparing the overdispersion parameter estimates with those obtained from the Negative Binomial (NB) model fit to the original data.

Usage

assess_NB(
  x,
  stochastic = FALSE,
  numRep = 100,
  cutoff = 0.05,
  plot = TRUE,
  verbose = TRUE
)

Arguments

Value

A list containing:

Examples

data <- simulate_birp()
est <- birp(data, negativeBinomial = TRUE)
res_assess <- assess_NB(est, numRep = 5)

Create a birp Object

Description

This function runs the Markov Chain Monte Carlo (MCMC) algorithm on a birp_data object to estimate model parameters and returns a fitted birp object.

Usage

birp(
  data,
  change = "rate",
  timesOfChange = c(),
  negativeBinomial = FALSE,
  stochastic = FALSE,
  rate_design = NULL,
  step_design = NULL,
  assumeTrueDetectionProbability = FALSE,
  iterations = 1e+05,
  numBurnin = 10,
  burnin = 1000,
  thinning = 10,
  verbose = TRUE
)

Arguments

Details

The 'rate_design' and 'step_design' matrices define a Before-After Control-Impact experimental design for the rates of change (gamma) and the step changes (Delta), respectively, with the following format: - Each **row** represents a group (e.g., Control or Intervention). The **first column** specifies the group name (e.g. 'Control' or 'Intervention'). - Each **column after the first** represents a different epoch. The numbers in these columns indicate which change parameter (\gamma or \Delta) to assign for each group and epoch. For example, BACI = matrix(c("A", "B", 1, 1, 1, 2), nrow = 2) corresponds to a canonical BACI design where the first row represents the control group (A) and the second row represents the intervention group (B). Please see the vignette for more examples.

Value

An object of type birp containing MCMC results and model estimates.

Examples

data <- simulate_birp()
est <- birp(data)

Create a birp_data Object from Count and Effort Matrices

Description

Constructs a 'birp_data' object from matrices of observed counts and corresponding efforts for a single method.

Usage

birp_data(counts, efforts, times, CI_groups = NULL, location_names = NULL)

Arguments

Value

An object of type birp_data

Examples

data <- birp_data(c(10,20,30), c(100,200,300), c(1,2,5))

Create a 'birp_data' Object from a Data Frame or List of Data Frames

Description

Constructs a 'birp_data' object from a single data frame or a list of data frames, with one per method.

Usage

birp_data_from_data_frame(data)

Arguments

Value

An object of type birp_data

Examples

df <- data.frame(
  timepoint = 1:10,
  location = rep(1, 10),
  counts = sample(1:100, 10),
  effort = rexp(10),
  CI_group = "intervention"
)
data <- birp_data_from_data_frame(df)

Create a birp_data Object from File(s)

Description

Constructs a 'birp_data' object from one or more input files, each representing data for a different method.

Usage

birp_data_from_file(filenames, method_names = NA, sep = ",")

Arguments

Value

An object of type birp_data

Examples

dir <- system.file("extdata", package = "birp")
filenames <- file.path(dir, "birp_Method_1_simulated_counts.txt")
data <- birp_data_from_file(filenames = filenames, sep = "\t")

Create a birp Object from Command-Line Output Files

Description

This function creates a birp object by reading the output files generated by the command-line version of the birp tool.

Usage

birp_from_command_line(path)

Arguments

Value

An object of type birp containing MCMC results and model estimates read from files.

Examples

est <- birp_from_command_line(file.path(system.file("extdata", package = "birp")))

Plot posterior distributions of rate and/or step change parameters

Description

Plots the posterior densities of the rate (gamma) and/or step change (Delta) parameters estimated by a birp object.

Usage

## S3 method for class 'birp'
plot(
  x,
  change = if (x$post_gamma$exists && x$post_Delta$exists) "both" else if
    (x$post_gamma$exists) "rate" else "step",
  shadingIncrease = NA,
  shadingDecrease = "#f2c7c7",
  col = "black",
  lwd = 1,
  lty = NULL,
  xlim = NA,
  ylim = NA,
  add = FALSE,
  xlab = NULL,
  ylab = "Posterior density",
  legend = NULL,
  lineAtZero = TRUE,
  ...
)

Arguments

Value

No return value, called for side effects.

See Also

birp

Examples

data <- simulate_birp(timepoints = 1:5)
est <- birp(data, change = "both")
plot(est)
plot(est, change = "rate")
plot(est, change = "step")

Plot a birp_data Object

Description

This function plots observed counts per unit of effort over time, for each method-location combination in a birp_data object.

Usage

## S3 method for class 'birp_data'
plot(
  x,
  col = 1:length(x$locations),
  lwd = 1,
  lty = 1:length(x$method_names),
  pch = 1:length(x$CI_groups),
  xlab = "time",
  ylab = "counts per unit of effort",
  legend.x = "topright",
  legend.y = NULL,
  legend.bty = "o",
  xlim = range(as.numeric(x$times)),
  ylim = NA,
  ...
)

Arguments

Value

No return value. Called for side effects.

Examples

data <- simulate_birp()
plot(data)

Plot joint posterior of two gamma parameters

Description

Plots a 2D density contour for the joint posterior of two gamma parameters from a birp object.

Usage

plot_epoch_pair(
  x,
  gamma1 = which(!x$post_gamma$is_fix)[1],
  gamma2 = which(!x$post_gamma$is_fix)[2],
  xlab = .getLabelGamma.birp(x, gamma1),
  ylab = .getLabelGamma.birp(x, gamma2),
  xlim = range(x$post_gamma$trace[, c(gamma1, gamma2)]),
  ylim = xlim,
  col = "deeppink",
  diag.col = "black",
  diag.lwd = 1,
  diag.lty = 1,
  zero.col = "black",
  zero.lwd = 1,
  zero.lty = 2,
  print.p = TRUE,
  add = FALSE,
  ...
)

Arguments

Value

No return value; called for side effects (plotting).

See Also

birp

Examples

data <- simulate_birp(timesOfChange = 2)
est <- birp(data, timesOfChange = 2)
plot_epoch_pair(est)

Plot MCMC Traces and Posterior Densities

Description

Visualizes the MCMC trace plots and posterior densities of the gamma and Delta parameters from a birp object.

Usage

plot_mcmc(x, col = c("black", "blue"))

Arguments

Value

No return value; the function is called for its side effects (plotting).

See Also

birp

Examples

data <- simulate_birp()
est <- birp(data)
plot_mcmc(est)

Plot Posterior Trend Estimates

Description

Visualizes posterior trends from a birp object by plotting the median and quantile intervals of the estimated relative densities over time. Optionally, vertical lines can be added to mark epoch boundaries and survey timepoints.

Usage

plot_trend(
  x,
  CI_group = 1,
  n_points = 1000,
  quantiles = c(0.99, 0.9, 0.5, 0.25),
  quantile.col = gray(seq(1, 0, length.out = length(quantiles) + 2)[2:(length(quantiles)
    + 1)]),
  quantile.border = NA,
  median.col = "deeppink",
  median.lwd = 2,
  median.lty = 1,
  epoch.col = "black",
  epoch.lwd = 1,
  epoch.lty = 1,
  times.col = "black",
  times.lwd = 1,
  times.lty = 2,
  log = FALSE,
  xlab = "Time",
  ylab = paste(c("log", "Relative Density")[c(log, TRUE)], collapse = " "),
  main = x$CI_groups[CI_group],
  ...
)

Arguments

Value

No return value, called for side effects.

See Also

birp

Examples

data <- simulate_birp()
est <- birp(data)
plot_trend(est)

Print a birp object

Description

Prints a summary of the estimated parameters from a birp model.

Usage

## S3 method for class 'birp'
print(x, ...)

Arguments

Value

Invisibly returns the input x, called for side effects.

See Also

birp

Examples

data <- simulate_birp()
est <- birp(data)
print(est)

Print a birp_data object Prints a summary of a birp_data object, including the number of methods, locations, control-intervention (CI) groups, and timepoints, as well as the names or identifiers for each.

Description

Print a birp_data object Prints a summary of a birp_data object, including the number of methods, locations, control-intervention (CI) groups, and timepoints, as well as the names or identifiers for each.

Usage

## S3 method for class 'birp_data'
print(x, ...)

Arguments

Value

No return value; this function is called for its side effects (printing to console).

Examples

data <- simulate_birp()
print(data)

Posterior probability of a step change

Description

Computes the posterior probability that a step change is increasing (positive) or decreasing (negative)

Usage

prob_step(x, positive = TRUE, Delta = NULL)

Arguments

Value

If 'Delta = NULL', a numeric vector containing posterior probabilities for all step change parameters. Otherwise, a single numeric value.

See Also

[birp()]

Examples

data <- simulate_birp()
est <- birp(data, change = "step")

# Posterior probabilities of positive step changes
prob_step(est)

# Posterior probability for a specific Delta
prob_step(est, Delta = 1)

# Posterior probabilities of negative step changes
prob_step(est, positive = FALSE)

Posterior probability of a population trend

Description

Computes the posterior probability that a population trend is increasing or decreasing.

Usage

prob_trend(x, positive = TRUE, gamma = NULL)

Arguments

Value

If 'gamma = NULL', a numeric vector containing posterior probabilities for all rate parameters. Otherwise, a single numeric value.

See Also

[birp()]

Examples

data <- simulate_birp()
est <- birp(data)

# Posterior probabilities of increasing trends
prob_trend(est)

# Posterior probability for a specific gamma
prob_trend(est, gamma = 1)

# Posterior probabilities of decreasing trends
prob_trend(est, positive = FALSE)

Pairwise posterior comparisons of population trends

Description

Computes pairwise posterior probabilities that one population trend exceeds another.

Usage

prob_trend_diff(x)

Arguments

Details

Element [i, j] of the returned matrix equals P(\gamma_i > \gamma_j \mid y), the posterior probability that the trend associated with row i is greater than the trend associated with column j.

Values close to 1 indicate strong evidence that \gamma_i > \gamma_j, values close to 0 indicate strong evidence that \gamma_i < \gamma_j, and values near 0.5 indicate little evidence for either comparison

Value

A square matrix of pairwise posterior probabilities. Element [i, j] gives P(\gamma_i > \gamma_j \mid y).

See Also

[birp()], [prob_trend()]

Examples

data <- simulate_birp(timepoints = 1:5)
est <- birp(data, timesOfChange = c(2,4))

prob_trend_diff(est)

Simulate Data for BIRP Models Generates simulated count data using the BIRP model framework with user-defined parameters.

Description

Simulate Data for BIRP Models Generates simulated count data using the BIRP model framework with user-defined parameters.

Usage

simulate_birp(
  timepoints = c(1, 2, 3),
  timesOfChange = c(),
  change = "rate",
  gamma = NULL,
  Delta = NULL,
  negativeBinomial = FALSE,
  stochastic = FALSE,
  numLocations = 2,
  numMethods = 1,
  numCIGroups = 1,
  numCovariatesEffort = 1,
  numCovariatesDetection = 0,
  rate_design = NULL,
  step_design = NULL,
  n_bar = 1000,
  N_0 = NULL,
  a = NULL,
  logSigma = NULL,
  logZeta = NULL,
  logPhi = NULL,
  covariatesEffort = "gamma(1, 2)",
  covariatesDetection = "normal(0, 1)",
  proportionZeroEffort = 0,
  verbose = TRUE
)

Arguments

Details

The 'rate_design' and 'step_design' matrices define a Before-After Control-Impact experimental design for the rates of change (gamma) and the step changes (Delta), respectively, with the following format: - Each **row** represents a group (e.g., Control or Intervention). The **first column** specifies the group name (e.g. 'Control' or 'Intervention'). - Each **column after the first** represents a different epoch. The numbers in these columns indicate which change parameter (\gamma or \Delta) to assign for each group and epoch. For example, BACI = matrix(c("A", "B", 1, 1, 1, 2), nrow = 2) corresponds to a canonical BACI design where the first row represents the control group (A) and the second row represents the intervention group (B). Please see the vignette for examples.

Value

An object of type birp_data containing the simulated dataset.

Examples

data <- simulate_birp()

This function simulates a birp_data object using all parameter estimates, dimensionality (methods, locations, timepoints) and the total number of counts nu_ij of a birp object

Description

This function simulates a birp_data object using all parameter estimates, dimensionality (methods, locations, timepoints) and the total number of counts nu_ij of a birp object

Usage

simulate_birp_from_results(
  x,
  negativeBinomial = FALSE,
  stochastic = FALSE,
  mu = NULL,
  b = NULL,
  logSigma = NULL,
  logZeta = NULL,
  logPhi = NULL,
  verbose = TRUE
)

Arguments

Value

An object of type birp_data

Examples

data  <- simulate_birp()
x <- birp(data)
data2 <- simulate_birp_from_results(x)

Summary method for birp objects

Description

Provides a printed summary of model estimates for a birp object.

Usage

## S3 method for class 'birp'
summary(object, ...)

Arguments

Value

Invisibly returns the input object, called for side effects.

See Also

birp

Examples

data <- simulate_birp()
est <- birp(data)
summary(est)

Summarize a birp_data object

Description

Provides a printed summary of the contents of a birp_data object.

Usage

## S3 method for class 'birp_data'
summary(object, ...)

Arguments

Value

No return value; this function is called for its side effects (printing to console).

Examples

data <- simulate_birp()
summary(data)