Read camera-trap data in Camtrap DP format

Create a camReport object from a Camtrap DP dataset.

Usage

camData(data, habitat, study_area, update, enrich_taxonomy = FALSE,
  ..., overwrite = FALSE)

Arguments

data

A character string giving the path to a Camtrap DP dataset, provided as a ZIP file or an extracted dataset directory.

habitat

An optional data frame containing habitat information for camera locations. The default is NULL.

study_area

An optional study-area boundary provided as a spatial file path, a SpatVector, or an sf object. The default is NULL.

update

A logical value (default FALSE) specifying whether to recreate a previously saved camReport object.

enrich_taxonomy

A single logical value (default FALSE) allowing GBIF taxonomy enrichment when the optional taxize package is installed. Only explicit TRUE permits these network requests. This affects fresh imports; use update = TRUE to rebuild a previously cached object.

...

Additional arguments. These are currently reserved for future use.

overwrite

A single logical value (default FALSE) allowing a ZIP input to replace archived files in an existing extraction directory. Other files in that directory are retained. This does not control reuse of a cached object when data is already a dataset directory; see update.

Value

A camReport object.

Details

The function reads the input Camtrap DP dataset and creates a camReport object. The resulting object contains processed camera-trap data, metadata, summaries, report text, report modules, and data-status information used to generate automated reports.

If habitat information is provided, it is linked to camera locations and used in habitat-related summaries. If a study-area boundary is provided, it is stored with the object and used in spatial summaries where relevant.

The camReport object is saved within an extracted dataset directory as __camReport_Object.rds. A later call using that directory reuses the saved object unless update = TRUE, in which case the object is recreated.

data currently accepts a file-system path, not an in-memory data frame or list. A dataset directory contains datapackage.json, deployments.csv, media.csv, and observations.csv. The following identifiers and columns explain the main relationships; this is not a complete Camtrap DP schema:

File	Contents and important links
datapackage.json	Project metadata and a taxonomic list with species names, taxon identifiers, ranks, families, orders, and optional vernacular names.
deployments.csv	One camera deployment per deploymentID, with locationID, locationName, longitude, latitude, deploymentStart, and deploymentEnd.
media.csv	Images or videos identified by mediaID, linked to deploymentID, with timestamp and optional capture-method and file metadata.
observations.csv	Species or other classifications linked to deploymentID, mediaID and/or eventID, with scientificName, observation level, event times, counts, and optional individual measurements.

A deployment is a period during which a camera is installed at a location. An observation records a classification at media or event level. An event groups related media; camtrapReport uses sequenceID internally for this event grouping and derives a sequences table from media timestamps. These internal sequences are not an additional input CSV file. See the Camtrap DP specification for definitions and the example-data provenance for a concrete dataset.

Import and status() provide package-specific data checks, not formal validation against the complete Camtrap DP schema. Check schema compliance upstream. After correcting source CSV or JSON files, call camData() again with update = TRUE and the optional inputs, then regenerate status(). Merely rerunning status() on the old object does not reread changed files.

Files and cache reuse

camData() writes __camReport_Object.rds beside the extracted data and, when a study area is supplied, writes study_area.map. A ZIP input is extracted before reading into a directory named after the ZIP file (without its extension) in the working directory. An existing target is rejected unless overwrite = TRUE. Explicit overwriting replaces archived members only; unrelated old files remain, and extraction is not transactional. A ZIP import reads the extracted files afresh and replaces the saved object only after a successful import. Use a writable copy of the input dataset, as in the examples, rather than an installed package directory. For directory inputs, a cached object is reused when update = FALSE. Lightweight file-size and modification-time checks warn if the four source CSV/JSON files were changed, added or removed in the dataset root or their recorded directories. The cache is still reused; use update = TRUE to rebuild it. Older caches without this metadata also warn because their freshness cannot be verified. No input contents are hashed or reread during this check. Changes that preserve both size and modification time, files in previously unknown nested directories, and changes to optional habitat or study_area inputs are not detected; rebuild explicitly for these. Only load datasets and saved R objects from sources you trust.

