camtrapReport
Reproducible reporting for camera-trap monitoring data
camtrapReport transforms camera-trap data in Camtrap
DP format into two complementary reports:
A camReport object brings together input data, settings, and reusable
reporting modules. Users can select and customize sections, or develop
modules and Analytical Profiles for particular monitoring workflows. The
package complements, rather than replaces, tools for camera-trap data
management and specialized ecological analysis.
The optional graphical interface (gui()) is designed to make these
workflows accessible to users with different levels of programming
experience. Shiny is used only for this interface; code-based workflows
using camData(), report(), and status() do not require launching
Shiny.
Overview of the camtrapReport workflow, from standardized
camera-trap data to automated reporting. See the
Data
Status Check,
Ecological
Report, and
Module
Management guides for the corresponding components of the workflow.
The package has been developed and tested with camera-trap datasets from monitoring sites across five continents, including the European Observatory of Wildlife (EOW). These applications inform software development but do not constitute formal validation of ecological estimates or a systematic usability assessment. See Resources.
camtrapReport requires R 4.1.0 or later. Install it from GitHub using
pak:
if (!requireNamespace("pak", quietly = TRUE)) {
install.packages("pak")
}
pak::pkg_install("spatialecology/camtrapReport")
Some modules require additional R packages. To install optional dependencies for available modules, run:
camtrapReport::install_all()
Use the R functions directly, or configure and generate reports through
the optional Shiny interface, gui(cm). Shiny is not needed to run the
R workflow. Report-generation time depends on dataset size and selected
analyses.
Provide a Camtrap DP dataset as a directory or ZIP archive. The main dataset cannot currently be supplied as in-memory R tables; optional habitat and study-area inputs can be R objects. Convert other formats to Camtrap DP before import (e.g., with Biowatch or a custom workflow).
Input validation: camtrapReport expects datasets in Camtrap
DP format but does not perform full
schema validation during import. Data exported directly from platforms
such as Agouti already follow this standard. For
datasets created or modified independently, users are encouraged to
validate compliance with the Camtrap DP specification before calling
camData(). The Data Status Check generated by status() assesses data
completeness and consistency but does not replace schema validation.
The example uses a bundled subset of GMU8_LEUVEN, with habitat data and a study-area boundary. Input files are copied to a writable temporary directory because processing may create files alongside the dataset.
library(camtrapReport)
# Prepare the example data
example_root <- tempfile("camtrapReport-example-")
dir.create(example_root)
file.copy(
system.file("external", "dataset", package = "camtrapReport"),
example_root,
recursive = TRUE
)
#> [1] TRUE
habitat <- read.csv(
system.file("external", "habitat", "habitat.csv", package = "camtrapReport")
)
study_area <- system.file(
"external", "study_area", "study_area.shp",
package = "camtrapReport"
)
# Create a camReport object
cm <- camData(
data = file.path(example_root, "dataset"),
habitat = habitat,
study_area = study_area,
update = TRUE
)
#> The camReport object is being created...
#> Dataset size: 6.6 MB.
#> File size looks modest, but full object creation may still take several minutes depending on the number of records.
#> Taxonomic class is unavailable for 43 recorded taxa. Class-dependent groups and mammal counts may be incomplete; missing classification does not indicate ecological absence. Supply source classifications or explicitly enable GBIF enrichment and rebuild with update = TRUE.
#> Setup is done!
#> Data loaded successfully in 30 sec.
#> camReport object is ready for GMU8 LEUVEN.
cm
#> Camera trap Object for the site : GMU8 LEUVEN
#> =====================================================
#> Total number of sequences : 10182
#> Total number of observations : 10798
#> Total number of animals : 4693
#> Total number of detected species: 41
#> Date/time (years) with data : 2018, 2019, 2020, 2021, 2022, and 2023
#> -----------------------------------------------------
camData() accepts a Camtrap DP directory or ZIP archive. Optional
habitat and study-area inputs support additional formats; see ?camData
for details.
Generated files: camData() saves __camReport_Object.rds
alongside the extracted dataset and, when a study area is provided, also
creates study_area.map. These files support reuse of processed data.
To rebuild the cached object after changes, use update = TRUE. The
example above uses a temporary dataset copy to avoid modifying the
bundled files.
status() generates a Data Status Check summarizing spatial and
temporal coverage, data completeness, classification consistency, and
annotation quality. It highlights potential issues requiring attention
before ecological analysis.
status_file <- status(cm, view = FALSE)
View example Data Status Check
report() combines selected modules, tables, figures, maps, and
data-informed narratives into a reproducible Ecological Report. Modules
can be selected, reordered, or extended. The function returns the output
path; view = TRUE opens the completed report.
report_file <- report(
cm,
view = FALSE
)
View example Ecological Report
Built-in modules cover study-area and sampling descriptions, camera locations, sampling effort, image and data processing, species detections and capture-based indices, species richness and accumulation, co-occurrence, activity patterns, habitat associations, spatial detection intensity, and Random Encounter Model (REM) density estimation. Outputs depend on the available data, module requirements, and methodological assumptions.
Explore the Module
Catalog
to compare available modules in the Data Status Check, default (Global)
and EOW reports, including methods, required inputs, and settings. Some
sections depend on optional packages, data availability, or analytical
prerequisites and may be absent from a particular report. Use
section_names() to inspect available sections in R.
Standardized data can yield different ecological estimates when analytical choices differ. Analytical Profiles specify reusable selections of modules, methods, settings, assumptions, and reporting conventions to improve consistency across sites and monitoring rounds.
Alongside the default profile, camtrapReport provides an EOW-oriented profile configured for European Observatory of Wildlife monitoring. Additional profiles are under development; users can define and share their own without implying formal network endorsement.
See the Profiles
guide
or ?reportProfile. To propose a workflow for your network, join
GitHub
Discussions.
Inspect metadata and select report modules (this changes the sections used in subsequent reports):
info(cm, name = c("title", "authors"))
selected_sections <- section_names(
keep = c(
"introduction",
"methods",
"study_area",
"sampling",
"effort"
)
)
sections(cm, selected_sections)
Modules may combine predefined narrative templates, Camtrap DP metadata, and computed results; this is where much of the report text originates. Review generated text before publication. Customize existing modules or add new ones in a writable project directory rather than editing installed package files; see Module management.
Use gui(cm) to edit report metadata, select modules, and generate
reports interactively. The R interface supports further customization.
A completed Data Status Check does not establish suitability for ecological inference. Interpret results in light of sampling effort, detectability, spatial and temporal coverage, and method-specific assumptions.
Retain source data, additional inputs, selected modules, analytical settings, and package versions for reproducibility. Review maps and outputs for sensitive species locations before sharing.
Taxonomy enrichment: camData() defaults to
enrich_taxonomy = FALSE and makes no GBIF requests. Set
enrich_taxonomy = TRUE explicitly to send species names to GBIF and
fill missing classifications; existing source classifications are
preserved. Use update = TRUE to rebuild an existing cache with the
revised setting. Missing classifications can affect taxonomic-group
filters. See ?camData.
The bundled example is a reduced subset of the GMU8_LEUVEN Camtrap DP dataset, published by INBO through GBIF. It contains 8 locations, 87 deployments, 15,492 retained media records, and 11,092 observations. This derived dataset is for demonstration and testing, not ecological inference. See the preparation notes.
camtrapdp supports Camtrap DP
data validation and transformation;
camtraptor supports data
exploration; and camtrapR
and ct support broader
camera-trap workflows. camtrapReport complements these tools by
assembling data-status diagnostics, ecological analyses, and explanatory
narratives into modular reports.
citation("camtrapReport")
camtrapReport is developed and maintained by Elham Ebrahimi.
Contributions to code, documentation, modules, and Analytical Profiles are welcome. See the contributing guidelines and Code of Conduct.