Merge pull request #70 from inbo/filenames

Update output names of write_dwc + Usage section in README

NEWS.md

@@ -5,7 +5,7 @@
 * New accessor functions `locations()`, `events()` and `taxa()` return a data frame with unique locations, events and taxa respectively (#22, #57, #17).
 * New functions `filter_deployments()`, `filter_observations()` and `filter_media()` allow to filter data. They work similarly to [dplyr](https://cran.r-project.org/package=dplyr)'s `filter()` (#23).
 * New function `write_dwc()` transforms a Camera Trap Data Package to a Darwin Core Archive (#55).
-* New function `example_package()` returns the latest Camtrap DP example dataset and caches the result (#24).
+* New function `example_package()` returns the latest Camtrap DP example dataset and caches the result (#24, #67).
 * New function `version()` allows to get the version of a camtrapdp object.
 * New internal function `check_camtrapdp()` validates a camtrapdp object (#34).
 * New internal function `convert()` converts camtrapdp objects to the latest version. This function is currently not used, as the only supported version is Camtrap DP 1.0 (#9).

R/write_dwc.R

@@ -80,8 +80,8 @@ write_dwc <- function(x, directory = ".") {
   # Start transformation
   cli::cli_h2("Transforming data to Darwin Core")
 
-  # Create dwc_occurrence
-  dwc_occurrence <-
+  # Create Darwin Core Occurrence core
+  occurrence <-
     observations(x) %>%
     dplyr::left_join(deployments(x), by = "deploymentID") %>%
     dplyr::arrange(.data$deploymentID, .data$eventStart) %>%
@@ -222,8 +222,8 @@ write_dwc <- function(x, directory = ".") {
       "identificationRemarks", "taxonID", "scientificName", "kingdom"
     )
 
-  # Create audiovisual extension
-  dwc_audiovisual <-
+  # Create Audubon/Audiovisual Media Description extension
+  multimedia <-
     observations(x) %>%
     dplyr::select(-"mediaID") %>%
     dplyr::left_join(
@@ -273,29 +273,29 @@ write_dwc <- function(x, directory = ".") {
     )
 
   # Write files
-  dwc_occurrence_path <- file.path(directory, "dwc_occurrence.csv")
-  dwc_audiovisual_path <- file.path(directory, "dwc_audiovisual.csv")
+  occurrence_path <- file.path(directory, "occurrence.csv")
+  multimedia_path <- file.path(directory, "multimedia.csv")
   meta_xml_path <- file.path(directory, "meta.xml")
   cli::cli_h2("Writing files")
   cli::cli_ul(c(
-    "{.file {dwc_occurrence_path}}",
-    "{.file {dwc_audiovisual_path}}",
+    "{.file {occurrence_path}}",
+    "{.file {multimedia_path}}",
     "{.file {meta_xml_path}}"
   ))
   if (!dir.exists(directory)) {
     dir.create(directory, recursive = TRUE)
   }
-  readr::write_csv(dwc_occurrence, dwc_occurrence_path, na = "")
-  readr::write_csv(dwc_audiovisual, dwc_audiovisual_path, na = "")
+  readr::write_csv(occurrence, occurrence_path, na = "")
+  readr::write_csv(multimedia, multimedia_path, na = "")
   file.copy(
     system.file("extdata", "meta.xml", package = "camtrapdp"), # Static meta.xml
     meta_xml_path
   )
 
   # Return list with Darwin Core data invisibly
   return <- list(
-    dwc_occurrence = dplyr::as_tibble(dwc_occurrence),
-    dwc_audiovisual = dplyr::as_tibble(dwc_audiovisual)
+    occurrence = dplyr::as_tibble(occurrence),
+    multimedia = dplyr::as_tibble(multimedia)
   )
   invisible(return)
 }

README.Rmd

@@ -44,7 +44,7 @@ devtools::install_github("inbo/camtrapdp")
 
 ## Usage
 
-With camtrapdp you can **read** a (downloaded) Camtrap DP dataset into your R environment:
+With camtrapdp you can **read** a Camtrap DP dataset into your R environment:
 
 ```{r}
 library(camtrapdp)
@@ -56,20 +56,24 @@ x
 
 `read_camtrapdp()` will automatically **convert** an older version of Camtrap DP to the latest version. It will also make the data easier to use, by assigning taxonomic information (found in the metadata) to the observations and `eventID`s (found in the observations) to the media.
 
-To access the data, use one of the [accessor functions](https://inbo.github.io/camtrapdp/reference/index.html#accessor-functions) like `locations()`:
+To **access** the data, use one of the [accessor functions](https://inbo.github.io/camtrapdp/reference/index.html#accessor-and-assignment-functions) like `locations()`:
 
 ```{r}
 locations(x)
 ```
 
-One can also **filter** data, which will automatically filter the related data. For example, here are all the event-based observations that have a media file that was marked as favourite:
+You can also **filter** data with one of the [filter functions](https://inbo.github.io/camtrapdp/reference/index.html#filter-functions), which automatically filter the related data. For example, here we filter observations on scientific name(s) and return the associated events in that subset:
 
 ```{r}
 x %>%
-  filter_observations(observationLevel == "event") %>%
-  filter_media(favorite == TRUE) %>%
-  observations()
+  filter_observations(
+    scientificName %in% c("Martes foina", "Mustela putorius")
+  ) %>%
+  events()
 ```
+
+For more functionality, see the [function reference](https://inbo.github.io/camtrapdp/reference/index.html).
+
 ## Meta
 
 - We welcome [contributions](https://inbo.github.io/camtrapdp/CONTRIBUTING.html) including bug reports.

README.md

@@ -43,8 +43,8 @@ devtools::install_github("inbo/camtrapdp")
 
 ## Usage
 
-With camtrapdp you can **read** a (downloaded) Camtrap DP dataset into
-your R environment:
+With camtrapdp you can **read** a Camtrap DP dataset into your R
+environment:
 
 ``` r
 library(camtrapdp)
@@ -65,8 +65,8 @@ Camtrap DP to the latest version. It will also make the data easier to
 use, by assigning taxonomic information (found in the metadata) to the
 observations and `eventID`s (found in the observations) to the media.
 
-To access the data, use one of the [accessor
-functions](https://inbo.github.io/camtrapdp/reference/index.html#accessor-functions)
+To **access** the data, use one of the [accessor
+functions](https://inbo.github.io/camtrapdp/reference/index.html#accessor-and-assignment-functions)
 like `locations()`:
 
 ``` r
@@ -80,28 +80,30 @@ locations(x)
 #> 4 ce943ced   B_DM_val 4_'t WAD              50.7      4.01                   187
 ```
 
-One can also **filter** data, which will automatically filter the
-related data. For example, here are all the event-based observations
-that have a media file that was marked as favourite:
+You can also **filter** data with one of the [filter
+functions](https://inbo.github.io/camtrapdp/reference/index.html#filter-functions),
+which automatically filter the related data. For example, here we filter
+observations on scientific name(s) and return the associated events in
+that subset:
 
 ``` r
 x %>%
-  filter_observations(observationLevel == "event") %>%
-  filter_media(favorite == TRUE) %>%
-  observations()
-#> # A tibble: 1 × 32
-#>   observationID deploymentID mediaID eventID  eventStart         
-#>   <chr>         <chr>        <chr>   <chr>    <dttm>             
-#> 1 f5707f70      29b7d356     <NA>    45ee3031 2020-08-02 05:00:14
-#> # ℹ 27 more variables: eventEnd <dttm>, observationLevel <fct>,
-#> #   observationType <fct>, cameraSetupType <fct>, scientificName <chr>,
-#> #   count <dbl>, lifeStage <fct>, sex <fct>, behavior <chr>,
-#> #   individualID <chr>, individualPositionRadius <dbl>,
-#> #   individualPositionAngle <dbl>, individualSpeed <dbl>, bboxX <dbl>,
-#> #   bboxY <dbl>, bboxWidth <dbl>, bboxHeight <dbl>, classificationMethod <fct>,
-#> #   classifiedBy <chr>, classificationTimestamp <dttm>, …
+  filter_observations(
+    scientificName %in% c("Martes foina", "Mustela putorius")
+  ) %>%
+  events()
+#> # A tibble: 4 × 4
+#>   deploymentID eventID  eventStart          eventEnd           
+#>   <chr>        <chr>    <dttm>              <dttm>             
+#> 1 577b543a     976129e2 2020-06-19 22:31:51 2020-06-19 22:31:56
+#> 2 577b543a     b4b39b00 2020-06-23 23:33:53 2020-06-23 23:33:58
+#> 3 577b543a     5be4f4ed 2020-06-28 22:01:12 2020-06-28 22:01:18
+#> 4 577b543a     a60816f2 2020-06-28 23:33:16 2020-06-28 23:33:22
 ```
 
+For more functionality, see the [function
+reference](https://inbo.github.io/camtrapdp/reference/index.html).
+
 ## Meta
 
 - We welcome

codemeta.json

@@ -181,7 +181,7 @@
     },
     "SystemRequirements": null
   },
-  "fileSize": "188.759KB",
+  "fileSize": "188.574KB",
   "releaseNotes": "https://github.com/inbo/camtrapdp/blob/master/NEWS.md",
   "readme": "https://github.com/inbo/camtrapdp/blob/main/README.md",
   "contIntegration": ["https://github.com/inbo/camtrapdp/actions/workflows/R-CMD-check.yaml", "https://app.codecov.io/gh/inbo/camtrapdp/"],

inst/extdata/meta.xml

@@ -1,7 +1,7 @@
 <archive xmlns="http://rs.tdwg.org/dwc/text/">
   <core encoding="UTF-8" fieldsTerminatedBy="," linesTerminatedBy="\n" fieldsEnclosedBy="" ignoreHeaderLines="1" rowType="http://rs.tdwg.org/dwc/terms/Occurrence">
     <files>
-      <location>dwc_occurrence.csv</location>
+      <location>occurrence.csv</location>
     </files>
     <id index="8"/>
     <field index="0" term="http://purl.org/dc/terms/type"/>
@@ -47,7 +47,7 @@
   </core>
   <extension encoding="UTF-8" fieldsTerminatedBy="," linesTerminatedBy="\n" fieldsEnclosedBy="" ignoreHeaderLines="1" rowType="http://rs.tdwg.org/ac/terms/Multimedia">
     <files>
-      <location>dwc_audiovisual.csv</location>
+      <location>multimedia.csv</location>
     </files>
     <coreid index="0"/>
     <field index="0" term="http://rs.tdwg.org/dwc/terms/occurrenceID"/>

tests/testthat/_snaps/write_dwc/meta.xml

@@ -1,7 +1,7 @@
 <archive xmlns="http://rs.tdwg.org/dwc/text/">
   <core encoding="UTF-8" fieldsTerminatedBy="," linesTerminatedBy="\n" fieldsEnclosedBy="" ignoreHeaderLines="1" rowType="http://rs.tdwg.org/dwc/terms/Occurrence">
     <files>
-      <location>dwc_occurrence.csv</location>
+      <location>occurrence.csv</location>
     </files>
     <id index="8"/>
     <field index="0" term="http://purl.org/dc/terms/type"/>
@@ -47,7 +47,7 @@
   </core>
   <extension encoding="UTF-8" fieldsTerminatedBy="," linesTerminatedBy="\n" fieldsEnclosedBy="" ignoreHeaderLines="1" rowType="http://rs.tdwg.org/ac/terms/Multimedia">
     <files>
-      <location>dwc_audiovisual.csv</location>
+      <location>multimedia.csv</location>
     </files>
     <coreid index="0"/>
     <field index="0" term="http://rs.tdwg.org/dwc/terms/occurrenceID"/>

tests/testthat/helper.R

@@ -9,8 +9,8 @@
 #' @inheritDotParams expect_identical info label
 #' @noRd
 #' @examples
-#' expect_comform_meta("tests/testthat/_snaps/write_dwc/dwc_audiovisual.csv")
-expect_comform_meta <- function(file, core = "dwc_occurrence.csv", ...) {
+#' expect_comform_meta("tests/testthat/_snaps/write_dwc/multimedia.csv")
+expect_comform_meta <- function(file, core = "occurrence.csv", ...) {
   core_or_extension <- ifelse(basename(file) == core, "core", "extension")
 
   # Parse reference meta.xml from inst/extdata/meta.xml

tests/testthat/test-write_dwc.R

@@ -8,11 +8,11 @@ test_that("write_dwc() writes CSV and meta.xml files to a directory and
 
   expect_identical(
     list.files(temp_dir),
-    c("dwc_audiovisual.csv", "dwc_occurrence.csv", "meta.xml")
+    c("meta.xml", "multimedia.csv", "occurrence.csv")
   )
-  expect_identical(names(result), c("dwc_occurrence", "dwc_audiovisual"))
-  expect_s3_class(result$dwc_occurrence, "tbl")
-  expect_s3_class(result$dwc_audiovisual, "tbl")
+  expect_identical(names(result), c("occurrence", "multimedia"))
+  expect_s3_class(result$occurrence, "tbl")
+  expect_s3_class(result$multimedia, "tbl")
 })
 
 test_that("write_dwc() returns the expected Darwin Core terms as columns", {
@@ -23,7 +23,7 @@ test_that("write_dwc() returns the expected Darwin Core terms as columns", {
   result <- suppressMessages(write_dwc(x, temp_dir))
 
   expect_identical(
-    colnames(result$dwc_occurrence),
+    colnames(result$occurrence),
     c(
       "type",
       "license",
@@ -68,7 +68,7 @@ test_that("write_dwc() returns the expected Darwin Core terms as columns", {
     )
   )
   expect_identical(
-    colnames(result$dwc_audiovisual),
+    colnames(result$multimedia),
     c(
       "occurrenceID",
       "identifier",
@@ -93,8 +93,8 @@ test_that("write_dwc() returns the expected Darwin Core mapping for the example
   on.exit(unlink(temp_dir, recursive = TRUE))
   suppressMessages(write_dwc(x, temp_dir))
 
-  expect_snapshot_file(file.path(temp_dir, "dwc_occurrence.csv"))
-  expect_snapshot_file(file.path(temp_dir, "dwc_audiovisual.csv"))
+  expect_snapshot_file(file.path(temp_dir, "occurrence.csv"))
+  expect_snapshot_file(file.path(temp_dir, "multimedia.csv"))
   expect_snapshot_file(file.path(temp_dir, "meta.xml"))
 })
 
@@ -106,6 +106,6 @@ test_that("write_dwc() returns files that comply with the info in meta.xml", {
   suppressMessages(write_dwc(x, temp_dir))
 
   # Use helper function to compare
-  expect_comform_meta(file.path(temp_dir, "dwc_occurrence.csv"))
-  expect_comform_meta(file.path(temp_dir, "dwc_audiovisual.csv"))
+  expect_comform_meta(file.path(temp_dir, "occurrence.csv"))
+  expect_comform_meta(file.path(temp_dir, "multimedia.csv"))
 })