R/fhProcess.R

In nevilamos/FAMEFMR: Functions For DELWP FAME Fire Analysis

#' Wrapper for main fhProcessing
#'
#' @details The function takes a shapefile or  geopackage layer of Fire history
#'   containing polygons with two fields: FIRETYPE and SEASON Where polygons of
#'   different FIRETYPE or SEASON overlap the function constructs unique
#'   non-overlapping polygon of their intersections ( and non intersecting areas
#'   ) and attributes each polygon with sequential fire SEASON (SEAS01, SEAS02
#'   ...) and corresponding FIRETYPE (TYPE01,TYPE02 ...)
#' @details It then calculates all the intervals between sequential fires, and
#'   Time Since fire (TSF) and Last Fire Type (LFT) and Last burnt year (LBY)
#'   for each SEASON as defined in the input arguments, these values are append
#'   to the output sf polygon dataframe.
#' @param rawFH path to the input fire history geodatabase (".gdb" or ".gpkg")
#'   or shapefile (".shp") usually  provided in settings
#' @param rawFHLayer if rawFH is a geodatabase the name of the layer containing
#'   the Fire History if this is not provided and the raw FH is a geodatabase or
#'   geopackage then the first layer in the file is returned.
#' @param start.SEASON integer First SEASON for which output is wanted (four
#'   digit year as integer), if NUll then second season in in history is used
#'   (cannot use first season because it has no interval, this may still fail if
#'   there is no overlap)
#'
#' @param end.SEASON  integer Last SEASON required, if NULL then largest value
#'   in fire history scenario used
#'
#' @param OtherAndUnknown integer Value to use for cases where fire type is:
#'   "OTHER" or "UNKNOWN" = NA, "BURN" = 1, "BUSHFIRE" = 2. NA = Fire excluded
#'   from analysis. usually set in settings file
#'
#' @param validFIRETYPE character vector of valid FIRETYPE values for checking
#'   the input file , provided in settings file.
#' @param inFHLayer Layer name if inFH has more than one layer
#' ( for instance in a .gpkg) this allows selection of a particular layer,
#' otherwise fist layer is used (Default = NULL)
#' @param secondFH Second fire history to be combined with FH1 to make a fire
#'  scenario same formats as for inFH
#' @param max_interval = NULL #integer number of years  maximum inter fire interval after a HIGH fir for
#'  which subsequent fire is reassigned to HIGH default is NULL in which case there
#'  is no reassignement
#'  @param baseFire Default NULL otherwise four digit integer SEASON for fire applied across the whole bounding box
#'
#' @return A list containing: \itemize{
#' \item OutDF sf polygons dataframe containing all the fire history attributes
#' \item TimeSpan integer vector sequence of SEASONS to in the analysis output
#' \item YSFNames names of TSF years in output, needed by downstream functions
#' \item LBYNames names of LBY years in output, needed by downstream functions
#' \item LFTNames names of LBY years in output, needed by downstream functions }
#'
#' @export
#'
fhProcess<-function(inFH,
                    inFHLayer,
                    secondFH,
                    secondFHLayer,
                    start.SEASON,    # first season for which output is wanted (four digit year as integer), if NUll then second season in in history is used (cannot use first season because it has no interval, this may still fail if there is no overlap)
                    end.SEASON,      # last season required, if NULL then largest value in fire history scenario used
                    OtherAndUnknown, #  Default is 2 ("BUSHFIRE").  (2,1,NA) value to use for cases where fire type is: "OTHER" or "UNKNOWN", "BURN" = 1, "BUSHFIRE" = 2. NA = Fire excluded from analysis.
                    validFIRETYPE,
                    max_interval,
                    baseFire){


  outFH1<-FAMEFMR::fhProcess1(inFH = inFH,inFHLayer,secondFH,secondFHLayer,OtherAndUnknown,baseFire)
  outFH2<-FAMEFMR::fhProcess2(inFH1 = outFH1,
                              #start.SEASON=start.SEASON,
                              #end.SEASON=end.SEASON,
                              #max_interval =max_interval
  )
  return(outFH2)
}