sampSurf-package: Sampling Surface Simulation

Description Details Classes For Use In sampSurf... Object Constructors Summary and plotting methods Helper methods Coercion methods Miscellaneous methods ‘sampSurf’ environments ‘sampSurf’ class unions “monte”: When is n Sufficiently Large? Author(s) References See Also

Description

The sampSurf package can be used to construct sampling surface simulations for different areal sampling methods common to forestry and ecology. These would include fixed-area plot methods, line intersect sampling, and various variable-radius plot sampling methods, the latter more commonly used in forestry. Most of these fall under the general probability proportional to size (PPS) umbrella and have some form of inclusion zone associated with each individual in the population. The inclusion zone has well-defined area (sometimes called the inclusion area) and may be thought of simply as that zone within which a sample point could fall and select the associated individual. The sample point can be the center of a circular fixed-area plot, an actual point as in horizontal point sampling, or say, the midpoint of a line in line intersect sampling.

In general we are interested in determining the properties of various sampling methods mentioned above when applied to fixed objects such as standing trees or down logs. The sampSurf package will allow generation of log or tree populations within a fixed tract area. The surface generated from the intersection of inclusion zones applied to the individuals in the population for a given attribute (e.g., cubic volume, number of individuals, etc.) are represented by the "sampSurf" class and can be displayed graphically. Estimator variance is directly associated with the sampling surface roughness, and so methods can also be compared visually.

sampSurf has support for several methods/protocols for sampling down logs; e.g.,...

Support for standing trees includes the following methods...

Monte Carlo subsampling on down logs and standing trees is also available outside of the areal sampling paradigm. In addition, some areal sampling methods have special Monte Carlo variants, but the tradiational Monte Carlo subsampling framework now in place on stem objects means that these methods can be applied in conjunction with virtually any areal method. Horizontal point sampling is an example where both special and traditional Monte Carlo methods are available in the package.

Boundary (slopover) correction is available either through buffering, or the mirage method at present. The the kind of “Tract” that is used in the simulations will define which correction is desired.

The class structure is designed to support additions with relative ease, so more methods will appear in future releases.

Details

Package: sampSurf
Type: Package
Version: 0.7-6
Date: 4-Mar-2021
License: GPL
LazyLoad: yes

The package is written in S4 and has a number of classes and constructors, as well as some helper functions. In general, the capabilities include the following...

Please note that there are several vignettes included within the package that explain in detail the classes and methods listed below using many examples. Please refer to the “Overview” vignette to get started. Then perhaps refer to the other vignettes in the order presented in the overview for detailed examples and descriptions. To find the vignettes on your help system, go to the index for the sampSurf package (see the link at the bottom of this page). The help files linked to below explain the various classes and methods in more detail, including slot and argument definitions.

In addition, the project homepage at R-Forge has some simple examples that might be helpful: http://sampsurf.r-forge.r-project.org/.

A companion package, ssWavelets, that supports wavelet filtering of sampling surfaces is found at: http://sswavelets.r-forge.r-project.org/.

Classes For Use In sampSurf...

The following S4 classes are defined within the sampSurf package to facilitate sampling surface generation. Note that it is not necessary to work with the class structures directly if all you want to do is generate a sampling surface for a population of synthetic logs or trees. However, some familiarization with the basic class structure is helpful in order to understand how the pieces fit together into a final sampling surface. Again, the vignettes are a source of much information.

The “Stem” class...

Objects of the non-virtual classes below can be created using constructor functions of the same name, see the Object Constructors section for details.

Stem Virtual base class for the following
downLog A class for down logs
standingTree A class for standing trees

The “StemContainer” class...

Container classes hold collections of individual “Stem” subclass objects of the corresponding name...

StemContainer Virtual base class for the following
downLogs Container class for a population of down log objects
standingTrees Container class for a population of standing tree objects

The “Tract” class...

