Change-Points Estimation (with Possibly Random Effects)

View source: R/seg.r

seg	R Documentation

Specifying a segmented/stepmented term in the segreg/stepreg formula

Description

Function used to define a segmented (stepmented) term within the segreg (stepreg) formula. The function simply passes relevant information to proper fitter functions.

Usage

seg(x, npsi = 1, psi = NA, est = NA, R = NA, fixed.psi = NULL, by = NULL, f.x = I)

Arguments

`x`	The segmented/stepmented (numeric) covariate
`npsi`	The number of breakpoints/jumpoints to estimate. Default to `npsi=1`. If `by` has been specified and `npsi` is a scalar, the same `npsi` applies to all categories of the factor `by`; otherwise it can be vector, wherein the entries represent the number of breakpoints of the segmented relationships within the categories of `by`. The `npsi` starting values are computed according the specification of `quant` in `seg.control`.
`psi`	Numerical vector indicating possible starting value(s) for the breakpoint(s). When provided, `psi` overwrites `npsi`. If `by` has been specified and `psi` is a vector, the same `psi` applies to all categories of the factor `by`. Otherwise `psi` can be a list, wherein the components represent the starting values of the segmented/stepmented relationships within the categories of `by`.
`est`	Possible vector (of length equal to `npsi+1`) of 1's and 0's to indicate whether the slopes have to be estimated or fixed to zero. `NA`, the default, means all ones, namely every slope is estimated. Consecutive zeroes are not allowed. If it is a vector and `by` has been specified, the same `est` applies to all categories of the factor `by`; otherwise `est` can be a list, wherein the components represent the slope constraints of the segmented relationships within the categories of `by`.
`R`	Matrix to constrain the slopes. If provided, it overwrites the matrix (which is built internally) coming from the specification of `est`. If matrix and `by` has been specified, the same `R` applies to all categories of the factor `by`; otherwise `R` can be a list, wherein the components represent the slope constraints of the segmented relationships within the categories of `by`.
`fixed.psi`	Possible fixed breakpoint values to be accounted for in addition to those being estimated. If `by` has been specified and `fixed.psi` is a vector, the same `fixed.psi` applies to all categories of the factor `by`. Otherwise `fixed.psi` can be a list, wherein the components refer to the segmented relationship within the levels of `by`. `slope` and `plot.segmented` will account for them correctly.
`by`	A possible factor meaning an interaction with the segmented term `x`. Hence, if specified, a different segmented relationship is fitted within each category of `by`.
`f.x`	an optional function meaning a function to apply to the covariate before fitting.

Details

The function is used within segreg and stepreg to 'build' information about the segmented relationships to fit.

Note that, when a grouping variable has been specified in by, npsi can be specified as a vector, and est, if specified, should be a list.

Value

The function simply returns the covariate with added attributes relevant to segmented term

Note

If any value is provided in fix.psi, the corresponding slope difference coefficient will be labelled by *.fixed.*. The slope function will compute the 'right' slopes also accounting for the fixed breakpoints.