readCamtrapDP: Convert Camtrap DP format data to camtrapR format

In camtrapR: Camera Trap Data Management and Analysis Framework

Convert Camtrap DP format data to camtrapR format

Description

This function converts camera trap data from the Camtrap DP standard format to the format used by camtrapR. Camtrap DP is an open standard for the FAIR exchange and archiving of camera trap data.

Usage

readCamtrapDP(
  file = "datapackage.json",
  deployments_file = NULL,
  media_file = NULL,
  observations_file = NULL,
  datapackage_file = NULL,
  min_gap_hours = 24,
  removeNA = FALSE,
  removeEmpty = FALSE,
  remove_bbox = TRUE,
  add_file_path = FALSE,
  filter_observations = NULL
)

Arguments

file	character. Path to the 'datapackage.json' file. Replaces individual CSV arguments.
deployments_file	Deprecated. Ignored in favor of 'file'.
media_file	Deprecated. Ignored in favor of 'file'.
observations_file	Deprecated. Ignored in favor of 'file'.
datapackage_file	Deprecated. Alias for 'file'.
min_gap_hours	numeric. Minimum gap in hours to consider as a camera interruption (default: 24)
removeNA	logical. Whether to remove columns with only NA values
removeEmpty	logical. Whether to remove columns with only empty values
remove_bbox	logical. Whether to remove bounding box columns in the observation table
add_file_path	logical. Whether to add file path from media table to the observation table
filter_observations	Controls which observation types to include. NULL or FALSE keeps all (default), TRUE keeps only animal, or provide a character vector of types.

Details

While the 'camtrapdp' package provides general functionality for reading, manipulating, and transforming Camtrap DP data, this function specifically converts Camtrap DP data directly into the format required by camtrapR, producing the camera trap table and recordTable objects that camtrapR functions expect.

This function acts as a wrapper around read_camtrapdp, utilizing it to robustly read the datapackage, upgrade older versions, and validate the schema, before applying camtrapR's specific formatting logic and gap analysis.

The function provides a fallback mechanism for location names and species names.

Value

List (of class 'cams_dp') containing three elements:

• CTtable: Data frame with camera trap deployment information in camtrapR format

• recordTable: Data frame with species records in camtrapR format

• metadata: List containing project metadata extracted from datapackage.json

Handling Optional Data and Fallbacks

The Camtrap DP standard is designed to be highly flexible, meaning several columns that are traditionally required by camtrapR (such as specific station names or common species names) are technically optional. To ensure your data always loads smoothly into camtrapR formats, the readCamtrapDP() function employs a robust fallback hierarchy.

Location / Station Fallbacks

In camtrapR, deployments are grouped by a Station identifier. Under the Camtrap DP standard, both locationID and locationName are optional. Real-world datasets vary wildly: the official standard example provides locationName, while other datasets might only provide locationID (leaving locationName as NA), or neither!

To guarantee a Station ID is created, the function looks for identifiers in this exact order:

1. locationID: The primary identifier.

2. locationName: Used if locationID is completely missing or all NA.

3. deploymentID: The ultimate fallback. If no location data is provided, the function treats each individual deployment as its own unique station.

(Note: If the chosen column has some missing values, those specific blanks are automatically filled with the deploymentID).

Taxonomy and Species Fallbacks

Similarly, vernacularNames (common names) are entirely optional in Camtrap DP. Furthermore, non-animal records (like camera misfires or human activity) will naturally lack a scientificName. In camtrapR, users typically expect a single classification column that contains both animals and non-animals.

To handle this, the function applies this taxonomic fallback hierarchy:

1. vernacularNames: If provided in the dataset, these are joined to the observations (e.g., as vernacularName_en). Non-animal records (which have no name) are filled using the core observationType (e.g., "blank", "human", "vehicle").

2. scientificName: If no vernacular names exist, the function falls back to using scientificName as the primary classification column. It will issue a warning to inform you of this, and populate any empty rows with the observationType so that non-animal events are not lost as NAs in downstream camtrapR analyses.

Note

The Camtrap DP standard structures data in a way that supports both media-based observations (using a single media file as source) and event-based observations (considering an event with a specified duration as source). For the purpose of this function, both are treated to be equivalent. Event-based observations are converted to a single timestamp in the recordTable (using the event start time).

References

Bubnicki, J.W., Norton, B., Baskauf, S.J., et al. (2023). Camtrap DP: an open standard for the FAIR exchange and archiving of camera trap data. Remote Sensing in Ecology and Conservation, 10(3), 283-295.

Desmet, P., Govaert, S., Huybrechts, P., Oldoni, D. (2024). camtrapdp: Read and Manipulate Camera Trap Data Packages. R package https://CRAN.R-project.org/package=camtrapdp

Examples

## Not run: 
# load the sample camtrap DP dataset included in camtrapR.
 path_camtrapdp <- system.file("sample_data/tdwg_camtrap-dp_1.0.2_example", 
                               package = "camtrapR")
camtrapdp_data <- readCamtrapDP(file = file.path(path_camtrapdp, "datapackage.json")) 
camtrapdp_data

# Extract components
ct_table     <- camtrapdp_data$CTtable
record_table <- camtrapdp_data$recordTable
metadata     <- camtrapdp_data$metadata

# See Vignette 6 for more thorough examples for working with camtrap DP data. 

## End(Not run)

camtrapR documentation built on July 28, 2026, 5:10 p.m.