Tract Land area holding the population of individuals
bufferedTract A "Tract" subclass with a buffer
mirageTract A "Tract" subclass with for the mirage method

The above classes are derived from the Raster class in the raster package. They conform to a rectangular area of ground such as a plot or any tract of land, tessellated into grid cells.

The “MonteCarloSampling” class...

MonteCarloSampling Virtual base class for Monte Carlo sampling
crudeMonteCarlo Crude Monte Carlo sampling
importanceSampling Importance subsampling
controlVariate Control variate sampling
antitheticSampling Antithetic sampling applied to any of the above

The above classes allow one to use the Monte Carlo methods mentioned to sample from individual "Stem" subclass objects. With these stand-alone classes, there is no areal context, sampling is done within individual stems.

Associated Container classes...
mcsContainer A collection of "MonteCarloSampling" objects
antitheticContainer A collection of "antitheticSampling" objects

The “ArealSampling” class...

These classes define the different sampling methods available and provide the method-based information for the subsequent construction of inclusion zones...

ArealSampling A class structure for describing areal sampling methods
circularPlot A subclass of "ArealSampling" for circular plot construction
pointRelascope A subclass of "ArealSampling" for point relascope sampling
perpendicularDistance A subclass of "ArealSampling" for variants of perpendicular distance sampling
distanceLimited A subclass of "ArealSampling" for distance limited sampling
angleGauge A subclass of "ArealSampling" for angle gauge (e.g., prism) sampling
lineSegment A subclass of "ArealSampling" for line-oriented sampling methods

The “InclusionZone” class...

InclusionZone Virtual base class for combining the sampling method with the individual down log or tree objects.
Classes for down logs...
downLogIZ Virtual subclass for all down log InclusionZone objects.
standUpIZ Class for the "standup" method of sampling down logs.
sausageIZ Class for the "sausage" method of sampling down logs.
chainSawIZ Class for the "chainsaw" method of sampling down logs.
fullChainSawIZ Class for the full "chainsaw" method of sampling down logs.
pointRelascopeIZ Class for the point relascope method of sampling down logs.
perpendicularDistanceIZ Class for the perpendicular distance method of sampling down logs.
omnibusPDSIZ Class for the omnibus perpendicular distance method of sampling down logs.
distanceLimitedPDSIZ Class for the distance limited perpendicular distance method of sampling down logs.
omnibusDLPDSIZ Class for the omnibus distance limited perpendicular distance method of sampling down logs.
hybridDLPDSIZ Class for the "hybrid" distance limited perpendicular distance method of sampling down logs.
distanceLimitedIZ Class for the distance limited method of sampling down logs.
distanceLimitedMCIZ Class for the distance limited Monte Carlo method of sampling down logs.
Classes for standing trees...
standingTreeIZ Virtual subclass for all standing tree InclusionZone objects.
circularPlotIZ Class for the sampling standing trees using circulat plots.
horizontalPointIZ Class for horizontal point sampling of standing trees.
horizontalPointCMCIZ Class for crude Monte Carlo subsampling within horizontal point sampling of standing trees.
horizontalPointISIZ Class for importance subsampling within horizontal point sampling of standing trees.
horizontalPointCVIZ Class for control variate subsampling within horizontal point sampling of standing trees.
criticalHeightIZ Class for critical height sampling of standing trees.
importanceCHSIZ Class for importance critical height sampling of standing trees.
antitheticICHSIZ Class for antithetic importance critical height sampling of standing trees.
pairedAICHSIZ Class for paired antithetic importance critical height sampling of standing trees.
horizontalLineIZ Class for horizontal line sampling of standing trees.
other...
MonteCarloSamplingIZ This class allows combining Monte Carlo with areal methods.

The “izContainer” class...

The following are container classes that hold collections of objects of the corresponding type for inclusion zones generated based on down logs or standing trees and the desired sampling methods. Each holds a collection of objects that are a subclass of “downLogIZ” or “standingTreeIZ”, respectively.

