ThermStats: Calculate statistics for thermal images

#' Statistics from \code{get_stats} for photo FLIR8565.jpg
#'
#' Results of running \code{get_stats} for photo FLIR8565.jpg. The image file is 
#' included in the package installation and can be located by:
#' \code{system.file("extdata/FLIR8565.jpg", package = "ThermStats")}. 
#' @docType data
#' @usage flir_stats
#' @format A list consisting of:
#'   \itemize{
#'     \item{df} {= A dataframe with one row for each pixel, and variables denoting:
#'     the pixel value (val); the original spatial location of the pixel (x and y);
#'     its patch classification (G_bin) into a hot (1), cold (-1) or no patch (0)
#'     according to the Z value (see \code{spdep::}\code{\link[spdep]{localG}});
#'     the unique ID of the patch in which the pixel fell;
#'     and the matrix ID (if applicable).}
#'     \item{patches} {= A SpatialPolygonsDataFrame of hot and cold patches. Hot
#'     patches have a value of 1, and cold patches a value of -1.}
#'     \item{pstats} {= A dataframe with patch statistics for hot patches and cold
#'     patches, respectively. See \code{\link{patch_stats}} for details of all the
#'     statistics returned.}
#'   }
#' @keywords datasets
#' @encoding UTF-8
#' @details This data is primarily included to speed up build time of the package
#' vignette (see \code{browseVignettes("ThermStats")}). If interested, you can
#' reproduce \code{flir_stats} following the example below.
#' @examples
#' head(flir_stats$df)
#' flir_stats$pstats
#' plot_patches(df = flir_stats$df,
#'              patches = flir_stats$patches, 
#'              save_plot = FALSE, 
#'              print_plot = TRUE)
#'              
#' # Recreate flir_stats ------------------------------------------------------
#' 
#' # Define raw data
#' raw_dat <- flir_raw$raw_dat$`8565`
#' # Define camera calibration constants dataframe
#' camera_params <- flir_raw$camera_params
#' # Define metadata
#' metadata <- flir_metadata
#' # Create vector denoting the position of photo within metadata
#' photo_index <- match(8565, metadata$photo_no)
#' # Convert
#' flir_converted <- 
#'     Thermimage::raw2temp(
#'         raw = raw_dat,
#'         # Emissivity = mean of range in Scheffers et al. 2017
#'         E = mean(c(0.982,0.99)),
#'         # Object distance = hypotenuse of right triangle where 
#'         # vertical side is 1.3 m (breast height) & angle down is 45°
#'         OD = (sqrt(2))*1.3,
#'         # Apparent reflected temperature & atmospheric temperature =
#'         # atmospheric temperature measured in the field
#'         RTemp = metadata$atm_temp[photo_index],
#'         ATemp = metadata$atm_temp[photo_index],
#'         # Relative humidity = relative humidity measured in the field
#'         RH = metadata$rel_humidity[photo_index],
#'         # Calibration constants from 'batch_extract'
#'         PR1 = camera_params[,"PlanckR1"],
#'         PB = camera_params[,"PlanckB"],
#'         PF = camera_params[,"PlanckF"],
#'         PO = camera_params[,"PlanckO"],
#'         PR2 = camera_params[,"PlanckR2"])
#'         
#' # Get stats
#' flir_stats <-
#'     get_stats(
#'         # The temperature dataset
#'         img = flir_converted,
#'         # The ID of the dataset
#'         id = "8565",
#'         # Whether or not to calculate thermal connectivity
#'         calc_connectivity = FALSE,
#'         # Whether or not to identify hot and cold spots
#'         patches = TRUE,
#'         # The image projection (only relevant for geographic data)
#'         img_proj = NULL,
#'         # The image extent (only relevant for geographic data)
#'         img_extent = NULL, 
#'         # The data to return
#'         return_vals = c("df", # Temperature data as dataframe
#'                         "patches", # Patch outlines
#'                         "pstats"), # Patch statistics dataframe
#'         # The summary statistics of interest
#'         sum_stats = c("median", "SHDI", "perc_5", "perc_95"))
"flir_stats"