Auxiliary function as user interface for 'segmented' fitting. Typically
only used when calling any 'segmented' method (segmented.lm
or segmented.glm
).
seg.control(toll = 1e-04, it.max = 10, display = FALSE, stop.if.error = TRUE,
K = 10, quant = FALSE, last = TRUE, maxit.glm = 25, h = 1,
n.boot=20, size.boot=NULL, gap=FALSE, jt=FALSE, nonParam=TRUE,
random=TRUE, powers=c(1,1), seed=NULL, fn.obj=NULL, digits=NULL)
positive convergence tolerance.
integer giving the maximal number of iterations.
logical indicating if the value of the working objective function should be printed at each iteration. The working objective function is the objective function of the working model including the gap coefficients (and therefore it should not be compared with the value at convergence). If bootstrap restarting is employed, the value of the real objective function (without gap coefficients) after every bootstrap iteration is printed. This value should decrease throughout the iterations.
logical indicating if non-admissible break-points should be removed
during the estimating algorithm. Set it to FALSE
if you want to perform a sort of
`automatic' breakpoint selection, provided that several starting values are provided for the breakpoints.
See argument psi
in segmented.lm
or segmented.glm
.
The idea of removing `non-admissible' break-points during the iterative process is discussed in
Muggeo and Adelfio (2011) and it is not compatible with the bootstrap restart algorithm.
This approach, indeed, should be considered as a preliminary and tentative approach to deal with an unknown number of
breakpoints.
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
.
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
.
logical indicating if output should include only the last fitted model.
integer giving the maximum number of inner IWLS iterations (see details).
positive factor (from zero to one) modifying the increments in breakpoint updates during the estimation process (see details).
number of bootstrap samples used in the bootstrap restarting algorithm. If 0 the standard algorithm,
i.e. without bootstrap restart, is used. Default to 20 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
.
the size of the bootstrap samples. If NULL
, it is taken equal to the actual sample size.
logical, if FALSE
the gap coefficients are always constrained to zero at the convergence.
logical. If TRUE
the values of the segmented variable(s) are jittered before fitting the model to the
bootstrap resamples.
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.
if TRUE
, when the algorithm fails to obtain a solution, random values are employed to obtain candidate values.
The powers of the pseudo covariates employed by the algorithm. These are possibly altered during the iterative process to stabilize the estimation procedure. Usually of no interest for the user.
The seed to be passed on to set.seed()
when n.boot>0
. Setting the seed can be useful to replicate
the results when the bootstrap restart algorithm is employed. In fact a segmented fit includes seed
representing
the integer vector saved just before the bootstrap resampling. Re-use it if you want to replicate the bootstrap
restarting algorithm with the same samples.
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
.
optional. If specified it means the desidered number of decimal points of the breakpoint to be used during the iterative algorithm.
A list with the arguments as components.
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.
In this case, it may be useful to set also stop.if.error=FALSE
to automate the procedure, see Muggeo and Adelfio (2011).
The maximum number of iterations (it.max
) should be also increased when the `automatic' procedure is used.
If last=TRUE
, the object resulting from segmented.lm
(or segmented.glm
) is a
list of fitted GLM; the i-th model is the segmented model with the values of the breakpoints at the i-th iteration.
Sometimes to stabilize the procedure, it can be useful to set h<1
to reduce the increments in the breakpoint
updates. At each
iteration the updated estimate is usually given by psi.new=psi.old+increm
. By setting h<1
(actually min(abs(h),1)
is considered) causes the following updates of the breakpoint estimate:
psi.new=psi.old+h*increm
.
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 flat. Notice bootstrap restart runs n.boot
iterations regardless of
toll
that only affects convergence within the inner loop.
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.
#decrease the maximum number inner iterations and display the
#evolution of the (outer) iterations
seg.control(display = TRUE, maxit.glm=4)
Run the code above in your browser using DataLab