Package Overview
Elham Ebrahimi
Package-Overview.RmdIntroduction
camtrapReport is designed to help users move from raw camera-trap records to clear, reproducible ecological outputs. Rather than treating data cleaning, summarisation, analysis, visualisation, and reporting as separate tasks, the package brings them together in a single workflow. This makes it easier to produce consistent outputs across study sites and survey periods while reducing the manual effort required to prepare reports.
This vignette provides a conceptual overview of how the package is
organised. It explains the main parts of the workflow, the role of the
central camReport object, and how data checks, analyses,
and report sections fit together. For a practical introduction to
installation, input data, and first use, see the Get
started page.
What camtrapReport is designed to do
The package has two main aims. First, it helps users assess whether a camera-trap dataset is complete, consistent, and ready for analysis. Second, it supports the generation of standardised ecological reports that combine summaries, figures, maps, and narrative text in a reproducible format.
In practice, camtrapReport can be used to:
- organise and prepare camera-trap data for downstream analysis,
- identify common data-quality problems before reporting,
- automate ecological analyses,
- generate reports and assemble outputs into an article-style document that can be reviewed, shared, and reproduced later.
The package is especially useful when the same type of reporting must be repeated across projects, sites, years, or species groups.
Package architecture
The camReport object
At the centre of the package is the camReport object,
created with camData(). This object acts as the main
workflow container. It stores the imported dataset, user settings,
intermediate results, and outputs generated by different parts of the
workflow.
Keeping these elements together in one object helps the package remain organised and reproducible. Instead of passing many separate files and arguments between functions, users work from a single object that keeps data, settings, and outputs connected.
Modular workflow structure
camtrapReport is built as a modular system. This means
that many parts of the ecological report are handled as separate
modules, each responsible for a specific output or analysis. A module
may produce a table, a figure, a map, a summary statistic, or a block of
narrative text.
This modular structure makes the package flexible. Users can run only the parts they need, combine selected outputs into a customised report, and extend the package by adding new modules when needed.
Reports, sections, and modules
A useful way to think about the package is as a workflow with three connected layers:
- Data preparation, where the input data are read, checked, cleaned, and organised;
- Analysis modules, where specific summaries and ecological outputs are generated;
- Report sections, where those outputs are assembled into a readable final document.
Modules supply the content, while report sections provide the structure. Because sections are built from modular outputs, they can be included, omitted, reordered, or expanded depending on the aims of the report.
Input data model
Camtrap-DP as the standard input format
camtrapReport is designed around the Camtrap-DP standard. In the package workflow, the required input is a single ZIP archive containing the standard camera-trap data resources. This gives users a consistent entry point and allows the package to automate much of the pre-processing and reporting workflow.
Using a standard format is important because it improves comparability and makes it easier to generate the same kinds of outputs across multiple datasets.
Required input data
The only mandatory input for the basic workflow is a camera-trap dataset in Camtrap-DP format. When this ZIP archive is read with camData(), the package extracts the relevant information, reorganises it internally, and prepares it for data checks and ecological analyses.
Optional supporting data
Although the ZIP archive is enough to run the workflow, additional supporting data can improve the final outputs. Examples include habitat information linked to camera locations, study-area boundaries for mapping, and custom text blocks for report sections.
These optional inputs are not required to create a report, but they can make the report more informative and easier to interpret.
Core functionality
Data import and preparation
The workflow starts by reading the input data and preparing them for downstream use. During this stage, the package organises the camera-trap data into internal structures that can be used consistently by later analyses and report sections.
This step also supports data harmonisation and summarisation, helping prepare the dataset for quality checks and ecological reporting.
Data quality assessment
One of the two main components of the package is the Data Status Report. This part of the workflow checks whether the dataset is complete and internally consistent, and whether it is ready for full ecological reporting.
The goal is not only to detect problems but also to help users understand what needs to be corrected before interpreting results.
Ecological report generation
The second main component is the Ecological Report workflow. Once data have been prepared and checked, the package can generate an article-style report that combines multiple outputs into a single document.
Depending on the selected modules, the report may include descriptive summaries, tables, figures, maps, and ecological analyses across spatial and temporal dimensions.
Visual and analytical outputs
A major strength of camtrapReport is that it links analysis and communication. Instead of producing isolated outputs, the package is designed to turn results into report-ready material.
This includes:
- summary tables,
- figures and graphs,
- spatial outputs such as maps,
- narrative text generated from metadata and results.
Because these outputs are generated within a single workflow, they remain consistent with the underlying data and analysis settings.
End-to-end workflow
Step 1: Prepare the input data
The workflow begins with a standardised input dataset, usually provided as a Camtrap-DP ZIP archive. Optional supporting inputs can also be added at this stage.
Step 2: Create the camReport object
The dataset is then read with camData(), which creates
the camReport object. This object stores the processed data and
provides the central structure used by the rest of the workflow.
Main outputs produced by the package
Data Status Report
The Data Status Report provides a structured overview of data quality. It helps users assess whether the dataset is suitable for analysis and highlights issues that may require attention before further processing.
Extending the workflow
Report sections
Report sections are the building blocks of the final document. Because they are assembled from modular outputs, users can adapt the structure of the final report to match different reporting needs.
Modules
Modules are what make the package extensible. New modules can be added to support additional ecological summaries, analyses, or visualisations. This allows the package to grow with the needs of different users and projects.
In this way, camtrapReport is not only a fixed reporting tool but also a framework that can be customised and extended.
Conclusion
camtrapReport provides a unified workflow for turning camera-trap data into reproducible ecological outputs. Its design combines data preparation, quality assessment, analysis, visualisation, and reporting within a single modular framework.
The package is built around a central camReport object and two main reporting pathways: the Data Status Report and the Ecological Report. Together, these make it easier to move from raw data to interpretable outputs in a way that is transparent, repeatable, and adaptable to different monitoring goals.
To see how data-quality checks work in detail, continue to the Data Status Report vignette. To explore how report content can be customised or extended, see Module Management.