cobsOld                 package:cobs                 R Documentation

_C_O_n_s_t_r_a_i_n_e_d _B-_S_p_l_i_n_e_s _N_o_n_p_a_r_a_m_e_t_r_i_c _R_e_g_r_e_s_s_i_o_n _Q_u_a_n_t_i_l_e_s

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

     Computes constrained quantile curves using linear or quadratic
     splines.  The median spline (L_1 loss) is a robust (constrained)
     smoother.

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

     cobsOld(x, y, constraint = c("none", "increase", "decrease",
                               "convex", "concave", "periodic"),
          z, minz = knots[1], maxz = knots[nknots], nz = 100,
          knots, nknots, method = "quantile",
          degree = 2, tau = 0.5, lambda = 0, ic = "aic",
          knots.add = FALSE, alpha = 0.1, pointwise,
          print.warn = TRUE, print.mesg = TRUE, trace = print.mesg,
          coef = rep(0,nvar), w = rep(1,n),
          maxiter = 20*n, lstart = log(big)^2, toler = 1e-6,
          factor = 1)

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

       x: vector of covariate.

       y: vector of response variable. It must have the same length as
          x.

constraint: character (string) specifying the kind of constraint; must
          be one of "increase", "decrease", "convex", "concave",
          "periodic" or "none".

       z: vector of grid points at which the fitted values are
          evaluated; default to an equally spaced grid with 'nz' grid
          points between 'minz' and 'maxz'.  If the fitted values at x
          are desired, use 'z = unique(x)'.

    minz: numeric needed if 'z' is not specified; defaults to 'min(x)'
          or the first knot if 'knots' are given.

    maxz: analogous to 'minz'; defaults to 'max(x)' or the last knot if
          'knots' are given.

      nz: number of grid points in 'z' if that is not given; defaults
          to 100.

   knots: vector of locations of the knot mesh; if missing, 'nknots'
          number of 'knots' will be created using the specified
          'method' and automatic knot selection will be carried out for
          regression B-spline (lambda=0); if not missing and
          'length(knots)==nknots', the provided knot mesh will be used
          in the fit and no automatic knot selection will be performed;
          otherwise, automatic knots selection will be performed on the
          provided 'knots'.

  nknots: maximum number of knots; defaults to 6 for regression
          B-spline, 10 for smoothing B-spline.

  method: character specifying the method for generating 'nknots'
          number of 'knots' when 'knots' is not provided; "quantile"
          (equally spaced in percentile levels) or "uniform" (equally
          spaced knots); defaults to "quantile".

  degree: degree of the splines; 1 for linear spline and 2 for
          quadratic spline; defaults to 2.

     tau: desired quantile level; defaults to 0.5 (median).

  lambda: penalty parameter; lambda = 0: no penalty (regression
          B-spline);
           lambda > 0: smoothing B-spline with the given lambda;
           lambda < 0: smoothing B-spline with lambda chosen by a
          Schwarz-type information criterion.

      ic: information criterion used in knot deletion and addition for
          regression B-spline method when lambda=0; "aic" (Akaike-type)
          or "sic" (Schwarz-type); default to "aic".

knots.add: logical indicating if an additional step of stepwise knot
          addition should be performed for regression B-splines.

   alpha: level of significance for the confidence band.

pointwise: an optional three-column matrix with each row specifies one
          of the following constraints:

          '( _1,_x_i,_y_i)': fitted value at xi will be >= yi;

          '(-_1,_x_i,_y_i)': fitted value at xi will be <= yi;

          '( _0,_x_i,_y_i)': fitted value at xi will be = yi;

          '( _2,_x_i,_y_i)': derivative of the fitted function at xi will be
               yi.

print.warn: logical flag for printing of interactive warning messages;
          default to T; probably needs to be set to F if performing
          monte carlo simulation. 

