camtrapR (version 3.1.0)

simulateCamtrapData: Simulate Camera Trapping Data

Description

Generates simulated camera trap data and a corresponding species record table. The output mimics the structure required by camtrapR, making it useful for creating reproducible examples, testing pipelines, and demonstrating package functionality.

Usage

simulateCamtrapData(
  nStations = 10,
  camerasPerStation = 1,
  duration_days = 40,
  nSeasons = 1,
  nSpecies = 8,
  nRecords = 300,
  startDate = "2023-01-01",
  probProblem = 0,
  bbox = c(xmin = 117.25, xmax = 117.5, ymin = 5.3, ymax = 5.5),
  covariates = list(continuous = list(elev = c(1000, 200)), categorical = list(habitat =
    3)),
  dateFormat = "ymd",
  seed = NULL
)

Value

A list containing two data.frames:

camtraps

Deployment metadata including Station, Camera (optional), Season (optional), longitude, latitude, Setup/Retrieval dates, Problem dates, and covariates.

recordTable

Simulated species record table including Station, Camera (optional), Season (optional), Species, and strictly formatted DateTimeOriginal, Date, and Time columns.

Arguments

nStations

Integer. The number of camera trap stations to simulate. Default is 10.

camerasPerStation

Integer (1 or 2). Number of cameras per station. If 2, a Camera column is generated to distinguish between devices at the same station. Default is 1.

duration_days

Numeric. The average deployment duration in days. Actual durations will have slight random jitter. Default is 40.

nSeasons

Integer. The number of seasons to simulate. If > 1, deployments are staggered by 180 days. Default is 1.

nSpecies

Integer. The total number of distinct species to simulate. Default is 8.

nRecords

Integer. The total number of species records (images/events) to distribute across the active deployments. Default is 200.

startDate

Character. The base start date for the first season's deployments, in "YYYY-MM-DD" format. Default is "2023-01-01".

probProblem

Numeric (0 to 1). The probability that a camera experiences a malfunction, triggering Problem1_from and Problem1_to dates. Default is 0 (no problems).

bbox

Numeric vector of length 4. Bounding box c(xmin, xmax, ymin, ymax) used to generate random deployment coordinates in decimal degrees.

covariates

List. Specifies the covariates to simulate. Must contain continuous (a named list of c(mean, sd)) and/or categorical (a named list specifying the number of factor levels).

dateFormat

Character. A lubridate-style format string specifying how Setup_date and Retrieval_date should be formatted (e.g., "ymd", "dmy HMS", "mdy").

seed

Numeric. A seed for the random number generator to ensure reproducible output.

Author

Juergen Niedballa

Details

The function simulates realistic deployment metadata and species detections. Species abundances are generated using a skewed, Zipf-like (harmonic) distribution, ensuring a realistic mix of common and rare species. Detection times are drawn uniformly across the active deployment periods. If probProblem > 0, a subset of cameras will simulate a single malfunction period (Problem1_from and Problem1_to). Cameras are set up and retrieved in the daytime.

Note: The initial draft of this function was generated with the assistance of an AI language model and subsequently modified.

Examples

# Simulate basic data (10 stations, 1 camera each, 1 season)

camera_data_simple <- simulateCamtrapData()

camop_simple <- cameraOperation(camera_data_simple$camtraps,
                                setupCol = "Setup_date",
                                retrievalCol = "Retrieval_date")

plot(camop_simple)



head(camera_data_simple$camtraps)
head(camera_data_simple$recordTable)



# Simulate multi-season, multi-camera data with custom covariates
# and camera malfuncion (problem columns)
camera_data_complex <- simulateCamtrapData(
  nStations = 10,
  camerasPerStation = 2,
  nSeasons = 2,
  dateFormat = "ymd HMS",
  covariates = list(continuous = list(elevation = c(500, 50)), 
                    categorical = list(treatment = 2)),
  probProblem = 0.5
)



camop_complex <- cameraOperation(camera_data_complex$camtraps,
                                 setupCol = "Setup_date",
                                 retrievalCol = "Retrieval_date",
                                 sessionCol = "Season",
                                 cameraCol = "Camera",
                                 hasProblems = TRUE,
                                 byCamera = FALSE,
                                 allCamsOn = FALSE,
                                 camerasIndependent = FALSE,   # this is made up, not simulated
                                 dateFormat = "ymd HMS")
                                 
summary(camop_complex)

plot(camop_complex)