diff --git a/R/helper.R b/R/helper.R index 339cd18..aea8877 100644 --- a/R/helper.R +++ b/R/helper.R @@ -18,13 +18,12 @@ #' @examples #' autofield("actel","units") #' autofield("glatos","res.start") -#' autofield("mort","res.end") +#' autofield("mort","res.end",data=events) #' autofield("vtrack","residences") autofield<-function(type,field,data){ - # data is optional - just needed for format="mort", to get "units" and "residences" if (is.null(type)){ stop("type must be specified if 'res.start', 'res.end', 'residences', - or 'units' are 'auto'. Please specify the format.") + or 'units' are 'auto'. Please specify the type.") } else if (type=="mort"){ if (field=="res.start"){ @@ -110,7 +109,7 @@ autofield<-function(type,field,data){ #' Extract residences from actel and Vtrack lists -#' @description Extracts residence information from lists that are generated +#' @description Extracts residence information from lists that are generated by #' actel and Vtrack. #' #' @param data the output from either actel or Vtrack @@ -124,7 +123,7 @@ autofield<-function(type,field,data){ #' @noRd #' #' @examples -#' \dontrun{extractres(data=data,format="vtrack")} +#' \dontrun{extractres(data=data,type="vtrack")} extractres<-function(data,type){ if (type=="actel"){ data.unlisted<-cbind(ID=as.character(),as.data.frame(data$valid.movements[[1]][0,])) @@ -183,6 +182,7 @@ extractres<-function(data,type){ #' @examples #' unitcheck(type="vtrack",units="secs") #' unitcheck(type="glatos",units="mins") +#' unitcheck(type="mort",units="secs",data=events) unitcheck<-function(type,units,data){ if (type=="mort"){ if (units!=sub("ResidenceLength.","",colnames(data)[grep("ResidenceLength",colnames(data))])){ diff --git a/R/mort.R b/R/mort.R index 66a10de..0ba357e 100644 --- a/R/mort.R +++ b/R/mort.R @@ -21,10 +21,10 @@ #' station name or receiver location. #' @param res.start 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 `format="manual"`. +#' YYYY-mm-dd HH:MM:SS if `type="manual"`. #' @param res.end 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 `format="manual"`. +#' YYYY-mm-dd HH:MM:SS if `type="manual"`. #' @param singles specifies if single detections (length of residence event = 0) #' should be retained. Default is `TRUE`. Note that if single detections are #' removed (`singles=FALSE`), `backwards` will also not include single detections. @@ -77,7 +77,11 @@ #' @export #' #' @examples -#' \dontrun{mort(data=res.events,format="manual",units="days",residences="ResidenceLength")} +#' morts_ex<-morts(data=events,type="mort",ID="ID", +#' station="Station.Name",method="any") +#' +#'morts_ex_bw<-morts(data=events,type="mort",ID="ID", +#'station="Station.Name",method="any",backwards=TRUE) morts<-function(data,type="mort",ID,station,res.start="auto",res.end="auto", method="all",units="auto",residences="auto", singles=TRUE,backwards=FALSE,drift="none",ddd=NULL, @@ -103,9 +107,9 @@ morts<-function(data,type="mort",ID,station,res.start="auto",res.end="auto", unitcheck(type=type,units=units,data=data) } - # Check that ID and station are specified (not "auto") for format="mort" + # Check that ID and station are specified (not "auto") for type="mort" if (type=="mort"&(ID=="auto"|station=="auto")){ - stop("ID and station must be specified (i.e., cannot be 'auto') for format='mort'") + stop("ID and station must be specified (i.e., cannot be 'auto') for type='mort'") } # Fill in auto fields @@ -374,8 +378,9 @@ morts<-function(data,type="mort",ID,station,res.start="auto",res.end="auto", } else {break} } + # To compensate for seasonality (which introduces "Breaks") if (any(res.temp[[station]]=="Break")){ - # Need two values, and determine which is lower + # Need two values, then determine which is lower # Value 1: difftime between end of most recent residence and station change (sc2) dt1<-difftime(res.temp[[res.end]][nrow(res.temp)], sc2[[res.start]][i], @@ -448,7 +453,7 @@ morts<-function(data,type="mort",ID,station,res.start="auto",res.end="auto", #' @param data a dataframe of residence events. Residence events must include #' tag ID, location name, start time, and duration. Residence events must also #' include end time if `season` is provided. -#' @param type the format used to generate the residence events. Options are +#' @param type 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`. #' @param ID a string of the name of the column in `data` that holds the tag or @@ -457,10 +462,10 @@ morts<-function(data,type="mort",ID,station,res.start="auto",res.end="auto", #' station name or receiver location. #' @param res.start 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 `format="manual"`. +#' YYYY-mm-dd HH:MM:SS if `type="manual"`. #' @param res.end 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 `format="manual"`. +#' YYYY-mm-dd HH:MM:SS if `type="manual"`. #' @param residences residences a character string with the name of the column in `data` #' that holds the duration of the residence events. #' @param units Units of the duration of the residence events in `data`. Options are "secs", @@ -510,19 +515,22 @@ morts<-function(data,type="mort",ID,station,res.start="auto",res.end="auto", #' "days", and "weeks". Recommended to be the same as used to generate #' residence events in `data`. #' -#' @details Example of `method="recent"`: if `threshold=10` and `recent.period=1` and -#' `recent.units="years"`, 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. +#' @details 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` and `start="2019-10-01"` and `end="2020-06-01"`, an animal +#' 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. #' #' @return 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. +#' `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. @@ -530,17 +538,16 @@ morts<-function(data,type="mort",ID,station,res.start="auto",res.end="auto", #' #' @examples #' ## Recent example -#' \dontrun{infrequent(data=data,format="manual",ID="TagID",station="Receiver", -#' res.start="ResStart",res.end="ResEnd",residences="ResidenceLength.days", -#' units="days",method="recent",threshold=0.5,recent.period=1, -#' recent.units="years")} +#' inf_recent<-infrequent(data=events,type="mort",ID="ID", +#' station="Station.Name",method="recent", +#' threshold=0.5,threshold.units="hours", +#' recent.period=52,recent.units="weeks") +#' #' ## User-defined example -#' \dontrun{infrequent(data=data,format="manual",ID="TagID",station="Receiver", -#' res.start="ResStart",res.end="ResEnd",residences="ResidenceLength.days", -#' units="days",method="defined",threshold=0.5,start="2019-10-01", -#' end="2020-06-01")} - - +#' inf_defined<-infrequent(data=events,type="mort",ID="ID", +#' station="Station.Name",method="defined", +#' threshold=0.5,threshold.units="hours", +#' start="2019-10-01",end="2020-06-01") infrequent<-function(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, @@ -561,9 +568,9 @@ infrequent<-function(data,type="mort",ID,station,res.start="auto", unitcheck(type=type,units=units,data=data) } - # Check that ID and station are specified (not "auto") for format="mort" + # Check that ID and station are specified (not "auto") for type="mort" if (type=="mort"&(ID=="auto"|station=="auto")){ - stop("ID and station must be specified (i.e., cannot be 'auto') for format='mort'") + stop("ID and station must be specified (i.e., cannot be 'auto') for type='mort'") } # Fill in auto fields diff --git a/R/options.R b/R/options.R index f3b212d..5ebc477 100644 --- a/R/options.R +++ b/R/options.R @@ -12,7 +12,7 @@ #' @param station a string of the name of the column in `data` that holds the #' station name or receiver location. #' @param res.start a string of the name of the column in `data` that holds the -#' start date and time. Must be specified and in POSIXt if `format="manual"`. +#' start date and time. Must be specified and in POSIXt if `type="manual"`. #' @param stnchange a dataframe with the start time and location of the most #' recent station or location change. Must use the same column names and in #' the same order as `data`. @@ -28,8 +28,20 @@ #' @export #' #' @examples -#' \dontrun{backwards(data=data,morts=morts,ID="TagID",station="Receiver", -#' res.start="ResidencesStart",stnchange=stn.change)} +#' morts<-morts(data=events,type="mort",ID="ID",station="Station.Name", +#' method="any") +#' +#' # If station change not identified yet: +#' morts_bw<-backwards(data=events,morts=morts,ID="ID", +#' station="Station.Name",res.start="ResidenceStart") +#' +#' # Identify station change first: +#' station.change<-stationchange(data=events,type="mort", +#' ID="ID",station="Station.Name") +#' +#' morts_bw<-backwards(data=events,morts=morts,ID="ID", +#' station="Station.Name",res.start="ResidenceStart", +#' stnchange=station.change) backwards<-function(data,morts,ID,station,res.start,stnchange=NULL){ if (any(data[[station]]=="Break")){ warning("Either a station name was 'Break' or data included seasonal @@ -84,7 +96,7 @@ backwards<-function(data,morts,ID,station,res.start,stnchange=NULL){ morts } -#' Dead drift +#' Dead and drifting #' @description Identifies sequential residence events where detected movement #' between stations may be due to drifting of an expelled tag or dead animal. #' @@ -99,10 +111,10 @@ backwards<-function(data,morts,ID,station,res.start,stnchange=NULL){ #' station name or receiver location. #' @param res.start 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 `format="manual"`. +#' YYYY-mm-dd HH:MM:SS if `type="manual"`. #' @param res.end 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 `format="manual"`. +#' YYYY-mm-dd HH:MM:SS if `type="manual"`. #' @param residences a character string with the name of the column in `data` #' that holds the duration of the residence events. #' @param units units of the duration of the residence events in `data`. @@ -125,9 +137,13 @@ backwards<-function(data,morts,ID,station,res.start,stnchange=NULL){ #' @export #' #' @examples -#' \dontrun{drift(data=data,format="manual",ID="TagID",station="Receiver", -#' res.start="ResidenceStart",res.end="ResidenceEnd",ddd=driftstations, -#' from.station="FrStation",to.station="ToStation")} +#' drift.events<-drift(data=events,type="mort",ID="ID", +#' station="Station.Name",ddd=ddd,from.station="From",to.station="To") +#' +#' # With cutoff: +#' drift.events<-drift(data=events,type="mort",ID="ID", +#' station="Station.Name",ddd=ddd,from.station="From",to.station="To", +#' cutoff=1,cutoff.units="days") drift<-function(data,type,ID,station,res.start="auto",res.end="auto", residences="auto",units="auto",ddd,from.station,to.station, cutoff=NULL,cutoff.units=NULL,progress.bar=TRUE){ @@ -145,9 +161,9 @@ drift<-function(data,type,ID,station,res.start="auto",res.end="auto", unitcheck(type=type,units=units,data=data) } - # Check that ID and station are specified (not "auto") for format="mort" + # Check that ID and station are specified (not "auto") for type="mort" if (type=="mort"&(ID=="auto"|station=="auto")){ - stop("ID and station must be specified (i.e., cannot be 'auto') for format='mort'") + stop("ID and station must be specified (i.e., cannot be 'auto') for type='mort'") } # Fill in auto fields @@ -170,7 +186,6 @@ drift<-function(data,type,ID,station,res.start="auto",res.end="auto", units<-autofield(type=type,field="units",data=data) } - # Could make this check be a function if (!is(data[[res.start]],"POSIXt")){ try(data[[res.start]]<-as.POSIXct(data[[res.start]],tz="UTC",silent=TRUE)) if (!is(data[[res.start]],"POSIXt")){ @@ -184,7 +199,7 @@ drift<-function(data,type,ID,station,res.start="auto",res.end="auto", } } - # Convert station to list (to hold all stations, in order) + # Convert station to list (to hold all stations, in chronological order) data[[station]]<-as.list(data[[station]]) # Get list of unique tag IDs @@ -264,10 +279,10 @@ drift<-function(data,type,ID,station,res.start="auto",res.end="auto", #' station name or receiver location. #' @param res.start 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 `format="manual"`. +#' YYYY-mm-dd HH:MM:SS if `type="manual"`. #' @param res.end 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 `format="manual"`. +#' YYYY-mm-dd HH:MM:SS if `type="manual"`. #' @param residences a character string with the name of the column in `data` #' that holds the duration of the residence events. #' @param units Units of the duration of the residence events in `data`. Options are "secs", @@ -294,9 +309,15 @@ drift<-function(data,type,ID,station,res.start="auto",res.end="auto", #' @export #' #' @examples -#' \dontrun{season(data=data,res.start="ResidenceStart",res.end="ResidenceEnd", -#' residences="ResidenceDuration",units="days",season.start="01-06", -#' season.end="31-10")} +#' # Seasons in format dd-mm +#' season.events<-season(data=events,type="mort",ID="ID", +#' station="Station.Name",season.start="01-06",season.end="31-10") +#' +#' # Seasons in format YYYY-mm-dd HH:MM:SS +#' season.start<-c("2003-06-15","2004-06-21") +#' season.end<-c("2003-10-15","2004-10-30") +#' season.events<-season(data=events,type="mort",ID="ID", +#' station="Station.Name",season.start=season.start,season.end=season.end) season<-function(data,type="mort",ID,station,res.start="auto",res.end="auto", residences="auto",units="auto",season.start, season.end,overlap=TRUE,progressbar=TRUE){ @@ -314,9 +335,9 @@ season<-function(data,type="mort",ID,station,res.start="auto",res.end="auto", unitcheck(type=type,units=units,data=data) } - # Check that ID and station are specified (not "auto") for format="mort" + # Check that ID and station are specified (not "auto") for type="mort" if (type=="mort"&(ID=="auto"|station=="auto")){ - stop("ID and station must be specified (i.e., cannot be 'auto') for format='mort'") + stop("ID and station must be specified (i.e., cannot be 'auto') for type='mort'") } # Fill in auto fields diff --git a/R/plot.R b/R/plot.R index 99a9065..f0c9e3e 100644 --- a/R/plot.R +++ b/R/plot.R @@ -14,10 +14,10 @@ #' station name or receiver location. #' @param res.start 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 `format="manual"`. +#' YYYY-mm-dd HH:MM:SS if `type="manual"`. #' @param res.end 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 `format="manual"`. +#' YYYY-mm-dd HH:MM:SS if `type="manual"`. #' @param morts a dataframe containing potential mortalities. The dataframe must #' have the same ID, station, res.start, res.end, and residences column names #' as `data`. @@ -56,8 +56,14 @@ #' @importFrom rlang .data #' #' @examples -#' \dontrun{plot<-mortsplot(data=data,type="mort",ID="TagID",station="Station.Name", -#' interactive=TRUE,residences="auto")} +#' plot<-mortsplot(data=events,type="mort",ID="ID",station="Station.Name") +#' +#' # With mortalities plotted over residences: +#' morts<-morts(data=events,type="mort",ID="ID",station="Station.Name", +#' method="any") +#' +#' plot<-mortsplot(data=events,type="mort",ID="ID",station="Station.Name", +#' morts=morts) mortsplot<-function(data,type,ID,station,res.start="auto",res.end="auto", morts=NULL,singles=TRUE,interactive=FALSE,residences=NULL, units=NULL, @@ -88,9 +94,9 @@ mortsplot<-function(data,type,ID,station,res.start="auto",res.end="auto", stop("For type='manual', all the following parameters must be specified: ID, station, res.start, res.end") } - # Check that ID and station are specified (not "auto") for format="mort" + # Check that ID and station are specified (not "auto") for type="mort" if (type=="mort"&(ID=="auto"|station=="auto")){ - stop("ID and station must be specified (i.e., cannot be 'auto') for format='mort'") + stop("ID and station must be specified (i.e., cannot be 'auto') for type='mort'") } # Fill in auto fields if (ID=="auto"){ @@ -335,7 +341,7 @@ mortsplot<-function(data,type,ID,station,res.start="auto",res.end="auto", } if (singles==TRUE){ - # Add a brief period to res.end so residences with 0 detections are visible + # Add a brief period to res.end, so residences with 0 detections are visible if (facet==TRUE){ ssn$Length<-difftime(ssn$End,ssn$Start,units="days") if (facet.axis=="y"){ @@ -377,12 +383,12 @@ mortsplot<-function(data,type,ID,station,res.start="auto",res.end="auto", if (!is.null(data$Year)&facet.axis=="y"){ plot<-plot+ ggplot2::facet_grid(Year~.,scales="free",space="free_y")+ - scale_x_datetime(date_labels = "%b %d") + ggplot2::scale_x_datetime(date_labels = "%b %d") } else if (!is.null(data$Year)&facet.axis=="x"){ plot<-plot+ ggplot2::facet_grid(.~Year,scales="free",space="free_x")+ - scale_x_datetime(date_labels = "%b %d") + ggplot2::scale_x_datetime(date_labels = "%b %d") } else if (!is.null(data$Season)){ plot<-plot+ diff --git a/R/residences.R b/R/residences.R index e05754d..10d5cb3 100644 --- a/R/residences.R +++ b/R/residences.R @@ -23,15 +23,14 @@ #' @importFrom utils setTxtProgressBar txtProgressBar #' #' @examples -#' \dontrun{residences(data=detections,ID="TagID",station="Receiver", -#' datetime="DateTimeUTC",cutoff=1,units="days")} +#' res.events<-residences(data=detections,ID="ID",station="Station.Name", +#' datetime="DateTimeUTC",cutoff=1,units="days") residences<-function(data,ID,station,datetime,cutoff,units){ # Create list of unique IDs tag<-unique(na.omit(data[[ID]])) - # Format date/times - # If datetime column is not already formatted as POSIXt + # Format date/times, if datetime column is not already formatted as POSIXt if (!is(data[[datetime]],"POSIXt")){ # If data not already in POSIXt, assume that time zone is UTC try(data[[datetime]]<-as.POSIXct(data[[datetime]],tz="UTC"),silent=TRUE) @@ -74,9 +73,7 @@ residences<-function(data,ID,station,datetime,cutoff,units){ if (!(is.na(res$ResidenceEnd[k]))){ break } - # If the same station name and within res.cutoff and the next - # record is not a manual record type (i.e., it is a receiver - # record), move to next row + # If the same station name and within res.cutoff, move to next row else if ((as.numeric(difftime(res.sub[[datetime]][j+1],res.sub[[datetime]][j],units=units))<=cutoff)& (res.sub[[station]][j+1]==res.sub[[station]][j])){ j<-j+1 diff --git a/R/review.R b/R/review.R index f14f036..6bfdedc 100644 --- a/R/review.R +++ b/R/review.R @@ -48,8 +48,11 @@ #' @export #' #' @examples -#' \dontrun{undead<-review(morts=morts,new.data=new.data,old.data=old.data, -#' ID="TagID",station="Station.Name",res.start="ResidenceStart")} +#' morts<-morts(data=events,type="mort",ID="ID",station="Station.Name", +#' method="any") +#' +#' undead<-review(morts=morts,new.data=new.data, +#' type="mort",ID="ID",station="Station.Name") review<-function(morts,new.data,old.data=NULL,type,ID,station,res.start="auto", res.end=NULL,residences=NULL,units=NULL, ddd=NULL,from.station=NULL,to.station=NULL){ @@ -67,9 +70,9 @@ review<-function(morts,new.data,old.data=NULL,type,ID,station,res.start="auto", and units must also be specified.") } - # Check that ID and station are specified (not "auto") for format="mort" + # Check that ID and station are specified (not "auto") for type="mort" if (type=="mort"&(ID=="auto"|station=="auto")){ - stop("ID and station must be specified (i.e., cannot be 'auto') for format='mort'") + stop("ID and station must be specified (i.e., cannot be 'auto') for type='mort'") } if (!is.null(ddd)){ @@ -137,10 +140,12 @@ review<-function(morts,new.data,old.data=NULL,type,ID,station,res.start="auto", stop("res.start is not in the format YYYY-mm-dd HH:MM:SS") } } - if (!is(old.data[[res.end]],"POSIXt")){ - try(old.data[[res.end]]<-as.POSIXct(old.data[[res.end]],tz="UTC",silent=TRUE)) + if (!is.null(res.end)){ if (!is(old.data[[res.end]],"POSIXt")){ - stop("res.end is not in the format YYYY-mm-dd HH:MM:SS") + try(old.data[[res.end]]<-as.POSIXct(old.data[[res.end]],tz="UTC",silent=TRUE)) + if (!is(old.data[[res.end]],"POSIXt")){ + stop("res.end is not in the format YYYY-mm-dd HH:MM:SS") + } } } } diff --git a/R/stationchange.R b/R/stationchange.R index 417e3df..b2d4921 100644 --- a/R/stationchange.R +++ b/R/stationchange.R @@ -16,10 +16,10 @@ #' @param residences a character string with the name of the column in `data` #' that holds the duration of the residence events. #' @param res.start a string of the name of the column in `data` that holds the -#' start date and time. Must be specified and in POSIXt if `format="manual"`. +#' start date and time. Must be specified and in POSIXt if `type="manual"`. #' @param res.end 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 `format="manual"`. +#' YYYY-mm-dd HH:MM:SS if `type="manual"`. #' @param drift option to account for potential drifting in identifying #' station changes. #' @param ddd a dataframe of stations/locations where detected movement between @@ -44,8 +44,7 @@ #' @export #' #' @examples -#' \dontrun{stationchange(data=res.events,format="manual",ID="TagID", -#' station="Receiver",res.start="StartUTC",residences="ResidencesLength.days")} +#' stn.change<-stationchange(data=events,type="mort",ID="ID",station="Station.Name") stationchange<-function(data,type="mort",ID,station,res.start="auto", res.end="auto",residences="auto", singles=TRUE,drift=FALSE,ddd=NULL,units=NULL,from.station=NULL, @@ -64,9 +63,9 @@ stationchange<-function(data,type="mort",ID,station,res.start="auto", stop("units must be specified if applying drift") } - # Check that ID and station are specified (not "auto") for format="mort" + # Check that ID and station are specified (not "auto") for type="mort" if (type=="mort"&(ID=="auto"|station=="auto")){ - stop("ID and station must be specified (i.e., cannot be 'auto') for format='mort'") + stop("ID and station must be specified (i.e., cannot be 'auto') for type='mort'") } # Fill in auto fields @@ -207,7 +206,7 @@ stationchange<-function(data,type="mort",ID,station,res.start="auto", #' @param station a string of the name of the column in `data` that holds the #' station name or receiver location. #' @param res.start a string of the name of the column in `data` that holds the -#' start date and time. Must be specified and in POSIXt if `format="manual"`. +#' start date and time. Must be specified and in POSIXt if `type="manual"`. #' @param residences a character string with the name of the column in `data` #' that holds the duration of the residence events. #' @param stnchange a dataframe with the start time and location of the most @@ -222,8 +221,13 @@ stationchange<-function(data,type="mort",ID,station,res.start="auto", #' @export #' #' @examples -#' \dontrun{resmax(data=res.events,ID="TagID",station="Receiver", -#' res.start="StartUTC",residences="ResidencesLength.days",stnchange=station.change)} +#' # Identify most recent station change +#' station.change<-stationchange(data=events,type="mort",ID="ID", +#' station="Station.Name") +#' +#' longest_res_events<-resmax(data=events,ID="ID",station="Station.Name", +#' res.start="ResidenceStart",residences="ResidenceLength.days", +#' stnchange=station.change) resmax<-function(data,ID,station,res.start, residences,stnchange,drift=FALSE,progressbar=TRUE){ res.max<-data[0,] @@ -280,9 +284,9 @@ resmax<-function(data,ID,station,res.start, #' @param station a string of the name of the column in `data` that holds the #' station name or receiver location. #' @param res.start a string of the name of the column in `data` that holds the -#' start date and time. Must be specified and in POSIXt if `format="manual"`. +#' start date and time. Must be specified and in POSIXt if `type="manual"`. #' @param res.end a string of the name of the column in `data` that holds the -#' end date and time. Must be specified and in POSIXt if `format="manual"`. +#' end date and time. Must be specified and in POSIXt if `type="manual"`. #' @param residences a character string with the name of the column in `data` #' that holds the duration of the residence events. #' @param units units of the duration of the residence events in `data`. @@ -298,9 +302,14 @@ resmax<-function(data,ID,station,res.start, #' @export #' #' @examples -#' \dontrun{resmaxcml(data=res.events,ID="TagID",station="Receiver", -#' res.start="StartUTC",res.end="EndUTC",residences="ResidencesLength.days", -#' units="days",stnchange=station.change)} +#' # Identify most recent station change +#' station.change<-stationchange(data=events,type="mort",ID="ID", +#' station="Station.Name") +#' +#' cumulative_events<-resmaxcml(data=events,ID="ID",station="Station.Name", +#' res.start="ResidenceStart",res.end="ResidenceEnd", +#' residences="ResidenceLength.days",units="days", +#' stnchange=station.change) resmaxcml<-function(data,ID,station,res.start,res.end, residences,units,stnchange,progressbar=TRUE){ res.maxcml<-data[0,] diff --git a/man/backwards.Rd b/man/backwards.Rd index 3c2a7a1..0a26ced 100644 --- a/man/backwards.Rd +++ b/man/backwards.Rd @@ -21,7 +21,7 @@ sample IDs.} station name or receiver location.} \item{res.start}{a string of the name of the column in \code{data} that holds the -start date and time. Must be specified and in POSIXt if \code{format="manual"}.} +start date and time. Must be specified and in POSIXt if \code{type="manual"}.} \item{stnchange}{a dataframe with the start time and location of the most recent station or location change. Must use the same column names and in @@ -41,6 +41,18 @@ Shift the start time of potential mortalities earlier, if station/location has not changed. } \examples{ -\dontrun{backwards(data=data,morts=morts,ID="TagID",station="Receiver", -res.start="ResidencesStart",stnchange=stn.change)} +morts<-morts(data=events,type="mort",ID="ID",station="Station.Name", +method="any") + +# If station change not identified yet: +morts_bw<-backwards(data=events,morts=morts,ID="ID", +station="Station.Name",res.start="ResidenceStart") + +# Identify station change first: +station.change<-stationchange(data=events,type="mort", +ID="ID",station="Station.Name") + +morts_bw<-backwards(data=events,morts=morts,ID="ID", +station="Station.Name",res.start="ResidenceStart", +stnchange=station.change) } diff --git a/man/drift.Rd b/man/drift.Rd index 3d85a9c..1ffa05d 100644 --- a/man/drift.Rd +++ b/man/drift.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/options.R \name{drift} \alias{drift} -\title{Dead drift} +\title{Dead and drifting} \usage{ drift( data, @@ -37,11 +37,11 @@ station name or receiver location.} \item{res.start}{a string of the name of the column in \code{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 \code{format="manual"}.} +YYYY-mm-dd HH:MM:SS if \code{type="manual"}.} \item{res.end}{a string of the name of the column in \code{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 \code{format="manual"}.} +YYYY-mm-dd HH:MM:SS if \code{type="manual"}.} \item{residences}{a character string with the name of the column in \code{data} that holds the duration of the residence events.} @@ -76,7 +76,11 @@ Identifies sequential residence events where detected movement between stations may be due to drifting of an expelled tag or dead animal. } \examples{ -\dontrun{drift(data=data,format="manual",ID="TagID",station="Receiver", -res.start="ResidenceStart",res.end="ResidenceEnd",ddd=driftstations, -from.station="FrStation",to.station="ToStation")} +drift.events<-drift(data=events,type="mort",ID="ID", +station="Station.Name",ddd=ddd,from.station="From",to.station="To") + +# With cutoff: +drift.events<-drift(data=events,type="mort",ID="ID", +station="Station.Name",ddd=ddd,from.station="From",to.station="To", +cutoff=1,cutoff.units="days") } diff --git a/man/infrequent.Rd b/man/infrequent.Rd index c29f495..133e99f 100644 --- a/man/infrequent.Rd +++ b/man/infrequent.Rd @@ -35,7 +35,7 @@ infrequent( tag ID, location name, start time, and duration. Residence events must also include end time if \code{season} is provided.} -\item{type}{the format used to generate the residence events. Options are +\item{type}{the method used to generate the residence events. Options are "mort", "actel", "glatos", "vtrack", or "manual". If "manual", then user must specify \code{ID}, \code{station}, \code{res.start}, \code{res.end}, \code{residences}, and \code{units}.} @@ -47,11 +47,11 @@ station name or receiver location.} \item{res.start}{a string of the name of the column in \code{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 \code{format="manual"}.} +YYYY-mm-dd HH:MM:SS if \code{type="manual"}.} \item{res.end}{a string of the name of the column in \code{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 \code{format="manual"}.} +YYYY-mm-dd HH:MM:SS if \code{type="manual"}.} \item{residences}{residences a character string with the name of the column in \code{data} that holds the duration of the residence events.} @@ -122,7 +122,9 @@ residence events in \code{data}.} if \code{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 \code{morts} is specified, any potential mortalities will be added to existing -\code{morts} dataframe. +\code{morts} dataframe. If \code{morts} is specified and \code{replace=TRUE}, then any +mortalities that are flagged by \code{infrequent()} and occurred at an earlier +time than those in \code{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. @@ -133,24 +135,26 @@ detections in passive acoustic telemetry data. Mortalities are identfied based on a user-defined threshold and timeframe. } \details{ -Example of \code{method="recent"}: if \code{threshold=10} and \code{recent.period=1} and -\code{recent.units="years"}, 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 \code{method="recent"}: if \code{threshold=10}, \code{threshold.units="mins"}, +\code{recent.period=52} and \code{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 \code{method="defined"}: if \code{threshold=10} and \code{start="2019-10-01"} and \code{end="2020-06-01"}, an animal +Example of \code{method="defined"}: if \code{threshold=10}, \code{threshold.units="mins"}, +\code{start="2019-10-01"}, and \code{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. } \examples{ ## Recent example -\dontrun{infrequent(data=data,format="manual",ID="TagID",station="Receiver", -res.start="ResStart",res.end="ResEnd",residences="ResidenceLength.days", -units="days",method="recent",threshold=0.5,recent.period=1, -recent.units="years")} +inf_recent<-infrequent(data=events,type="mort",ID="ID", +station="Station.Name",method="recent", +threshold=0.5,threshold.units="hours", +recent.period=52,recent.units="weeks") + ## User-defined example -\dontrun{infrequent(data=data,format="manual",ID="TagID",station="Receiver", -res.start="ResStart",res.end="ResEnd",residences="ResidenceLength.days", -units="days",method="defined",threshold=0.5,start="2019-10-01", -end="2020-06-01")} +inf_defined<-infrequent(data=events,type="mort",ID="ID", +station="Station.Name",method="defined", +threshold=0.5,threshold.units="hours", +start="2019-10-01",end="2020-06-01") } diff --git a/man/morts.Rd b/man/morts.Rd index 54639f2..c60d00a 100644 --- a/man/morts.Rd +++ b/man/morts.Rd @@ -45,11 +45,11 @@ station name or receiver location.} \item{res.start}{a string of the name of the column in \code{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 \code{format="manual"}.} +YYYY-mm-dd HH:MM:SS if \code{type="manual"}.} \item{res.end}{a string of the name of the column in \code{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 \code{format="manual"}.} +YYYY-mm-dd HH:MM:SS if \code{type="manual"}.} \item{method}{the method to be used in flagging mortalities. Options are "last", "any", "cumulative", or "all"} @@ -127,5 +127,9 @@ acoustic telemetry data. Mortalities are identified based on thresholds derived from the dataset itself. } \examples{ -\dontrun{mort(data=res.events,format="manual",units="days",residences="ResidenceLength")} +morts_ex<-morts(data=events,type="mort",ID="ID", +station="Station.Name",method="any") + +morts_ex_bw<-morts(data=events,type="mort",ID="ID", +station="Station.Name",method="any",backwards=TRUE) } diff --git a/man/mortsplot.Rd b/man/mortsplot.Rd index 155ddaa..91a3cbc 100644 --- a/man/mortsplot.Rd +++ b/man/mortsplot.Rd @@ -40,11 +40,11 @@ station name or receiver location.} \item{res.start}{a string of the name of the column in \code{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 \code{format="manual"}.} +YYYY-mm-dd HH:MM:SS if \code{type="manual"}.} \item{res.end}{a string of the name of the column in \code{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 \code{format="manual"}.} +YYYY-mm-dd HH:MM:SS if \code{type="manual"}.} \item{morts}{a dataframe containing potential mortalities. The dataframe must have the same ID, station, res.start, res.end, and residences column names @@ -97,6 +97,12 @@ Plot residence events, with the option of plotting identified mortalities. Plotting uses ggplot2. Interactive option also uses plotly. } \examples{ -\dontrun{plot<-mortsplot(data=data,type="mort",ID="TagID",station="Station.Name", -interactive=TRUE,residences="auto")} +plot<-mortsplot(data=events,type="mort",ID="ID",station="Station.Name") + +# With mortalities plotted over residences: +morts<-morts(data=events,type="mort",ID="ID",station="Station.Name", +method="any") + +plot<-mortsplot(data=events,type="mort",ID="ID",station="Station.Name", +morts=morts) } diff --git a/man/new.data.Rd b/man/new.data.Rd index 8b6d172..a3a0f7f 100644 --- a/man/new.data.Rd +++ b/man/new.data.Rd @@ -18,10 +18,13 @@ function. The variables are as follows: \itemize{ -\item DateTimeUTC. The date and time of each detection, in POSIXct format. The -data are in UTC, as they would be when downloaded from the receivers. -\item Station.Name Name of the receiver location. -\item ID Unique ID of the fish. +\item ResidenceStart. The start time of the residence events, in POSIXct. +\item Station.Name. Name of the receiver location. +\item ID. Unique ID of the fish. +\item ResidenceEnd. The end time of the residence events, in POSIXct. +\item ResidenceLength.days. The duration of the residence events. The units are +days, as indicated by the variable name (which is automatically generated +by mort::residences()) } } \keyword{datasets} diff --git a/man/residences.Rd b/man/residences.Rd index 4c57f2c..55f9d88 100644 --- a/man/residences.Rd +++ b/man/residences.Rd @@ -37,6 +37,6 @@ appears and after the progress bar has reached 100\%, which may be substantial depending on the size of the telemetry dataset. } \examples{ -\dontrun{residences(data=detections,ID="TagID",station="Receiver", -datetime="DateTimeUTC",cutoff=1,units="days")} +res.events<-residences(data=detections,ID="ID",station="Station.Name", +datetime="DateTimeUTC",cutoff=1,units="days") } diff --git a/man/resmax.Rd b/man/resmax.Rd index a5a3b23..104422c 100644 --- a/man/resmax.Rd +++ b/man/resmax.Rd @@ -27,7 +27,7 @@ sample IDs.} station name or receiver location.} \item{res.start}{a string of the name of the column in \code{data} that holds the -start date and time. Must be specified and in POSIXt if \code{format="manual"}.} +start date and time. Must be specified and in POSIXt if \code{type="manual"}.} \item{residences}{a character string with the name of the column in \code{data} that holds the duration of the residence events.} @@ -50,6 +50,11 @@ Find the maximum duration of a single residence in the dataset that occurred before a station change (i.e., the animal can be assumed to be alive) } \examples{ -\dontrun{resmax(data=res.events,ID="TagID",station="Receiver", -res.start="StartUTC",residences="ResidencesLength.days",stnchange=station.change)} +# Identify most recent station change +station.change<-stationchange(data=events,type="mort",ID="ID", +station="Station.Name") + +longest_res_events<-resmax(data=events,ID="ID",station="Station.Name", +res.start="ResidenceStart",residences="ResidenceLength.days", +stnchange=station.change) } diff --git a/man/resmaxcml.Rd b/man/resmaxcml.Rd index 1f1c7e2..f34981c 100644 --- a/man/resmaxcml.Rd +++ b/man/resmaxcml.Rd @@ -28,10 +28,10 @@ sample IDs.} station name or receiver location.} \item{res.start}{a string of the name of the column in \code{data} that holds the -start date and time. Must be specified and in POSIXt if \code{format="manual"}.} +start date and time. Must be specified and in POSIXt if \code{type="manual"}.} \item{res.end}{a string of the name of the column in \code{data} that holds the -end date and time. Must be specified and in POSIXt if \code{format="manual"}.} +end date and time. Must be specified and in POSIXt if \code{type="manual"}.} \item{residences}{a character string with the name of the column in \code{data} that holds the duration of the residence events.} @@ -59,7 +59,12 @@ included, provided there are no intervening residence events at other stations/locations. } \examples{ -\dontrun{resmaxcml(data=res.events,ID="TagID",station="Receiver", -res.start="StartUTC",res.end="EndUTC",residences="ResidencesLength.days", -units="days",stnchange=station.change)} +# Identify most recent station change +station.change<-stationchange(data=events,type="mort",ID="ID", +station="Station.Name") + +cumulative_events<-resmaxcml(data=events,ID="ID",station="Station.Name", +res.start="ResidenceStart",res.end="ResidenceEnd", +residences="ResidenceLength.days",units="days", +stnchange=station.change) } diff --git a/man/review.Rd b/man/review.Rd index dd9528e..39d1d2f 100644 --- a/man/review.Rd +++ b/man/review.Rd @@ -83,6 +83,9 @@ flagged as a mortality made a station/location change and may therefore be alive. } \examples{ -\dontrun{undead<-review(morts=morts,new.data=new.data,old.data=old.data, -ID="TagID",station="Station.Name",res.start="ResidenceStart")} +morts<-morts(data=events,type="mort",ID="ID",station="Station.Name", +method="any") + +undead<-review(morts=morts,new.data=new.data, +type="mort",ID="ID",station="Station.Name") } diff --git a/man/season.Rd b/man/season.Rd index 08da213..8f802e8 100644 --- a/man/season.Rd +++ b/man/season.Rd @@ -35,11 +35,11 @@ station name or receiver location.} \item{res.start}{a string of the name of the column in \code{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 \code{format="manual"}.} +YYYY-mm-dd HH:MM:SS if \code{type="manual"}.} \item{res.end}{a string of the name of the column in \code{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 \code{format="manual"}.} +YYYY-mm-dd HH:MM:SS if \code{type="manual"}.} \item{residences}{a character string with the name of the column in \code{data} that holds the duration of the residence events.} @@ -80,7 +80,13 @@ increase the threshold use to identify mortalities, which would then cause potential mortalities to be missed. } \examples{ -\dontrun{season(data=data,res.start="ResidenceStart",res.end="ResidenceEnd", -residences="ResidenceDuration",units="days",season.start="01-06", -season.end="31-10")} +# Seasons in format dd-mm +season.events<-season(data=events,type="mort",ID="ID", +station="Station.Name",season.start="01-06",season.end="31-10") + +# Seasons in format YYYY-mm-dd HH:MM:SS +season.start<-c("2003-06-15","2004-06-21") +season.end<-c("2003-10-15","2004-10-30") +season.events<-season(data=events,type="mort",ID="ID", +station="Station.Name",season.start=season.start,season.end=season.end) } diff --git a/man/stationchange.Rd b/man/stationchange.Rd index 7257624..1b86dc9 100644 --- a/man/stationchange.Rd +++ b/man/stationchange.Rd @@ -36,11 +36,11 @@ sample IDs.} station name or receiver location.} \item{res.start}{a string of the name of the column in \code{data} that holds the -start date and time. Must be specified and in POSIXt if \code{format="manual"}.} +start date and time. Must be specified and in POSIXt if \code{type="manual"}.} \item{res.end}{a string of the name of the column in \code{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 \code{format="manual"}.} +YYYY-mm-dd HH:MM:SS if \code{type="manual"}.} \item{residences}{a character string with the name of the column in \code{data} that holds the duration of the residence events.} @@ -81,6 +81,5 @@ Identify the most recent station or location change from passive acoustic telemetry data. } \examples{ -\dontrun{stationchange(data=res.events,format="manual",ID="TagID", -station="Receiver",res.start="StartUTC",residences="ResidencesLength.days")} +stn.change<-stationchange(data=events,type="mort",ID="ID",station="Station.Name") } diff --git a/vignettes/a1_data-prep.Rmd b/vignettes/a1_data-prep.Rmd index 8f2d919..2a51e8c 100644 --- a/vignettes/a1_data-prep.Rmd +++ b/vignettes/a1_data-prep.Rmd @@ -41,7 +41,7 @@ knitr::kable(head(events),align="c") `ID` is defined by the user. ID could be the tag transmitter ID, the tag serial number, or a unique ID associated with the detections by the user. If the latter, `residences()` and the other functions in mort can accommodate multiple tag deployments (i.e., a tag is returned and re-deployed on another animal), because the ID is unique to the animal. -`station` is also definied by the user. It could be the receiver serial number (if the same receiver is always deployed at the same location), a unique location name, or a cluster of receivers (similar to Array in the actel package). +`station` is also defined by the user. It could be the receiver serial number (if the same receiver is always deployed at the same location), a unique location name, or a cluster of receivers (similar to Array in the [actel](https://cran.r-project.org/web/packages/actel/index.html) package). Note that `units` specifies the units of the cutoff (in the example above, the cutoff is 1 day). These units will also be used to calculate the residence duration. @@ -57,7 +57,7 @@ attributes(data$DateTimeUTC)$tzone<-"UTC" mort functions support the output from other packages for acoustic telemetry data. Note that the following information will be most useful if referenced while exploring the other mort functions. ### actel -Residence events are called "movement events" in actel, and are generated using the `explore()` function. +Residence events are called "movement events" in [actel](https://cran.r-project.org/web/packages/actel/index.html), and are generated using the `explore()` function. Actel provides residence duration in the format HH:MM:SS. mort converts the duration to a numeric vector, with units of seconds. @@ -68,12 +68,12 @@ warning("If actel date/times are in local time, they will be converted to UTC. V ``` ### glatos -Residence events are called "detection events" in glatos, and are generated using the `detection_events()` function. +Residence events are called "detection events" in [glatos](https://github.com/ocean-tracking-network/glatos), and are generated using the `detection_events()` function. glatos uses seconds for the units of residence duration and UTC as the timezone for datetimes. ### VTrack -Residence events are called "residences" in VTrack, and are generated using the `RunResidenceExtraction()` function. +Residence events are called "residences" in [VTrack](https://github.com/RossDwyer/VTrack), and are generated using the `RunResidenceExtraction()` function. As of VTrack version 2.10, it looks as though VTrack assigns the local time of the user's computer to datetimes. As detection data are typically downloaded in UTC, mort assumes that the datetimes output by VTrack are actually in UTC, rather than local time. Users will receive a warning when using VTrack residence events: