Change-Points Estimation (with Possibly Random Effects)

seg.control

R Documentation

Auxiliary for controlling segmented/stepmented model fitting

Description

Auxiliary function as user interface for 'segmented' and 'stepmented' fitting. Typically only used when calling any 'segmented' or 'stepmented' method.

Usage

seg.control(n.boot=10, display = FALSE, tol = 1e-05, it.max = 30, fix.npsi=TRUE,
    K = 10, quant = FALSE, maxit.glm = NULL, h = 1.25, break.boot=5, size.boot=NULL, 
    jt=FALSE, nonParam=TRUE, random=TRUE, seed=NULL, fn.obj=NULL, digits=NULL, 
    alpha = NULL, fc=.95, check.next=TRUE, tol.opt=NULL, fit.psi0=NULL, eta=NULL, 
    min.nj=2)

Arguments

`n.boot`	number of bootstrap samples used in the bootstrap restarting algorithm. If 0 the standard algorithm, i.e. without bootstrap restart, is used. Default to 10 that appears to be sufficient in most of problems. However when multiple breakpoints have to be estimated it is suggested to increase `n.boot`, e.g. `n.boot=50`, and even `break.boot`.
`display`	logical indicating if the value of the objective function should be printed along with current breakpoint estimates at each iteration or at each bootstrap resample (but no more than 5 breakpoints are printed). If bootstrap restarting is employed, the values of objective and breakpoint estimates should not change at the last runs.
`tol`	positive convergence tolerance.
`it.max`	integer giving the maximal number of iterations.
`fix.npsi`	logical (it replaces previous argument `stop.if.error`) If `TRUE` (default) the number (and not location) of breakpoints is held fixed throughout iterations. Otherwise a sort of ‘automatic’ breakpoint selection is carried out, provided that several starting values are supplied for the breakpoints, see argument `psi` in `segmented.lm` or `segmented.glm`. The idea, relying on removing the ‘non-admissible’ breakpoint estimates at each iteration, is discussed in Muggeo and Adelfio (2011) and it is not compatible with the bootstrap restart algorithm. `fix.npsi=FALSE`, indeed, should be considered as a preliminary and tentative approach to deal with an unknown number of breakpoints. Alternatively, see `selgmented`.
`K`	the number of quantiles (or equally-spaced values) to supply as starting values for the breakpoints when the `psi` argument of `segmented` is set to `NA`. `K` is ignored when `psi` is different from `NA`.
`quant`	logical, indicating how the starting values should be selected. If `FALSE` equally-spaced values are used, otherwise the quantiles. Ignored when `psi` is different from `NA`.
`maxit.glm`	integer giving the maximum number of inner IWLS iterations (see details). If `NULL`, the number is low in the first iterations and then increases as th eprocess goes on. Ignored for segmented lm fits
`h`	positive factor modifying the increments in breakpoint updates during the estimation process (see details).
`break.boot`	Integer, less than `n.boot`. If `break.boot` consecutive bootstrap samples lead to the same objective function during the estimation process, the algorithm stops without performing all `n.boot` 'trials'. This can save computational time considerably. Default is `5` for the `segmented` and `5+2` for the `stepmented` functions. However if the number of changepoints is large, `break.boot` should be increased, even 10 or 15.
`size.boot`	the size of the bootstrap samples. If `NULL`, it is taken equal to the actual sample size. If the sample is very large, the idea is to run bootstrap restarting using smaller bootstrap samples.
`jt`	logical. If `TRUE` the values of the segmented variable(s) are jittered before fitting the model to the bootstrap resamples.
`nonParam`	if `TRUE` nonparametric bootstrap (i.e. case-resampling) is used, otherwise residual-based. Currently working only for LM fits. It is not clear what residuals should be used for GLMs.
`random`	if `TRUE`, when the algorithm fails to obtain a solution, random values are employed to obtain candidate values.
`seed`	The seed to be passed on to `set.seed()` when `n.boot>0`. If `NULL`, a seed depending on the response values is generated and used. Otherwise it can be a numerical value or, if `NA`, a random value is generated. Fixing the seed can be useful to replicate exactly the results when the bootstrap restart algorithm is employed. Whichever choice, the segmented fit includes the component `seed` representing the value saved just before the bootstrap resampling. Re-use it if you want to replicate the bootstrap restarting algorithm with the same re-samples.
`fn.obj`	A character string to be used (optionally) only when `segmented.default` is used. It represents the function (with argument `'x'`) to be applied to the fit object to extract the objective function to be minimized. Thus for `"lm"` fits (although unnecessary) it should be `fn.obj="sum(x$residuals^2)"`, for `"coxph"` fits it should be `fn.obj="-x$loglik[2]"`. If `NULL` the ‘minus log likelihood’ extracted from the object, namely `"-logLik(x)"`, is used. See `segmented.default`.
`digits`	optional. If specified it means the desidered number of decimal points of the breakpoint to be used during the iterative algorithm.
`alpha`	optional numerical values. The breakpoints are estimated within the quantiles `alpha[1]` and `alpha[2]` of the relevant covariate. If a single value is provided, it is assumed `alpha` and `1-alpha`. Defaults to `NULL` which means `alpha=max(.05, 1/n)`. Note: Providing `alpha=c(mean(x<=a),mean(x<=b))` means to constrain the breakpoint estimates within `[a,b]`.
`fc`	A proportionality factor (`\le 1`) to adjust the breakpoint estimates if these come close to the boundary or too close each other. For instance, if `psi` turns up close to the maximum, it will be changed to `psi*fc` or to `psi/fc` if close to the minimum. This is useful to get finite point estimate and standard errors for each slope paramete.
`check.next`	logical, effective only for stepmented fit. If `TRUE` the solutions next to the current one are also investigated.
`tol.opt`	Numerical value to be passed to `tol` in `optimize`.
`fit.psi0`	Possible list including preliminary values.
`eta`	Only for segmented/stepmented fits: starting values to be passed to `etastart` in `glm.fit`.
`min.nj`	How many observations (at least) should be in the covariate intervals induced by the breakpoints?

Details

Fitting a ‘segmented’ GLM model is attained via fitting iteratively standard GLMs. The number of (outer) iterations is governed by it.max, while the (maximum) number of (inner) iterations to fit the GLM at each fixed value of psi is fixed via maxit.glm. Usually three-four inner iterations may be sufficient.

When the starting value for the breakpoints is set to NA for any segmented variable specified in seg.Z, K values (quantiles or equally-spaced) are selected as starting values for the breakpoints.

Since version 0.2-9.0 segmented implements the bootstrap restarting algorithm described in Wood (2001). The bootstrap restarting is expected to escape the local optima of the objective function when the segmented relationship is noisy and the loglikelihood can be flat. Notice bootstrap restart runs n.boot iterations regardless of tol that only affects convergence within the inner loop.

Value

A list with the arguments as components.

Author(s)

Vito Muggeo

References

Muggeo, V.M.R., Adelfio, G. (2011) Efficient change point detection in genomic sequences of continuous measurements. Bioinformatics 27, 161–166.

Wood, S. N. (2001) Minimizing model fitting objectives that contain spurious local minima by bootstrap restarting. Biometrics 57, 240–244.

Examples


     #decrease the maximum number inner iterations and display the 
     #evolution of the (outer) iterations
     #seg.control(display = TRUE, maxit.glm=4)

segmented documentation built on Oct. 25, 2024, 5:07 p.m.