R: Obtain smooths for a trait by fitting spline functions and,...

traitSmooth {growthPheno}

R Documentation

Obtain smooths for a trait by fitting spline functions and, having compared several smooths, allows one of them to be chosen and returned in a `data.frame`.

Description

Takes a response that has been observed for a set of individuals over a number times and carries out one or more of the following steps:

Smooth:: Produces response.smoothed using splines for a set of smoothing parameter settings and, optionally, computes growth rates either as differences or derivatives. (see smoothing.args below and args4smoothing) This step is bypassed if a data.frame that is also of class smooths.frame is supplied to data.
Profile plots:: Produces profile plots of response.smoothed and its growth rates that compare the smooths; also, boxplots of the deviations of the observed from smoothed data can be obtained. (see profile.plot.args below and args4profile_plot) Whether these plots are produced is controlled via which.plots or whether profile.plot.args is set to NULL.
Median deviations plots:: Produces plots of the medians of the deviations of the observed response, and its growth rates, from response.smoothed, and its growth rates. These aid in the assessment of the different smooths. (see meddevn.plot.args below and args4meddevn_plot) Whether these plots are produced is controlled via which.plots or whether meddevn.plot.args is set to NULL.
Deviations boxplots:: Produces boxplots of the absolute or relative deviations of the observed response, and its growth rates, from response.smoothed, and its growth rates. These aid in the assessment of the different smooths. (see devnboxes.plot.args below and args4devnboxes_plot) Whether these plots are produced is controlled via which.plots or whether devnboxes.plot.args is set to NULL.
Choose a smooth:: Extract a single, favoured response.smoothed, and its growth rates, for a chosen set of smoothing parameter settings. (see chosen.smooth.args below and args4chosen_smooth) This step will be omitted if chosen.smooth.args is NULL.
Chosen smooth plot:: Produces profile plots of the chosen smooth and its growth rates. (see chosen.plot.args below and args4chosen_plot) Whether these plots are produced is controlled by whether chosen.plot.args is set to NULL.

Each of the 'args4' functions has a set of defaults that will be used if the corresponding argument, ending in '.args', is omitted. The defaults have been optimized for traitSmooth.

Input to the function can be either a data.frame, that contains data to be smoothed, or a smooths.frame, that contains data that has been smoothed. The function can be run (i) without saving any output, (ii) saving the complete set of smooths in a data.frame that is also of class smooths.frame, (iii) saving a subset of the smooths in a supplied smooths.frame, or (iv) saving a single smooth in a data.frame, which can be merged with a pre-existing data.frame such as the data.frame that contains the unsmoothed data.

The Tomato vignette illustrates the use of traitSmooth and traitExtractFeatures to carry out the SET procedure for the example presented in Brien et al. (2020). Use vignette("Tomato", package = "growthPheno") to access it.

Usage