ZIP inventories are checked before extraction for unsafe or ambiguous paths and resource limits. The defaults are 100,000 entries (including directories) and 20 GiB of total declared uncompressed size. To adjust these limits, set options(camtrapReport.max_zip_entries = 100000, camtrapReport.max_zip_bytes = 20 * 1024^3) before import. Each limit must be a positive finite number. These checks are practical safeguards, not a security sandbox or complete protection against malicious archives.

Optional taxonomy enrichment

The default enrich_taxonomy = FALSE never initiates GBIF taxonomy requests, whether or not taxize is installed. With explicit enrich_taxonomy = TRUE and taxize installed, a fresh import sends scientific names to GBIF to fill missing class and order information. A message announces this network access. Requests can affect import time, privacy and reproducibility. Source-provided names, identifiers and valid classifications are retained; external results fill only missing values after an unambiguous identifier and name match. Existing normalization of taxon-ID URLs to their last path component is unchanged; the original metadata remain available in object$info$json. Ambiguous, unmatched or incomplete results remain missing, with a concise warning that does not list the species inventory. Optional lookup failures do not prevent import of the underlying data.

No package-level timeout or complete-operation time limit is imposed. The supported taxize lookup stages do not offer one consistently verified end-to-end timeout interface; R's global timeout option is not a guarantee for these HTTP requests. For predictable offline operation, leave enrichment disabled and supply adequate taxonomy in datapackage.json.

Without enrichment, imported species names, families, orders and counts are retained, including classes when supplied in the source. Taxonomic classes may otherwise be unavailable. Groups defined by class (for example wild_mammals, birds, reptiles or amphibians) may then be absent. Setup reports missing classifications; existing mammal-count summaries can be incomplete and must not be interpreted as ecological absence. Explicit class-based capture requests require available class metadata with a verified match when classification is incomplete; otherwise they stop with a clear error. Partial metadata with verified matches produces a warning. Default order-based groups remain usable when the source supplies the relevant orders. This option does not remove taxonomy already present in a reused cache. Reusing __camReport_Object.rds does not query GBIF, even if the enrichment setting changes; use update = TRUE to rebuild with that setting. This is a processed-object cache, not a cache of individual GBIF responses. Remote taxonomy can change between fresh lookups. Preserve the source data, processed object and package versions used in analyses.

Study areas that change over time

study_area accepts one boundary per object. Multiple Shiny uploads are the component files of a shapefile (.shp, .shx, .dbf, .prj, etc.), not a set of year-specific boundaries. For different survey footprints, prepare separate year-specific datasets and objects with the corresponding boundary, or supply a custom module with an explicit year-to-boundary mapping.

See also

report(), status(), info(), gui()

Examples

# \donttest{
# Small import demonstration, not data for ecological inference.
# The larger analytical example is in system.file("external", "dataset",
# package = "camtrapReport"); see the vignettes for its complete workflow.
source_dataset <- system.file(
  "external",
  "example-small",
  package = "camtrapReport"
)
example_dataset <- tempfile("camtrapReport-example-")
dir.create(example_dataset)
invisible(file.copy(
  list.files(source_dataset, full.names = TRUE),
  example_dataset,
  recursive = TRUE
))

cm <- camData(example_dataset)
#> The camReport object is being created...
#> Dataset size: 164.4 KB.
#> File size looks modest, but full object creation may still take several minutes depending on the number of records.
#> Taxonomic class is unavailable for 10 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 16 sec.
#> camReport object is ready for GMU8 LEUVEN.

cm
#> Camera trap Object for the site : GMU8 LEUVEN 
#> ===================================================== 
#> Total number of sequences       :  256 
#> Total number of observations    :  267 
#> Total number of animals         :  85 
#> Total number of detected species:  10 
#> Date/time (years) with data     :  2018 
#> -----------------------------------------------------

unlink(example_dataset, recursive = TRUE, force = TRUE)
# }