Package 'basefun'

Title: Infrastructure for Computing with Basis Functions
Description: Some very simple infrastructure for basis functions.
Authors: Torsten Hothorn [aut, cre]
Maintainer: Torsten Hothorn <[email protected]>
License: GPL-2
Version: 1.2-0
Built: 2024-11-19 19:19:38 UTC
Source: https://github.com/r-forge/ctm

Help Index


General Information on the basefun Package

Description

The basefun package offers a small collection of objects for handling basis functions and corresponding methods.

The package was written to support the mlt package and will be of limited use outside this package.

Author(s)

This package is authored by Torsten Hothorn <[email protected]>.

References

Torsten Hothorn (2018), Most Likely Transformations: The mlt Package, Journal of Statistical Software, forthcoming. URL: https://cran.r-project.org/package=mlt.docreg


Convert Formula or Factor to Basis Function

Description

Convert a formula or factor to basis functions

Usage

as.basis(object, ...)
## S3 method for class 'formula'
as.basis(object, data = NULL, remove_intercept = FALSE, 
         ui = NULL, ci = NULL, negative = FALSE, scale = FALSE, 
         Matrix = FALSE, prefix = "", ...)
## S3 method for class 'factor_var'
as.basis(object, ...)
## S3 method for class 'ordered_var'
as.basis(object, ...)
## S3 method for class 'factor'
as.basis(object, ...)
## S3 method for class 'ordered'
as.basis(object, ...)

Arguments

object

a formula or an object of class factor, factor_var, ordered or ordered_var

data

either a vars object or a data.frame

remove_intercept

a logical indicating if any intercept term shall be removed

ui

a matrix defining constraints

ci

a vector defining constraints

negative

a logical indicating negative basis functions

scale

a logical indicating a scaling of each column of the model matrix to the unit interval (based on observations in data)

Matrix

a logical requesting a sparse model matrix, that is, a Matrix object.

prefix

character prefix for model matrix column names (allows disambiguation of parameter names).

...

additional arguments to model.matrix, for example contrasts

Details

as.basis returns a function for the evaluation of the basis functions with corresponding model.matrix and predict methods.

Unordered factors (classes factor and factor_var) use a dummy coding and ordered factor (classes ordered or ordered_var) lead to a treatment contrast to the last level and removal of the intercept term with monotonicity constraint. Additional arguments (...) are ignored for ordered factors.

Linear constraints on parameters parm are defined by ui %*% parm >= ci.

Examples

## define variables and basis functions
  v <- c(numeric_var("x"), factor_var("y", levels = LETTERS[1:3]))
  fb <- as.basis(~ x + y, data = v, remove_intercept = TRUE, negative = TRUE,
                 contrasts.arg = list(y = "contr.sum"))

  ## evaluate basis functions
  model.matrix(fb, data = as.data.frame(v, n = 10))
  ## basically the same as (but wo intercept and times -1)
  model.matrix(~ x + y, data = as.data.frame(v, n = 10))

  ### factor
  xf <- gl(3, 1)
  model.matrix(as.basis(xf), data = data.frame(xf = xf))

  ### ordered
  xf <- gl(3, 1, ordered = TRUE)
  model.matrix(as.basis(xf), data = data.frame(xf = unique(xf)))

Box Product of Basis Functions

Description

Box product of two basis functions

Usage

b(..., sumconstr = FALSE)

Arguments

...

named objects of class basis

sumconstr

a logical indicating if sum constraints shall be applied

Details

b() joins the corresponding design matrices by the row-wise Kronecker (or box) product.

Examples

