plotSmoothsMedianDevns: Calculates and plots the medians of the deviations from the observed values for several sets of smoothed values stored in a `data.frame` in long format.

Description

Calculates and plots the medians of the deviations of the supplied smoothed values from the supplied observed values for traits and combinations of different smoothing parameters, possibly for subsets of non-smoothing-factor combinations. The observed and smoothed values are supplied in long format i.e. with the values for each set of smoothing parameters stacked one under the other in the supplied data.frame. Such data can be generated using probeSmooths; to prevent probeSmooths producing the plots, which it is does using plotSmoothsComparison, plotDeviationsBoxes and plotSmoothsMedianDevns, set which.plots to none. The smoothing parameters include spline.types, df, lambdas and smoothing.methods (see probeSmooths).

Multiple plots, possibly each having multiple facets, are produced using ggplot2. The layout of these plots is controlled via the smoothing-parameter factors Type, Tuning (the combination of TunePar and TuneVal) and Method that can be supplied to the arguments plots.by, plots.group, facet.x and facet.y. These plots and facet arguments can also include factors other than the smoothing-parameter factors, that are also associated with the data. The basic principle is that the number of levels combinations of the smoothing-parameter factors included in the plots and facet arguments must be the same as those covered by the combinations of the values supplied to spline.types, df, lambdas and Method and incorporated into the smooths.frame input to plotSmoothsMedianDevns via the data argument. This ensures that smooths from different parameter sets are not pooled in a single plot. Envelopes of the median value of a trait for each factor combination can be added.

Usage

plotSmoothsMedianDevns(data, response, response.smoothed = NULL, 
                       individuals = "Snapshot.ID.Tag",  times = "DAP", 
                       trait.types = c("response", "AGR", "RGR"), 
                       x.title = NULL, y.titles = NULL, 
                       meddevn.plot.args = 
                         args4meddevn_plot(plots.by = NULL, plots.group = NULL,
                                           facet.x = ".", facet.y = ".", 
                                           propn.note = TRUE, 
                                           propn.types = c(0.1, 0.5, 0.75)), 
                       printPlot = TRUE, ...)

Value

A list that consists of two components: (i) a componenent named

plots that stores a two-level list of the median deviations plots; the first-level list has a component for each

trait.types and each of these list(s) is a second-level

list that contains the set of plots specified by plots.by

(if plots.by is NULL, a single plot is stored); (ii) a component named

med.dev.dat that stores the data.frame containing the median deviations that have been plotted. Each plot in the plots

list is in an object of class ggplot, which can be plotted using print.

Arguments

data: A smooths.frame, such as is produced by probeSmooths and that contains the data resulting from smoothing a response over time for a set of individuals, the data being arranged in long format both with respect to the times and the smoothing-parameter values used in the smoothing. That is, each response occupies a single column. The smooths.frame must include the columns Type, TunePar, TuneVal, Tuning and Method, and the columns nominated using the arguments individuals, times, plots.by, facet.x, facet.y, plots.group, response, response.smoothed, and, if requested, the AGR and the RGR of the response and response.smoothed. The names of the growth rates should be formed from response and response.smoothed by adding .AGR and .RGR to both of them.
response: A character specifying the response variable for which the observed values are supplied. Depending on the setting of trait.types, the observed values of related trait.types may also need to be be supplied.
response.smoothed: A character specifying the name of the column containing the values of the smoothed response variable, corresponding to response and obtained for the combinations of smoothing.methods and df, usually using smoothing splines. If response.smoothed is NULL, then response.smoothed is set to the response to which is added the prefix s. Depending on the setting of trait.types, the smoothed values of related trait.types may also need to be be supplied.
individuals: A character giving the name of the factor that defines the subsets of the data for which each subset corresponds to the response values for an individual (e.g. plant, pot, cart, plot or unit).
times: A character giving the name of the column in data containing the times at which the data was collected, either as a numeric, factor, or character. It will be used to provide the values to be plotted on the x-axis. If a factor or character, the values should be numerics stored as characters.
trait.types: A character giving the traits types that are to be plotted. While AGR and RGR are commonly used, the names can be arbitrary, except that response is a special case that indicates that the original response is to be plotted. If all, each of response, AGR and RGR is plotted.
x.title: Title for the x-axis. If NULL then set to times.
y.titles: A character giving the titles for the y-axis, one for each trait specified by trait.types. If NULL, then set to the traits derived for response from trait.types.
meddevn.plot.args: A named list that is most easily generated using args4meddevn_plot, it documenting the options available for varying median deviations plots. Note that if args4meddevn_plot is to be called to change from the default settings given in the default plotSmoothsMedianDevns call and some of those settings are to be retained, then the arguments whose settings are to be retained must also be included in the call to args4meddevn_plot; be aware that if you call args4meddevn_plot, then the defaults for this call are those for args4meddevn_plot, NOT the call to args4meddevn_plot shown as the default for plotSmoothsMedianDevns.
printPlot: A logical indicating whether or not to print the plot.
...: allows passing of arguments to other functions; not used at present.

Author

Chris Brien

Examples

Run this code

data(exampleData)
vline <- list(ggplot2::geom_vline(xintercept=29, linetype="longdash", size=1))
traits <- probeSmooths(data = longi.dat, 
                       response = "PSA", response.smoothed = "sPSA", 
                       times = "DAP", 
                       get.rates = FALSE, trait.types = "response", 
                       smoothing.args = 
                         args4smoothing(smoothing.methods = "direct", 
                                        spline.types = "NCSS", 
                                        df = c(4,7), lambdas = NULL), 
                       which.plots = "none")
med <- plotSmoothsMedianDevns(data = traits, 
                              response = "PSA", response.smoothed = "sPSA", 
                              times = "DAP", trait.types = "response",  
                              meddevn.plot.args = 
                                args4meddevn_plot(plots.by = NULL, 
                                                  plots.group = "Tuning", 
                                                  facet.x = ".", facet.y = ".", 
                                                  propn.types = 0.02,
                                                  ggplotFuncs = vline))