R/data.R

In robschick/tangled: Creates data objects and plots for Knowlton, Schick et al. manuscript on entanglement

#' Information about gear carrying time on entangled right whales
#'
#' A dataset generated by Amy Knowlton of the New England Aquarium as part of
#' the PCAD/PCOD project looking at health and the impacts of disturbance on
#' vital rates in North Atlantic right whales. These data are used to establish
#' the "windows" when animals are entangled and in turn to intersect those
#' windows with estimates of health.
#'
#' @format a data frame containing 102 rows and 9 variables: \describe{
#'   \item{EGNo}{4 number code that identifies individual right whales}
#'   \item{EventNo}{Integer labelling the consecutive number of each
#'   entanglement event} \item{Date prior w/no gear}{A character variable
#'   describing the first date the animal was seen without gear} \item{First
#'   date w/gear}{A character variable describing the first date the animal was
#'   seen with gear} \item{Last date w/gear}{A character variable describing the
#'   last date the animal was seen with gear} \item{line gone}{A character
#'   variable describing the first date the animal was seen that the gear is
#'   verified to be gone from the animal} \item{min time carrying gear}{Integer
#'   denoting the minimum number of days the animal was carrying the gear}
#'   \item{max dur}{Integer denoting the maximum number of days the animal was
#'   carrying the gear} \item{AmyEdits}{Comments from Amy Knowlton about
#'   individual entries she updated and/or inserted} }
'etime'

#' Information about estimated start data of entanglement events
#' 
#' A dataset generated by Amy Knowlton of the New England Aquarium
#' as part of the PCAD/PCOD project looking at health and the impacts
#' of disturbance on vital rates in North Atlantic right whales. These
#' data are used to establish the start of "windows" that denote when animals 
#' are entangled and in turn to intersect those windows with estimates of health.
#' 
#' @format a data frame containing 130 rows and 6 variables:
#' \describe{
#'  \item{EntanglementId}{A unique identifier for the entanglement event in the NEAq DIGITS database}
#'  \item{EGNo}{4 number code that identifies individual right whales}
#'  \item{EventNo}{Integer labelling the consecutive number of each entanglement event}
#'  \item{StartDate}{A character variable describing the estimated first date of the 
#'  entanglement event}
#'  \item{EndDate}{A character variable describing the observed last date of the 
#'  entanglement event}
#'  \item{EntanglementComment}{Comments from Amy Knowlton about the entanglement events}
#' }
'estStartDates'

#' Information about entanglement events - raw
#' 
#' 
#' 
#' @format A data frame of 1,194 rows and 12 columns:
#' \describe{
#'  \item{EntanglementId}{A unique identifier for the entanglement event in the NEAq DIGITS database}
#'  \item{EGNo}{4 number code that identifies individual right whales}
#'  \item{EventNo}{Integer labelling the consecutive number of each entanglement event}
#'  \item{StartDate}{A time variable describing the estimated first date of the 
#'  entanglement event}
#'  \item{EndDate}{A time variable describing the observed last date of the 
#'  entanglement event}
#'  \item{EntanglementComment}{Comments from Amy Knowlton about the entanglement events}
#' \item{AgeSex}{Character vector comment describing the age and gender of the animal, e.g. 'Unknown age female', '2 year old male', etc.}
#' \item{TimeFrame}{Amy Knowlton's descriptive comments concerning the time frame and duration of the entanglement event}
#' \item{Severity}{One of three categories of worsening injury: minor, moderate, severe. These are standard definitions created by NEA}
#' \item{gear}{Integer variable describing whether or not the animal is carrying gear as part of the entanglement: 0 for no gear; 1 for gear}
#' \item{LiveStatus}{Character vector indicating whether the animal is 'ALIVE' or 'DEAD'}
#' \item{Gender}{Character descriptor of the animal's sex: "female," "male," or NA}
#' }
'tangleAll'



