null.space.dimension          package:mgcv          R Documentation

The basis of the space of un-penalized functions for a t.p.r.s.

Description:

     The thin plate spline penalties give zero penalty to some
     functions. The space of these functions is spanned by a set of
     polynomial terms. 'null.space.dimension' finds the dimension of
     this space, M, given the number of covariates that the smoother is
     a function of, d, and the order of the smoothing penalty, m. If m
     does not satisfy 2m>d then the smallest possible dimension for the
     null space is found given d and the requirement that the smooth
     should be visually smooth. 'null.space.basis.powers()' produces an
     'M' by 'd' array, the ith row of which gives the powers of each of
     the d covariates featuring in the ith basis term.
     'null.space.basis.names()' gives the equivalent information as a
     list of basis labels - the key feature of which is that the same
     term will always have the same label, irrespective of the order in
     which variables are supplied to the routine. For some models a
     smooth may be multiplied by a 'by' variable: in such cases the
     basis labels can include this name as well, but note that the
     constant label will be returned as if the 'by' variable didn't
     exist (to meet requirements of function 'gam.side.conditions').

Usage:

     null.space.dimension(d,m)
     null.space.basis.powers(m,d)
     null.space.basis.labels(names,m,by="NA")

Arguments:

       d: is a positive integer - the number of variables of which the
          t.p.s. is a function. 

       m: a non-negative integer giving the order of the penalty
          functional, or signalling that the default order should be
          used.

   names: is an array of 'd' variable names

      by: the name of any 'by' variable, which multiplies all the terms
          in the penalty null space basis.

Details:

     Thin plate splines are only visually smooth if the order of the
     wiggliness penalty, m, satisfies 2m > d+1. If 2m<d+1 then this
     routine finds the smallest m giving visual smoothness for the
     given d, otherwise the supplied m is used. The null space
     dimension is given by:

     M=(m+d+1)!/(d!(m-d)!

     which is the value returned.

Value:

     'null.space.dimension' returns an integer (array), the null space
     dimension M: this is the only one of these functions that accepts
     array arguments. 
       'null.space.basis.powers' produces a 2-d array, 'p', say: each
     row corresponds to one of the 'M' basis vectors, while each column
     corresponds to one covariate. So if 'x1', 'x2', 'x3', etc are the
     covariates, the ith basis vector is given by
     'x1^p[i,1]*x2^p[i,2]*x3^p[i,3]...'. 
      'null.space.basis.labels()' just produces uniques labels for the
     basis terms.

WARNING:

     This routine operates symbolically, not numerically: your model
     may still be numerically un-identifiable, and the routine can't
     tell if two variables with different names are really the same.

Author(s):

     Simon N. Wood simon@stats.gla.ac.uk

References:

     Wood, S.N. (2003) Thin plate regression splines. J.R.Statist.Soc.B
     65(1):95-114

     <URL: http://www.stats.gla.ac.uk/~simon/>

See Also:

     'gam.side.conditions', 'gam'

Examples:

     null.space.dimension(2,0)
     null.space.basis.powers(2,2)
     null.space.basis.labels(c("x","z"),m=2)
     null.space.basis.labels(c("z","x"),m=2) # labels are invariant

