Package 'LandWebUtils'

Title: Helper functions for the LandWeb project
Description: Additional utilities for LandWeb analyses.
Authors: Eliot J B McIntire [aut] , Alex M Chubaty [aut, cre] , His Majesty the Queen in Right of Canada, as represented by the Minister of Natural Resources Canada [cph]
Maintainer: Alex M Chubaty <[email protected]>
License: GPL-3
Version: 1.0.2
Built: 2024-12-25 06:31:10 UTC
Source: https://github.com/PredictiveEcology/LandWebUtils

Help Index

Clean up the LandWeb study area from David Andison

Description

Clean up the LandWeb study area from David Andison

Usage

.cleanLandWebStudyArea(poly, minFRI = 40)

Arguments

poly

A polygon or character string identifying the path to polygon
minFRI

Numeric or integer, indicating the minimum fire return interval that will be part of the cleanup of polygon. Anything below this will be NA.

Simulation timesteps for analyses

Description

Simulation timesteps for analyses

Usage

analysesOutputsTimes(period, interval)

Arguments

period

numeric vector of length 2 corresponding to the start and end times to use for analyses.
interval

numeric indicating the interval between timesteps for analyses

Value

numeric vector of timesteps for which to run analyses

CASFRItoSpRasts

Description

TODO: description and title needed

Usage

CASFRItoSpRasts(
  CASFRIRas,
  CASFRIattrLong,
  CASFRIdt,
  sppEquiv,
  sppEquivCol,
  destinationPath
)

Arguments

CASFRIRas

TODO: description needed
CASFRIattrLong

TODO: description needed
CASFRIdt

TODO: description needed
sppEquiv

table with species name equivalencies between the kNN and final naming formats. See data("sppEquivalencies_CA", "LandR"). For functions that have mixedType e.g., vegTypeMapGenerator, this only necessary if mixedType == 2. If not provided and mixedType == 2, will attempt to use data("sppEquivalencies_CA", "LandR").
sppEquivCol

the column name to use from sppEquiv. For functions that have mixedType e.g., vegTypeMapGenerator, Only necessary if mixedType == 2. If not provided and mixedType == 2, will attempt to use "Boreal".
destinationPath

path to data directory where objects will be downloaded or saved to

Value

TODO: description needed

Extract study area name from run name

Description

Extract study area name from run name

Usage

cleanAreaName(area)

Arguments

area

Simulated area (i.e., run) name

Find LandWeb simulation output file

Description

Find LandWeb simulation output file

Usage

findSimFile(outputDir, rep)

Arguments

outputDir

path to LandWeb output directory.
rep

integer giving the replicate id, or character string in the form of "rep01".

Value

path to the file

Core Burn function for Andison's LandMine Fire Module

Description

The main function for the Andison Fire Module. See details.

Usage

landmine_burn1(
  landscape,
  startCells,
  fireSizes = 5,
  nActiveCells1 = c(10, 36),
  spawnNewActive = c(0.46, 0.2, 0.26, 0.11),
  maxRetriesPerID = 10L,
  sizeCutoffs = c(8000, 20000),
  spreadProbRel = NA_real_,
  spreadProb = 0.77,
  omitPixels = NULL
)

landmine_burn(
  landscape,
  startCells,
  fireSizes = 5,
  nActiveCells1 = c(10, 36),
  spawnNewActive = c(0.46, 0.2, 0.26, 0.11),
  sizeCutoffs = c(8000, 20000),
  spreadProbRel = 0.23
)

Arguments

landscape

A RasterLayer. This only provides the extent and resolution for the fire spread algorithm.
startCells

A numeric vector indicating the indices on the landscape where the fires will start with 100%% certainty.
fireSizes

A numeric vector indicating the final size of each of the fires. Must be same length as startCells.
nActiveCells1

A numeric vector of length 2. These are cutoffs above and below each of which different values of spawnNewActive are used. See details.
spawnNewActive

A numeric vector of length 4. These are the probabilities of creating spreading to 2 neighbours instead of the 1 default neighbour, each time step. The 4 values are for 4 different fire size conditions. See details.
maxRetriesPerID

Integer. Maximum number of retry attempts per firelet ID.
sizeCutoffs

A numeric vector of length 2. These are 2 size (in hectares) thresholds that affect which spawnNewActive probabilities are used. See details.
spreadProbRel

