smoothCon                package:mgcv                R Documentation

_P_r_e_d_i_c_t_i_o_n/_C_o_n_s_t_r_u_c_t_i_o_n _w_r_a_p_p_e_r _f_u_n_c_t_i_o_n_s _f_o_r _G_A_M _s_m_o_o_t_h _t_e_r_m_s

_D_e_s_c_r_i_p_t_i_o_n:

     Wrapper functions for construction of and prediction from smooth
     terms in a GAM. The purpose of the wrappers is to allow
     user-transparant re-parameterization of smooth terms, in order to
     allow identifiability constraints to be absorbed into the
     parameterization of each term, if required. The routine also
     handles `by' variables and construction of identifiability
     constraints automatically,  although this behaviour can be
     over-ridden.

_U_s_a_g_e:

     smoothCon(object,data,knots,absorb.cons=FALSE,
               scale.penalty=TRUE,n=nrow(data),dataX=NULL,
               null.space.penalty=FALSE)
     PredictMat(object,data,n=nrow(data))

_A_r_g_u_m_e_n_t_s:

  object: is a smooth specification object or a smooth object.

    data: A data frame, model frame or list containing the values of
          the  (named) covariates at which the smooth term is to be 
          evaluated. If it's a list then 'n' must be supplied.

   knots: An optional data frame supplying any knot locations to be
          supplied for basis construction.

absorb.cons: Set to 'TRUE' in order to have identifiability constraints
          absorbed into the basis.

scale.penalty: should the penalty coefficient matrix be scaled to have
          approximately the same `size' as the inner product of the
          terms model matrix with itself? This can improve the
          performance of 'gamm' fitting.

       n: number of values for each covariate, or if a covariate is a
          matrix,  the number of rows in that matrix: must be supplied
          explicitly if 'data' is a list. 

   dataX: Sometimes the basis should be set up using data in 'data',
          but the model matrix should be constructed with another set
          of data provided in 'dataX' - 'n' is assumed to  be the same
          for both. Facilitates smooth id's.

null.space.penalty: Should an extra penalty be added to the smooth
          which will penalize the  components of the smooth in the
          penalty null space: provides a way of penalizing terms out of
          the model altogether.

_D_e_t_a_i_l_s:

     These wrapper functions exist to allow smooths specified using
     'smooth.construct' and 'Predict.matrix' method functions to be
     re-parameterized so that identifiability constraints are no longer
     required in fitting. This is done in a user transparent manner,
     but is typically of no importance in use of GAMs. The routine's 
     also handle 'by' variables and will create default identifiability
      constraints.

     If a user defined smooth constructor handles 'by' variables
     itself, then its  returned smooth object should contain an object
     'by.done'. If this does not exist  then 'smoothCon' will use the
     default code. Similarly if a user defined 'Predict.matrix'  method
     handles 'by' variables internally then the returned matrix should
     have a  '"by.done"' attribute.

     Default centering constraints, that terms should sum to zero over
     the covariates, are produced unless  the smooth constructor
     includes a matrix 'C' of constraints. To have no constraints (in
     which case  you had better have a full rank penalty!) the matrix
     'C' should have no rows.

     'smoothCon' returns a list of smooths because factor 'by'
     variables result in multiple copies  of a smooth, each multiplied
     by the dummy variable associated with one factor level.
     'smoothCon' modifies  the smooth object labels in the presence of
     'by' variables, to ensure that they are unique, it also stores 
     the level of a by variable factor associated with a smooth, for
     later use by 'PredMat'.

     The parameterization used by 'gam' can be controlled via
     'gam.control'.

_V_a_l_u_e:

     From 'smoothCon' a list of 'smooth' objects returned by the
     appropriate 'smooth.construct' method function. If constraints are
     to be absorbed then the objects will have  attributes '"qrc"' and
     '"nCons"', the qr decomposition of the constraint matrix (returned
     by 'qr') and the number of constraints, respectively: these are 
     used in the re-parameterization. 

     For 'predictMat' a matrix which will map the parameters associated
     with the smooth to the vector of values of the smooth evaluated at
     the covariate values given in 'object'.

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

     <URL: http://www.maths.bath.ac.uk/~sw283/>

_S_e_e _A_l_s_o:

     'gam.control', 'smooth.construct', 'Predict.matrix'