Identifies potential mortalities or expelled tags from infrequent detections in passive acoustic telemetry data. Mortalities are identfied based on a user-defined threshold and timeframe.
infrequent(
data,
type = "mort",
ID,
station,
res.start = "auto",
res.end = "auto",
residences = "auto",
units = "auto",
method,
threshold,
threshold.units = NULL,
recent.period = NULL,
recent.units = NULL,
start = NULL,
end = NULL,
morts.prev = NULL,
replace = FALSE,
backwards = FALSE,
ddd = NULL,
from.station = NULL,
to.station = NULL,
drift.cutoff = NULL,
drift.units = NULL,
verbose = TRUE
)a dataframe of residence events. Residence events must include tag ID, location name, start time, end time, and duration.
the method used to generate the residence events. Options are
"mort", "actel", "glatos", "vtrack", or "manual". If "manual", then user
must specify ID, station, res.start, res.end, residences, and units.
a string of the name of the column in data that holds the tag or
sample IDs.
a string of the name of the column in data that holds the
station name or receiver location.
a string of the name of the column in data that holds the
start date and time. Must be specified and in POSIXt or character in the format
YYYY-mm-dd HH:MM:SS if type="manual".
a string of the name of the column in data that holds the
end date and time. Must be specified and in POSIXt or character in the format
YYYY-mm-dd HH:MM:SS if type="manual".
residences a character string with the name of the column in data
that holds the duration of the residence events.
Units of the duration of the residence events in data. Options are "secs",
"mins", "hours", "days", and "weeks".
a character string of the threshold method. Options are "recent"
and "defined". If "recent", must specify recent.period and recent.units.
If "defined", must specify start and end.
the minimum summed duration of residence events for an animal
to be considered alive. Units must be the same as the units of residences.
the units of threshold. Options are "secs",
"mins", "hours", "days", and "weeks". If NULL, assumed to be the same as
units.
the length of the period of time in which an animal must
be detected longer than the threshold to be considered alive. The period
ends with the most recent detection of a given animal.
the units of recent.period. Options are "secs", "mins", "hours", "days", and "weeks".
character string with the start of the user-defined time period to search for infrequent
detections if method="defined". Must be in the format
YYYY-mm-dd HH:MM:SS. The time zone is the same as res.start or
assumed to be UTC if no time zone is defined for res.start.
character string with the end of the user-defined time period to search for infrequent
detections if method="defined". Must be in the format
YYYY-mm-dd HH:MM:SS. The time zone is the same as res.start or
assumed to be UTC if no time zone is defined for res.start.
a dataframe containing potential mortalities. The dataframe must
have the same columns and in the same order as data.
if morts specified and an animal with infrequent detections
is already in morts, the record in morts will be replaced if TRUE.
Default is FALSE.
option to examine residence events prior to the one that was flagged as a potential mortality. If prior residence events are at the same station/location as the flagged event, the time of the potential mortality is shifted earlier.
an optional dataframe of stations/locations where detected movement between stations may be due to drifting of an expelled tag or dead animal.
a string of the name of the column in ddd that contains
the station/location names where drifting detections may start from. Must
be identical to the station/location names in data.
a string of the name of the column in ddd that contains
the station/location names where drifting detections may move to. Must
be identical to the station/location names in data.
the maximum allowable time difference between detections to be
considered a single residence event. Recommended to be the same as used
to generate residence events in data.
the units of the cutoff. Options are "secs", "mins", "hours",
"days", and "weeks". Recommended to be the same as used to generate
residence events in data.
option to display updates and progress bars as sub-functions are called and run. Default is TRUE.
if morts=NULL, a dataframe with one row for each tag ID, including the date/time of
the residence start when the potential mortality or expelled tag was identified.
If morts is specified, any potential mortalities will be added to existing
morts dataframe. If morts is specified and replace=TRUE, then any
mortalities that are flagged by infrequent() and occurred at an earlier
time than those in morts will be replaced to the earlier date.
All input data fields
(e.g., any name, location, or species information that was included with the
input data) will be retained.
Example of method="recent": if threshold=10, threshold.units="mins",
recent.period=52 and recent.units="weeks" (1 year), an animal will be
flagged as a potential mortality if it was detected for less than 10 minutes
within a year, ending with the most recent detection.
Example of method="defined": if threshold=10, threshold.units="mins",
start="2019-10-01", and end="2020-06-01", an animal
will be flagged as a potential mortality if it was detected for less than 10
minutes between 01 October 2019 and 01 June 2020.
## Recent example
inf_recent<-infrequent(data=events,type="mort",ID="ID",
station="Station.Name",method="recent",
threshold=72,threshold.units="hours",
recent.period=52,recent.units="weeks",
verbose=FALSE)
head(inf_recent)
#> ResidenceStart Station.Name ID ResidenceEnd
#> 51 2005-09-16 14:26:04 1 B 2005-09-16 18:05:15
#> 837 2006-07-08 14:36:35 20 I 2006-07-08 14:42:27
#> 11475 2005-10-15 05:12:03 2 M 2005-10-15 05:12:03
#> ResidenceLength.days
#> 51 0.152210648
#> 837 0.004074074
#> 11475 0.000000000
## User-defined example
inf_defined<-infrequent(data=events,type="mort",ID="ID",
station="Station.Name",method="defined",
threshold=12,threshold.units="hours",
start="2006-06-15",end="2006-10-15",
verbose=FALSE)
head(inf_defined)
#> ResidenceStart Station.Name ID ResidenceEnd
#> 54 2006-07-09 04:39:28 1 B 2006-07-09 04:39:28
#> 11486 2006-06-23 01:51:18 2 M 2006-06-23 01:51:18
#> ResidenceLength.days
#> 54 0
#> 11486 0