'res.param' computes basic statistics for a numeric vector.  By default, it plots a density approximation for the vector.  Typically it is used to display a plot of the posterior distribution of a parameter in a BUGS analysis.  Upon request, it displays credible intervals and location statistics on the graph.  

ARGUMENTS:

'samples' - a numeric vector whose distribution is to be displayed.  Typically, 'samples' is the vector of simulated estimates of a parameter that results from a WinBUGS run.

'plot.dist = TRUE' (default) to produce a density plot that shows the distribution of 'samples'. In addition, the function returns a vector of descriptive statistics.  If 'plot.dist = FALSE & plot.hist = FALSE', no plot is produced. The function returns the the xy coordinates of the density.  

'method.density' determines the method by which the density of 'samples' is approximated.  The default method is 'density' which uses the 'density' function in the 'stats' package.  If 'method.density' is set to 'logspline', then the 'logspline' function in the 'polspline' package is used to estimate the density of 'samples'.  See ?density and ?logspline for descriptions of these two methods.

'lwd' controls the weight of the line in a density plot (default  'lwd = 3', if one is placed on the plot. 

'plot.hist = TRUE' (default) to produce a histogram of the samples from the distribution of 'samples'.  The histogram is scaled so that the total area of the histogram equals 1.0.  WARNING: If the MCMC chain is gets stuck at fixed values, then some of the bars in the histogram may be much higher than the density curve.  To check for this, compare length(x) to length(unique(x)) where x is the variable assigned to the samples argument.  If 'plot.dist = FALSE & plot.hist = FALSE', no plot is produced. The function returns the the xy coordinates of the density.

'hist.col' controls the color of the histogram.

'show.conf = TRUE' (default) places a credible interval on the plot. 

'conf.label' controls how the credible interval is labeled on the histogram and/or density plot.  If 'conf.label = "default"', the credible interval is labeled with the level and the type of credible interval, e.g., "95% HDI" is the label for a 95% highest density interval.  If 'method.ci = "equal.tails", the default label would be "95% C.I.".  The user can select any other label for the credible interval.  If 'conf.label = "", then the credible interval has no label.  

'method.ci' determines the type of credible interval.  The default is 'HDI' (highest density interval), but a credible interval with equal probability tails can be selected (method.ci = 'equal.tails'). 

If 'ROPE = NULL' (default), the Region of Practical Equivalence (ROPE) is not plotted.  If 'ROPE = c(x1, x2)' (where x1 and x2 are any numbers), then markers are placed on the X-axis to show the location of x1 and x2.  If 'ROPE = x' where x is a scalar, then markers are placed on the X-axis at -x and +x.

If 'conf.back.ht = 1' (default), then the default height of the background for the label of the confidence interval.  If, e.g., 'conf.back.ht = 1.25', then the height of the background is 1.25 times greater than the default height.  

If 'conf.txt.ht = 1' (default), then the confidence interval label is plotted at the default height.  If, e.g., 'conf.txt.ht = 1.25', then the confidence interval label is plotted at 1.25 times the default height.  

If 'show.stats = TRUE', then statistics for the distribution are plotted on the figure.  If 'show.stats = FALSE', then the statistics are not plotted on the figure.  Note that even if 'show.stats = FALSE', the statistics can still be returned as output.  Whether the function returns descriptive statistics is determined by the 'output' argument.  

The statistics selected by 'stats.which' are outputted as a vector by 'samples'; optionally, the values of these statistics are printed on the density plot by setting 'show.stats = TRUE'.  If 'show.stats = FALSE', the statistics selected by 'stats.which' are outputted by 'samples' but they are not plotted on the density plot.  'stats.which' can be set to any or all of the statistics, 'mean','median','mode', 'conf' or 'n.samples'.  If 'stats.which' includes 'conf', the lower and upper bounds of a credible interval are computed and optionally printed on the density plot.  The level of the credible interval is set by 'level'  (choose any number between 0 and 1.0 - the default value is .95).  A pre-4/5/2011 version used an argument called 'conf.pct' to set the level of the credible interval.  The 'conf.pct' argument has been retained in this function to make the function compatible with older code, but in post-4/5/2011 uses of this function, use 'level' to indicate the level of the credible interval.

'digits' specifies the number of digits to the right of the decimal place to display in the statistics.  The default is 3 digits; if desired, different  numbers of digits can be specified for each statistics.  WARNING: If specifying separate numbers of digits for each statistic, you need to specify the number of digits for each of the statistics, 'mean','median','mode' and 'conf', even if only a subset of these statistics is selected. 

'cex.stats' controls the character expansion of the stats displayed on the plot.  

'stats.spacing' controls the line spacing for the stats.  It defaults to 1.  Set it, e.g., to 1.25 to increase the line spacing by 25%.  

'stats.ht' is an obsolete argument that has been retained to maintain backwards compatibility with pre-6/5/2013 code.  It was used to control the height at which statistics were printed on the plot.  Use 'stats.yLoc' for this same purpose.  

'stats.xLoc' controls the distance that statistics are printed from the right or left figure margin.  The default setting, 0.21, indicates that the equal sign will be printed at 21% of the distance from the left margin to the right margin of the figure if the statistics are printed on the left half of the figure, and at 16% of the distance from the right margin to the left margin if the statistics are printed on the right half of the figure.  These locations were chosen because they are generally reasonably attractive.  If the user changes 'stats.xLoc' to, e.g., 0.25, then the equal sign will be plotted at 25% of the distance from the left margin to the right margin of the figure if the statistics are printed on the left half of the figure, and at 20% of the distance from the right margin to the left margin if the statistics are printed on the right half of the figure.  

'stats.yLoc' controls the height at which the statistics are printed on a plot, expressed as a proportion of the maximum height of the density plot.  The default, 'stats.yLoc = .90', indicates that the stats are vertically centered around 90% of the maximum height of the density plot.  The stats are automatically plotted on the left or right side of the figure, where the left or right side is selected automatically whether the mode of the density is to the left or right of the mode of the density.  

The range of values displayed on the X axis is controlled by 'xlim' - if 'xlim = NA' (default), the default X axis range is used.  Similarly, the range of values to be plotted on the Y axis is controlled by 'ylim' - if 'ylim = NA' (default), the Y axis limits are 0 and the maximum Y value on the density plot.  

The axis labels to be displayed on the X and Y axes are controlled by 'xlab' and 'ylab'.  The figure title is controlled by the 'title' argument - when it is set to its default, "default", the figure title is "Samples from <VariableName> Posterior".  'cex.lab' controls the character size on the Y-axis.  The X-axis label and title are set to be 1.35 times the size of the Y-axis. 

'output':  The 'res.param' function has an 'output' argument to maintain compatility with an earlier version of 'res.param' but it no longer plays a functional role, i.e., the specification of a value for the 'output' argument has no effect on the operation of the 'res.param' function.