Plot method for segmented mixed objects

Takes a fitted segmented.lme object returned by segmented.lme() and plots (or adds) the fitted broken-line relationship for the segmented term.

Usage

# S3 method for class 'segmented.lme'
plot(x, level=1, id = NULL, res = TRUE, pop = FALSE, offs=0, yscale = 1, xscale = 1, 
    n.plot, pos.leg = "topright", vline = FALSE, lines = TRUE, 
    by=NULL, add=FALSE, conf.level=0, withI=TRUE, vcov.=NULL, shade=FALSE, 
    drop.var=NULL, text.leg=NULL, id.name=TRUE, ci.psi.pop=-1, ...)

Arguments

x: Object of class "segmented.lme"
level: An integer giving the level of grouping to be used when computing the segmented relationship(s). level=0 means depending on fixed effects estimates only (such estimates are also said, to some extend, 'population' or 'marginal' estimates), otherewise the segmented lines will also depend on the random effects predictions.
id: A scalar or vector meaning which subjects profiles have to be drawn. If NULL (default) all profiles are drawn. Ignored if level=0.
res: If TRUE, the data points are also drawn. Ignored if level=0.
pop: if TRUE, the fitted segmented relationships based on fixed-effects only is also portrayed. Ignored if level=0.
offs: Values (scalar or 100-length) to be added to the fitted values before plotting. Only if level=0.
yscale: If >= 0, the same and common y-scale is used for all 'subjects' (panels); otherwise the y-scale will depend on the actual (observed and fitted) values for each 'subject'.
xscale: If >= 0, the same and common x-scale is used for all 'subjects' (panels); otherwise the x-scale will depend on the actual observed values of the segmented covariate for each 'subject'.
n.plot: a vector to be passed to par(mfrow=c(..)) for plotting multiple panels (should be coherent with length(id)). If missing, it is computed automatically depending on length(id). Type n.plot=1 to draw all the segmented profiles on the same panel.
pos.leg: a character ('topright', 'topleft',...) meaning the location of the legend. Set NULL for no legend.
vline: logical, if TRUE a vertical dashed segment is added to emphasize the breakpoint location.
lines: logical, if FALSE points, rather than lines, are used to portray the segmented relationships.
by: A named list indicating covariate names and corresponding values affecting the fitted segmented relationship. For instance: by=list(sex="male",z=.2), provided that the variables sex and z affect the segmented relationship. Effective only if level=0.
add: If TRUE the (fixed-effect) fitted segmented relationship is added to the current plot. Effective only if level=0.
conf.level: The confidence level for pointwise confidence intervals. Effective only if level=0.
withI: If TRUE, the level 0 segmented relationship is computed with the model intercept. Effective only if level=0.
vcov.: The fixed effects covariance matrix. If NULL, it is computed by vcov.segmented.lme(). Effective only if level=0.
shade: If TRUE (and conf.level>0) the area within the pointiwise CIs is shaded. Effective only if level=0.
drop.var: Possible coefficient names to be removed before computing the segmented relationship (E.g. the group-specific intercept.).
text.leg: If specified (and pos.leg has been also specified), it is the legend text. Effective only if level=0.
id.name: If pos.leg is different from NULL, id.name=TRUE will portray the cluster variable name along the value. Namely id.name=TRUE leads to 'country = italy' on each panel, while id.name=FALSE to 'italy'.
ci.psi.pop: Should the point estimate and CI for the population breakpoint be added? If ci.psi.pop>0 both the point estimate and CI (at level ci.psi.pop) are added; if ci.psi.pop=0 only the point estimate.
...: additional arguments, such as ylab,xlab, ylim and xlim; l.col,l.lwd,l.lty (for the fitted individual lines - can be vectors and will be recycled); p.col, p.lwd, p.lty for the population line (if pop=TRUE); col, cex, pch for the data points (if res=TRUE); t.col for the legend color, if pos.leg is not NULL. If level=0 and conf.level>0, lty and lwd can be vectors.

Details

The function plots the 'subject'-specific segmented profiles for the 'subjects' specificed in id or, if level=0, the fitted segmented relationship based on fixed effects only. The number of panels to drawn is actually the minimum between length(id) and prod(n.plot), but if n.plot=c(1,1) (or also simply n.plot=1), the `individual' profiles will be pictured on the same panel.

Value

A single or multiple (depending on level and id) plot showing the fitted segmented profiles.

Author

Vito Muggeo

Note

If by is specified (and level=0 is set), a legend is also added in the plot reporting covariate(s) name and value affecting the segmented relationship. Set pos.leg=TRUE to have no legend. On the other hand, use text.leg to add legend reporting the covariate baseline values.

Warning

All the functions for segmented mixed models (*.segmented.lme) are still at an experimental stage

Examples

if (FALSE) { # \dontrun{
#continues example from segmented.lme

plot(os, yscale=-1) #different y-scales

plot(os2, n.plot=1, l.col=2:6, l.lwd=2) #all segmented profiles on the same plot

} # }