summarize_observations() counted a scientific name once per deployment when group_by did not contain deploymentID (#432).summarize_deployments() and summarize_observations() returned wrong time groups when group_time_by is used and a deploymentStart, deploymentEnd or eventStart falls exactly on a calendar boundary (#433).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.
camtraptor now offers a step-by-step workflow to explore and visualize data:
read_camtrapdp() (reexported from camtrapdp::read_camtrapdp()). This function supports Camtrap DP 1.0 or higher.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 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.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").
summarize_deployments() calculates the duration effort. Users can define the grouping field(s) (e.g. locationID) and temporal level (e.g. month) (#366).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).map_summary() creates a Leaflet map showing a selected feature from a summary table generated by summarize_deployments() or summarize_observations().filter_out_timelapse() allows to filter out timelapse observations (#306).add_coordinates() adds the deployment coordinates to observations (#350).The following functions are reexported from {camtrapdp}:
filter_deployments(), filter_media() and filter_observations(). They return a data package with filtered data (#315).deployments(), media(), observations(), locations(), events(), taxa(), individuals(), and contributors(). They return a data frame (#317).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_dataset(). It returns a minimal example data package (from the Camtrap DP standard) and replaces the mica dataset.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)
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)
CITATION.cff file has been added (#345).get_detection_history() calculates the detection history based on a record table and a camera operation matrix. Some analogies with camtrapR::detectionHistory (#360).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).get_custom_effort() returns now the effort for each deployment separately (#333). The returned data frame has two new columns: deploymentID and locationName.read_camtrap_dp() detects Camtrap DP version from package$profile using
regex (#295).
This supports reading Camtrap DPs created by the GBIF IPT.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).read_camtrap_dp() when reading a Camtrap DP 1.0 (#292).write_eml() for Camtrap DP 1.0 datasets (#290).read_camtrap_dp() will now always populate taxonID from the
package.taxonomy (#290).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).