cgam (version 1.21)

s.decr.incr: Specify a Decreasing-Increasing Shape-Restriction in a CGAM Formula

Description

A symbolic routine to define that a surface is decreasing in one predictor and increasing in another in a formula argument to cgam.

Usage

s.decr.incr(x1, x2, numknots = c(0, 0), knots = list(k1 = 0, k2 = 0), space = c("E", "E"))

Value

The vectors \(x_1\) and \(x_2\). Each of them has six attributes, i.e., name: names of \(x_1\) and \(x_2\); shape: "wps_di"(decreasing-increasing); numknots: the numknots argument in "s.decr.incr"; knots: the knots argument in "s.decr.incr"; space: the space argument in "s.decr.incr"; decreasing: two logical values indicating the monotonicity of the isotonically-constrained surface with respect to \(x_1\) and \(x_2\), which are TRUE and FALSE.

Arguments

x1

A numeric predictor which has the same length as the response vector.

x2

A numeric predictor which has the same length as the response vector.

numknots

A vector of the number of knots used to constrain \(x_1\) and \(x_2\). It will not be used if the user specifies the knots argument and each predictor is within the range of its knots. The default is numknots = c(0, 0).

knots

A list of two vectors of knots used to constrain \(x_1\) and \(x_2\). User-defined knots will be used if each predictor is within the range of its knots. Otherwise, numknots and space will be used to create knots. The default is knots = list(k1 = 0, k2 = 0).

space

A vector of the character specifying the method to create knots for \(x_1\) and \(x_2\). It will not be used if the user specifies the knots argument. If "E" is used, then equally spaced knots will be created; if "Q" is used, then a vector of equal quantiles will be created with duplicate elements removed. The number of knots is numknots when numknots is a positive integer \(> 4\). Otherwise it is of the order \(n^{1/6}\). The default is space = c("E", "E").

Author

Mary C. Meyer and Xiyue Liao

Details

"s.decr.incr" returns the vectors "x1" and "x2", and imposes on each vector six attributes: name, shape, numknots, knots, space and decreasing.

The name attribute is used in the subroutine plotpersp; the numknots, knots and space attributes are the same as the numknots, knots and space arguments in "s.decr.incr"; the shape attribute is "wps_di"(decreasing-increasing); the decreasing values for "x1" and "x2" are TRUE and FALSE. According to the value of the vector itself and its shape, numknots, knots, space and decreasing attributes, the cone edges will be made by warped-plane spline basis functions in Meyer (2016). The cone edges are a set of basis employed in the hinge algorithm.

Note that "s.decr.incr" does not make the corresponding cone edges itself. It sets things up to a subroutine called makedelta_wps.

See references cited in this section for more details.

References

Meyer, M. C. (2017) Estimation and inference for regression surfaces using shape-constrained splines.

See Also

s.incr.incr, s.incr.decr, s.decr.decr, cgam

Examples

if (FALSE) {
  # generate data
  n <- 100
  set.seed(123)
  x1 <- runif(n)
  x2 <- runif(n)
  y <- 4 * (x2 - x1) - x1 * x2 + rnorm(n, sd = .2)

  # regress y on x1 and x2 under the shape-restriction: "decreasing-increasing"
  # using the penalized estimator
  ans <- cgam(y ~ s.decr.incr(x1, x2), pnt = TRUE)

  # make a 3D plot of the constrained surface
  plotpersp(ans)
}