Provide option to filter out observations related to timelapse

[peterdesmet]

@PatrickAJansen mentions in tdwg/camtrap-dp#207 (comment):

People trying to interpret the observations.csv directly reach the conclusion that a dataset is not completely annotated, even when it is. Camptrapdp should be logical / interpretable / useable without camptraptor. Timelapse observations should be recognizable as such.

This won’t change in Camtrap DP, but the R package should be able to filter out timelapses.

[peterdesmet]

This is now possible with:

library(camtrapdp)
x <- example_dataset()
x %>%
  filter_media(captureMethod != "timeLapse") %>%
  filter_observations(observationLevel == "event") %>% # optional
  observations()
#> # A tibble: 36 × 32
#>    observationID deploymentID mediaID eventID  eventStart         
#>    <chr>         <chr>        <chr>   <chr>    <dttm>             
#>  1 705e6036      00a2c20d     <NA>    4bb69c45 2020-05-30 02:57:37
#>  2 1fcdba64      00a2c20d     <NA>    f99bfff4 2020-05-31 04:05:10
#>  3 4729dc5c      00a2c20d     <NA>    45abeadc 2020-05-31 20:06:43
#>  4 a3cf89e5      00a2c20d     <NA>    ea72c74f 2020-06-05 02:49:20
#>  5 254635b0      00a2c20d     <NA>    52107a58 2020-06-06 04:11:07
#>  6 22a452e1      00a2c20d     <NA>    52107a58 2020-06-06 04:11:07
#>  7 277b2a9f      00a2c20d     <NA>    7363b68a 2020-06-09 03:16:11
#>  8 05230014      00a2c20d     <NA>    79204343 2020-06-12 04:04:29
#>  9 5ead5692      00a2c20d     <NA>    79204343 2020-06-12 04:04:29
#> 10 29939500      00a2c20d     <NA>    79204343 2020-06-12 04:04:29
#> # ℹ 26 more rows
#> # ℹ 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>, …

^{Created on 2024-05-02 with reprex v2.1.0}

@damianooldoni how are you planning to import this in camtraptor?

[damianooldoni]

Hi @peterdesmet! I was thinking to create a wrapper function around this. But as filtering is now handled by camtrapdp, I would put these wrappers with more "complex" filtering (I suppose this one will not be the only one users could benefit of) in camtrapdp itself.

What do you think?

[peterdesmet]

would put these wrappers with more "complex" filtering in camtrapdp

I would not. These are use cases that are specific to camera trap research, which I would implement in camtraptor (note: in the future, camtrapdp will be used for acoustic data too). Similarly, we could keep column names consistent in camtraptor (even if they would change in Camtrap DP).

I'll move these issue to camtraptor.

[damianooldoni]

Hi @peterdesmet. Yes indeed, we discussed this at the coffie corner ☕
I agree to implement a function in camtraptor which would be a shortcut of the code you wrote above. As it is not so much work, it can be done during the ongoing refactoring of camtraptor to support camtrap dp v1.0.

The point is to decide:

• output of the function: entire package or just observations?
• function name?

Option 1

The first option arising in my mind is to apply the "get" philosophy behind camtraptor and so to provide a get_*()function to do this: is get_obs_no_timelapse() a good name? Notice that this option would return a dataframe with observations.

## THIS CODE IS A SIMULATION, NOT YET IMPLEMENTED
library(camtraptor)
x <- example_dataset() # I would import this camtrapdp function into camtraptor too
get_obs_no_timelapse(x)
#> # A tibble: 36 × 32
#>    observationID deploymentID mediaID eventID  eventStart         
#>    <chr>         <chr>        <chr>   <chr>    <dttm>             
#>  1 705e6036      00a2c20d     <NA>    4bb69c45 2020-05-30 02:57:37
#>  2 1fcdba64      00a2c20d     <NA>    f99bfff4 2020-05-31 04:05:10
#>  3 4729dc5c      00a2c20d     <NA>    45abeadc 2020-05-31 20:06:43
#>  4 a3cf89e5      00a2c20d     <NA>    ea72c74f 2020-06-05 02:49:20
#>  5 254635b0      00a2c20d     <NA>    52107a58 2020-06-06 04:11:07
#>  6 22a452e1      00a2c20d     <NA>    52107a58 2020-06-06 04:11:07
#>  7 277b2a9f      00a2c20d     <NA>    7363b68a 2020-06-09 03:16:11
#>  8 05230014      00a2c20d     <NA>    79204343 2020-06-12 04:04:29
#>  9 5ead5692      00a2c20d     <NA>    79204343 2020-06-12 04:04:29
#> 10 29939500      00a2c20d     <NA>    79204343 2020-06-12 04:04:29
#> # ℹ 26 more rows
#> # ℹ 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>, …

Option 2

Another option is to return the entire (filtered) package back. This approach is more flexible as it allows users to get not only the filtered observations but also the filtered media data.frame at once. I slightly prefer this option. Do we create a new function called filter_out_timelapse()?

## THIS CODE IS A SIMULATION, NOT YET IMPLEMENTED
library(camtraptor)
x <- example_dataset() # I would import this camtrapdp function into camtraptor too

# Return the (filtered) data package
filter_out_timelapse(x)

# Return the filtered observations (data.frame), same output as option 1
filter_out_timelapse(x) %>% observations(x)

# Return the filtered media (data.frame). This is not possible in option 1
filter_out_timelapse(x) %>% media(x)

@peterdesmet, @jimcasaer, @PatrickAJansen? What do you think about it? Are there other shortcuts-like filtering functions worth being implemented? It will help finding the best name for this function as well.

[peterdesmet]

Before I read option 2, I thought:

It should be called filter_out_timelapse() and return the package.

And that is exactly what you suggest in option 2, so I definitely prefer that. I think all filter functions (including the "shortcut" ones in camtraptor) should return the package.

[damianooldoni]

Closed by #342. The functionality has been added to dev branch version-1.0.