probeSmooths: For a response in a 'data.frame' in long format, computes and...

In growthPheno: Functional Analysis of Phenotypic Growth Data to Smooth and Extract Traits

For a response in a data.frame in long format, computes and compares, for sets of smoothing parameters, smooths of the response, possibly along with growth rates calculated from the smooths.

Description

Takes an observed response and, for each individual, uses byIndv4Times_SplinesGRs to smooth its values employing the smoothing parameters specified by (i) spline.types, (ii) the tuning parameters, being the degrees of freedom values in df or the smoothing penalties in lambdas, and (iii) the smoothing.methods. The values of these, and other, smoothing arguments are set using the helper function args4smoothing.

Provided get.rates is TRUE or includes raw and/or smoothed and depending on the setting of trait.types, the Absolute Growth Rates (AGR) and/or the Relative Growth Rates (RGR) are calculated for each individual from the unsmoothed, observed response and from the smooths of the response, using either differences or first derivatives, as specified by rates.method.

Generally, profile plots for the traits (a response, an AGR or an RGR) specified in traits.types are produced if which.plots is profiles; if which.plots specifies one or more deviations plots, then those deviations plots will also be produced, these being based on the unsmoothed data from which the smoothed data has been subtracted. The layout of the plots is controlled via combinations of one or more of the smoothing-parameter factors Type, TunePar, TuneVal, Tuning (the combination of TunePar and TuneVal) and Method, as well as other factors associated with the data. The factors that are to be used for the profile plots are supplied via the argument profile.plot.args using the helper function args4profile_plot and for the and deviations boxplots using the helper function args4devnboxes_plot. These helper functions set plots.by, facet.x, and facet.y. For the plots of the medians of the deviations, the factors are supplied via the argument meddevn.plot.args using the helper function args4meddevn_plot to set plots.by, facet.x, facet.y and plots.group. Here, the basic principle is that the number of levels combinations of the smoothing-parameter factors included in the set of plots and facets arguments to one of these helper functions must be the same as those covered by the combinations of the values supplied to spline.types, df, lambdas and smoothing.methods and incorporated into the smooths.frame, such as is returned by probeSmooths. This ensures that smooths from different parameter sets are not pooled together in a single plot. It is also possible to include factors that are not smoothing-parameter factors in the plots amd facets arguments.

The following profiles plots can be produced using args4profile_plot: (i) separate plots of the smoothed traits for each combination of the smoothing parameters (include Type, Tuning and Method in plots.by); (ii) as for (i), with the corresponding plot for the unsmoothed trait preceeding the plots for the smoothed trait (also set include.raw to alone); (iii) profiles plots that compare a smoothed trait for all combinations of the values of the smoothing parameters, arranging the plots side-by-side or one above the other (include Type, Tuning and Method in facet.x and/or facet.y - to include the unsmoothed trait set include.raw to one of facet.x or facet.y; (iv) as for (iii), except that separate plots are produced for each combination of the levels of the factors in plot.by and each plot compares the smoothed traits for the smoothing-parameter factors included in facet.x and/or facet.y (set both plots.by and one or more of facet.x and facet.y).

Deviation plots that can be produced are the absolute and relative deviations boxplots and plots of medians deviations (see which.plots).

The handling of missing values is controlled via na.x.action and na.y.action supplied to the helper function args4smoothing.

The probeSmooths arguments are grouped according to function in the following order:

1. Data description arguments: data, response, response.smoothed, individuals, times, keep.columns, trait.types, get.rates, rates.method, ntimes2span.

2. Smoothing arguments: smoothing.args (see args4smoothing).

3. General plot control: x.title, y.titles, facet.labeller, which.plots.

4. Profile plots (pf) features: profile.plot.args (see args4profile_plot)

5. Median-deviations (med) plots features: meddevn.plot.args (see args4meddevn_plot)

6. Deviations boxplots (box) features: devnboxes.plot.args (see args4devnboxes_plot)

Usage

probeSmooths(data, response = "PSA", response.smoothed = NULL, 
             individuals="Snapshot.ID.Tag", times = "DAP", 
             keep.columns = NULL, 
             get.rates = TRUE, 
             rates.method="differences", ntimes2span = NULL, 
             trait.types = c("response", "AGR", "RGR"), 
             smoothing.args = 
               args4smoothing(smoothing.methods = "direct", 
                              spline.types = "NCSS", 
                              df = NULL, lambdas = NULL), 
             x.title = NULL, y.titles = NULL, 
             which.plots = "profiles", 
             profile.plot.args = 
               args4profile_plot(plots.by = NULL, 
                                 facet.x = ".", facet.y = ".", 
                                 include.raw = "no"), 
             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)), 
             devnboxes.plot.args = 
               args4devnboxes_plot(plots.by = NULL, 
                                 facet.x = ".", facet.y = ".", 
                                 which.plots = "none"), 
             ...)