izContainer Virtual base class for the following
downLogIZs Holds inclusion zone objects associated with down logs
standingTreeIZs Holds inclusion zone objects associated with standing trees

The “InclusionZoneGrid” class...

InclusionZoneGrid Not for general use, see documentation for details
csFullInclusionZoneGrid Not for general use, see documentation for details
mirageInclusionZoneGrid Not for general use, see documentation for details

The “sampSurf” class...

sampSurf The class structure for the final sampling surface simulation

Again, many of these classes will only be of interest to someone wanting to do special simulations or for someone who wants to add extensions–for example, new sampling methods.

Object Constructors

For each of the classes defined in the table above, we must be able to create objects that can be used in R. This is done using class-specific "constructor" methods that take the drudgery away from creating what can often be somewhat complicated (with all the graphical components) new object instances. There may be more than one constructor for a given class of object, and these are differentiated by the method signature; see the links provided below for more details...

“Stem” class constructors...

downLog Constructor for individual "downLog" objects
standingTree Constructor for individual "standingTree" objects

The “StemContainer” class...

downLogs Constructs a container object holding multiple "downLog" objects
standingTrees Constructs a container object holding multiple "standingTree" objects

“Tract” class constructors...

Tract Constructor for "Tract" objects
bufferedTract Constructs a "bufferedTract" object
mirageTract Constructs a "mirageTract" object

The “MonteCarloSampling” class constructors...

crudeMonteCarlo Apply Crude Monte Carlo sampling
importanceSampling Apply importance subsampling
controlVariate Apply control variate sampling
antitheticSampling Apply antithetic sampling to any of the above
Associated Container class constructors...
mcsContainer A collection of "MonteCarloSampling" objects
antitheticContainer A collection of "antitheticSampling" objects

“ArealSampling” class constructors...

circularPlot Constructs a circular plot object
pointRelascope Constructs a point relascope object
perpendicularDistance Constructs a perpendicular distance object
distanceLimited Constructs a distance limited object
angleGauge Constructs an angle gauge object
lineSegment Constructs a line segment object

“InclusionZone” class constructors...

Classes for down logs...
standUpIZ Creates an "InclusionZone" object for the 'stand-up' sampling method
sausageIZ Creates an "InclusionZone" object for the 'sausage' sampling method
chainSawIZ Creates an "InclusionZone" object for the 'chainsaw' sampling method
fullChainSawIZ Creates an "InclusionZone" object for the full 'chainsaw' sampling method
pointRelascopeIZ Creates an "InclusionZone" object for the 'point relascope' sampling method
perpendicularDistanceIZ Creates an "InclusionZone" object for the 'perpendicular distance' sampling method
omnibusPDSIZ Creates an "InclusionZone" object for the 'omnibus perpendicular distance' sampling method
distanceLimitedPDSIZ Creates an "InclusionZone" object for the 'distance limited perpendicular distance' sampling method
omnibusDLPDSIZ Creates an "InclusionZone" object for the 'omnibus distance limited perpendicular distance' sampling method
hybridDLPDSIZ Creates an "InclusionZone" object for the 'hybrid distance limited perpendicular distance' sampling method
distanceLimitedIZ Creates an "InclusionZone" object for the 'distance limited' sampling method
distanceLimitedMCIZ Creates an "InclusionZone" object for the 'distance limited Monte Carlo' sampling method
Classes for standing trees...
circularPlotIZ Creates an "InclusionZone" object for the fixed-area circular plot sampling method
horizontalPointIZ Creates an "InclusionZone" object for the horizontal point (prism) sampling method
horizontalPointCMCIZ Creates an "InclusionZone" object for HPS with crude Monte Carlo subsampling
horizontalPointISIZ Creates an "InclusionZone" object for HPS with importance subsampling
horizontalPointCVIZ Creates an "InclusionZone" object for HPS with control variate subsampling
criticalHeightIZ Creates an "InclusionZone" object for the critical height (CH) sampling method
importanceCHSIZ Creates an "InclusionZone" object for the importance critical height sampling method
antitheticICHSIZ Creates an "InclusionZone" object for the antithetic importance CH sampling method
pairedAICHSIZ Creates an "InclusionZone" object for the paired antithetic importance CH sampling method
horizontalLineIZ Creates an "InclusionZone" object for the horizontal line sampling method

