smooth.construct.tp.smooth.spec     package:mgcv     R Documentation

_P_e_n_a_l_i_z_e_d _t_h_i_n _p_l_a_t_e _r_e_g_r_e_s_s_i_o_n _s_p_l_i_n_e_s _i_n _G_A_M_s

_D_e_s_c_r_i_p_t_i_o_n:

     'gam' can use isotropic smooths of any number of variables,
     specified via terms like 's(x,z,bs="tp",m=3)' (or just 's(x,z)' as
     this is the default basis). These terms are based on thin plate 
     regression splines. 'm' specifies the order of the derivatives in
     the thin plate spline penalty.

     Thin plate regression splines are constructed by starting with the
     basis and penalty for a full thin plate spline and then truncating
     this basis in an optimal manner, to obtain a low rank smoother.
     Details are given in Wood (2003). One key advantage of the
     approach is that it avoids the knot placement problems of
     conventional regression spline modelling, but it also has the
     advantage that smooths of lower rank are nested within smooths of
     higher rank, so that it is legitimate to use conventional
     hypothesis testing methods to compare models based on pure
     regression splines. Note that the basis truncation does not change
     the  meaning of the thin plate spline penalty (it penalizes
     exactly what it  would have penalized for a full thin plate
     spline). 

     The t.p.r.s. basis and penalties can become expensive to calculate
     for large datasets. For this reason the default behaviour is to
     randomly subsample 'max.knots' unique data locations if there are
     more than 'max.knots' such, and to use the sub-sample for basis
     construction. The sampling is always done with the same random
     seed to ensure repeatability (does not reset R RNG). 'max.knots'
     is 3000, by default. Both seed and 'max.knots' can be modified
     using the 'xt' argument to 's'. Alternatively the user can supply
     knots from which to construct a basis. 

     The '"ts"' smooths are t.p.r.s. with the penalty modified so that
     the term is shrunk to zero  for high enough smoothing parameter,
     rather than being shrunk towards a function in the  penalty null
     space (see details).

_U_s_a_g_e:

     ## S3 method for class 'tp.smooth.spec':
     smooth.construct(object, data, knots)
     ## S3 method for class 'ts.smooth.spec':
     smooth.construct(object, data, knots)

_A_r_g_u_m_e_n_t_s:

  object: a smooth specification object, usually generated by a term
          's(...,bs="tp",...)' or  's(...,bs="ts",...)'

    data: a list containing just the data (including any 'by' variable)
          required by this term,  with names corresponding to
          'object$term' (and 'object$by'). The 'by' variable  is the
          last element.

   knots: a list containing any knots supplied for basis setup - in
          same order and with same names as 'data'.  Can be 'NULL'

_D_e_t_a_i_l_s:

     The default basis dimension for this class is 'k=10*3^(d-1)' where
     'd' is the number of covariates for the term. This is essentially
     arbitrary, and should be checked.

     The default is to set 'm' (the order of derivative in the thin
     plate spline penalty) to the smallest value satisfying '2m > d+1'
     where 'd' if the number of covariates of the term: this yields
     `visually smooth' functions. In any case '2m>d' must be satisfied. 

     The constructor is not normally called directly, but is rather
     used internally by 'gam'.  To use for basis setup it is
     recommended to use 'smooth.construct2'.  

     For these classes the specification 'object' will contain
     information on how to handle large datasets in their 'xt' field.
     The default is to randomly subsample 3000 `knots' from which to
     produce a tprs basis, if the number of unique predictor variable
     combinations in excess of 3000. The default can be modified via
     the 'xt' argument to 's'. This is supplied as a list with elements
     'max.knots' and 'seed' containing a number to use in place of
     3000, and the random number seed to use (either can be missing). 

     For these bases 'knots' has two uses. Firstly, as mentioned
     already, for large datasets  the calculation of the 'tp' basis can
     be time-consuming. The user can retain most of the advantages of
     the t.p.r.s.  approach by supplying  a reduced set of covariate
     values from which to obtain the basis -  typically the number of
     covariate values used will be substantially  smaller than the
     number of data, and substantially larger than the basis dimension,
     'k'. This approach is  the one taken automatically if the number
     of unique covariate values (combinations) exceeds 'max.knots'. The
     second possibility  is to avoid the eigen-decomposition used to
     find the t.p.r.s. basis altogether and simply use  the basis
     implied by the chosen knots: this will happen if the number of
     knots supplied matches the  basis dimension, 'k'. For a given
     basis dimension the second option is  faster, but gives poorer
     results (and the user must be quite careful in choosing knot
     locations).

     The shrinkage version of the smooth, eigen-decomposes the
     wiggliness penalty matrix, and sets its zero eigenvalues to small 
     multiples of the smallest strictly positive eigenvalue. The
     penalty is then set to the matrix with eigenvectors corresponding 
     to those of the original penalty, but eigenvalues set to the
     peturbed versions. This penalty matrix has full rank and shrinks 
     the curve to zero at high enough smoothing parameters.

_V_a_l_u_e:

     An object of class '"tprs.smooth"' or '"ts.smooth"'. In addition
     to the usual elements of a  smooth class documented under
     'smooth.construct', this object will contain: 

   shift: A record of the shift applied to each covariate in order to
          center it around zero and  avoid any co-linearity problems
          that might otehrwise occur in the penalty null space basis of
          the term. 

      Xu: A matrix of the unique covariate combinations for this smooth
          (the basis is constructed by first stripping  out duplicate
          locations).

      UZ: The matrix mapping the t.p.r.s. parameters back to the
          parameters of a full thin plate spline.

null.space.dimension: The dimension of the space of functions that have
          zero wiggliness according to the  wiggliness penalty for this
          term.

_A_u_t_h_o_r(_s):

     Simon N. Wood simon.wood@r-project.org

_R_e_f_e_r_e_n_c_e_s:

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

_E_x_a_m_p_l_e_s:

     ## see ?gam