A raster layer of of relative probabilities, with non-flammable pixels NA.
spreadProb

A raster layer of spread probabilities, with non-flammable pixels NA.
omitPixels

An optional vector of pixel IDs to omit from fire size calculations. Can be used if spreadProb or spreadProbRel do not designate non-flammable pixels as NA, to allow fires to move through these pixels, while excluding these pixels from burn area calculations. Useful in study areas with discontinuous fuels, which would otherwise result in fires getting 'stuck' too often, and not reach their target size.

Details

This algorithm is a modified contagious cellular automaton.

Value

A data.table with 4 columns (initialPixels, pixels, state, order).

Algorithm

Core

Each fire starts at a single pixel, startCells and will spread, i.e., visit and convert from a 0 to the fire id number. It will iteratively spread until the number of cells visited is equal to floor(fireSizes).

Adjustments due to current fire size and number of active pixels

That can vary too, but it gets a bit complicated, so use that for now. Spawning probability was originally set at 13%, but created problems with very large and very small fires, so over time has been adjusted to vary depending on: a) number of active "firelets" (NF); and b) fire size (FS), such that: 

  - If 10 <= NF < 36 and FS < 20,000 ha then P = 20%;
  - If NF > 36 and FS < 8,000 ha, P = 11%;
  - If NF < 36 and FS > 20,000 ha, P = 26%;
  - If NF < 10 then P = 46%;

These rule create more heterogeneity in the pattern of burning.

Fire jumping

If the fire has not reached its target size, it will try to pick new neighbours among the 8 immediate neighbours up to 4 times. If it still did not find enough neighbours, then it will jump or "spot" up to 4 pixels away. It will then repeat the previous 2 stages again once (i.e., 4 neighbours, 1 jump, repeat), then it will stop, unable to achieve the desired fireSize.

Note

The original version (landmine_burn()) is deprecated and should not be used. Use landmine_burn1() instead.

LandMine burn optimization function

Description

LandMine burn optimization function

Usage

landmine_optim_burnFun(
  ros,
  centreCell,
  fireSize,
  spawnNewActive,
  sizeCutoffs,
  spreadProb
)

Arguments

ros

RasterLayer of LandMine Raster Of Spread values
centreCell

TODO
fireSize

TODO
spawnNewActive

TODO
sizeCutoffs

TODO
spreadProb

TODO

Value

named list of length 2 containing: burnedMap: rasterLayer of burned pixels; LM: data.frame of patch statistics from SDMTools::PatchStats().

Export objects used for optimization and load packages on cluster

Description

Export objects used for optimization and load packages on cluster

Usage

landmine_optim_clusterExport(cl = NULL, objs = NULL, pkgs = NULL)

Arguments

cl

a cluster object or NULL
objs

character vector of names of objects to export
pkgs

character vector of packages to pre-load on the cluster nodes

Value

NULL. Invoked for its side effects.

Setup a cluster for LandMine optimization

Description

Setup a cluster for LandMine optimization

Usage

landmine_optim_clusterSetup(nodes = NULL)

Arguments

nodes

positive integer of length 1 specifying the number of threads to use on the current machine (localhost), or a character vector of hostnames on which to run worker copies.

Value

a cluster objct

Wrapper function to setup cluster, export objects and load packages

Description

Wrapper function to setup cluster, export objects and load packages

Usage

landmine_optim_clusterWrap(cl = NULL, nodes, reps, objs, pkgs)

Arguments

cl

a cluster object or NULL
nodes

positive integer of length 1 specifying the number of threads to use on the current machine (localhost), or a character vector of hostnames on which to run worker copies.
reps

integer. number of replicates to run.
objs

character vector of names of objects to export
pkgs

character vector of packages to pre-load on the cluster nodes

Value

named list of length 2 containing: cl - a cluster object; out - a list of burn maps (aka burnMapList)

LandMine objective functions

Description

landmine_fitSN() is used for the module.

Usage

landmine_optim_fitSN(
  sna,
  ros,
  centreCell,
  fireSizes = 10^(2:5),
  desiredPerimeterArea = 0.004
)

landmine_optim_fitSN2(
  par,
  ros,
  centreCell,
  fireSizes = 10^(2:5),
  desiredPerimeterArea = 0.003,
  spreadProb = 0.9
)

Arguments

sna

TODO
ros

TODO
centreCell

TODO
fireSizes

TODO
desiredPerimeterArea

TODO
par