print.mesg: logical flag for printing of intermediate messages; default
          to T; probably needs to be set to F if performing monte carlo
          simulation. 

   trace: integer >= 0 indicating how much the Fortran routine
          'drqssbc' should print intermediate messages; defaults to
          'print.mesg', i.e. 1 (or 0).

    coef: initial guess of the B-spline coefficients; default to a
          vector of zeros.

       w: vector of weights the same length as x (y) assigned to both x
          and y; default to uniform weights adding up to one; using
          normalized weights that add up to one will speed up
          computation. 

 maxiter: upper bound of the number of iteration; default to 20*n.

  lstart: starting value for lambda when performing parametric
          programming in lambda if 'lambda < 0'; defaults to
          'log(big)^2'.

   toler: numeric tolerance for ???? ; default 1e-6 used to be builtin.

  factor: determines how big a step to the next smaller lambda should
          be while performing parametric programming in lambda; the
          default '1' will give all unique lambda's; use of a bigger
          factor (> 1 &  < 4) will save time for big problems.

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

     'cobsOld()' computes the constraint quantile smoothing B-spline
     with penalty when lambda is not zero.
      If lambda < 0, an optimal lambda will be chosen using Schwarz
     type information criterion. 
      If lambda > 0, the supplied lambda will be used.
      If lambda = 0, cobsOld computes the constraint quantile
     regression B-spline with no penalty using the provided knots or
     those selected by Akaike or Schwarz information criterion.

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

     a list with components 

    coef: B-spline coefficients.

     fit: fitted value at z.

   resid: vector of residuals from the fit.

       z: as in input.

   knots: the final set of knots used in the computation.

     ifl: exit code:

          _1 - ok;

          _2 - problem is infeasible, check specification of the
               'pointwise' argument;

          _3 - maxiter is reached before finding a solution, either
               increase maxiter and restart the program with 'coef' set
               to the value upon previous exit or use a smaller
               'lstart' value when lambda<0 or use a smaller 'lambda'
               value when lambda>0;

          _4 - program aborted, numerical difficulties due to
               ill-conditioning.

    icyc: number of cycles taken to achieve convergence.

       k: the effective dimensionality of the final fit.

  lambda: the penalty parameter used in the final fit.

pp.lambda: vector of all unique lambda's obtained from parametric
          programming when lambda < 0 on input.

     sic: vector of Schwarz information criteria evaluated at
          pp.lambda.

   cb.lo: lower bound of the confidence band

   cb.up: upper bound of the confidence band

   ci.lo: lower bound of the pointwise confidence interval

   ci.up: upper bound of the pointwise confidence interval

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

     This is still a beta version, and we do appreciate comments and
     suggestions; 'library(help = cobs)' shows the authors.

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

     He, X. and Ng, P. (1999) COBS: Qualitatively Constrained Smoothing
     via Linear Programming; _Computational Statistics_ *14*, 315-337.

     Koenker, R. and Ng, P. (1996) A Remark on Bartels and Conn's
     Linearly Constrained L1 Algorithm, _ACM Transaction on
     Mathematical Software_ *22*, 493-495.

     Ng, P. (1996) An Algorithm for Quantile Smoothing Splines,
     _Computational Statistics & Data Analysis_ *22*, 99-118.

     Bartels, R. and Conn A. (1980) Linearly Constrained Discrete L_1
     Problems, _ACM Transaction on Mathematical Software_ *6*, 594-608.

     A postscript version of the paper that describes the details of
     COBS can be downloaded from <URL:
     http://www.cba.nau.edu/pin-ng/cobs.html>

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

     'smooth.spline' for unconstrained smoothing splines; 'bs' for
     unconstrained (regression) B-splines.

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

     x <- seq(-1,1,,50)
     y <- (f.true <- pnorm(2*x)) + rnorm(50)/10
     ## specify pointwise constraints (boundary conditions)
     con <- rbind(c( 1,min(x),0), # f(min(x)) >= 0
                  c(-1,max(x),1), # f(max(x)) <= 1
                  c(0,  0,   0.5))# f(0)      = 0.5

     ## obtain the median regression B-spline using automatically selected knots
     cobsOld(x,y,constraint="increase",pointwise=con)->cobs.o

     plot(x,y)
     lines(cobs.o$z, cobs.o$fit, col = 2, lwd = 1.5)
     lines(spline(x,f.true), col = "gray40")
     lines(cobs.o$z, cobs.o$cb.lo,lty=2, col = 3)
     lines(cobs.o$z, cobs.o$cb.up,lty=2, col = 3)

     ## compute the median smoothing B-spline using automatically chosen lambda
     cobsOld(x,y,constraint="increase",pointwise=con,lambda=-1)->cobs.oo
     plot(x,y, main = "COBS Median smoothing spline, automatical lambda")
     lines(spline(x,f.true), col = "gray40")
     lines(cobs.oo$z, cobs.oo$fit)
     lines(cobs.oo$z, cobs.oo$cb.lo,lty=2)
     lines(cobs.oo$z, cobs.oo$cb.up,lty=2)

     plot(cobs.oo$pp.lambda[-1], cobs.oo$sic[-1], log = "x",
          main = "SIC ~ lambda", xlab = expression(lambda), ylab = "SIC")
     axis(1, at = cobs.oo$lambda, label = expression(hat(lambda)),
          col.axis = 2, mgp = c(3, 0.5, 0))