The “izContainer” class constructors...

downLogIZs Creates a collection of "downLogIZ" objects for down logs
standingTreeIZs Creates a collection of "standingTreeIZ" objects for standing trees

“InclusionZoneGrid” class constructors...

izGrid Creates an "InclusionZoneGrid" or subclass object (i.e., "csFullInclusionZoneGrid")
izGridMirage Creates an "mirageInclusionZoneGrid" object.

“sampSurf” class constructors...

sampSurf Constructor for "sampSurf" objects

Summary and plotting methods

Almost without exception, the objects created above have graphical content made possible by using classes from the sp or raster packages. Therefore, methods have been added to the plot generics to allow for graphical display of objects. In addition, summary and show methods are also available (sometimes producing the same result) for printing information within the object...

hist Create a histogram of object attributes
plot To plot one of the package objects
plot3D To plot "sampSurf" objects using package 'rgl'
show To succinctly print one of the package objects
summary To summarize one of the package objects
smithPlot Generate H. F. Smith plots for simulation comparisions.

Helper methods

Slots in S4 objects can be accessed directly using slot method or the @ operator. However, some "helper" functions have been provided for certain objects, along with other potentially useful routines...

area Returns the area of a spatial object
bbox Return the bounding box for a spatial object
bboxCheck Check for a valid bounding box for a spatial object
bboxToPoly Convert a bbox matrix to a "SpatialPolygons" object
bboxSum Calculate an overall bbox from and array of bbox matrices
getID Returns the IDs associated with objects
getProxy Return the desired proxy function for MC sampling
perimeter Returns the perimeter of a spatial object, which can then be plotted
spCircle Returns a circular "SpatialPolygons" object

Coercion methods

Object coercion is accomplished in S4 by a call to as with the appropriate object and class to which one wants to convert...

as Convert from a "downLogs" or "standingTrees" object to a data frame
as Convert "downLogIZs" or "standingTreeIZs" object to respective "StemContainer"

The resulting data frame in the first method will be compatible with those generated from calls to either “sampleLogs” or “sampleTrees”. The second takes the drudgery out of getting a log collection from, say, the izContainer slot of a sampSurf object.

Miscellaneous methods

Some methods that might be useful as stand-alone routines...

boltDimensions Calculates segment volumes, surface area, etc.
checkStemDimensions Checks for inconsistencies in attribute slots.
clipStemsToTract Clips or removes stems outside the tract
gridCellEnhance Draws grid lines and centers.
heapIZ Used to heap inclusion zone grids into a sampling surface.
initRandomSeed Initialize .Random.seed.
sampleLogs Draws a simulated sample of down logs and returns a data frame.
sampleTrees Draws a simulated sample of standing trees and returns a data frame.
segmentVolume Calculates segment volumes for down logs or standing trees.
taperInterpolate Interpolates diameters or lengths within down logs or standing trees.
transparentColorBase Transparancy in base graphics.

‘sampSurf’ environments

This package uses a “hidden” environment to keep things that are not necessary for the user out of mind. There is little reason to peak into it, except that some function argument defaults are specified directly via this environment. Thus, to enable you to figure out better what is going on, the environment is exported and its members can be accessed if desired.

.StemEnv This environment holds parameters for much of the package.

‘sampSurf’ class unions

There are a few class unions that are documented here only for the sake of completeness. It is unlikely that the casual user would ever need to be concerned about these.