#' Information about entanglement events - filtered and modified for use in analysis
#' 
#' Whereas \code{tangleAll} contains the raw information on the entanglement events, \code{tangleOut} is designed to be used in the analysis of the effects of entanglement on health. This means that the 'windows' have been created according to different rules, the gear status information has been added, and the indices have been added for the windows to facilitate data extraction from the health data as part of the model output.
#' 
#' Starting with the \code{StartDate} and \code{EndDate} from the raw data we have the entire window/duration when the animal may have been entangled. However, in reality, these windows can be really long - most often just associated with sighting gaps in the animal's history. In certain cases, then, it makes sense to pare down these windows into something a bit shorter. We have generated a set of rules for both the starting dates as well as the ending dates; the rules are as follows:
#' 
#' For any window that is greater than or equal to 3 months, the window gets shortened to 3 months. We do this by evaluating the duration between \code{StartDateWindow} and \code{EndDateWindow}. If that value exceeds 3 months, then a new start date is calculated by subtracting 3 months from the end date.
#'  
#' For any window >= 1 & <2 months, the window gets shortened to 1 month. Processing is as above.
#' 
#' For any window < 1 month, the window gets lengthened to 1 month. Processing is as above.
#' 
#' For any window >= 2 & <3 months, the window gets set to 2 month. Processing is as above. 
#' 
#' @format A data frame of 910 rows and 22 columns:
#' \describe{
#'  \item{EGNo}{4 number code that identifies individual right whales}
#'  \item{EventNo}{Integer labelling the consecutive number of each entanglement event}
#'  \item{StartDate}{A time variable describing the estimated first date of the 
#'  entanglement event} 
#'  \item{EndDate}{A time variable describing the end of the entanglement event}  
#' \item{Severity}{One of three categories of worsening injury: minor, moderate, severe. These are standard definitions created by NEA}
#' \item{gear}{Integer variable describing whether or not the animal is carrying gear as part of the entanglement: 0 for no gear; 1 for gear}
#' \item{StartDateWindow}{Date of the altered start of the window using rules outlined below}
#' \item{EndDateWindow}{Date of the end of the window - same as \code{EndDate}}
#' \item{LastDatewGear}{Date of the last photographic observation of the whale where it was seen carrying gear}
#' \item{LineGone}{Date of the first time the animal was confirmed to be free of gear}
#' \item{firstSevere}{Date of the first (if any) severe entanglement event experienced by the individual whale. This is used as a flag to make sure we do not include any subsequent events in the health calculations, i.e. once an animal has had a severe event, they are forever impaired.}
#' \item{recov12months}{Date of 12 months past the entanglement event. Note that this means different things for different animals. For animals that are known to carry gear, this is 12 months past either \code{LastDatewGear} or \code{LineGone} (whichever is finite); for non-gear carrying whales this is 12 months beyond \code{EndDateWindow}}
#' \item{firstCalf}{Date format denoting January of the first year during which the whale was observed with a calf. This is used in establishing the before/after calf status of the animal for documenting health}
#' \item{firstCalfidx}{Integer corresponding to the location in \code{myName} of the date in \code{firstCalf}}
#' \item{smonyr}{Character version of \code{StartDate} designed to intersect with \code{myName} to peel off the health values in the matrix of estimated heatlh, e.g. '2-1986'}
#' \item{emonyr}{Character version of \code{EndDate} designed to intersect with \code{myName} to peel off the health values in the matrix of estimated heatlh, e.g. '2-1986'}
#' \item{swindmonyr}{Character version of \code{StartDateWindow} designed to intersect with \code{myName} to peel off the health values in the matrix of estimated heatlh, e.g. '2-1986'}
#' \item{ewindmonyr}{Character version of \code{EndDateWindow} designed to intersect with \code{myName} to peel off the health values in the matrix of estimated heatlh, e.g. '2-1986'}
#' \item{fsevmonyr}{Character version of \code{firstSevere} designed to intersect with \code{myName} to peel off the health values in the matrix of estimated heatlh, e.g. '2-1986'}
#' \item{rec12monyr}{Character version of \code{recov12months} designed to intersect with \code{myName} to peel off the health values in the matrix of estimated heatlh, e.g. '2-1986'}
#' \item{afterCalf1}{Logical of whether or not the entanglement event is after the first calving event (\code{firstCalf})}
#' }
'tangleOut'



