Describe supported R options in vignette

vignettes/model-based-annotations.Rmd

@@ -67,13 +67,15 @@ Supporting computed and model-fit based annotations in ggplots can be implemente
 
 The statistics defined in 'ggpmisc' even if usable with geometries from package 'ggplot2', in most cases have as default geometries defined in package 'ggpp'. These new geometries are better suited for plot annotations than those from 'ggplot2', which are designed for data labels.
 
-In user interfaces there is always a compromise between simplicity and flexibility in which the choice of default arguments plays a key role in finding a balance. I have aimed to make everyday use simple without constraining the flexibility inherent to the Grammar of Graphics. However, the assumption is that users desire/need the flexibility inherent in the layered approach of the Grammar of Graphics, and that the layer functions provided will be combined with those from 'ggplot2', 'ggpp' and other packages extending the Grammar of Graphics as implemented in 'ggplot2'.
+In user interfaces there is always a compromise between simplicity and flexibility in which the choice of default arguments plays a key role in finding a balance. I have aimed to make everyday use simple without limiting the flexibility inherent to the Grammar of Graphics. However, the assumption is that users desire/need the flexibility inherent in the layered approach of the Grammar of Graphics, and that the layer functions provided will be combined with those from 'ggplot2', 'ggpp' and other packages extending the Grammar of Graphics as implemented in 'ggplot2'.
 
 ## Statistics
 
 Currently, the core statistics made available by package 'ggpmisc' help with reporting parameter- and other estimates from fitted models, both as equations and numbers in annotations and by plotting. Similarly to `ggplot2::stat_smooth()` they call model-fit-functions to fit a model-formula to the plot-layer data and, as all ggplot statistics, return new `data` as a data frame that is in turn passed to a geometry. The statistics are `stat_poly_line()`, `stat_poly_eq()`, `stat_ma_line()`, `stat_ma_eq()`, `stat_quant_line()`, `stat_quant_band()`, `stat_quant_eq()`, `stat_fit_residuals()`, `stat_fit_deviations()`, `stat_fit_glance()`, `stat_fit_augment()`, `stat_fit_tidy()` and `stat_fit_tb()`. In addition, `stat_correlation()` helps with the reporting of Pearson, Kendall and Spearman correlations. Most of these statistics support orientation flipping, both using parameter `orientation` similarly to package 'ggplot2' in recent versions or through a model `formula` with `x` as response variable and `y` as explanatory variable.
 
-These statistics support grouping and faceting. In the case of those that return character strings to be mapped to the `label` aesthetic they also return suitable `x` and `y`, or `npcx` and `npcy` values as well as `hjust` and `vjust` values. These default values ensure that the annotations do not spill out the borders of the plotting area that also minimize overlaps among labels. The automatic computation of these positions can be adjusted through arguments passed to these statistics and also overridden by user-supplied manual positions.
+These statistics support grouping and faceting. In the case of those that return character strings to be mapped to the `label` aesthetic they also return suitable `x` and `y`, or `npcx` and `npcy` values as well as `hjust` and `vjust` values. These default values ensure that the annotations do not spill out the borders of the plotting area. The automatic computation of these positions can be adjusted through arguments passed to these statistics and also overridden by user-supplied manual positions.
+
+***Not all possible model formulas can be decoded to produce valid fitted model equations. In most cases, for incompatible model formulas, no equation label will be automatically generated, and a warning triggered. Other labels are always generated, and a suitable fitted model equation can be generated by user code within the aesthetic mapping using the numeric values that are also returned.**
 
 Table 1 below summarizes the use of the model-fittings statistics and the type of plot-layer geometries they are most useful with them. The four statistics at the bottom of the table require in their use more effort as the mapping to aesthetics and conversion of numeric values into character strings must be coded in the layer function call, but on the other hand they support all model fit objects catered by package 'broom' itself or any of the packages extending 'broom' such as 'broom.mixed' (see next section).
 
@@ -224,6 +226,13 @@ Package 'broom' provides a *translation layer* between various model fit functio
 
 Statistics `stat_peaks()` and `stat_valleys()` can be used to locate and annotate global and local maxima and minima in the variable mapped to the `y` (or `x` ) aesthetic. Date time variables mapped to the `x` or `y` aesthetics are supported.
 
+### R options
+
+Some default arguments that should in most cases be consistent across annotations in the plots of a document can be set through R options. These include the character used as decimal point, through the option used by R itself, `OutDec`, the use of upper- or lower case letters as symbol for probability and pearson correlation and coefficient of determination: `ggpmisc.small.p`, `ggpmisc.small.r` and the ordering of terms in the model fit equation label (not the in the model formula argument) `ggpmisc.decreasing.poly.eq`.
+
+The labels can be generated using different types of markup: R plotmath expressions,
+Markdown, $\LaTeX$, and plain text. Character strings suitable for parsing are the default unless the argument to parameter `geom` is `richtext` or `textbox`, in which case Markdown encoded character strings are returned. The default for `parse` is `TRUE` only if suitable strings are being returned.
+
 ## Scales
 
 When plotting *omics* data we usually want to highlight observations based on the outcome of tests of significance for each one of 100's or 1000's genes or metabolites. We define some scales, as wrappers on continuous `x` and `y` scales from package `ggplot2` that are suitable for 1) differences in abundance expressed as fold changes, 2) *P*-value and 3) FDR.
@@ -246,7 +255,7 @@ Several simple use examples are given in the help for each of the layer and othe
 
 ### stat_correlation()
 
-The statistic `stat_correlation()` computes one of Pearson, Kendall or Spearman correlation coefficients and tests if the differ from zero. This is done by calling `stats::cor.test()`, with all of its formal parameters supported. Depending on the argument passed to parameter `output.type` the values returned very. The default behaviour is to generate labels as character strings using R's *expression* syntax, suitable to be *parsed*. This ggplot statistic can also output labels using other mark-up languages, including $\LaTeX$ and Markdown, or just numeric values. Nevertheless, all examples below use expression syntax, which is the most commonly used.
+The statistic `stat_correlation()` computes one of Pearson, Kendall or Spearman correlation coefficients and tests if they differ from zero. This is done by calling `stats::cor.test()`, with all of its formal parameters supported. Depending on the argument passed to parameter `output.type` the values returned very. The default behaviour is to generate labels as character strings using R's *expression* syntax, suitable to be *parsed*. This ggplot statistic can also output labels using other mark-up languages, including $\LaTeX$ and Markdown, or just numeric values. Nevertheless, all examples below use expression syntax, which is the most commonly used.
 
 We first generate a set of artificial data suitable for the plotting examples in this and subsequent sections.