dlsIZNull Accepts either class "distanceLimitedIZ" (or subclass) or "NULL".
dlsNumeric Accepts either class "distanceLimited" or "numeric".
monteBSSampleOrNULL Accepts either class "monteBSSample" or "NULL".
monteNTSampleOrNULL Accepts either class "monteNTSample" or "NULL".
numericNULL Accepts either class "numeric" or "NULL".
pdsIZNull Accepts either class "perpendicularDistanceIZ" (or subclass) or "NULL".
horizontalPointMonteCarloSamplingIZ Accepts any of the MC and horizontal point sampling combinations.
SPNULL Accepts either class "SpatialPolygons" or "NULL".
RLNULL Accepts either class "RasterLayer" or "NULL".
izgNULL Accepts either class "InclusionZoneGrid" or "NULL".

“monte”: When is n Sufficiently Large?

This section has both classes and methods defined for doing Monte Carlo analysis of the convergence of confidence interval catch rates as sample size increases.

montePop Population class with constructor montePop.
monteSample Virtual repeated sampling class with the following two subclasses.
monteNTSample Normal theory repeated sampling class with constructor monteNTSample.
monteBSSample Bootstrap repeated sampling class with constructor monteBSSample.
monte Main Monte Carlo class with constructor monte.

Please see the ‘“monte”: When is n Sufficiently Large?’ vignette for more details and examples.

Author(s)

Jeffrey H. Gove

References

The first two references describe the sampling surface method in detail. The rest provide some examples of its use, or document some of the methods in the package, and are not exhaustive.

Williams, M. S. 2001. New approach to areal sampling in ecological surveys. Forest Ecology and Management 154:11–22.

Williams, M. S. 2001. Nonuniform random sampling: an alternative method of variance reduction for forest surveys. Canadian Journal of Forest Research 31:2080–2088.

Williams, M. S. and Gove, J. H. 2003. Perpendicular distance sampling: an alternative method for sampling downed coarse woody debris. Canadian Journal of Forest Research 33:1564–1579.

Gove, J. H., Williams, M. S., Stahl, G., and Ducey, M. J. 2005. Critical point relascope sampling for unbiased volume estimation of downed coarse woody debris. Forestry 78:417–431.

Stahl, G., Gove, J. H., Williams, M. S., and Ducey, M. J. 2010. Critical length sampling: a method to estimate the volume of downed coarse woody debris. European Journal of Forest Research 129:993–1000.

Gove, J. H. and Van Deusen, P. C. 2011. On fixed-area plot sampling for downed coarse woody debris. Forestry 84:109–117.

Gove, J. H., Ducey, M. J. and Valentine, H. T. 2012. A distance limited method for sampling downed coarse woody debris. Forest Ecology and Management 282:53–62.

Ducey, M. J., Williams, M. S., Gove, J. H., Roberge, S. and Kenning, R. S. 2013. Distance limited perpendicular distance sampling for coarse woody material: Theory and field results. Forestry 86:119–128

Gove, J. H., Ducey, M. J., Valentine, H. T. and Williams, M. S. 2013. A comprehensive comparison of perpendicular distance sampling methods for sampling down coarse woody debris. Forestry 86:129–143.

Lynch,T. B. and Gove, J. H. 2013. An antithetic variate to facilitate upper-stem height measurements for critical height sampling with importance sampling. Canadian Journal of Forest Research 43:1151–1161.

Lynch,T. B. and Gove, J. H. 2014. The unbiasedness of a generalized mirage boundary correction method for Monte Carlo integration estimators of volume. Canadian Journal of Forest Research 44:810–819.

Gove, J. H. 2017. Some Refinements on the Comparison of Areal Sampling Methods via Simulation. Forests 8,393:1–24.

See Also

The package makes extensive use of existing GIS packages within R. Please see the sp and raster packages for details on the underlying grid and polygon classes and methods.


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