data.frame.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:
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.
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.
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.
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.
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.
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.
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,
...)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.
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.
A character specifying the response variable to be
smoothed.
A character specifying the name of the column
to contain the values of the smoothed response variable, corresponding
to response.
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).
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.
A character vector giving the names of columns
from data that are to be included in the
smooths.frame that will be returned.
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.
A character specifying the method to use in
calculating the growth rates for response.smoothed. The two
possibilities are "differences" and "derivatives".
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.
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.
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.
Title for the x-axis, used for all plots. If NULL then set
to times.
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.
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.
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.
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.
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.
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.
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 factors 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.
A data.frame that is to have the values for the
trait.types for the smooth specified by chosen.smooth.args
merged 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.
Chris Brien
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.
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. tools:::Rd_expr_doi("10.1186/s13007-020-00577-6").
args4smoothing, args4meddevn_plot, args4profile_plot,
args4chosen_smooth,
args4chosen_plot, probeSmooths
plotSmoothsComparison and
plotSmoothsMedianDevns, ggplot.
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))
Run the code above in your browser using DataLab