Arguments

data	A data.frame containing the data or a smooths.frame as is produced by probeSmooths. if data is not a smooths.frame, then smoothing will be performed. If data is a smooths.frame, then the plotting and selection of smooths will be performed as specified by smoothing.args and which.plots.
response	A character specifying the response variable to be supplied to smoothSpline and that is to be plotted on the y-axis.
response.smoothed	A character specifying the name of the column containing the values of the smoothed response variable, corresponding to response. If response.smoothed is NULL, then response.smoothed is set to the response to which is added the prefix s.
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 as the values of the predictor variable to be supplied to smooth.spline and to be plotted on the x-axis. If a factor or character, the values should be numerics stored as characters.
keep.columns	A character vector giving the names of columns from data that are to be included in the smooths.frame that will be returned. Its main use is when no plots are being produced by probeSmooths, but there are columns in the supplied data.frame that are likely to be needed for the plots and facets arguments when producing plots subsequently.
get.rates	A logical or a character specifying which of the response and the response.smoothed are to have growth rates (AGR and/or RGR) computed and stored. If set to TRUE or c("raw", "smoothed"), growth rates will be obtained for both. Setting to only one of raw or smoothed, results in the growth rates for either the response or the response.smoothed being computed. If set to none or FALSE, no growth rates ar computed. Which growth.rates are computed can be changed using the arguments traits.types and the method used for computing them for the response.smooth by rates.method. The growth rates for the response can only be computed by differencing.
rates.method	A character specifying the method to use in calculating the growth rates for response.smoothed. The two possibilities are "differences" and "derivatives".
ntimes2span	A numeric giving the number of values in times to span in calculating growth rates by differencing. For ntimes2span set to NULL, if rates.method is set to differences then ntimes2span is set to 2; if rates.method is set to derivatives then ntimes2span is set to 3. Note that when get.rates is includes raw or is TRUE, the growth rates for the unsmoothed response must be calculated by differencing, even if the growth rates for the smoothed response are computed using derivatives. When differencing, each growth rate is calculated as the difference in the values of one of the responses for pairs of times values that are spanned by ntimes2span times values divided by the difference between this pair of times values. For ntimes2span set to 2, a growth rate is the difference between consecutive pairs of values of one of the responses divided by the difference between consecutive pairs of times values.
trait.types	A character giving the trait.types that are to be plotted. If growth rates are included in trait.types, then they will be computed for either the response and/or the response.smoothed, depending on the setting of get.rates. Any growth rates included in trait.types for the response that are available in data, but have not been specified for computation in get.rates, will be retained in the returned smooths.frame. If all, the response.smoothed, its AGR and RGR, will be plotted. The response, and its AGR and RGR, will be plotted as the plotting options require it.
smoothing.args	A list that is most easily generated using args4smoothing, it documenting the options available for smoothing the data. It gives the settings of smoothing.methods, spline.types, df, lambdas, smoothing.segments, npspline.segments, na.x.action, na.y.action, external.smooths, and correctBoundaries, to be used in smoothing the response or in selecting a subset of the smooths in data, depending on whether data is a data.frame or a smooths.frame, respectively. Set smoothing.args to NULL if data is a smooths.frame and only plotting or extraction of a chosen smooth is required.
x.title	Title for the x-axis, used for all plots. 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 and used for all plots. If NULL then set to the traits derived for response from trait.types.
which.plots	A logical indicating which plots are to be produced. The options are either none or some combination of profiles, absolute.boxplots, relative.boxplots and medians.deviations. The various profiles plots that can be poduced are described in the introduction to this function. Boxplots of the absolute deviations are specified by absolute.boxplots, the absolute deviations being the values of a trait minus their smoothed values (observed - smoothed). Boxplots of the relative deviations are specified by relative.boxplots, the relative deviations being the absolute deviations divided by the smoothed values of the trait. The option medians.deviations results in a plot that compares the medians of the absolute deviations over the values of times for each combination of the smoothing-parameter values. The arguments to probeSmooths that apply to medians.deviations plots have the suffix med.
profile.plot.args	A named list that is most easily generated using args4profile_plot, it documenting the options available for varying profile plots and boxplots. Note that if args4profile_plot is to be called to change from the default settings given in the default probeSmooths 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 args4profile_plot; be aware that if you call args4profile_plot, then the defaults for this call are those for args4profile_plot, NOT the call to args4profile_plot shown as the default for probeSmooths.
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 probeSmooths 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 probeSmooths.
devnboxes.plot.args	A named list that is most easily generated using args4devnboxes_plot, it documenting the options available for varying the boxplots. Note that if args4devnboxes_plot is to be called to change from the default settings given in the default probeSmooths 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 args4devnboxes_plot; be aware that if you call args4devnboxes_plot, then the defaults for this call are those for args4devnboxes_plot, NOT the call to args4devnboxes_plot shown as the default for probeSmooths.
...	allows passing of arguments to plotProfiles.

