args4smoothing {growthPheno}

Creates a list of the values for the smoothing parameters to be passed to a smoothing function

Description

Creates a list of the values for the smoothing parameters to be passed to a smoothing function. Note that smoothing.methods, spline.types, df and lambdas are combined to define the set of smooths. The default settings are optimized for traitSmooth so that, if you want to change any of these from their default settings when using args4smoothing with a function other than traitSmooth, then it is recommended that you specify all of them to ensure that the complete set has been correctly specified. Otherwise, the default settings will be those shown here and these may be different to the default settings shown for the function with which you are using args4smoothing.

Usage

 args4smoothing(smoothing.methods = "logarithmic", 
                spline.types = c("NCSS","PS"), 
                df = 5:7, 
                lambdas = list(PS = round(10^c(-0.5, 0, 0.5, 1), 
                                          digits = 3)),
                smoothing.segments = NULL, 
                npspline.segments = NULL, 
                na.x.action="exclude", na.y.action = "trimx", 
                external.smooths = NULL, 
                correctBoundaries = FALSE, 
                combinations = "allvalid", 
                ...)

Arguments

smoothing.methods

A character giving the smoothing method to use. The two possibilites are (i) "direct", for directly smoothing the observed response, and (ii) "logarithmic", for smoothing the log-transformed response and then back-transforming by taking the exponentional of the fitted values.

spline.types

A character giving the type of spline to use. Currently, the possibilites are (i) "NCSS", for natural cubic smoothing splines, and (ii) "PS", for P-splines.

df

A numeric with at least one value that specifies, for natural cubic smoothing splines (NCSS), the desired equivalent numbers of degrees of freedom of the smooths (trace of the smoother matrix). Lower values result in more smoothing. If df = NULL, the amount of smoothing can be controlled by including a component named NCSS in the list for lambdas. If df is NULL and lambda does not include a component named NCSS, then an error is issued.

lambdas

A named list or a numeric specifying the positive penalties to apply in order to control the amount of smoothing. The amount of smoothing decreases as lamda decreases. If lambdas is a list, then include a components with lambdas values and named for each of the specified values of spline.types for which lambdas are to be used. If spline.types includes PS, then a component named PS with at least one numeric value must be present. If a numeric, then it will be converted to a list with the single component named PS.

smoothing.segments

A named list, each of whose components is a numeric pair specifying the first and last values of an times-interval whose data is to be subjected as an entity to smoothing using splines. The separate smooths will be combined to form a whole smooth for each individual. If get.rates includes smoothed or is TRUE, rates.method is differences and ntimes2span is 2, the smoothed growth rates will be computed over the set of segments; otherwise, they will be computed within segments. If smoothing.segments is NULL, the data is not segmented for smoothing.

npspline.segments

A numeric specifying, for P-splines (PS), the number of equally spaced segments between min(x) and max(x), excluding missing values, to use in constructing the B-spline basis for the spline fitting. If npspline.segments is NULL, npspline.segments is set to the maximum of 10 and ceiling((nrow(data)-1)/2) i.e. there will be at least 10 segments and, for more than 22 times values, there will be half as many segments as there are times values. The amount of smoothing decreases as npspline.segments increases. When the data has been segmented for smoothing (smoothing.segments is not NULL), an npspline.segments value can be supplied for each segment.

na.x.action

A character string that specifies the action to be taken when values of x are NA. The possible values are fail, exclude or omit. For exclude and omit, predictions and derivatives will only be obtained for nonmissing values of x. The difference between these two codes is that for exclude the returned data.frame will have as many rows as data, the missing values have been incorporated.

na.y.action

A character string that specifies the action to be taken when values of y, or the response, are NA. The possible values are fail, exclude, omit, allx, trimx, ltrimx or rtrimx. For all options, except fail, missing values in y will be removed before smoothing. For exclude and omit, predictions and derivatives will be obtained only for nonmissing values of x that do not have missing y values. Again, the difference between these two is that, only for exclude will the missing values be incorporated into the returned data.frame. For allx, predictions and derivatives will be obtained for all nonmissing x. For trimx, they will be obtained for all nonmissing x between the first and last nonmissing y values that have been ordered for x; for ltrimx and utrimx either the lower or upper missing y values, respectively, are trimmed.

external.smooths

A data.frame containing the one or more smooths of a response in the column specified by smoothed.response. Multiple smoooths should be supplied in long.format with the same columns as the smooths.frame data, except for the smoothing-parameter columns Type, TunePar, TuneVal, Tuning and Method. Only those smoothing-parameter columns that are to be used in any of plots.by, plots.group, facet.x and facet.y should be included with labels appropriate to the external.smooths. Those smoothing-parameter columns not included in external.smooths will have columns of "Other" added to external.smooths.

The growth rates will be computed by differencing according to the settings of get.rates and trait.types in the function that calls args4smoothing.

correctBoundaries

A logical indicating whether the fitted spline values are to have the method of Huang (2001) applied to them to correct for estimation bias at the end-points. Note that spline.type must be NCSS and lambda and deriv must be NULL for correctBoundaries to be set to TRUE.

combinations

A character specifying how the values of the different smoothing parameters are to be combined to specify the smooths that are to be obtained. The option allvalid results in a smooth for each of the combinations of the values of smoothing.methods, spline.types, df and lambdas that are valid; the other smoothing.args will be the same for all smooths.

The option parallel specifies that, if set, each of four smoothing parameters, smoothing.methods, spline.types, df and lambdas, must have the same number of values and that this number is the number of different smooths to be produced. The values of the parameters in the same position within each parameter collectively specify a single smooth. Because the value of only one of df and lambdas must be specified for a smooth, one of these must be set to NA and the other to the desired value for each smooth. If all values for one of them is NA, then the argument may be omitted or set to NULL.

The option single is for the specification of a single smooth. This will mean that only one of df or lambdas should be set.

...

allows arguments to be passed to other functions; not used at present.

Value

A named list.

Author(s)

Chris Brien

See Also

traitSmooth and probeSmooths.

Examples

args4smoothing(smoothing.methods = "direct", 
               spline.types = "NCSS", df = NULL, lambdas = NULL, 
               smoothing.segments = NULL, npspline.segments = NULL, 
               combinations = "allvalid")
args4smoothing(smoothing.methods = c("log","dir","log"), 
               spline.types = c("NCSS","NCSS","PS"), 
               df = c(4,5,NA), lambdas = c(NA,NA,0.36), 
              combinations = "parallel")
args4smoothing(smoothing.methods = "log", 
               spline.types = "PS", df = NULL, 
               lambdas = 0.36, combinations = "single")