ffm_param_variance: Randomly perturbs values for selected numeric parameters in a...

View source: R/monte_carlo_functions.R

ffm_param_varianceR Documentation

Randomly perturbs values for selected numeric parameters in a table.

Description

Given an input parameters table, this function adds random noise to specified numeric parameters and returns an updated copy of the table. Noise can be based on a Normal (Gaussian), Beta or Uniform distribution. The maximum absolute perturbation is controlled by the max.prop argument.

Usage

ffm_param_variance(
  tbl,
  max.prop = 0.1,
  labels = c("leafWidth", "leafLength", "leafThickness", "leafSeparation"),
  method = c("normal", "beta", "uniform"),
  beta.a = 2,
  beta.b = 2
)

Arguments

tbl

Input parameter table.

max.prop

The maximum absolute perturbation to apply, expressed as a proportion between 0 and 1.

labels

Labels of the parameters whose values are to be perturbed. It only makes sense to specify parameters with numeric values.

method

Method used to generate perturbations.

normal

Draw perturbations from a Normal distribution, with zero mean and where max.prop corresponds to 3 standard deviations.

beta

Draw random deviates from a modal Beta distribution (ie. beta.a and beta.b both greater than 1) and scale them to accord with max.prop

.

uniform

Draw perturbations from a Uniform distribution

.

beta.a

First shape parameter for the Beta distribution. Ignored if method is not "beta".

beta.b

Second shape parameter for the Beta distribution. Ignored if method is not "beta".

Details

When method = "normal" (the default), random deviates are drawn from a Normal distribution with mean zero and standard deviation equal to x * max.prop / 3 where x is the input parameter value. This results in 99 beyond this range are discarded and re-drawn, effectively rendering the distribution a (slightly) truncated Normal.

When method = "beta", it is possible to generate both symmetric and skewed deviates depending on the values of the distribution parameters beta.a and beta.b. The function constrains the choice of parameters to both be greater than 1.0 so that a mode exists for the distribution, and will issue an error message if this is not the case. Random deviates between 0 and 1 are drawn from the distribution and scaled such that the mode of the distribution corresponds to the input parameter value. For a symmetric distribution (beta.a == beta.b) a deviate of 0 is scaled to -max.prop * x and a deviate of 1 is scaled to max.prop * x, where x is the input parameter value. Skewed Beta distributions (beta.a != beta.b) give correspondingly skewed distributions of perturbations. Random deviates drawn from the distribution are scaled such that those lying on the side of the mode with the longest tail can approach the full range of pertubation, while those lying on the other side have a reduced range.

When method = "uniform", perturbations are uniformly distributed either side of the input parameter value.

Value

A copy of the input parameter table with selected values updated.

Examples

## Not run: 
# Vary leaf traits for all species with Uniform perturbations which are,
# at most, 20% of the input values
tbl.updated <- ffm_param_variance(tbl, max.prop = 0.2, method = "unif")

# Vary ignition temperatures by up to 10% for all species based on Normal 
# perturbations
tbl.updated <- ffm_param_variance(tbl, labels = "ignitionTemp", max.prop=0.1)

# Use with the pipe operator to vary species and site parameters
# separately (requires either the dplyr or maggritr package)

tbl.updated <- tbl %>%
  # vary leaf traits uniformly
  ffm_param_variance(max.prop = 0.2, method = "uniform") %>%
  
  # vary fuel load with a skew
  ffm_param_variance(labels = "fuelLoad", max.prop = 0.5,
                     method = "beta", beta.a = 2, beta.b = 5)

## End(Not run)


pzylstra/frame_r documentation built on Nov. 12, 2023, 1:55 a.m.