Changelog • camtraptor

camtraptor (development version)

camtraptor 1.0.0

This major release updates the internal data model of camtraptor to Camtrap DP 1.0, drops support for Camtrap DP 0.1.6 and facilitates a step-by-step exploration workflow with new functions.

New workflow

camtraptor now offers a step-by-step workflow to explore and visualize data:

Read Camtrap DP files with read_camtrapdp() (reexported from camtrapdp::read_camtrapdp()). This function supports Camtrap DP 1.0 or higher.
Filter the data with filter_deployments(), filter_media() and filter_observations() (also reexported from camtrapdp). These functions replace the predicate functions (which only worked on deployments) and filter arguments in get_ functions.
Summarize deployments and observations with summarize_deployments() and summarize_observations(). These calculate features (e.g. effort_duration or n_events) grouped by fields (e.g. deploymentID, latitude and longitude) and temporal levels (e.g. "month") of your choice.
Visualize those summary tables using map_summary(), which creates a Leaflet map for the desired feature. This function replaces map_dep().

Here’s an example where you read files, filter on coordinates and adult animals, calculate observation-level summaries, and create a map showing the number of individuals:

library(camtraptor)
file <- "https://raw.githubusercontent.com/tdwg/camtrap-dp/1.0/example/datapackage.json"
x <- read_camtrapdp(file)
x %>%
  filter_deployments(latitude > 51.0, longitude > 5.0) %>%
  filter_observations(lifeStage == "adult") %>%
  summarize_observations() %>%
  map_summary(feature = "sum_count")

Note how you can stop and explore (all) the summary results returned by summarize_observations() before selecting one ("sum_count") to visualize with map_summary():

x %>%
  filter_deployments(latitude > 51.0, longitude > 5.0) %>%
  filter_observations(lifeStage == "adult") %>%
  summarize_observations()
#> # A tibble: 4 × 10
#> # Groups:   deploymentID, latitude, longitude, scientificName [4]
#>   deploymentID latitude longitude scientificName     n_scientificName n_events
#>   <chr>           <dbl>     <dbl> <chr>                         <int>    <int>
#> 1 29b7d356         51.2      5.66 Anas platyrhynchos                1        3
#> 2 577b543a         51.2      5.66 Martes foina                      1        1
#> 3 577b543a         51.2      5.66 Mustela putorius                  1        3
#> 4 577b543a         51.2      5.66 Vulpes vulpes                     1        1
#> # ℹ 4 more variables: n_observations <int>, sum_count <int>,
#> #   rai_observations <dbl>, rai_count <dbl>

Before, you had to use a specific get_ function to see a specific summary result. And you had to repeat the filters in map_dep():

# Before
x <- read_camtrap_dp(file)
get_n_individuals(
  x,
  life_stage = "adult",
  pred_and(pred_gt("latitude", 51.0), pred_gt("longitude", 5.0))
)
map_dep(
  x,
  feature = "n_individuals",
  life_stage = "adult",
  pred_and(pred_gt("latitude", 51.0), pred_gt("longitude", 5.0))
)

More details about the new workflow can be found in the vignette vignette("workflow").

New functions