Value

A smooths.frame that contains the unsmoothed and smoothed data in long format. That is, all the values for either an unsmoothed or a smoothed trait are in a single column. The smooths for a trait for the different combinatons of the smoothing parameters are placed in rows one below the other. The columns that are included in the smooths.frame are Type, TunePar, TuneVal, Tuning and Method, as well as those specified by individuals, times, response, and response.smoothed. and any included in the keep.columns, plots and facet arguments. If trait.types includes AGR or RGR, then the included growth rate(s) of the response and response.smoothed must be present, unless get.rates is TRUE or includes raw and/or smoothed. In this case, the growth rates specified by trait.types will be calculated for the responses nominated by get.rates and the differences between the times used in calculating the rates will be computed and added. Then, the names of the growth rates are formed from response and response.smoothed by appending .AGR and .RGR as appropriate; the name of the column with the times differences will be formed by appending .diffs to the value of times. The external.smooths will also be included. A smooths.frame has the attributes described in smooths.frame.

Columns in the supplied data.frame that have not been used in probeSmooths will not be included in the returned smooths.frame. If they might be needed subsequently, such as when extra plots are produced, they can be included in the smooths.frame by listing them in a character vector for the keep.columns argument.

The smooths.frame is returned invisibly.

Author(s)

Chris Brien

See Also

args4smoothing, , args4meddevn_plot, args4profile_plot, traitSmooth,
smoothSpline, byIndv4Times_SplinesGRs, byIndv4Times_GRsDiff, smooth.spline, psNormal, plotSmoothsComparison,
plotSmoothsMedianDevns, ggplot.

Examples

data(exampleData)
longi.dat <- longi.dat[1:140,] #reduce to a smaller data set
vline <- list(ggplot2::geom_vline(xintercept=29, linetype="longdash", linewidth=1))
yfacets <- c("Smarthouse", "Treatment.1")
probeSmooths(data = longi.dat, 
             response = "PSA", response.smoothed = "sPSA",
             individuals = "Snapshot.ID.Tag",times = "DAP", 
             smoothing.args = 
               args4smoothing(df = c(4,7), 
                              lambda = list(PS = c(0.316,10))),
             profile.plot.args = 
               args4profile_plot(plots.by = NULL, 
                                 facet.x = "Tuning", 
                                 facet.y = c("Smarthouse", "Treatment.1"), 
                                 include.raw = "no", 
                                 alpha  = 0.4, 
                                 colour.column = "Method", 
                                 colour.values = c("orange", "olivedrab"), 
                                 ggplotFuncs = vline))

#An example that supplies three smoothing schemes to be compared
data(tomato.dat)
probeSmooths(data = tomato.dat, 
             response = "PSA", response.smoothed = "sPSA", 
             times = "DAP", 
             smoothing.args = 
               args4smoothing(spline.types      = c(  "N", "NCS",   "P"), 
                              df                = c(   4,     6,    NA), 
                              lambdas           = c(  NA,    NA,     1), 
                              smoothing.methods = c("dir", "log", "log"),
                              combinations      = "parallel"),
             which.plots = "medians.deviations",
             meddevn.plot.args = 
               args4meddevn_plot(plots.by = NULL, 
                                 plots.group = c("Type", "Tuning", "Method"),              
                                 facet.x = ".", facet.y = ".", 
                                 propn.note = FALSE, propn.types = NULL))

growthPheno documentation built on Sept. 11, 2024, 6:42 p.m.