traitSmooth(data, response, response.smoothed, individuals, times, 
            keep.columns = NULL, 
            get.rates = TRUE, 
            rates.method="differences", ntimes2span = NULL, 
            trait.types = c("response", "AGR", "RGR"), 
            smoothing.args = args4smoothing(), 
            x.title = NULL, y.titles = NULL, 
            which.plots = c("profiles", "medians.deviations"), 
            profile.plot.args = args4profile_plot(), 
            meddevn.plot.args = args4meddevn_plot(), 
            devnboxes.plot.args = args4devnboxes_plot(),
            chosen.smooth.args = args4chosen_smooth(), 
            chosen.plot.args = args4chosen_plot(), 
            mergedata = NULL, 
            ...)

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` , `which.plots`, `chosen.smooth.args` and `chosen.plot.args`.
`response`	A `character` specifying the response variable to be smoothed.
`response.smoothed`	A `character` specifying the name of the column to contain the values of the smoothed response variable, corresponding to `response`.
`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 `numeric`, or `factor` with numeric levels, that contains the values of the predictor variable to be supplied to `smooth.spline` and to be plotted on the x-axis.
`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.
`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. If `data` is a `data.frame`, then smoothing will be performed. If `data` is a `smooths.frame`, no smoothing will be carried out. If `smoothing.args` is `NULL` then a `smooths.frame` will only be used for plotting. Otherwise, the setting of `smoothing.args` will specifying the smooths that are to be extracted from the `smooths.frame`, in which case `smoothing.args` must specify a subset of the smooths in `data`.
`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 the response, the AGE and the RGR. They are used for all plots. If `NULL` then they are set to the `response` and the `response` with `.AGR` and `.RGR` appended.
`which.plots`	A `logical` indicating which plots of the smooths specified by `smoothing.args` 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. The plot of a chosen smooth is dealt with separately by the argument `chosen.plot.args`.
`profile.plot.args`	A named `list` that is most easily generated using `args4profile_plot`, it documenting the options available for varying the profile plots. Note that if `args4profile_plot` is being called from `traitSmooth` to change some arguments from the default settings, then it is safest to set all of the following arguments in the call: `plots.by`, `facet.x` `facet.y` and `include.raw`. If this argument is set to `NULL`, these plots will not be produced.
`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 being called from `traitSmooth` to change some arguments from the default settings, then it is safest to set all of the following arguments in the call: `plots.by`, `plots.group`, `facet.x` and `facet.y`. If this argument is set to `NULL`, these plots will not be produced.
`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 being called from `traitSmooth` to change some arguments from the default settings, then it is safest to set all of the following arguments in the call: `plots.by`, `facet.x` and `facet.y`. If this argument is set to `NULL`, these plots will not be produced.
`chosen.smooth.args`	A named `list` with just one element or `NULL` for each component. It is most easily generated using `args4chosen_smooth` with `combinations` set to `single`. The call to `args4smoothing` should give the settings of `smoothing.methods`, `spline.types`, `df` and `lambdas` for a single smooth that is to be extracted and that is amongst the smooths that have been produced for the settings specified in `smoothing.methods`. If both `df` and `lambda` in `chosen.smooth.args` are `NULL`, then, depending on the settings for `spline.type` and `smoothng.method`, the value of either `df` or `lambdas` that is the median value or the observed value immediatly below the median value will be added to `chosen.smooth.args`. Otherwise, one of `df` and `lambda` should be `NULL` and the other should be a single `numeric` value. If a value in `chosen.smooth.args` is not amongst those investigated, a value that was investigated will be substituted.
`chosen.plot.args`	A named `list` that is most easily generated using `args4chosen_plot`, it documenting the options available for varying profile plots. Because this plot includes only a single smooth, the `chosen.smooth.args`, the smoothing-parameter `factor`s are unnecessary and an error will be given if any are included. Note that if `args4chosen_plot` is to be called to change from the default settings given in the default `traitSmooth` call, then it is safest to set all of the following arguments in the call: `plots.by`, `facet.x`, `facet.y` and `include.raw`. If set to `NULL`, then no chosen-smooth plot will be produced.
`mergedata`	A `data.frame` that is to have the values for the `trait.types` for the smooth specified by `chosen.smooth.args` `merge`d with it. It must contain columns with the names given in `individuals` and `times`, and for which there is only one row for each combination of unique values in these columns. In general, it will be that the number of rows in `mergedata` is equal to the number of unique combinations of the values in the columns of the `chosen.smooth.args` whose names are given by `individuals` and `times`, but this is not mandatory. If only one smooth has been produced, then it will be merged with `data` provided `mergedata` is `NULL` and `data` is not a `smooths.frame`. Othewrwise, a single smooth will be be merged with `mergedata`.
`...`	allows arguments to be passed to `plotProfiles`.

Details

This function is a wrapper function for probeSmooths, plotSmoothsComparison, plotSmoothsComparison and plotDeviationsBoxes. It uses the helper functions args4smoothing, args4profile_plot and args4meddevn_plot to se arguments that control the smoothing and plotting.

It takes a response that has been observed for a set of individuals over a number times and produces response.smoothed, using probeSmooths, for a default set of smoothing parameter settings (see args4smoothing for the defaults). The settings can be varied from the defaults by specifying alternate values for the smoothing parameters, the parameters being the type of spline (spline.types), the degrees of freedom (df) or smoothing penalty (lambdas) and smoothing.methods. There are also several other smoothing arguments that can be manipulated to affect the smooth (for details see args4smoothing). The secondary traits of the absolute growth rate (AGR) and relative growth rate (RGR) are calculated from the two primary traits, the response and response.smoothed.

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 and deviations boxplots are supplied via the argument profile.plot.args using the helper function args4profile_plot to 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).

By default, the single smooth for an arbitrarily chosen combination of the smoothing parameters is returned by the function. The smooth for a single combination other than default combination can be nominated for return using the chosen.smooth.args argument. This combination must involve only the supplied values of the smoothing parameters. The values for response, the response.smoothed and their AGRs and RGRs are are added to data, after any pre-existing columns of these have been removed from data. Profile plots of the three smoothed traits are produced using plotProfiles. However, if chosen.smooth.args is NULL, all of the smooths will be returned in a smooths.frame, and plots for the single combination of the smoothing parameters will not be produced.

Value

A smooths.frame or a data.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.

A smooths.frame will be returned when (i) chosen.smooth.args is NULL and there is more than one smooth specified by the smoothing parameter arguments, or (ii) chosen.smooth.args is not NULL but mergedata is NULL. It will contain the smooths for a trait for the different combinatons of the smoothing parameters, the values for the different smooths being 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 when the smooths were produced. The AGR or RGR for the response and response.smoothed, if obtained, will also be included. A smooths.frame has the attributes described in smooths.frame.

A data.frame will be returned when (i) chosen.smooth.args and mergedata are not NULL or (ii) chosen.smooth.args is NULL, data is not a smooths.frame and there is only one smooth specified by the smoothing parameter arguments. In either case, if mergedata is not NULL, the chosen smooth or the single smooth will be merged with the data.frame specified by mergedata. When there is a single smooth and both mergedata and chosen.smooth.args are NULL, the data.frame will include the columns individuals, times, response, and response.smoothed, and any included in the keep.columns, plots and facet arguments, as well as any growth rates calculated as a result of get.rates and trait.type.

The smooths.frame/data.frame is returned invisibly.

Author(s)

Chris Brien

References

Brien, C., Jewell, N., Garnett, T., Watts-Williams, S. J., & Berger, B. (2020). Smoothing and extraction of traits in the growth analysis of noninvasive phenotypic data. Plant Methods, 16, 36. doi:10.1186/s13007-020-00577-6.

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")
smth.dat <- traitSmooth(data = longi.dat, 
                        response = "PSA", response.smoothed = "sPSA",
                        individuals = "Snapshot.ID.Tag",times = "DAP", 
                        keep.columns = yfacets, 
                        smoothing.args = 
                          args4smoothing(df = c(5,7), 
                                         lambda = list(PS = c(0.316,10))),
                        profile.plot.args = 
                          args4profile_plot(facet.y = yfacets, 
                                            ggplotFuncs = vline),
                        chosen.plot.args = 
                          args4chosen_plot(facet.y = yfacets,  
                                           ggplotFuncs = vline))

[Package growthPheno version 2.1.25 Index]

Obtain smooths for a trait by fitting spline functions and, having compared several smooths, allows one of them to be chosen and returned in a data.frame.