New summarize_deployments() calculates the duration effort. Users can define the grouping field(s) (e.g. locationID) and temporal level (e.g. month) (#366).
New summarize_observations() calculates several observation-related features, such as the number of taxa, the number of events, the number of observations, the sum of individual counts and the Relative Abundance Index (RAI). Users can define the grouping field(s) and temporal level (#367).
New map_summary() creates a Leaflet map showing a selected feature from a summary table generated by summarize_deployments() or summarize_observations().
New filter_out_timelapse() allows to filter out timelapse observations (#306).
New add_coordinates() adds the deployment coordinates to observations (#350).

The following functions are reexported from camtrapdp:

Filter functions: filter_deployments(), filter_media() and filter_observations(). They return a data package with filtered data (#315).
Get data functions: deployments(), media(), observations(), locations(), events(), taxa(), individuals(), and contributors(). They return a data frame (#317).
Assign data functions: deployments<-, media<-, observations<-, contributors<-. They assign a data frame back to the data package and should be used with care, as it can invalidate a data package (#328).
Example data: example_dataset(). It returns a minimal example data package (from the Camtrap DP standard) and replaces the mica dataset.

Superseded functionality

The following functions will continue to work, but are superseded in favour of equivalent camtrapR functions:

Before	Now
`get_cam_op()`	`camtrapR::readCamtrapDP()` and `camtrapR::cameraOperation()` (#419)
`get_detection_history()`	`camtrapR::readCamtrapDP()` and `camtrapR::detectionHistory()` (#419)
`get_record_table()`	`camtrapR::readCamtrapDP()` and `camtrapR::recordTable()` (#419)

Deprecated functionality

The following functions still work for now, but will be removed in a future version:

Before	Now
`animal_pos`	`animal_positions`, with the column `sequenceID` renamed to `eventID` (#402, #242)
`calc_animal_pos()`	`calculate_individual_radius_angle()` (#242)
`calib_models`	`calibration_models` (#402, #242)
`get_custom_effort()`	`summarize_deployments()`, column `effort_duration` (#366)
`get_effort()`	`summarize_deployments()`, column `effort_duration` (#366)
`get_n_individuals()`	`summarize_observations()`, column `sum_count` (#367)
`get_n_obs()`	`summarize_observations()`, column `n_observations` (#367)
`get_n_species()`	`summarize_observations()`, column `n_scientificName` (#243)
`get_rai()`	`summarize_observations()`, column `rai_observations` (#243)
`get_rai_individuals()`	`summarize_observations()`, column `rai_count` (#243)
`get_species()`	`taxa()` (#343)
`map_dep()`	`map_summary()` (#231, #91)
`mica`	`example_dataset()` (#402)
`read_camtrap_dp()`	`read_camtrapdp()` (without underscore) (#298)

The following functions and objects no longer work:

Before	Now
`apply_filter_predicate()`	This helper function is no longer needed (#316)
`check_species()`	`taxa()` to return all taxa (#235)
`get_scientific_name()`	`taxa()` to return all taxa (#235)
`pred()`	`filter_deployments(locationID == "e254a13c")` (#316)
`pred_not()`	`filter_deployments(locationID != "e254a13c")` (#316)
`pred_gt()`	`filter_deployments(x, latitude > 51)` (#316)
`pred_gte()`	`filter_deployments(x, latitude >= 51)` (#316)
`pred_lt()`	`filter_deployments(x, latitude < 51)` (#316)
`pred_lte()`	`filter_deployments(x, latitude <= 51)` (#316)
`pred_in()`	`filter_deployments(x, locationID %in% c("e254a13c", "2df5259b"))` (#316)
`pred_notin()`	`filter_deployments(x, !locationID %in% c("e254a13c", "2df5259b"))` (#316)
`pred_na()`	`filter_deployments(x, is.na(setupBy))` (#316)
`pred_notna()`	`filter_deployments(x, !is.na(setupBy))` (#316)
`pred_and()`	`filter_deployments(x, cameraHeight >= 1.0 & cameraHeading >= 100)` (#316)
`pred_or()`	`filter_deployments(x, cameraHeight >= 1.0 \| cameraHeading >= 100)` (#316)
`read_wi()`	Removed as it is out of scope. Wildlife Insights will provide Camtrap DP export functionality (#351).
`round_coordinates()`	Moved to `camtrapdp::round_coordinates()` (#327)
`write_dwc()`	Moved to `camtrapdp::write_dwc()`
`write_eml()`	Moved to `camtrapdp::write_eml()`

The following arguments have or will be removed:

Before	Now
`sex` in `map_dep()` and `get_` functions	Use `filter_observations(sex = "female")` first
`life_stage` in `map_dep()` and `get_` functions	Use `filter_observations(lifeStage = "adult")` first
`datapkg` in `read_camptrap_dp()`	`read_camtrapdp(x)`
`package` as the first argument in many functions	Renamed to `x` (#324)

Other changes

CITATION.cff file has been added (#345).
Sanne Govaert and Wolf Missotten have been added as authors.

camtraptor 0.28.0

get_detection_history() calculates the detection history based on a record table and a camera operation matrix. Some analogies with camtrapR::detectionHistory (#360).

camtraptor 0.27.0

get_record_table() returns now 4 new columns: longitude, latitude (deployment coordinates), clock (clock time of the observation in radians) and solar (sun time of the observation in radians) (#341).

camtraptor 0.26.0

get_custom_effort() returns now the effort for each deployment separately (#333). The returned data frame has two new columns: deploymentID and locationName.

camtraptor 0.25.0

read_camtrap_dp() detects Camtrap DP version from package$profile using regex (#295). This supports reading Camtrap DPs created by the GBIF IPT.

camtraptor 0.24.0

Replicate old Camtrap DP 0.1.6 behaviour and populate angle and radius for event-based observations. Values are taken from the first media-based observation (fields individualPositionRadius and individualPositionAngle) for each eventID/individualID combination (#291).

camtraptor 0.23.0

Fix bug in read_camtrap_dp() when reading a Camtrap DP 1.0 (#292).

camtraptor 0.22.0

Fix bug in write_eml() for Camtrap DP 1.0 datasets (#290).
read_camtrap_dp() will now always populate taxonID from the package.taxonomy (#290).

camtraptor 0.21.0

read_camtrap_dp() supports Camtrap DP 1.0 (upcoming Agouti export format) in favour of Camtrap DP 1.0-rc.1 (#284). To avoid breaking changes to users, it will down-convert Camtrap DP 1.0 to 0.1.6 which is currently used as internal data model for camtraptor.
get_custom_effort() now calculates per calendar month/week (#219).
write_dwc() has an updated mapping for dwc_audubon.csv (#274).
get_record_table() returns the number of observed individuals (#279).
get_cam_op() allows to add session and camera IDs to the station names output (#288).