get_detection_clumps: Get detection clumps

In edwardlavender/flapper: Routines for the Analysis of Passive Acoustic Telemetry Data

Get detection clumps

Description

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.

Usage

get_detection_clumps(
  acoustics,
  fct = NULL,
  interval = "days",
  summarise = TRUE
)

Arguments

acoustics	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’.
fct	(optional) A character that defines the name of a column in acoustics that distinguishes acoustic time series for different individuals.
interval	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.
summarise	A logical input that defines whether or not to summarise detection clumps in terms of the frequency distribution of clump lengths (see Value).

Details

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.

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.

Author(s)

Edward Lavender

See Also

get_detection_days, get_residents

Examples

#### 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)

#### 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")

#### 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")
## 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")

#### Example (4): Identify the timing of each clump with summarise = FALSE
get_detection_clumps(eg, summarise = FALSE)

edwardlavender/flapper documentation built on Jan. 22, 2025, 2:44 p.m.