### set-up a Bernstein polynomial
  xv <- numeric_var("x", support = c(1, pi))
  bb <- Bernstein_basis(xv, order = 3, ui = "increasing")
  ## and treatment contrasts for a factor at three levels
  fb <- as.basis(~ g, data = factor_var("g", levels = LETTERS[1:3]))
  
  ### join them: we get one intercept and two deviation _functions_
  bfb <- b(bern = bb, f = fb)

  ### generate data + coefficients
  x <- expand.grid(mkgrid(bfb, n = 10))
  cf <- c(1, 2, 2.5, 2.6)
  cf <- c(cf, cf + 1, cf + 2)

  ### evaluate bases
  model.matrix(bfb, data = x)

  ### plot functions
  plot(x$x, predict(bfb, newdata = x, coef = cf), type = "p",
       pch = (1:3)[x$g])
  legend("bottomright", pch = 1:3, 
         legend = colnames(model.matrix(fb, data = x)))

Bernstein Basis Functions

Description

Basis functions defining a polynomial in Bernstein form

Usage

Bernstein_basis(var, order = 2, ui = c("none", "increasing", "decreasing", 
                                       "cyclic", "zerointegral", "positive",
                                       "negative", "concave", "convex"),
                extrapolate = FALSE, log_first = FALSE)

Arguments

var

a numeric_var object

order

the order of the polynomial, one defines a linear function

ui

a character describing possible constraints

extrapolate

logical; if TRUE, the polynomial is extrapolated linearily outside support(var). In particular, the second derivative of the polynomial at support(var) is constrained to zero.

log_first

logical; the polynomial in Bernstein form is defined on the log-scale if TRUE. It makes sense to define the support as c(1, q)$, ie putting the first basis function of the polynomial on log(1).

Details

Bernstein_basis returns a function for the evaluation of the basis functions with corresponding model.matrix and predict methods.

References

Rida T. Farouki (2012), The Bernstein Polynomial Basis: A Centennial Retrospective, Computer Aided Geometric Design, 29(6), 379–419, doi:10.1016/j.cagd.2012.03.001.

Examples

### set-up basis
  bb <- Bernstein_basis(numeric_var("x", support = c(0, pi)), 
                        order = 3, ui = "increasing")

  ### generate data + coefficients
  x <- as.data.frame(mkgrid(bb, n = 100))
  cf <- c(1, 2, 2.5, 2.6)

  ### evaluate basis (in two equivalent ways)
  bb(x[1:10,,drop = FALSE])
  model.matrix(bb, data = x[1:10, ,drop = FALSE])

  ### check constraints
  cnstr <- attr(bb(x[1:10,,drop = FALSE]), "constraint")
  all(cnstr$ui %*% cf > cnstr$ci)

  ### evaluate and plot Bernstein polynomial defined by
  ### basis and coefficients
  plot(x$x, predict(bb, newdata = x, coef = cf), type = "l")

  ### evaluate and plot first derivative of 
  ### Bernstein polynomial defined by basis and coefficients
  plot(x$x, predict(bb, newdata = x, coef = cf, deriv = c(x = 1)), 
       type = "l")

  ### illustrate constrainted estimation by toy example
  N <- 100
  order <- 10
  x <- seq(from = 0, to = pi, length.out = N)
  y <- rnorm(N, mean = -sin(x) + .5, sd = .5)

  if (require("coneproj")) {
    prnt_est <- function(ui) {
      xv <- numeric_var("x", support = c(0, pi))
      xb <- Bernstein_basis(xv, order = 10, ui = ui)
      X <- model.matrix(xb, data = data.frame(x = x))
      uiM <- as(attr(X, "constraint")$ui, "matrix")
      ci <- attr(X, "constraint")$ci
      if (all(is.finite(ci)))
        parm <- qprog(crossprod(X), crossprod(X, y), 
                      uiM, ci, msg = FALSE)$thetahat
      else
        parm <- coef(lm(y ~ 0 + X))
      plot(x, y, main = ui)
      lines(x, X %*% parm, col = col[ui], lwd = 2)
    }
    ui <- eval(formals(Bernstein_basis)$ui)
    col <- 1:length(ui)
    names(col) <- ui
    layout(matrix(1:length(ui), 
                  ncol = ceiling(sqrt(length(ui)))))
    tmp <- sapply(ui, function(x) try(prnt_est(x)))
  }

Join Basis Functions

Description

Concatenate basis functions column-wise

