---
title: "Package Overview"
author: "Elham Ebrahimi"
description: "An overview of the camtrapReport workflow, core functionality, and the data quality checks and ecological reports it produces."
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Package Overview}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
resource_files:
  - figures/package-architecture.png
---

## Introduction

`camtrapReport` provides a reproducible workflow for turning standardised
camera-trap data into structured ecological reports. It brings data-quality
checks, ecological summaries, visualisation, and report generation together so
that users can move from a Camtrap DP dataset to a documented report without
having to assemble each step separately.

The workflow starts with `camData()`, which creates a `camReport` object from
the input data. The same object is then used to generate two main outputs:

- a **Data Status Check**, created with `status()`, which helps users identify
  issues in the data before interpretation or analysis; and
- an **Ecological Report**, created with `report()`, which combines selected
  analyses, figures, tables, maps, and explanatory text in a single document.

## Input data

The main input is a camera-trap dataset in
[Camtrap DP format](https://camtrap-dp.tdwg.org/), supplied either as a ZIP
archive or as an extracted Camtrap DP directory.

Optional supporting data can also be provided. These include habitat
information and a study-area boundary, which can be used in relevant
summaries, maps, and ecological analyses.

### Bundled example data

The package includes a relationship-preserving subset of the GMU8_LEUVEN
Camtrap DP dataset for examples, demonstrations, and automated tests. It
contains eight derived camera locations, 87 deployments, 15,492 retained media
records, and 11,092 observation records. Bundled habitat data and a derived
study-area boundary provide optional inputs for exercising those parts of the
workflow. The subset is a software fixture and should not be used for
ecological inference; its provenance and transformations are documented in
`inst/external/README-Leuven-dataset.md` in the source repository.

## Key outputs

### Data Status Check

The Data Status Check is intended to help users inspect the quality and
completeness of a dataset before moving on to ecological interpretation. It
summarises issues such as missing information, annotation and validation
status, temporal inconsistencies, spatial outliers, observation types, and
other aspects of data readiness.

It is generated with:

```r
status(cm)
```

The report is diagnostic rather than inferential: passing the checks does not
mean that a sampling design is suitable for every ecological analysis.

### Ecological Report

The Ecological Report brings together selected ecological summaries,
analyses, figures, tables, maps, and explanatory text in an article-style
document.

It is generated with:

```r
report(cm)
```

The content of the report depends on the selected sections, available data,
and analytical settings. Users can therefore adapt the report to the purpose
and scope of a particular monitoring project.

Both `status()` and `report()` create an HTML file together with the
intermediate R Markdown file used to render it. With their default relative
filenames, these files are written beside the writable camera-trap data used to
create the object. Supply an explicit file stem or an existing output directory
through `filename` to control where the files are written. Package examples
copy the bundled data and write generated reports to temporary directories.

## Working with the `camReport` object

The `camReport` object keeps the input data, metadata, settings, and report
outputs together during the workflow. For most users, the important point is
that the same object can be inspected, adjusted, and then used to regenerate
reports with updated settings.

For example, metadata can be viewed or changed with `info()`:

```r
info(cm)

info(cm, name = "authors")

info(cm, name = "authors") <- c(
  "Elham Ebrahimi",
  "Patrick Jansen"
)
```

Users can also change the taxonomic focus, select years, adjust filters, or
choose which report sections should be included before regenerating the
report.

## A modular reporting workflow

`camtrapReport` is modular in the sense that a report is assembled from
separate sections rather than from one fixed template. Users can keep only
the sections relevant to their data and reporting needs, and can omit or
reorder sections when needed.

For example:

```r
# Inspect available report sections
section_names()

# Keep only selected sections
n <- section_names(
  keep = c(
    "introduction",
    "methods",
    "study_area"
  )
)

# Apply the selection
sections(cm, n)

# Generate the report
report(cm)
```

This makes it possible to use the same overall workflow for projects that
differ in species, survey duration, spatial extent, available covariates, or
reporting objectives.

Users who want to develop or manage additional report modules can find more
detail in the
[Module management and extension](https://spatialecology.github.io/camtrapReport/articles/modules.html)
guide.

## Reproducibility, interpretation, and scope

`camtrapReport` supports reproducible reporting by applying a consistent
workflow from data checking through ecological analysis to report generation.
Analytical modules use established ecological and statistical methods, with
default settings that provide a common starting point across camera-trap
datasets.

Because the workflow is modular, users can select relevant analyses and adjust
module-specific settings, species groups, and thresholds according to their
data, study design, and analytical objectives. Results should therefore be
interpreted in relation to the characteristics of the dataset, sampling design,
and assumptions of the selected methods.

General guidance on recording computational environments and managing
reproducible research workflows is available from the
[Reproducible Research CRAN Task View](https://cran.r-project.org/view=ReproducibleResearch).

## Relationship to other camera-trap packages

`camtrapReport` is intended to complement, rather than replace, existing
camera-trap and ecological analysis packages. Different packages address
different parts of the workflow.

| Area | Examples | Relationship to `camtrapReport` |
|---|---|---|
| Standardised camera-trap data | [`camtrapdp`](https://inbo.github.io/camtrapdp/) | `camtrapReport` uses Camtrap DP as its main input format. |
| Data management and exploration | [`camtrapR`](https://doi.org/10.32614/CRAN.package.camtrapR), [`ct`](https://doi.org/10.32614/CRAN.package.ct), [`camtraptor`](https://inbo.github.io/camtraptor/) | These packages provide complementary tools for preparing, exploring, and summarising camera-trap data. |
| Activity, diversity, abundance, and density analyses | [`activity`](https://doi.org/10.32614/CRAN.package.activity), [`overlap`](https://doi.org/10.32614/CRAN.package.overlap), [`iNEXT`](https://doi.org/10.32614/CRAN.package.iNEXT), [`camtrapDensity`](https://github.com/MarcusRowcliffe/camtrapDensity), [`Distance`](https://CRAN.R-project.org/package=Distance) | Specialised methods can support individual analyses used within a reporting workflow. |
| Hierarchical and spatial modelling | [`unmarked`](https://doi.org/10.32614/CRAN.package.unmarked), [`secr`](https://CRAN.R-project.org/package=secr) | These packages provide specialised modelling frameworks outside the main reporting role of `camtrapReport`. |

The main role of `camtrapReport` is therefore not to reproduce every
specialised method. Its focus is on bringing data checks, selected ecological
analyses, visual outputs, metadata, and explanatory text together in a
consistent report generated from a standardised dataset.

## Conclusion

`camtrapReport` provides a structured workflow for moving from standardised
camera-trap data to quality-checked and reproducible ecological reporting.
Its modular design allows the workflow to be adapted to different datasets,
monitoring objectives, and analytical needs.

For more detail, see the
[Data Status Check](https://spatialecology.github.io/camtrapReport/articles/data-status-report.html),
[Ecological Report](https://spatialecology.github.io/camtrapReport/articles/ecological-report.html),
and
[Module management and extension](https://spatialecology.github.io/camtrapReport/articles/modules.html)
articles.