\name{segreg}
\alias{segreg}
\alias{stepreg}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{
Fitting segmented/stepmented regression
}
\description{
\code{segreg} (\code{stepreg}) fits (generalized) linear segmented (stepmented) regression via a symbolic description of the linear predictor. This is an alternative but equivalent function, introduced since version 2.0-0 (segreg) and 2.1-0 (stepreg), to \code{segmented.(g)lm} or \code{stepmented.(g)lm}.
}
\usage{
segreg(formula, data, subset, weights, na.action, family = lm, offset, 
    control = seg.control(), transf = NULL, contrasts = NULL, model = TRUE, 
    x = FALSE, var.psi = TRUE, ...)
      
stepreg(formula, data, subset, weights, na.action, family = lm, offset, 
    control = seg.control(), transf = NULL, contrasts = NULL, model = TRUE, 
    x = FALSE, var.psi = FALSE, ...)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
  \item{formula}{
A standard model formula also including one or more 'segmented'/'stepmented' terms via the function \code{\link{seg}}
}
  \item{data}{
The possible dataframe where the variables are stored
}
  \item{subset}{
Possible subset, as in \code{\link{lm}} or \code{\link{glm}}
}
  \item{weights}{
Possible weight vector, see \code{weights} in \code{\link{lm}} or \code{\link{glm}}
}
  \item{na.action}{
a function which indicates what happen when the data contain NA values. See \code{na.action} in \code{\link{lm}} or \code{\link{glm}}.
}
  \item{family}{
The family specification, similar to \code{family} in \code{\link{glm}}. Default to \code{'lm'} for segmented/stepmented linear models.
}
  \item{offset}{
  A possible offset term.
}
  \item{control}{
See \code{\link{seg.control}}
}
  \item{transf}{
an optional character string (with "y" as argument) meaning a function to apply to the response variable before fitting
}
  \item{contrasts}{
see \code{contrasts} in \code{\link{glm}}
}
  \item{model}{
If \code{TRUE}, the model frame is returned.
}
  \item{x}{
If \code{TRUE}, the model matrix is returned.
}
  \item{var.psi}{
logical, meaning if the standard errors for the breakpoint estimates should be returned in the object fit. If \code{FALSE}, 
the standard errors will be computed by \code{\link{vcov.segmented}} or \code{\link{summary.segmented}}. Setting \code{var.psi=FALSE} could speed up model estimation for very large datasets. Default to \code{TRUE} for \code{segreg} and \code{FALSE} for \code{stepreg}.  
}
  \item{\dots}{
Ignored
}
}
\details{
The function allows to fit segmented/stepmented (G)LM regression models using a formula interface. Results will be the 
same of those coming from the traditional \code{segmented.lm} and \code{segmented.glm} (or \code{stepmented.lm} or 
\code{stepmented.glm}), but there are some additional facilities: i) it is possible to estimate strightforwardly the segmented/stepmented 
relationships in each level of a categorical variable, see argument \code{by} in  \code{\link{seg}}; 
ii) it is possible to constrain some slopes of the segmented relationship, see argument \code{est} or \code{R} in \code{\link{seg}}.

See  \code{\link{segmented}} and \code{\link{stepmented}} for some details on the fit objects.
}
\value{
An object of class "segmented" (or "stepmented") which inherits from the class "lm" or "glm" depending on \code{family} specification. See \code{\link{segmented.lm}}.
}
\references{
Muggeo, V.M.R. (2003) Estimating regression models with unknown break-points. Statistics in Medicine 22, 3055-3071.
}
\author{
Vito Muggeo
}
\note{
When the formula includes even a single segmented term with constraints (specified via the argument \code{est} in \code{seg()}), the relevant coefficients returned do not represent the slope differences as in \code{segmented.lm} or \code{segmented.glm}. The values depend on the constraints and are not usually interpretable. Use \code{\link{slope}} the recover the actual slopes of the segmented relationships. 
}

\section{Warning }{
Currently for fits returned by \code{segreg}, \code{\link{confint.segmented}} only works if \code{method="delta"}.
Constraints on the mean levels (possibly via argument 'est' of \code{seg}) are not yet allowed when calling \code{stepreg}.
For \code{stepreg} fits, when printing the iterative process (i.e. \code{display=TRUE} in \code{seg.control()}), the changepoints displayed are based on the working approximation of the indicator function. Thus, also the last value (at convergence) will be different from the one reported in the component \code{psi.rounded} of the fit.    
} 

\seealso{
\code{\link{seg}}, \code{\link{segmented}}, \code{\link{stepmented}}
}
\examples{
###########################
#An example using segreg()
###########################

set.seed(10)
x<-1:100
z<-runif(100)
w<-runif(100,-10,-5)
y<-2+1.5*pmax(x-35,0)-1.5*pmax(x-70,0)+10*pmax(z-.5,0)+rnorm(100,0,2)

##the traditional approach
out.lm<-lm(y~x+z+w)
o<-segmented(out.lm, seg.Z=~x+z, psi=list(x=c(30,60),z=.4))

o1<-segreg(y ~ w+seg(x,npsi=2)+seg(z))
all.equal(fitted(o), fitted(o1))

#put some constraints on the slopes
o2<-segreg(y ~ w+seg(x,npsi=2, est=c(0,1,0))+seg(z))
o3<-segreg(y ~ w+seg(x,npsi=2, est=c(0,1,0))+seg(z, est=c(0,1)))

slope(o2)
slope(o3)

##see ?plant for an additional example


###########################
#An example using stepreg()
###########################

### Two stepmented covariates (with 1 and 2 breakpoints)
n=100
x<-1:n/n
z<-runif(n,2,5)
w<-rnorm(n)
mu<- 2+ 1*(x>.6)-2*(z>3)+3*(z>4)
y<- mu + rnorm(n)*.8

os <-stepreg(y~seg(x)+seg(z,2)+w) #also includes 'w' as a possible linear term
os
summary(os)
plot(os, "z", col=2:4) #plot the effect of z


}
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory (show via RShowDoc("KEYWORDS")):
% \keyword{ ~kwd1 }
% \keyword{ ~kwd2 }
% Use only one keyword per line.
% For non-standard keywords, use \concept instead of \keyword:
% \concept{ ~cpt1 }
% \concept{ ~cpt2 }
% Use only one concept per line.
