cobs                  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:

     cobs(x, y, constraint = c("none", "increase", "decrease",
                               "convex", "concave", "periodic"),
          knots, nknots, method = "quantile",
          degree = 2, tau = 0.5, lambda = 0, ic = "aic",
          n.sub = n1000cut(n),
          knots.add = FALSE, pointwise,
          print.warn = TRUE, print.mesg = TRUE, trace = print.mesg,
          coef = rep(0,nvar), w = rep(1,n),
          maxiter = 20*n, lstart = 7872, toler.kn = 1e-6,
          eps = .Machine$double.eps, factor = 1)

     n1000cut(n)

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

       x: vector of covariate; missing values are omitted.

       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 the values in the default list, above; may be
          abbreviated.

   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, 20 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 an
          information criterion, see 'ic'.

      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".

   n.sub: integer, not larger than sample size 'n'; the default has
          'n.sub == n' as long as 'n' is less than 1000.

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

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;
          true by default; probably needs to be set to 'FALSE' if
          performing simulation.

print.mesg: logical flag or integer for printing of intermediate
          messages; true by default.  Probably needs to be set to
          'FALSE' in simulations.

   trace: integer >= 0 indicating how much the Fortran routine
          'drqssbc' should print intermediate messages; defaults to
          'print.mesg'.

    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.kn: numeric tolerance for shifting the boundary knots outside;
          default 1e-6 used to be built in.

     eps: tolerance passed to 'qbsks' and 'drqssbc'.

  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.

       n: integer, the sample size.

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

     'cobs()' 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, cobs 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:

     an object of class 'cobs', a list with components 

    call: the 'cobs(..)' call used for creation.

tau, degree: as input

constraint: as input (but no more abbreviated).

    call: the 'cobs(..)' call used for creation.

    coef: B-spline coefficients.

   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: length 2: number of cycles taken to achieve convergence for
          final lambda, and total number of cycles for all lambdas.

       k: the effective dimensionality of the final fit.

      k0: (usually the same)

    x.ps: the pseudo design matrix X (as returned by 'qbsks').

   resid: vector of residuals from the fit.

  fitted: vector of fitted values from the fit.

     SSy: the sum of squares around centered 'y' (e.g. for computation
          of R^2.)

  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'.

_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
     Rbs <- cobs(x,y,constraint="increase",pointwise=con)
     Rbs

     plot(x,y)
     lines(predict(Rbs), col = 2, lwd = 1.5)
     lines(spline(x,f.true), col = "gray40")

     Rbsub <- cobs(x,y,constraint="increase",pointwise=con, n.sub = 45)
     summary(Rbsub)
     lines(predict(Rbsub), col = 4, lwd = 1)

     ## compute the median smoothing B-spline using automatically chosen lambda
     Sbs <- cobs(x,y,constraint="increase",pointwise=con,lambda=-1)
     Sbs
     plot(Sbs$pp.lambda[-1], Sbs$sic[-1], log = "x",
          main = "SIC ~ lambda", xlab = expression(lambda), ylab = "SIC")
     axis(1, at = Sbs$lambda, label = expression(hat(lambda)),
          col.axis = 2, mgp = c(3, 0.5, 0))

     Sb1 <- cobs(x,y,constraint="increase",pointwise=con,lambda=-1, degree=1)
     summary(Sb1)
     pxx <- predict(Sb1, xx <- seq(-1.2, 1.2, len = 201), interval = "both")
     plot(x,y, main = deparse(Sb1$call),
          xlim = range(xx), ylim = range(y, pxx[,"fit"]))
     lines(pxx, col = 2)
     rug(Sb1$knots, col = 4, lwd = 1.6)# (too many knots)
     matlines(pxx[,1], pxx[,-(1:2)], col= rep(c("green","blue"),c(2,2)), lty=2)

