Skip to content

Commit

Permalink
verified examples and documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@rosieluain
rosieluain committed Jun 28, 2023
1 parent 6b2ee9b commit f8657de
Show file tree
Hide file tree
Showing 20 changed files with 247 additions and 151 deletions.
10 changes: 5 additions & 5 deletions R/helper.R
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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"){
Expand Down Expand Up @@ -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
Expand All @@ -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,]))
Expand Down Expand Up @@ -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))])){
Expand Down
61 changes: 34 additions & 27 deletions R/mort.R
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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,
Expand All @@ -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
Expand Down Expand Up @@ -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],
Expand Down Expand Up @@ -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
Expand All @@ -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",
Expand Down Expand Up @@ -510,37 +515,39 @@ 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.
#' @export
#'
#' @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,
Expand All @@ -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
Expand Down
61 changes: 41 additions & 20 deletions R/options.R
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
Expand All @@ -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
Expand Down Expand Up @@ -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.
#'
Expand All @@ -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`.
Expand All @@ -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){
Expand All @@ -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
Expand All @@ -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")){
Expand All @@ -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
Expand Down Expand Up @@ -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",
Expand All @@ -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){
Expand All @@ -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
Expand Down
24 changes: 15 additions & 9 deletions R/plot.R
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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"){
Expand Down Expand Up @@ -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"){
Expand Down Expand Up @@ -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+
Expand Down
Loading

0 comments on commit f8657de

Please sign in to comment.