R/get_detections.R
get_id_rec_overlap.RdThis function calculates the duration of the overlap (in days) between individuals' time at liberty and receivers' operational periods. To implement this function, a dataframe with individual deployment periods and another with receiver deployment periods must be specified. The duration of the overlap between these intervals can be calculated for all combinations of individuals and receivers within these two dataframes, for all combinations of specified individuals and receivers, or for specific individual/receiver pairs. The function returns a dataframe of the overlap duration for these individual/receiver combinations or a vector of values that is matched against another dataframe.
get_id_rec_overlap(
ids,
moorings,
individual_id = NULL,
receiver_id = NULL,
type = 1L,
match_to = NULL
)A dataframe that defines individual deployment periods. This must contain a column that defines individual IDs (named `individual_id') and the time of tagging (named `tag_start_date') and time of tag retrieval (`tag_end_date') (see dat_ids for an example).
A dataframe that defines receiver deployment periods. This must contain a column that defines receiver IDs (named `receiver_id') and the time of receiver deployment (named `receiver_start_date') and retrieval (named `receiver_end_date') (see dat_moorings for an example).
(optional) A vector of individuals for which to calculate overlap duration.
(optional) A vector of receivers for which to calculate overlap duration.
If both individual_id and receiver_id are specified, then type is an integer that defines whether or not to calculate overlap duration for (a) each individual/receiver pair (type = 1L) or (b) all combinations of specified individuals/receivers (type = 2L).
(optional) A dataframe against which to match the calculated overlap duration(s). This must contain an `individual_id' and `receiver_id' column, as in ids and moorings respectively. If supplied, an integer vector of overlap durations for individual/receiver combinations, matched against the individuals/receivers in this dataframe, is returned (see also Value).
The function returns a dataframe with the deployment overlap duration for specific or all combinations of individuals and receivers, with the `individual_id', `receiver_id', `tag_start_date', `tag_end_date', `receiver_start_date' and `receiver_end_date' columns retained, plus `tag_interval' and `receiver_interval' columns that define individual and receiver deployment periods as Interval-class objects. The `id_rec_overlap' column defines the temporal overlap (days). Alternatively, if match_to is supplied, a vector of overlap durations that matches each individual/receiver observation in that dataframe is returned.
#### Prepare data to include required columns
# moorings requires 'receiver_id', 'receiver_start_date' and 'receiver_end_date'
# ids requires 'individual_id', 'tag_start_date' and 'tag_end_date'
# These columns are already supplied in the example datasets
# ... except tag_end_date:
dat_ids$tag_end_date <- as.Date("2017-06-05")
#### Example (1): Temporal overlap between all combinations
# ... of individuals and receivers
dat <- get_id_rec_overlap(dat_ids, dat_moorings)
#### Example (2): Temporal overlap between all combinations of specified
# ... individuals/receivers
dat <- get_id_rec_overlap(dat_ids,
dat_moorings,
individual_id = c(25, 26),
receiver_id = c(3, 4),
type = 2L
)
#### Example (3): Temporal overlap between specified individual/receiver pairs
dat <- get_id_rec_overlap(dat_ids,
dat_moorings,
individual_id = c(25, 26),
receiver_id = c(3, 4),
type = 1L
)
#### Example (4): Match temporal overlap to another dataframe
dat_acoustics$get_id_rec_overlap <-
get_id_rec_overlap(dat_ids,
dat_moorings,
match_to = dat_acoustics,
type = 1L
)