crDistnShiny: Simple Shiny application for the Chapman-Richards...
In Mensuration: Miscellaneous Forest Mensuration Routines

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

This is a simple Shiny application that will display in a webpage. It allows one to explore the range of shapes of the numbers density using sliders to change the parameters of the diameter distribution (i.e., the vital rate parameters) illustrating the results in graphs and tabular output.

crDistnShiny(R = 7,
             M = 0.051,
             recruitRange = c(1, 100),
             mortRange = c(0.001, 0.5),
             m = 0.4,
             gamma = 0.053,
             eta = 0.4,
             mRange = c(-2, 0.78),
             gammaRange = c(0.001, 0.1),
             etaRange = c(0, 1),
             d0 = 1e-08,
             units = c('English', 'metric'),
             returnVar = NA,
             useDT = TRUE,
             maxBA = 200,
             includeTiny = FALSE,
             ...)
crDistnUI(params.run,
          mortRange,
          recruitRange,
          mRange,
          gammaRange,
          etaRange,
          useDT,
          ...
         )
crDistnServer(growth,         #function
              recruitment,    #function
              mortality,      #function
              ssd.cr,         #function
              params.run,
              d0,
              returnVar,
              conv,
              useDT,
              maxBA,
              includeTiny,
              ...
             )

`R`	The initial recruitment rate into the smallest class in terms of numbers.
`M`	The initial per capita mortality rate.
`recruitRange`	The slider range for `R`.
`mortRange`	The slider range for `M`.
`m`	The initial m parameter value for the Chapman-Richards model.
`gamma`	The initial gamma parameter value for the Chapman-Richards model.
`eta`	The initial eta parameter value for the Chapman-Richards model.
`mRange`	The slider range for `m`.
`gammaRange`	The slider range for `gamma`.
`etaRange`	The slider range for `eta`.
`d0`	Lower diameter limit for calculations, this must be slightly larger than zero!
`units`	“English” or “metric” units.
`returnVar`	This is the name of a variable that will hold a list of relevant stand parameters, including the data frame shown in the webpage; it will be created in the user's workspace (global environment). It must be a character string. Use it like a normal assignment from the return of a function when run from the workspace—more details below.
`useDT`	`TRUE`: use the Shiny DataTable for nicer display of the data; `FALSE`: use a normal html table for the table display.
`maxBA`	This is the maximum basal area stocking allowed, before the application shows a warning message.
`includeTiny`	`TRUE`: include all trees down to `d0` diameter; `FALSE`: only include small trees to the lower bound of the first dbh class. When `TRUE`, the routine will remind you that the smallest class is wider than all other classes (except perhaps the largest, depending on the maximum DBH).
`conv`	A list of conversion factors, no need to be concerned about this since you should not call `crDistnServer` directly (see below).
`growth`	A growth function of the form `growth = function(d, params, ...)`, where `d` is diameter and `params` are as in `params.run` below. This argument should not be a concern as `crDistnServer` should only be accessed from `crDistnShiny`.
`mortality`	A mortality function of the form `mortality = function(d, params, ...)`, where `d` is diameter and `params` are as in `params.run` below. This argument should not be a concern as `crDistnServer` should only be accessed from `crDistnShiny`.
`recruitment`	A recruitment function of the form `recruitment = function(d, params, ...)`, where `d` is diameter and `params` are as in `params.run` below. This argument should not be a concern as `crDistnServer` should only be accessed from `crDistnShiny`.
`params.run`	A vector of current CR growth and vital rate parameters.
`ssd.cr`	The Chapman-Richards distribution function. This argument should not be a concern as `crDistnServer` should only be accessed from `crDistnShiny`.
`...`	Passed on.

Running the crDistnShiny function will display the application in your web browser. Its use is self-explanatory, there are several sliders for input that change both the graphs and the tabular output essentially instantaneously. The best thing to do is play with it.

Both crDistnServer and crDistnUI are meant to be called only from crDistnShiny. So please do not run these yourself (I know you will since I said this).

Now, because of the way a Shiny application is structured, there is no way to return a variable in the usual manner through R's return statement when calling a function: Shiny is in control of both the user interface (UI) and the server. Therefore, one has to kludge to get the final result back. In this case, the argument returnVar can be used to capture the tabular results on exit (actually all throughout the application's existence). It always gets saved to the user's workspace, so treat it like any other object with regard to the fact that it will delete any existing object of the same name. (If requested, an environment argument could be added to change where it is saved.)

Please use the “Exit Application” button to stop the application gracefully. Otherwise at the command line type control-c or escape, whatever works on your system.

All of the arguments mentioned above can be changed when starting the crDistnShiny function. Please be careful, there is no checking in the code on the ultimate limits that are assigned to the ranges for the parameters, and it is quite easy (even with the defaults) to generate errors. The interplay of the parameters is such the defaults are a reasonable compromise, without restricting the density too much.

The default parameter values are for “English” units, they will generate a very small stand if you choose “metric”. The best way around this is to increase the largest diameter using the eta parameter, decrease mortality, and increase recruitment. All these taken together will get you in the ballpark for a more realistic metric stand. crDistnShiny does not distiguish diameter units, so the default parameters will give the same range in cm as in inches with no conversion, this is why the default settings when used in metric will generate a stand with very low basal area. The “metric” setting in the units argument is basically used only to convert the basal area-size distribution to the correct units. This is why one must play with the parameters a bit to get a realistic metric stand.

Note that the width of the largest diameter class will vary with each change of parameters as it depends on the three Chapman-Richards growth parameters. You may notice that the superimposed numbers or basal area curves end lower or higher than the bars in this last class, this is due to the width of the class being larger or smaller, respectively, than the nominally chosen class width. This behavior is fine and is to be expected; when includeTiny=TRUE the smallest class will extend to d0 and the curve will display similar behavior as the largest class. The program now lets you know about the sizes of the lower and upper class to remind you when they are not of nominal width.

Note that the numbers and basal area density bars, as well as the values given in the tabular output are exact and come from integrate the respective numbers density and basal area-size density. Midpoint approximations are also calculated and returned if returnVar=TRUE. If requested, the beta density curve is also exact, but the tabular values and bar heights are from the midpoint approximation (just to reduce calculations for quicker response time).

Returns an object of class “shiny.appobj”. If you want to capture this, simply assign it to a variable. Otherwise, the return value gets “printed”, which runs the application.

However, if you choose to save the results of the run using the returnVar argument, then a list is placed in the session .GlobalEnv with the following components...

`dcl`	Diameter class parameters.
`dcWidths`	Dbh class widths (the last can be different than the others).
`totals`	Stand totals: numbers, basal area.
`params.run`	The final parameter values for the session.
`df`	A data frame with the tabular results (exact).
`df.approx`	A data frame with the midpoint approximations.

J. H. Gove

: Please see http://shiny.rstudio.com/articles/ for more information about Shiny and its use.

: Gove, J. H. 2015. A demographic study of the exponential distribution as applied to uneven-aged forests. Submitted.

: Gove, J. H. and T. B. Lynch. 2015. Notes on the Chapman-Richards size-structured distibution. Unpublished R vignette (Available from the author).

The shiny package. Also see qDistnShiny.

#
# cut and paste these examples if desired...
#
## Not run: 
crDistnShiny(recruitRange = c(1, 20))  #run immediately
crsh = crDistnShiny()                  #assign to crsh
str(crsh)                              #look at it
crsh                                   #run it

## End(Not run)