smithPlot: A function to make H. F. Smith plots
In sampSurf: Sampling Surface Simulation for Areal Sampling Methods

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

This function will create so-called “Smith plots” from the simulation results of several objects of class sampSurf. The simulation results should be stored in a named list structure as described below for input to this routine. Please see Smith (1938) for the original study and Gove (2017) for a recent application.

smithPlot(hfs,
          showPlot = TRUE,
          ylab = "Total surface variance",
          xlab = "Average Inclusion Zone Area",
          type = "b",
          pch = 19,
          theme = c("ggplot", "custom", "plain", "economist"),
          cols = c("#00526D", "#00A3DB", "#7A2713", "#939598"),
          ...)

`hfs`	A named list of named lists with the following structure... top = sampling methods; these should be named appropriately, e.g., ‘hps’, ‘chs’, etc. sub = within each sampling method, a list of sampSurf objects, one for each different plot size/baf, etc.; e.g., ‘HPSbaf5’, ‘CHSbaf7’, etc.
`showPlot`	`TRUE`: display the plot; `FALSE`: create and return the plot only.
`ylab`	Label for y-axis – see `par`.
`xlab`	Label for x-axis – see `par`.
`type`	See `par`.
`pch`	See `par`.
`theme`	A theme from the provided list – see latticeExtra ‘styles’ for more information.
`cols`	A vector of alternative colors for the line graphs; `NULL` will use the default theme colors; those listed above are essentially those from the economist theme.
`...`	Passed on to `xyplot`.

A conceptual example setup for the hfs argument as used in the manuscript cited below would be...

$hps
[1] “HPSbaf3” “HPSbaf5” “HPSbaf7” “HPSbaf9”
$chs
[1] “CHSbaf3” “CHSbaf5” “CHSbaf7” “CHSbaf9”
$cmc
[1] “CMCbaf3” “CMCbaf5” “CMCbaf7” “CMCbaf9”
$cps
[1] “CPSrad5” “CPSrad6” “CPSrad7” “CPSrad9”

where the “$” names are the ‘top’ list entries, and then each with its own corresponding named ‘sub’ list for that sampling method with the different “sampSurf” objects corresponding to the row names in the respective sublist. Thus there are four sampling methods (top names = ‘hps’,‘chs’,‘cmc’,‘cps’), each with four sets of “sampSurf” simulations named as shown, for a total of 16 “sampSurf” objects in the entire list. Please see the example below for more information.

In general, hfs can be ragged; that is, the sublists do not need to be all the same length. Therefore some sampling methods may have fewer simulation results than others.

A list is returned invisibly with...

`df`	The data frame that was used to create the figure.
`plt`	The lattice (class “trellis”) plot object for the figure.

Gove (2017) provides a graphical example created from this function corresponding to the example given below. That reference also shows how these plots can be extended for use with the results of a MODWT wavelet analysis. The main idea behind the variance relationship dates back to the seminal study of Smith (1938).

Jeffrey H. Gove

: Gove, J. H. 2017. Some refinements on the comparison of areal sampling methods via simulation. Forests, (Submitted).

: Smith, H. F. 1938. An empirical law describing heterogeneity in the yields of agricultural crops. Journal of Agricultural Science, 28:1–23.

“sampSurf”

#
#  Using smithPlot entails generating several simulations for each sampling
#  method and thus some rather lengthy code--too much so for
#  reproduction here. However, assume that we have several sampSurf
#  simulation objects as follows (see example in Details above)...
#
#  horizontal point sampling:         sshps.3, sshps.5, sshps.7, sshps.9
#  critical height sampling:          sschs.3, sschs.5, sschs.7, sschs.9
#  HPS /w crude Monte Carlo sampling: sscmc.3, sscmc.5, sscmc.7, sscmc.9
#  all with metric bafs 3, 5, 7 and 9.
#
#  Also we have four sampSurf circular plot sampling objects with plot
#  radii 5, 6, 7, and 9m...
#
#  sscps.5, sscps.6, sscps.7, sscps.9 
#
#  Then we can form the input lists required by smithPlot as...
#
## Not run: 
hps = list(HPSbaf3 = sshps.3, HPSbaf5 = sshps.5, HPSbaf7 = sshps.7, HPSbaf9 = sshps.9)
chs = list(CHSbaf3 = sschs.3, CHSbaf5 = sschs.5, CHSbaf7 = sschs.7, CHSbaf9 = sschs.9)
cmc = list(CMCbaf3 = sscmc.3, CMCbaf5 = sscmc.5, CMCbaf7 = sscmc.7, CMCbaf9 = sscmc.9)
cps = list(CPSrad5 = sscps.5, CPSrad6 = sscps.6, CPSrad7 = sscps.7, CPSrad9 = sscps.9)
hfs = list(hps = hps, chs = chs, cmc = cmc, cps = cps)
#
#  Finally, we create the Smith plot using...
#
res = smithPlot(hfs)
names(res)  #show the result object names

## End(Not run)