getProxy: Proxy functions for Monte Carlo sampling methods in...

Description Usage Arguments Details Value Author(s) References See Also Examples

View source: R/MonteCarloProxy.R

Description

These functions encapsulate the proxy capabilities under Monte Carlo sampling within "Stem" subclass objects for the estimation of volume.

Usage

1
2
3
4
5
6
7
8
getProxy(proxy = c("cmcProxy", "gvProxy", "wbProxy"), ...) 

cmcProxy(stem, u.s, segBnds, ...)

gvProxy(stem, u.s, segBnds, ...)

wbProxy(stem, u.s, segBnds, solidTypeProxy = 3, truncateProxyStem = TRUE,
        wbProxySolve = c('uniroot', 'nlminb'), warningsOn = FALSE, ...)

Arguments

proxy

A character argument specifying the name of the proxy function to retrieve.

stem

An object that is a subclass of "Stem", i.e., a "downLog" or "standingTree" object.

u.s

The uniform (0,1) random number vector for Monte Carlo sampling to determine the sampled heights for the respective method.

segBnds

A vector of length two giving the lower and upper height/length bounds for volume estimation within the bole. These bounds correspond to the limits of integration along the bole.

solidTypeProxy

The applicable values for this and what they do depend on whether the default sampSurf taper equation was used to construct the stem object passed. In general, specifying NA will use the exact taper for the stem, so there should be no estimation error. Otherwise, this specifies a value for the shape parameter to be used in the proxy function in the default taper system. Specifying a value between zero and one will yield a proxy stem with shape parameter that is this proportion of the true shape parameter for the stem passed (i.e., a value of 0.9 gives a proxy that is pretty close to the actual stem). If user-defined taper model was used to construct stem, then this this range is not applicable and the default vaule of 3 is used. This has been a very terse explanation of this argument, please consult the vignette refernece below for details on its use.

truncateProxyStem

TRUE enlarge the tip diameter if it is zero so inflation of the estimate is not a concern if cross-sectional areas close to zero are sampled in importance sampling. FALSE the proxy will taper to the tip if the stem passed does. Again, more details are given in the vignette.

wbProxySolve

The two options specify which method is used to numerically solve for the proxy heights. The default should normally be used, the 'nlminb' option is slow.

warningsOn

TRUE: print warnings if necessary; FALSE: runs silently (default).

...

Used to ignore extraneious arguments passed at present.

Details

The first function, getProxy, returns one of the built-in proxy functions from the sampSurf namespace so that it can be used within the respective Monte Carlo sampling method. In the case of a user proxy, it will also look for the proxy within the user's workspace. The function does a number of checks for the minimal format of “proxy” functions that are described in the vignette reference below. Therefore, it will catch problems with arguments and return lists in user-defined proxies. This is necessary to make sure all user-written proxy functions accept and return the standard set of arguments and list components.

The built-in proxy functions are discussed in detail in the vignette. The built-in proxies range from very simple to fairly complex. They include...

cmcProxy: This is the default proxy used for crude Monte Carlo sampling in the crudeMonteCarlo object constructor. It is also used in control variate sampling in the controlVariate constructor for selecting the height/length sample points.

gvProxy: This is a simple proxy that is proportional to cross-sectional area at a given sampled height. It is the default proxy used in importanceSampling and controlVariate (as the proxy cross-sectional area model) methods for creation of their respective objects. Details on its uses and potential concerns are found in the vignette.

wbProxy: This proxy uses the default taper equation in sampSurf. This is a much more complicated proxy than the other two, and can take more arguments. It can be used in both importanceSampling and controlVariate methods for determination of the sample heights and cross-sectional areas. Please see the vignette below for details on this function and its use.

Value

getProxy returns the proxy function. The other functions return a list of the form...

g

The function (closure) that actually determines the cross-sectional area at a given height.

G

The volume integral for the stem segment.

hgt.s

The sampled heights along the bole segment at which g will be evaluated.

Please see the vignette for more details.

Author(s)

Jeffrey H. Gove

References

Gove, J. H. 2013. Monte Carlo sampling methods in sampSurf. Package vignette.

See Also

MonteCarloSampling, crudeMonteCarlo, importanceSampling, controlVariate, antitheticSampling.

Examples

1
2
3
4
5
6
#
# retrieve a built-in proxy and use it...
#
sTree = standingTree(dbh = 40, topDiam = 0, height = 20, solidType = 2.8)
cmcFun = getProxy('cmcProxy')
( cmcFun(sTree, runif(4), c(0, sTree@height)) )

sampSurf documentation built on March 5, 2021, 3:01 p.m.