Calculate the number of operational units through time — get_n_operational

This function calculates the number of operational units through time (e.g., the number of individuals at liberty or the number of active acoustic receivers over the course of a study). To implement the function, a dataframe (data) must be supplied that defines the start and end time of each unit's operational period. Then, for each time step in a user-specified sequence of times, or an automatically generated sequence of times from the earliest start time to the latest end time in data, the function counts the number of units that were operational on each time step and returns a dataframe (and, if specified, a plot) with this information.

get_n_operational_ts(data, start, stop, times = NULL, plot = TRUE, ...)

Arguments

data: A dataframe of observations. At a minimum, this should contain two columns that define the start and end of each unit's operational period, identified by start and stop below.
start: A character string that defines the name of the column in data that defines the start time of each unit's operational period.
stop: A character string that defines the name of the column in data that defines the end time of each unit's operational period.
times: A vector of times for which to calculate the number of units that were operational at each time. If times = NULL, a regular sequence of dates from the first to the last date in data is used.
plot: A logical variable that defines whether or not to plot the time series of the number of operational units.
...: Additional arguments, passed to pretty_plot, to customise the plot.

Value

The function returns a dataframe that, for each time step (`time'), defines the number of operational units at that time (`n'). If plot = TRUE, the function also plots a time series of the number of operational units.

Details

This is a simple metric of sampling effort. For acoustic receivers, get_detection_area_ts provides another metric of sampling effort.

Author

Edward Lavender

Examples

#### Example (1): Number of operational receivers over an acoustic telemetry study
dat_n <- get_n_operational_ts(
  data = dat_moorings,
  start = "receiver_start_date",
  stop = "receiver_end_date"
)

utils::head(dat_n)
#>         time  n
#> 1 2016-03-03 18
#> 2 2016-03-04 18
#> 3 2016-03-05 18
#> 4 2016-03-06 18
#> 5 2016-03-07 18
#> 6 2016-03-08 18

#### Example (2): Number of individuals at liberty over a tagging study
# Define 'tag_end_date' as hypothetical end date of a study
# ...  and assume that all individuals remained tagged until this time
dat_ids$tag_end_date <- as.Date("2017-06-05")
dat_n <- get_n_operational_ts(
  data = dat_ids,
  start = "tag_start_date",
  stop = "tag_end_date"
)


#### Example (3): Specify the time period under consideration
dat_n <- get_n_operational_ts(
  data = dat_ids,
  start = "tag_start_date",
  stop = "tag_end_date",
  times = seq(
    min(dat_moorings$receiver_start_date),
    max(dat_moorings$receiver_end_date), 1
  )
)


#### Example (4): Suppress or customise the plot
dat_n <- get_n_operational_ts(
  data = dat_ids,
  start = "tag_start_date",
  stop = "tag_end_date",
  plot = FALSE
)
dat_n <- get_n_operational_ts(
  data = dat_ids,
  start = "tag_start_date",
  stop = "tag_end_date",
  xlab = "Time", ylab = "N (individuals)",
  type = "l"
)


#### Example (5): Additional examples with simulated data
# Example with one unit deployed on each day
tmp <- data.frame(
  id = 1:3L,
  start = as.Date(c("2016-01-01", "2016-01-02", "2016-01-03")),
  stop = as.Date(c("2016-01-01", "2016-01-02", "2016-01-03"))
)
get_n_operational_ts(data = tmp, start = "start", stop = "stop")
#> Lower and upper limits for an inputted variable are identical. This is usually because all values of this variable are identical. Adjusted limits (+/- 25 % or +/- 0.25 or +/- 60 s) implemented.

#>         time n
#> 1 2016-01-01 1
#> 2 2016-01-02 1
#> 3 2016-01-03 1
# Example with one unit deployed over a longer period
tmp <- data.frame(
  id = 1:3L,
  start = as.Date(c("2016-01-01", "2016-01-02", "2016-01-03")),
  stop = as.Date(c("2016-01-10", "2016-01-02", "2016-01-03"))
)
get_n_operational_ts(data = tmp, start = "start", stop = "stop")

#>          time n
#> 1  2016-01-01 1
#> 2  2016-01-02 2
#> 3  2016-01-03 2
#> 4  2016-01-04 1
#> 5  2016-01-05 1
#> 6  2016-01-06 1
#> 7  2016-01-07 1
#> 8  2016-01-08 1
#> 9  2016-01-09 1
#> 10 2016-01-10 1