Generate residence events from passive acoustic telemetry data.

residences(data, ID, station, datetime, cutoff, units, verbose = TRUE)

Arguments

data

a data frame of detection data.

ID

a string of the name of the column in data that holds the tag or sample IDs.

station

a string of the name of the column in data that holds the station name or receiver location.

datetime

a string of the name of the column in data that holds the date and time.

cutoff

the maximum allowable time difference between detections to be considered a single residence event.

units

the units of the cutoff. These will also be the units used to calculate the duration of the residence events. Options are "secs", "mins", "hours", "days", and "weeks".

verbose

option to display progress bar as residences are generated. Default is TRUE.

Value

A data frame with one row for each residence event, including date/time of residence start, date/time of residence end, and duration of residence event. All input data fields (e.g., any name, location, or species information that was included with detection data) will be retained.

Details

Note that a progress bar appears, based on how many of the unique tag IDs have been processed. There will be a delay both before the progress bar appears and after the progress bar has reached 100%, which may be substantial depending on the size of the telemetry dataset.

Examples

head(detections)
#>           DateTimeUTC Station.Name ID
#> 1 2003-09-21 23:49:45           11  A
#> 2 2003-09-21 23:51:29           11  A
#> 3 2003-09-21 23:57:45           11  A
#> 4 2003-09-21 23:59:08           11  A
#> 5 2003-09-22 00:08:18           11  A
#> 6 2003-09-22 00:20:28            1  A
res.events<-residences(data=detections[1:500,],ID="ID",station="Station.Name",
datetime="DateTimeUTC",cutoff=1,units="days",verbose=FALSE)
head(res.events)
#>        ResidenceStart Station.Name ID        ResidenceEnd ResidenceLength.days
#> 1 2003-09-21 23:49:45           11  A 2003-09-22 00:08:18           0.01288194
#> 2 2003-09-22 00:20:28            1  A 2003-09-22 00:50:36           0.02092593
#> 3 2003-09-24 16:56:36            1  A 2003-09-25 18:01:11           1.04484954