Combine get_rai() and get_rai_individuals() into new function rai()

[peterdesmet]

Suggested in camtraptor July 2023 coding sprint

get_rai() returns the rai of observations per deployment and species. In contrast with #237, scientificName is always returned.

library(camtraptor)
get_rai(mica, species = "Anas platyrhynchos")
#> There are 3 deployments without observations: 577b543a-2cf1-4b23-b6d2-cda7e2eac372, 62c200a9-0e03-4495-bcd8-032944f6f5a1 and 7ca633fa-64f8-4cfc-a628-6b0c419056d7
#> # A tibble: 4 × 3
#>   deploymentID                         scientificName       rai
#>   <chr>                                <chr>              <dbl>
#> 1 29b7d356-4bb4-4ec4-b792-2af5cc32efa8 Anas platyrhynchos  40.2
#> 2 577b543a-2cf1-4b23-b6d2-cda7e2eac372 Anas platyrhynchos   0  
#> 3 62c200a9-0e03-4495-bcd8-032944f6f5a1 Anas platyrhynchos   0  
#> 4 7ca633fa-64f8-4cfc-a628-6b0c419056d7 Anas platyrhynchos   0

^{Created on 2023-07-13 with reprex v2.0.2}

get_rai_individuals() returns the rai of individuals per deployment and species. In contrast with #237, scientificName is always returned.

library(camtraptor)
get_rai_individuals(mica, species = "all")
#> # A tibble: 36 × 3
#>    deploymentID                         scientificName       rai
#>    <chr>                                <chr>              <dbl>
#>  1 29b7d356-4bb4-4ec4-b792-2af5cc32efa8 Anas platyrhynchos 131. 
#>  2 29b7d356-4bb4-4ec4-b792-2af5cc32efa8 Anas strepera       60.3
#>  3 29b7d356-4bb4-4ec4-b792-2af5cc32efa8 Ardea                0  
#>  4 29b7d356-4bb4-4ec4-b792-2af5cc32efa8 Ardea cinerea        0  
#>  5 29b7d356-4bb4-4ec4-b792-2af5cc32efa8 Castor fiber         0  
#>  6 29b7d356-4bb4-4ec4-b792-2af5cc32efa8 Homo sapiens         0  
#>  7 29b7d356-4bb4-4ec4-b792-2af5cc32efa8 Martes foina         0  
#>  8 29b7d356-4bb4-4ec4-b792-2af5cc32efa8 Mustela putorius     0  
#>  9 29b7d356-4bb4-4ec4-b792-2af5cc32efa8 Vulpes vulpes        0  
#> 10 577b543a-2cf1-4b23-b6d2-cda7e2eac372 Anas platyrhynchos   0  
#> # ℹ 26 more rows

^{Created on 2023-07-13 with reprex v2.0.2}

We suggest to combine this behaviour into a single function rai() that returns RAI characteristics per deployment and species. Filters are removed from the function, but supported by filters_ functions

get_rai(
  package = NULL,
  group_by = c("deployment", "scientificName") # new param, not sure if other groups make sense
  # ... removed, see filters
  # species = "all" removed, see filters
  # sex = NULL removed, see filters
  # life_stage = NULL, see filters
  # datapkg removed
)

The returned information would be:

deploymentID
scientificName
rai_events # a suggestion, bundles multiple observations within same event to one
rai_observations # same as rai of get_rai
rai_individuals # same as rai of get_rai_individuals

[damianooldoni]

About deprecating vs removing old function: see idea in #237 (comment)