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

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.,...

Fixed area plots, which includes the so-called ‘stand-up,’ ‘sausage,’ and ‘chainsaw’ protocols.

Point relascope sampling (PRS).

Perpendicular distance sampling (PDS) in several forms: Canonical PDS, omnibus PDS, canonical distance limited PDS (DLPDS), omnibus DLPDS, and hybrid DLPDS. Each of these PDS variants can be used with any one of three selection attributes: volume, coverage or surface areas.

Distance limited sampling in two forms: Simple (DLS), and Monte Carlo (DLMCS).

Support for standing trees includes the following methods...

Circular fixed area plots.

Horizontal point (angle gauge) sampling (and tradiational Monte Carlo variants).

Critical height sampling (also a Monte Carlo HPS variant) and importance sampling variants of CHS.

Horizontal line (angle gauge) sampling.

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.

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...

Generate synthetic populations of logs or standing trees as “

`Stem`

” objects. Note that data from field measurements can also be used if available.Construct inclusion zones around each individual in the population and assign attributes to the zone for volume, etc.

Generate “

`Tract`

” objects of given dimension (x,y) and resolution (grid cell size) to hold the objects. The grid cell resolution is related directly to sampling intensity: each grid cell center can be thought of as a sample point for the method under consideration.Combine the above into a sampling surface and calculate summary statistics, or display visually.

Simulate multiple realizations of the same method with differing populations of objects to get more general results over many “plots” (i.e., “Tract” objects). (This is not implemented yet.)

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/.

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.

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 |

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 |

`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.

`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.

`mcsContainer` | A collection of
"`MonteCarloSampling` " objects |

`antitheticContainer` | A collection of
"`antitheticSampling` " objects |

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 |

`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 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 |

`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 |

`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.

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...

`downLog` | Constructor for individual "downLog" objects |

`standingTree` | Constructor for individual "standingTree" objects |

`downLogs` | Constructs a container object holding multiple "downLog" objects |

`standingTrees` | Constructs a container object holding multiple "standingTree" objects |

`Tract` | Constructor for "Tract" objects |

`bufferedTract` | Constructs a "bufferedTract" object |

`mirageTract` | Constructs a "mirageTract" object |

`crudeMonteCarlo` | Apply Crude Monte Carlo sampling |

`importanceSampling` | Apply importance subsampling |

`controlVariate` | Apply control variate sampling |

`antitheticSampling` | Apply antithetic sampling to any of the above |

`mcsContainer` | A collection of
"`MonteCarloSampling` " objects |

`antitheticContainer` | A collection of
"`antitheticSampling` " objects |

`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 |

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 |

`downLogIZs` | Creates a collection of "downLogIZ" objects for down logs |

`standingTreeIZs` | Creates a collection of "standingTreeIZ" objects for standing trees |

`izGrid` | Creates an "InclusionZoneGrid" or subclass object (i.e., "csFullInclusionZoneGrid") |

`izGridMirage` | Creates an "mirageInclusionZoneGrid" object. |

`sampSurf` | Constructor for "sampSurf" objects |

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. |

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 |

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.

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. |

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. |

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". |

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.

Jeffrey H. Gove

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.

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.

Embedding an R snippet on your website

Add the following code to your website.

For more information on customizing the embed code, read Embedding Snippets.