R/tangled.R

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

#' tangled: a package for analysis and plotting of effects of entanglement on right whales
#' 
#' The tangled package takes output from the model described in Schick et al. 
#' 2013, PLoS-ONE. In the package we analyse the data, prepare it for plotting
#' and make plot objects to be used in the entanglement paper. This paper
#' (Knowlton, Schick, et al. \emph{in prep}) describes the effect of 
#' entanglements on the health and survival of right whales. There are 5
#' main components to the package: 1) extraction summary; 2) changes in health
#' over time; 3) health during entanglements; 4) sub-lethal impacts of impaired
#' health; and 5) effects on survival. I'll document those briefly in the sections
#' below, but they are spelled out in greater detail in each of the vignettes that
#' accompany this package.
#' 
#' @section Extraction summary:
#' The goal of this section is to show for the readers how we extract health 
#' information with respect to the start/end times and duration of the 
#' entanglements. The important function is \code{winDiagram}
#' 
#' @section Changes in Health:
#' This part of the package describes how we plot changes in health
#' over time as a function of entanglement severity. There are 4 prep functions:
#' \code{prepSlopeHealthData}, \code{prepSlopeHealthDataBarplot}, 
#' \code{prepSlopeHealthDataMedian}, and \code{prepSlopeHealthDataAnnotation}; 
#' there is 1 plot function: \code{plotSlopeHealth}.
#' 
#' @section Health during entanglements:
#' While the Changes in Health section describes the change across the entanglement
#' period - the goal of this analysis is to examine health \emph{during} the 
#' period. There are 2 main functions: \code{prepBoxplotHealthData} and  
#' \code{plotBoxplotHealth}.
#' 
#' @section Sub-lethal impacts of entanglement:
#' This section documents the amount of time animals are spending in impaired
#' health status during their entanglements. The idea is to see if animals
#' are spending more time in worse health - as defined by the reproductive
#' threshold enumerated in Rolland et al. (2016) Marine Ecology Progress
#' Series 542:265-82. We compare health below this threshold status as
#' a function of increasing entanglement severity and complexity. There are 4
#' main functions: \code{prepThreshDataUnImp}, \code{prepThreshDataRepro},
#' \code{prepHealthThresholdPlotData}, and \code{plotHealthThreshold}.
#' 
#' @section Effects of survival:
#' This section examines survival of entangled right whales as a function
#' of injury category. As with the other sections, it combines data prep \&
#' analysis with data plotting. Unlike the others, we also add a section
#' comparing the statistics of the different curves and models. There are 6
#' main functions: \code{calcpresdSurvdat}, \code{calckdpaSurvdat} both of which
#' prepare the survival data for each of the three types: known dead, presumed
#' dead, and presumed alive. The next 2 functions: \code{calcKMCurves} and
#' \code{calcKMCurvesSevGen} prepare Kaplan-Meier survivorship data. Finally,
#' \code{plotSurv} and \code{potSurvGenderSeverity} make the plots of this
#' survivorship data.
#' 
#' @docType package
#' @name tangled
#' @importFrom magrittr %>%
NULL