Usage

## S3 method for class 'basis'
c(..., recursive = FALSE)

Arguments

...

named objects of class basis

recursive

always FALSE

Details

c() joins the corresponding design matrices column-wise, ie, the two functions defined by the two bases are added.

Examples

### set-up Bernstein and log basis functions
  xv <- numeric_var("x", support = c(1, pi))
  bb <- Bernstein_basis(xv, order = 3, ui = "increasing")
  lb <- log_basis(xv, remove_intercept = TRUE)
  
  ### join them
  blb <- c(bern = bb, log = lb)

  ### generate data + coefficients
  x <- as.data.frame(mkgrid(blb, n = 100))
  cf <- c(1, 2, 2.5, 2.6, 2)

  ### evaluate bases
  model.matrix(blb, data = x[1:10, ,drop = FALSE])

  ### evaluate and plot function defined by
  ### bases and coefficients
  plot(x$x, predict(blb, newdata = x, coef = cf), type = "l")

  ### evaluate and plot first derivative of function
  ### defined by bases and coefficients
  plot(x$x, predict(blb, newdata = x, coef = cf, deriv = c(x = 1)), 
       type = "l")

Cyclic Basis Function

Description

The cyclic basis function for modelling seasonal effects

Usage

cyclic_basis(var, order = 3, frequency)

Arguments

var

a numeric_var object

order

the order of the basis function

frequency

frequency

Details

cyclic_basis returns a set of sin and cosine functions for modelling seasonal effects, see Held and Paul (2012), Section 2.2.

For any choice of coefficients, the function returns the same value when evaluated at multiples of frequency.

References

Leonhard Held and Michaela Paul (2012), Modeling Seasonality in Space-time Infectious Disease Surveillance Data, Biometrical Journal, 54(6), 824–843, doi:10.1002/bimj.201200037

Examples

### set-up basis
  cb <- cyclic_basis(numeric_var("x"), order = 3, frequency = 2 * pi)

  ### generate data + coefficients
  x <- data.frame(x = c(0, pi, 2 * pi))

  ### f(0) = f(2 * pi)
  cb(x)

Intercept-Only Basis Function

Description

A simple intercept as basis function

Usage

intercept_basis(ui = c("none", "increasing", "decreasing"), negative = FALSE)

Arguments

ui

a character describing possible constraints

negative

a logical indicating negative basis functions

Details

intercept_basis returns a function for the evaluation of the basis functions with corresponding model.matrix and predict methods.

Examples

### set-up basis
  ib <- intercept_basis()

  ### generate data + coefficients
  x <- as.data.frame(mkgrid(ib))

  ### 2 * 1 
  predict(ib, newdata = x, coef = 2)

Legendre Basis Functions

Description

Basis functions defining a Legendre polynomial

Usage

Legendre_basis(var, order = 2, ui = c("none", "increasing", "decreasing", 
                                      "cyclic", "positive", "negative"), ...)

Arguments

var

a numeric_var object

order

the order of the polynomial, one defines a linear function

ui

a character describing possible constraints

...

additional arguments passed to legendre.polynomials

Details

Legendre_basis returns a function for the evaluation of the basis functions with corresponding model.matrix and predict methods.

References

Rida T. Farouki (2012), The Bernstein Polynomial Basis: A Centennial Retrospective, Computer Aided Geometric Design, 29(6), 379–419, doi:10.1016/j.cagd.2012.03.001.

Examples

### set-up basis
  lb <- Legendre_basis(numeric_var("x", support = c(0, pi)), 
                       order = 3)

  ### generate data + coefficients
  x <- as.data.frame(mkgrid(lb, n = 100))
  cf <- c(1, 2, 2.5, 1.75)

  ### evaluate basis (in two equivalent ways)
  lb(x[1:10,,drop = FALSE])
  model.matrix(lb, data = x[1:10, ,drop = FALSE])

  ### evaluate and plot Legendre polynomial defined by
  ### basis and coefficients
  plot(x$x, predict(lb, newdata = x, coef = cf), type = "l")

