Rethinking get_custom_effort and get_effort

[damianooldoni]

While reviewing get_*() functions vs features of map_dep() (see #171) I found the function name get_custom_effort() very misleading.

@jimcasaer, @LynnINBO and I added get_custom_effort() to allow the user to select a start date, an end date and also a group_by interval, e.g. "days". See #70.
Notice that such effort is calculated over all deployments (filtering by predicates is of course possible)!

But why not adding start, end and group_by to get_effort() as well and renaming get_custom_effort() as get_total_effort() or get_global_effort()?

Of course users can continue to use get_custom_effort, but its usage will be deprecated.

@jimcasaer, @LynnINBO, @peterdesmet: what do you think about it?

[damianooldoni]

Decided with @jimcasaer:

• yes, start, end and group_by fit perfectly get_effort(). The default values (start = NULL, end = NULL, group_by = NULL) will return the effort as it is returned now and will be by far the most typical usage.
• agree to rename get_custom_effort. However, get_global_effort() doesn't soudn good for @jimcasaer as it reminds a calculation over the globe, the entire Earth, not anymore project wise.
• @jimcasaer's alternatives: get_project_effort() (I give 👍 ) or get_overall_effort() (I give 👎 ).

@peterdesmet: which name is the best, do you think? Other alternatives are welcome.

[peterdesmet]

What is the difference in functionality of get_effort(start, end, group_by) vs get_project_effort()?

[damianooldoni]

get_effort is at deployment level, the actual get_custom_effort() (to be renamed maybe as get_project_effort()) is over all deployments. Default examples:

library(camtraptor)

get_effort(mica)
#> # A tibble: 4 × 4
#>   deploymentID                         effort unit  effort_duration       
#>   <chr>                                 <dbl> <chr> <Duration>            
#> 1 29b7d356-4bb4-4ec4-b792-2af5cc32efa8   239. hour  859859s (~1.42 weeks) 
#> 2 577b543a-2cf1-4b23-b6d2-cda7e2eac372   219. hour  786802s (~1.3 weeks)  
#> 3 62c200a9-0e03-4495-bcd8-032944f6f5a1   529. hour  1903602s (~3.15 weeks)
#> 4 7ca633fa-64f8-4cfc-a628-6b0c419056d7   335. hour  1204929s (~1.99 weeks)

get_custom_effort(mica)
#> # A tibble: 1 × 3
#>   begin      effort unit 
#>   <date>      <dbl> <chr>
#> 1 2019-10-09  1321. hour

get_custom_effort(mica, group_by = "day")
#> # A tibble: 558 × 3
#>    begin      effort unit 
#>    <date>      <dbl> <chr>
#>  1 2019-10-09   12.7 hour 
#>  2 2019-10-10   24   hour 
#>  3 2019-10-11   24   hour 
#>  4 2019-10-12   24   hour 
#>  5 2019-10-13   24   hour 
#>  6 2019-10-14   24   hour 
#>  7 2019-10-15   24   hour 
#>  8 2019-10-16   24   hour 
#>  9 2019-10-17   24   hour 
#> 10 2019-10-18   24   hour 
#> # … with 548 more rows

Created on 2022-09-15 with reprex v2.0.2

[peterdesmet]

Why not a call the function get_effort() (get_custom_effort() behaviour) where you can group_by = "deployment" to replicate the current get_effort() behaviour?

[jimcasaer]

when looking at the list #171 of get_() functions, it seems to me that there are two families of get_() functions:

• those that return information for each deployment and are afterwards used in map_dep()
• the others that return information based on the export that is being analyzed

would it not be logical to keep the get_ as a prefix for all of them and differentiate using get_dep_() for the first group and get_projet_() or get_export_() for the second ? I do not like the suggestion to use summarize (as suggested in #173 ) given that these functions are for me not really summarizing something, but returning characteristics for each deployment

[peterdesmet]

Suggested in camtraptor July 2023 coding sprint

• Regarding aligning get_custom_effort() and get_effort(), see Combine get_effort() and get_custom_effort() into new function effort() #236
• @jimcasaer agree that there are multiple families of get_ functions:
  • Get information per deployment, like get_effort()
  • Get information for camtrapR, like get_recordTable()
  • Get species info, like get_scientific_name()
    We decided to remove the get_ function names, see e.g. Rename map_dep() to map_deployments() #231 Remove check_species(), get_scientific_name() #235 ...

Closing this issue in favour of #236