#' Information about entanglement events of reproductively active females
#' 
#' Whereas \code{tangleOut} contains all the filtered information on the entanglement events, \code{tangRepro} contains the same information for only the reproductively active females.
#' 
#' 
#' @format A data frame of 113 rows and 22 columns:
#' \describe{
#'  \item{EGNo}{4 number code that identifies individual right whales}
#'  \item{EventNo}{Integer labelling the consecutive number of each entanglement event}
#'  \item{StartDate}{A time variable describing the estimated first date of the 
#'  entanglement event} 
#'  \item{EndDate}{A time variable describing the end of the entanglement event}  
#' \item{Severity}{One of three categories of worsening injury: minor, moderate, severe. These are standard definitions created by NEA}
#' \item{gear}{Integer variable describing whether or not the animal is carrying gear as part of the entanglement: 0 for no gear; 1 for gear}
#' \item{StartDateWindow}{Date of the altered start of the window using rules outlined below}
#' \item{EndDateWindow}{Date of the end of the window - same as \code{EndDate}}
#' \item{LastDatewGear}{Date of the last photographic observation of the whale where it was seen carrying gear}
#' \item{LineGone}{Date of the first time the animal was confirmed to be free of gear}
#' \item{firstSevere}{Date of the first (if any) severe entanglement event experienced by the individual whale. This is used as a flag to make sure we do not include any subsequent events in the health calculations, i.e. once an animal has had a severe event, they are forever impaired.}
#' \item{recov12months}{Date of 12 months past the entanglement event. Note that this means different things for different animals. For animals that are known to carry gear, this is 12 months past either \code{LastDatewGear} or \code{LineGone} (whichever is finite); for non-gear carrying whales this is 12 months beyond \code{EndDateWindow}}
#' \item{firstCalf}{Date format denoting January of the first year during which the whale was observed with a calf. This is used in establishing the before/after calf status of the animal for documenting health}
#' \item{firstCalfidx}{Integer corresponding to the location in \code{myName} of the date in \code{firstCalf}}
#' \item{smonyr}{Character version of \code{StartDate} designed to intersect with \code{myName} to peel off the health values in the matrix of estimated heatlh, e.g. '2-1986'}
#' \item{emonyr}{Character version of \code{EndDate} designed to intersect with \code{myName} to peel off the health values in the matrix of estimated heatlh, e.g. '2-1986'}
#' \item{swindmonyr}{Character version of \code{StartDateWindow} designed to intersect with \code{myName} to peel off the health values in the matrix of estimated heatlh, e.g. '2-1986'}
#' \item{ewindmonyr}{Character version of \code{EndDateWindow} designed to intersect with \code{myName} to peel off the health values in the matrix of estimated heatlh, e.g. '2-1986'}
#' \item{fsevmonyr}{Character version of \code{firstSevere} designed to intersect with \code{myName} to peel off the health values in the matrix of estimated heatlh, e.g. '2-1986'}
#' \item{rec12monyr}{Character version of \code{recov12months} designed to intersect with \code{myName} to peel off the health values in the matrix of estimated heatlh, e.g. '2-1986'}
#' \item{afterCalf1}{Logical of whether or not the entanglement event is after the first calving event (\code{firstCalf})}
#' }
'tangRepro'

