This function identifies unique, uninterrupted series of detections (`clumps') over a given time interval--for example, occasions when detections clumped into periods of one, two, three, ..., \(n\) days in duration without gaps longer than one day in length. A dataframe identifying each clump and the associated start time or the frequency distribution of the duration of clumps is returned.
get_detection_clumps(
acoustics,
fct = NULL,
interval = "days",
summarise = TRUE
)A dataframe that contains passive acoustic telemetry detection time series (see dat_acoustics for an example). At a minimum, this should contain a POSIXct vector of time stamps when detections were made named `timestamp'.
(optional) A character that defines the name of a column in acoustics that distinguishes acoustic time series for different individuals.
A character that defines the time interval. This must be supported by round_date. The default is "days", in which case the function identifies clumps in units of days, with detections within the same clump occurring within one day of each other.
A logical input that defines whether or not to summarise detection clumps in terms of the frequency distribution of clump lengths (see Value).
For implementations with summarise = FALSE, the function returns a dataframe that defines, for each fct, the number of intervals in a given clump (`n_intervals') and start time of the clump (`timestamp').
For implementations with summarise = TRUE, the function returns a dataframe that defines the frequency distribution of the duration of detection clumps (i.e., the number of occasions when detection clumps lasted different lengths of time). This includes the following columns: (1) `n_interval', the duration of the clump, in units of interval; (2) `n_occasions', the number of occasions when detections clumped into windows of that duration; (3) `eg_occasions', the time stamp of an example clump of the specified duration; and, if fct is supplied, a column that distinguishes each individual.
Detection clumps (and, more specifically, the frequency distribution of the duration of clump lengths) provide a means to assess residency within an array by determining how long individuals tended to spend around receivers.
#### Define a hypothetical series of detections
# with one occasion when the 'chunk length' is 1 day
# ... two separate occasions when the chunk length is two days
# ... ... (i.e., the individual was detected on two consecutive days
# ... .... on two different occasions)
# ... one occasion when the chunk length is 5 days
# ... one occasion when the chunk length is 7 days
eg <-
data.frame(
timestamp =
as.POSIXct(
c(
"2016-01-01", # one week of continuous detections
"2016-01-02",
"2016-01-03",
"2016-01-04",
"2016-01-05",
"2016-01-06",
"2016-01-07",
"2016-02-01", # one day with an isolated detection
"2016-02-03", # two days with detections
"2016-02-04",
"2016-02-15", # another two days with detections
"2016-02-16",
"2016-03-01", # five days of continuous detections
"2016-03-02",
"2016-03-03",
"2016-03-04",
"2016-03-05"
)
)
)
#### Example (1): Implement function with default options
# ... (for one individual, with a daily time interval)
get_detection_clumps(eg)
#> n_intervals n_occasions eg_occasions
#> 1 1 1 2016-02-01
#> 2 2 2 2016-02-03
#> 3 5 1 2016-03-01
#> 4 7 1 2016-01-01
#### Example (2): Implement function for multiple individuals
# Use a factor to distinguish IDs. As an example:
eg$individual_id <- 1L
get_detection_clumps(eg, fct = "individual_id")
#> n_intervals n_occasions eg_occasions individual_id
#> 1 1 1 2016-02-01 1
#> 2 2 2 2016-02-03 1
#> 3 5 1 2016-03-01 1
#> 4 7 1 2016-01-01 1
#### Example (3): Change the time interval
## E.g. Use an hourly interval:
# There are 17 unique clumps in this dataset, each comprising a single hour
get_detection_clumps(eg, interval = "hours")
#> n_intervals n_occasions eg_occasions
#> 1 1 17 2016-01-01
## E.g. Use a monthly interval
# There is a single 'three-month' clump of detections for this individual
# ... when viewed at a monthly timescale:
get_detection_clumps(eg, interval = "months")
#> n_intervals n_occasions eg_occasions
#> 1 3 1 2016-01-01
#### Example (4): Identify the timing of each clump with summarise = FALSE
get_detection_clumps(eg, summarise = FALSE)
#> n_intervals timestamp
#> 1 7 2016-01-01
#> 2 1 2016-02-01
#> 3 2 2016-02-03
#> 4 2 2016-02-15
#> 5 5 2016-03-01