segmented             package:segmented             R Documentation

_S_e_g_m_e_n_t_e_d _r_e_l_a_t_i_o_n_s_h_i_p_s _i_n _r_e_g_r_e_s_s_i_o_n _m_o_d_e_l_s

_D_e_s_c_r_i_p_t_i_o_n:

     Fits regression models with segmented relationships between the
     response and one or more explanatory variables. Break-point
     estimates are provided.

_U_s_a_g_e:

     segmented(obj, seg.Z, psi, control = seg.control(), 
         model.frame = TRUE, ...)

     segmented.lm(obj, seg.Z, psi, control = seg.control(), 
         model.frame = TRUE, ...)

     segmented.glm(obj, seg.Z, psi, control = seg.control(), 
         model.frame = TRUE, ...)

_A_r_g_u_m_e_n_t_s:

     obj: standard `linear' model of class "lm" or "glm". 

   seg.Z: a formula with no response variable, indicating the
          (continuous) explanatory variables having segmented
          relationships with the response 

     psi: named list of vectors. The names have to match the variables
          of the 'seg.Z' argument. Each vector includes starting values
          for the break-point(s) for the corresponding variable in
          'seg.Z' 

 control: a list of parameters for controlling the fitting process. See
          the documentation for 'seg.control' for details. 

model.frame: logical value indicating if the model.frame should be
          returned.

     ...: optional arguments. 

_D_e_t_a_i_l_s:

     Given a linear regression model (of class "lm" or "glm"),
     segmented tries to estimate a new model having broken-line
     relationships with the variables specified in seg.Z. A segmented
     (or broken-line) relationship is defined by the slope parameters
     and the break-points where the linear relation changes. The number
     of breakpoints of each segmented relationship is fixed via the
     'psi' argument, where initial values for the break-points must be
     specified. The model is estimated simultaneously yielding point
     estimates and relevant approximate standard errors of all the
     model parameters, including the break-points.

_V_a_l_u_e:

     The returned object depends on the 'last' component returned by
     'seg.control'. If last=TRUE, the default, segmented returns an
     object of class "segmented" which inherits from the class "lm" or
     "glm" depending on the class of 'obj'. Otherwise a list is
     returned, where the last component is the fitted model at the
     final iteration, see 'seg.control'. 

     An object of class "segmented" is a list containing the components
     of the original object 'obj' with additionally the followings: 

    psi : estimated break-points and relevant (approximate) standard
          errors

     it : number of iterations employed

epsilon : difference in the objective function when the algorithm stops

  mframe: the model frame

     Other components are not of direct interest of the user.

_W_a_r_n_i_n_g:

     It is well-known that the log-likelihood function for the 
     break-point may be not concave, especially  for poor clear-cut
     kink-relationships. In these circumstances the initial guess for
     the break-point,  i.e. the 'psi' argument, must be provided with
     care. For instance visual  inspection of a, possibly smoothed, 
     scatter-plot is usually a good way to obtain some idea on
     breakpoint location.  Moreover it is also advisable to look at the
     coefficients of the `gap' variables. At the convergence they
     should be small or at least, non-significantly different from
     zero. 'summary.segmented' and 'print.summary.segmented' return
     information of the `gap' coefficients.

_N_o_t_e:

        1.  The algorithm will start if the 'it.max' argument returned
           by 'seg.control' is greater than zero. If 'it.max=0'
           'segmented' will estimate a new linear model with
           break-point(s) fixed at the values reported in 'psi'.

        2.  In the returned object, the name of the
           difference-in-slopes parameter is  labelled with
           `U.name_of_variable'.

        3.  Methods specific to the class '"segmented"' are

           *  'print.segmented'

           *  'summary.segmented'

           *  'print.summary.segmented'

        Others are inherited from the class '"lm"' or '"glm"' depending
        on the class of 'obj'.

_A_u_t_h_o_r(_s):

     Vito M. R. Muggeo, vmuggeo@dssm.unipa.it

_R_e_f_e_r_e_n_c_e_s:

     Muggeo, V.M.R. (2003) Estimating regression models with unknown 
     break-points. _Statistics in Medicine_ *22*, 3055-3071.

_S_e_e _A_l_s_o:

     'lm', 'glm'

_E_x_a_m_p_l_e_s:

     set.seed(12)
     xx<-1:100
     zz<-runif(100)
     yy<-2+1.5*pmax(xx-35,0)-1.5*pmax(xx-70,0)+15*pmax(zz-.5,0)+rnorm(100,0,2)
     dati<-data.frame(x=xx,y=yy,z=zz)
     out.lm<-lm(y~x,data=dati)
     o<-segmented(out.lm,seg.Z=~x,psi=list(x=c(30,60)),
         control=seg.control(display=FALSE))
     slope(o)

     out.lm1<-lm(y~z,data=dati)
     o1<-update(o,seg.Z=~x+z,psi=list(x=c(30,60),z=.3))

                 

