New function request: changes to 'get_custom_effort'

[MartijnUH]

@damianooldoni following our meeting of 09/09/'24, @jimcasaer and I suggest the following changes to the get_custom_effort function:

inputs: no changes required

outputs:

• return the effort per group: one of "day", "week", "month", "year" and per deploymentID
• add a column deploymentID to the output data.frame
• add a column locationName to the output data.frame

This allows users to seamlessly calculate the total effort over all deployments (current default behaviour), effort per location or effort per deployment. (We could also add a new input parameter level that is one of: "overall", "location", "deployment" that acts as a switch between the desired output -- total effort - effort per location - effort per deployment. Then users do not have to calculate this themselves).

[MartijnUH]

I worked out an example of the function (extract the R-script in the zip-file and run locally):
get_custom_effort2.zip

Note: I rewrote the function using my own syntax. It seems to be faster (but without the necessary checks. Still it might be interesting to benchmark the two implementations).
Note2: In the original get_custom_effort function the abovementioned feature request can be achieved by changing to using the reshape::melt function on cam_op:

  # Camera operation matrix with filter(s) on deployments
  cam_op <- get_cam_op(package, ..., station_col = "deploymentID")
  
  # effort per deployment for each day  (in day units)
  dep_effort <- reshape::melt(cam_op)
  colnames(dep_effort) <- c("deploymentID", "date", "effort")
  dep_effort <- dplyr::mutate(dep_effort, date = lubridate::as_date(date))
  
  # join the locationNames to effort per deployment
  dep_effort <- dplyr::left_join(
    dep_effort, 
    dplyr::select(deployments, deploymentID, locationName), 
    "locationName")

and to work with dep_effort from thereon.

[damianooldoni]

This issue is strictly linked to existent one: #280. More or less same conclusions.
I will implement this soon and so updating to camtraptor 0.26.0.

Notice that I will think more about the future of get_effort() and get_custom_effort() (see #236) while working on camtraptor 1.0.0.