Logarithmic Basis Function

Description

The logarithmic basis function

Usage

log_basis(var, ui = c("none", "increasing", "decreasing"),
          remove_intercept = FALSE)

Arguments

var

a numeric_var object

ui

a character describing possible constraints

remove_intercept

a logical indicating if the intercept term shall be removed

Details

log_basis returns a function for the evaluation of the basis functions with corresponding model.matrix and predict methods.

Examples

### set-up basis
  lb <- log_basis(numeric_var("x", support = c(0.1, pi)))

  ### generate data + coefficients
  x <- as.data.frame(mkgrid(lb, n = 100))

  ### 1 + 2 * log(x) 
  max(abs(predict(lb, newdata = x, coef = c(1, 2)) - (1 + 2 * log(x$x))))

Polynomial Basis Functions

Description

Basis functions defining a polynomial

Usage

polynomial_basis(var, coef, ui = NULL, ci = NULL)

Arguments

var

a numeric_var object

coef

a logical defining the order of the polynomial

ui

a matrix defining constraints

ci

a vector defining constraints

Details

polynomial_basis returns a function for the evaluation of the basis functions with corresponding model.matrix and predict methods.

Examples

### set-up basis of order 3 ommiting the quadratic term
  pb <- polynomial_basis(numeric_var("x", support = c(0, pi)), 
                         coef = c(TRUE, TRUE, FALSE, TRUE))

  ### generate data + coefficients
  x <- as.data.frame(mkgrid(pb, n = 100))
  cf <- c(1, 2, 0, 1.75)

  ### evaluate basis (in two equivalent ways)
  pb(x[1:10,,drop = FALSE])
  model.matrix(pb, data = x[1:10, ,drop = FALSE])

  ### evaluate and plot polynomial defined by
  ### basis and coefficients
  plot(x$x, predict(pb, newdata = x, coef = cf), type = "l")

Evaluate Basis Functions

Description

Evaluate basis functions and compute the function defined by the corresponding basis

Usage

## S3 method for class 'basis'
predict(object, newdata, coef, dim = !is.data.frame(newdata), ...)
## S3 method for class 'cbind_bases'
predict(object, newdata, coef, dim = !is.data.frame(newdata), 
         terms = names(object), ...)
## S3 method for class 'box_bases'
predict(object, newdata, coef, dim = !is.data.frame(newdata), ...)

Arguments

object

a basis or bases object

newdata

a list or data.frame

coef

a vector of coefficients

dim

either a logical indicating that the dimensions shall be obtained from the bases object or an integer vector with the corresponding dimensions (the latter option being very experimental

terms

a character vector defining the elements of a cbind_bases object to be evaluated

...

additional arguments

Details

predict evaluates the basis functions and multiplies them with coef. There is no need to expand multiple variables as predict uses array models (Currie et al, 2006) to compute the corresponding predictions efficiently.

References

Ian D. Currie, Maria Durban, Paul H. C. Eilers, P. H. C. (2006), Generalized Linear Array Models with Applications to Multidimensional Smoothing, Journal of the Royal Statistical Society, Series B: Methodology, 68(2), 259–280.

Examples

### set-up a Bernstein polynomial
  xv <- numeric_var("x", support = c(1, pi))
  bb <- Bernstein_basis(xv, order = 3, ui = "increasing")
  ## and treatment contrasts for a factor at three levels
  fb <- as.basis(~ g, data = factor_var("g", levels = LETTERS[1:3]))

  ### join them: we get one intercept and two deviation _functions_
  bfb <- b(bern = bb, f = fb)

  ### generate data + coefficients
  x <- mkgrid(bfb, n = 10)
  cf <- c(1, 2, 2.5, 2.6)
  cf <- c(cf, cf + 1, cf + 2)

  ### evaluate predictions for all combinations in x (a list!)
  predict(bfb, newdata = x, coef = cf)

  ## same but slower
  matrix(predict(bfb, newdata = expand.grid(x), coef = cf), ncol = 3)