#' Information about entanglement events of non-reproductively active whales
#' 
#' Whereas \code{tangleOut} contains all the filtered information on the entanglement events, \code{tangNonRepro} contains the same information for all the non-reproductively active females. Note that this can include reproductively active females but only for the times \emph{before} they have their first calf. In other words, it contains males of all ages, and females up until they've had a calf. Once they've had a calf, the event gets tallied in \code{tangRepro}
#' 
#' 
#' @format A data frame of 797 rows and 22 columns:
#' \describe{
#'  \item{EGNo}{4 number code that identifies individual right whales}
#'  \item{EventNo}{Integer labelling the consecutive number of each entanglement event}
#'  \item{StartDate}{A time variable describing the estimated first date of the 
#'  entanglement event} 
#'  \item{EndDate}{A time variable describing the end of the entanglement event}  
#' \item{Severity}{One of three categories of worsening injury: minor, moderate, severe. These are standard definitions created by NEA}
#' \item{gear}{Integer variable describing whether or not the animal is carrying gear as part of the entanglement: 0 for no gear; 1 for gear}
#' \item{StartDateWindow}{Date of the altered start of the window using rules outlined below}
#' \item{EndDateWindow}{Date of the end of the window - same as \code{EndDate}}
#' \item{LastDatewGear}{Date of the last photographic observation of the whale where it was seen carrying gear}
#' \item{LineGone}{Date of the first time the animal was confirmed to be free of gear}
#' \item{firstSevere}{Date of the first (if any) severe entanglement event experienced by the individual whale. This is used as a flag to make sure we do not include any subsequent events in the health calculations, i.e. once an animal has had a severe event, they are forever impaired.}
#' \item{recov12months}{Date of 12 months past the entanglement event. Note that this means different things for different animals. For animals that are known to carry gear, this is 12 months past either \code{LastDatewGear} or \code{LineGone} (whichever is finite); for non-gear carrying whales this is 12 months beyond \code{EndDateWindow}}
#' \item{firstCalf}{Date format denoting January of the first year during which the whale was observed with a calf. This is used in establishing the before/after calf status of the animal for documenting health}
#' \item{firstCalfidx}{Integer corresponding to the location in \code{myName} of the date in \code{firstCalf}}
#' \item{smonyr}{Character version of \code{StartDate} designed to intersect with \code{myName} to peel off the health values in the matrix of estimated heatlh, e.g. '2-1986'}
#' \item{emonyr}{Character version of \code{EndDate} designed to intersect with \code{myName} to peel off the health values in the matrix of estimated heatlh, e.g. '2-1986'}
#' \item{swindmonyr}{Character version of \code{StartDateWindow} designed to intersect with \code{myName} to peel off the health values in the matrix of estimated heatlh, e.g. '2-1986'}
#' \item{ewindmonyr}{Character version of \code{EndDateWindow} designed to intersect with \code{myName} to peel off the health values in the matrix of estimated heatlh, e.g. '2-1986'}
#' \item{fsevmonyr}{Character version of \code{firstSevere} designed to intersect with \code{myName} to peel off the health values in the matrix of estimated heatlh, e.g. '2-1986'}
#' \item{rec12monyr}{Character version of \code{recov12months} designed to intersect with \code{myName} to peel off the health values in the matrix of estimated heatlh, e.g. '2-1986'}
#' \item{afterCalf1}{Logical of whether or not the entanglement event is after the first calving event (\code{firstCalf})}
#' }
'tangNonRepro'

#' Table describing all of the calving events in the right whale population
#' 
#' This table is from Philip Hamilton (New England Aquarium) and contains
#' all the known information regarding calving. Each row contains calving 
#' information from the perspective of the mom. There are 4 columns in the data
#' frame as follows:
#' \describe{
#'    \item{EGNo}{4 number code that identifies individual right whale mothers}
#'    \item{CalvingYear}{Integer noting the year that the calf was born}
#'    \item{CalfNo}{The 4 number code identifying the ID of the calf. It's not
#'        known in all cases, e.g. '1973CalfOf1002'.}
#'    \item{CalvingInterval}{Integer describing the time since the mom last had a 
#'        calf}
#' }
'calfTable'