sampSurf-package: Sampling Surface Simulation
In sampSurf: Sampling Surface Simulation for Areal Sampling Methods
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.,...
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.
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...
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/.
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, 5:06 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
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.,...
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.
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...
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/.
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.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
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.