parameter vector of length 5
spreadProb

spread probability

Details

landmine_fitSN2() is an alternative version tries the optimization using fewer parameters, to test whether a simpler version gets better/different results. Although this version was not used for the final module, we preserve it here for posterity.

Value

data.table (TODO)

LandMine diagnostic plots

Description

  • landmine_plot_areaBurnedOverTime() plots the area burned over time by LTHFC polygon;

  • landmine_plot_LTHFC() produces a rasterVis::levelplot() a map of the LTHFC polygons;

  • landmine_plot_FRI() plots

Usage

landmine_plot_areaBurnedOverTime(areaBurnedOverTime)

landmine_plot_LTHFC(lthfc, studyAreaName, ...)

landmine_plot_FRI(friSummary)

Arguments

areaBurnedOverTime

Summary data.frame of area burned over time, containing the following columns: time (numeric) gives the simulation time (year); haBurned (numeric) gives the burned area in hectares; FRI (numeric) identifies the fire return interval polygon.
lthfc

long-term historic fire cycle map (raster).
studyAreaName

study area name (character).
...

additional arguments passed to rasterVis::levelplot().
friSummary

Summary data.frame of simulated fire return intervals (FRI) vs. the long-term historic fire cycles (LTHFC), containing the following columns: simArea (character) gives the study area name; LTHFC (numeric) is the expected (i.e., historic) FRI; FRI (numeric) is the simulated FRI.

Value

a ggplot2 or rasterVis object; invoked for side effect of creating plots.

Calculate proportion of large patches in NRV

Description

TODO: needs description

Usage

LargePatches(
  tsf,
  vtm,
  poly,
  labelColumn,
  id,
  ageClassCutOffs,
  ageClasses,
  sppEquivCol,
  sppEquiv,
  crop2poly = FALSE
)

Arguments

tsf

A single filename, relative or absolute, pointing to a Time Since Fire raster. Can be any format that raster can use.
vtm

A single filename, relative or absolute, pointing to a Vegetation Type Map raster. Can be any format that raster can use.
poly

A single SpatialPolygonsDataFrame object or a factor RasterLayer. This layer MUST have a column labelled shinyLabel
labelColumn

TODO: description needed
id

TODO: description needed
ageClassCutOffs

A numeric vector with the endpoints for the ageClasses. Should be length(ageClasses) + 1. See .ageClassCutOffs.
ageClasses

A character vector with labels for age classes to bin the tsf times, e.g., c("Young", "Immature", "Mature", "Old"). See .ageClasses.
sppEquivCol

Character giving the column name to use in sppEquiv.
sppEquiv

Species equivalency table, e.g., derived from LandR::sppEquivalencies_CA.
crop2poly

logical indicating whether to crop/mask vtm and tsf rasters to poly. Default FALSE for backwards compatibility.

Calculate proportion of landscape occupied by each vegetation class

Description

This function is recursive. If poly is a SpatialPolygon, then the function will enter once, and convert this to a fasterized version, and pass that into the function replacing poly. It is also recursive of passed a vector of filenames for tsf and vtm.

Usage

LeadingVegTypeByAgeClass(
  tsf,
  vtm,
  poly,
  ageClassCutOffs,
  ageClasses,
  sppEquivCol,
  sppEquiv
)

Arguments

tsf

A single filename, relative or absolute, pointing to a Time Since Fire raster. Can be any format that raster can use.
vtm

A single filename, relative or absolute, pointing to a Vegetation Type Map raster. Can be any format that raster can use.
poly

A single SpatialPolygonsDataFrame object or a factor RasterLayer. This layer MUST have a column labelled shinyLabel
ageClassCutOffs

A numeric vector with the endpoints for the ageClasses. Should be length(ageClasses) + 1. See .ageClassCutOffs.
ageClasses

A character vector with labels for age classes to bin the tsf times, e.g., c("Young", "Immature", "Mature", "Old"). See .ageClasses.
sppEquivCol

Character giving the column name to use in sppEquiv.
sppEquiv

Species equivalency table, e.g., derived from LandR::sppEquivalencies_CA.

Value

A data.table with proportion of the pixels in each vegetation class, for each given age class within each polygon.

Load CASFRI data for LandWeb

Description

TODO: description needed

Usage

loadCASFRI(
  CASFRIRas,
  attrFile,
  headerFile,
  sppEquiv,
  sppEquivCol,
  type = c("cover", "age")
)

Arguments

CASFRIRas

TODO: description needed
attrFile

TODO: description needed
headerFile

TODO: description needed
sppEquiv

table with species name equivalencies between the kNN and final naming formats. See data("sppEquivalencies_CA", "LandR"). For functions that have mixedType e.g., vegTypeMapGenerator, this only necessary if mixedType == 2. If not provided and mixedType == 2, will attempt to use data("sppEquivalencies_CA", "LandR").
sppEquivCol

the column name to use from sppEquiv. For functions that have mixedType e.g., vegTypeMapGenerator, Only necessary if mixedType == 2. If not provided and mixedType == 2, will attempt to use "Boreal".
type

Character string. Either "cover" or "age".

Value

TODO: description needed

Calculate the mean of a truncated Pareto distribution

Description

Calculate the mean of a truncated Pareto distribution

Usage

meanTruncPareto(k, lower, upper, alpha)

Arguments

k

TODO: description needed
lower

TODO: description needed
upper

TODO: description needed
alpha

TODO: description needed

Value

TODO: description needed

Do an arbitrary set of operations on a polygon

Description

Do an arbitrary set of operations on a polygon

Usage

polygonClean(poly, fn = NULL, type = NULL, ...)

Arguments

poly

A polygon object, or a character string identifying the shapefile path to load, and clean.
fn

A function identifying the type of cleaning to do.
type

If fn is not known, an character string can be specified to identify which fn to use. This MUST be a known type for this function.
...

Passed to fn

Prepare species layers from CASFRI v4

Description

Prepare species layers from CASFRI v4

Usage

prepSpeciesLayers_CASFRI(
  destinationPath,
  outputPath,
  url = NULL,
  studyArea,
  rasterToMatch,
  sppEquiv,
  sppEquivCol,
  ...
)

Arguments

destinationPath

path to data directory where objects will be downloaded or saved to
outputPath

TODO: description needed
url

if NULL, the default, use the default source url
studyArea

A ⁠SpatialPolygons*⁠ object used as the principle study region, passed to reproducible::prepInputs().
rasterToMatch

A RasterLayer objects to use as the template for all subsequent raster operations (i.e., the one used throughout the simulation).
sppEquiv

table with species name equivalencies between the kNN and final naming formats. See data("sppEquivalencies_CA", "LandR"). For functions that have mixedType, this only necessary if mixedType == 2. If not provided and mixedType == 2, will attempt to use data("sppEquivalencies_CA", "LandR").
sppEquivCol

the column name to use from sppEquiv. For functions that have mixedType, only necessary if mixedType == 2. If not provided and mixedType == 2, will attempt to use "Boreal".
...

other arguments, used for compatibility with other prepSpeciesLayers functions.

Create a list of rasters in each rep, at each timestep, for each polygon area

Description

Create a list of rasters in each rep, at each timestep, for each polygon area

Usage

rasterListByPoly(files, polys, names, col, filter)

Arguments

files

character vector giving paths to raster files
polys

polygon object of class sf
names

character vector giving the names of each of the subpolygons in poly
col

character string giving the column name in poly to use
filter

regex string giving partial filename in files to be filtered out (i.e., when extracting reps, times, etc. from filenames) (e.g., 'rstTimeSinceFire_', 'vegTypeMap_')

Value

list of RasterLayer objects with attributes reps, times, polyNames

Note

uses future_lapply internally to loop across files; set e.g., option future.availableCores.fallback appropriately for your system.

Generate box and whisker plots for leading vegetation cover

Description

TODO: description needed

Usage

runBoxPlotsVegCover(map, functionName, analysisGroups, dPath)

Arguments

map

A map object.
functionName

TODO: description needed
analysisGroups

TODO: description needed
dPath

Destination path for the resulting PNG files.

Generate histograms for large patches

Description

TODO: description needed

Usage

runHistsLargePatches(map, functionName, analysisGroups, dPath)

Arguments

map

A map object.
functionName

TODO: description needed
analysisGroups

TODO: description needed
dPath

Destination path for the resulting PNG files.

Generate histograms for leading vegetation cover

Description

TODO: description needed

Usage

runHistsVegCover(map, functionName, analysisGroups, dPath)

Arguments

map

A map object.
functionName

TODO: description needed
analysisGroups

TODO: description needed
dPath

Destination path for the resulting PNG files.