

polymars(polymars)                           R Documentation

_M_u_l_t_i_-_r_e_s_p_o_n_s_e _M_u_l_t_i_v_a_r_i_a_t_e _A_d_a_p_t_i_v_e _R_e_g_r_e_s_s_i_o_n _S_p_l_i_n_e_s

_D_e_s_c_r_i_p_t_i_o_n_:

     is.polymars and summary.polymars are available.
     print.polymars defaults to summary.polymars.

_U_s_a_g_e_:

     polymars(responses, predictors, weights, maxsize, gcv=4, additive=F,
     startmodel, no.interact, knots, knot.space=3, ts.resp, ts.pred,
     ts.weights, classify, factors, tolerance, verbose=F)

_A_r_g_u_m_e_n_t_s_:

responses: vector of responses, or a matrix for multiple
          response regression.  In the case of a matrix each
          column corresponds to a response and each row cor-
          responds to an observation. Missing values are not
          allowed.

predictors: matrix of predictor variables for the regres-
          sion. Each column corresponds to a predictor and
          each row corresponds to an observation in the same
          order as they appear in the response argument.
          Missing values are not allowed.

 weights: vector of observation weights; if supplied, the
          algorithm fits to minimize the sum of the weights
          multiplied by the squared residuals.  The length
          of weights must be the same as the number of
          observations. The weights must be nonnegative.

 maxsize: the maximum number of basis functions that the
          model is allowed to grow to in the stepwise addi-
          tion procedure. The default is min(6*(num-
          ber.of.observations^(1/3)),number.of.observa-
          tions/4,100).

     gcv: parameter used to find the overall best model from
          a sequence of fitted models.  The residual sum of
          squares of a model is penalized by dividing by the
          square of 1-(gcv x model size)/cases.  A larger
          gcv value would tend to produce a smaller model.
          By default gcv is set to 4.

additive: Should the fitted model be additive in the predic-
          tors?

startmodel: the first model that is to be fit by the poly-
          mars function. It is either an object of the class
          polymars or a model specified by the user.  In
          that case, it takes the form of a 4 x n matrix (n
          = number of basis functions in the starting model
          excluding the intercept term). Each row corre-
          sponds to one basis function (with two possible
          components). Column 1 is the index of the first
          predictor involved. Column 2 is a possible knot in
          this predictor. If column 2 is NA, the first com-
          ponent is linear. Column 3 is the possible second
          predictor involved (if column 3 is NA the basis
          function only depends on one predictor). Column 4
          contains the possible knot for the predictor in
          column 3, and it is NA when this component is lin-
          ear.  Example: if a row reads 3 NA 2 4.7, the cor-
          responding basis function is [X3 * (X2-4.7)_+]; if
          a row reads 2 4.3 NA NA the corresponding basis
          function is [(X2-4.3)_+].

          A fifth column can be added with 1's and 0's, The
          1's specify which basis functions of the start-
          model must be in each model. Thus, these functions
          stay in the model during the whole stepwise fit-
          ting procedure.

          If no startmodel is specified polymars starts with
          a model that only contains the intercept.

no.interact: a matrix used if certain predictor interactions
          are not allowed in the model.  It is given as a
          matrix (2 * m), with predictor indices as entries.
          The two predictors of any row cannot have interac-
          tion terms with each other.

   knots: defines how the function is to find potential
          knots for the spline basis functions.  This can be
          set to the maximum number of knots you would like
          to be considered for each predictor.  Usually, to
          avoid the design matrix becoming singular the
          actual number of knots produced is constrained to
          at most every third order statistic in any predic-
          tor. This constraint can be adjusted using the
          `knot.space' argument.  It can also be a vector
          with the number of potential knots for each pre-
          dictor.  Again the actual number of knots produced
          is constrained to be at most every third order
          statistic any predictor.  A third possibility is
          to provide a matrix where each columns corresponds
          to the ordered knots you would like to have con-
          sidered for that predictor.  This matrix should be
          filled out to a rectangular data structure with
          NAs.  The default is min(20,round(ncases/4)) knots
          per predictor.

          When specifying knots as a vector an entry of -1
          indicates that the predictor is a categorical
          variable and each unique entry in it's column is
          treated as a level.

          When specifying knots as a single number or a
          matrix and there are categorical variables these
          are specified separately as such using the factor
          argument.

knot.space: is an integer describing the minimum number of
          order statistics apart that two knots can be.
          Knots should not be too close to insure numerical
          stability.  The default is 3.

 ts.resp: testset responses for model selection. Should have
          the same number of columns as the training set
          response. A testset can be used for the model
          selection.  Depending on the value of classify,
          either the model with the smallest testset resid-
          ual sum of squares or the smallest testset classi-
          fication error is provided.  Overrides gcv.

 ts.pred: testset predictors. Should have the same number of
          columns as the training set predictors.

ts.weights: testset observation weights. A vector of length
          equal to the number of cases of the testset. All
          weights must be non-negative.

classify: when the response is discrete (categorical), poly-
          mars can be used for classification. In particu-
          lar, when classify = T, a discrete response with K
          levels is replaced by K indicator variables as
          response. Model selection is still being carried
          out using gcv, except when a testset is provided,
          in which case testset misclassification is used to
          select the best model.

 factors: used to indicate that certain variables in the
          predictor set are categorical variables. Specified
          as a vector containing the appropriate predictor
          indices (column numbers of categorical variables
          in predictors matrix). Factors can also be set
          when the "knots" argument is given as a vector,
          with -1 as the appropriate entries for factors.

tolerance: for each possible candidate to be added/deleted
          the resulting residual sums of squares of the
          model, with/without this candidate, must be calcu-
          lated.  The inversion of of the "X-transpose by X"
          matrix, X being the design matrix, is done by an
          updating procedure c.f. C.R. Rao - Linear Statis-
          tical Inference and Its Applications, 2nd. edi-
          tion, page 33.  In the inversion the size of the
          bottom right-hand entry of this matrix is criti-
          cal. If it's value is near zero or the value of
          it's inverse is almost zero then the inversion
          procedure becomes somewhat inaccurate. The lower
          the tolerance value the more careful the procedure
          is in selecting candidates for addition to the
          model but it may exclude too conservatively. And
          the other hand if the tolerance is set too high a
          spurious result with a singular or otherwise sub-
          optimal model may occur. By default tolerance is
          set to 1.0e-5.

 verbose: when set =T, the function will print out a line
          for each addition or deletion stage. For example,
          " + 8 : 5 3.25 2 NA" means adding interaction
          basis function of predictor 5 with knot at 3.25
          and predictor 2 (linear), to make a model of size
          8, including intercept.

_V_a_l_u_e_:

     The returned object contains information about the fit-
     ting steps and the model selected. The first data frame
     contains a row for each step of the fitting procedure.
     In the columns are: a 1 for an addition step or a 0 for
     a deletion step, the size of the model at each step,
     residual sums of squares (RSS) and the generalized
     cross validation value (GCV), testset residual sums of
     squares or testset misclassification, whatever was used
     for the model selection.

     The second data frame, model, contains a row for each
     basis function of the model. Each row corresponds to
     one basis function (with two possible components). The
     pred1 column contains the indices of the first predic-
     tor of the basis function. Column knot1 is a possible
     knot in this predictor. If this column is NA, the first
     component is linear. If any of the basis functions of
     the model is categorical then there will be a level1
     column. Column pred2 is the possible second predictor
     involved (if it is NA the basis function only depends
     on one predictor). Column knot2 contains the possible
     knot for the predictor pred2, and it is NA when this
     component is linear. This is a similar format to the
     startmodel argument together with an additional first
     row corresponding to the intercept but the startmodel
     doesn't use a separate column to specify levels of a
     categorical variable . If any predictor in pred2 is
     categorical then there will be a level2 column. The
     column "coefs" (more than one column in the case of
     multiple response regression) contains the coeffi-
     cients.

     The returned object also contains the fitted values and
     residuals of the data used in fitting the model.

_R_e_f_e_r_e_n_c_e_s_:

     Friedman, J. H. (1991). Multivariate adaptive regres-
     sion splines (with discussion).  The Annals of Statis-
     tics, 19, 1-141.

     Kooperberg, C., Bose, S. and Stone, C. J. (1997). Poly-
     chotomous Regression.  Journal of the American Statis-
     tical Association, 92,  - .

_S_e_e _A_l_s_o_:

     plot.polymars, predict.polymars, summary.polymars

_E_x_a_m_p_l_e_s_:

     state.pm<-polymars(state.region,state.x77,knots=15,classify=T)

     data<-na.omit(auto.stats)
     auto.pm<-polymars(data[1:40,1],data[1:40,-1],factor=c(2,3),ts.pred=data[41:66,-1],ts.resp=data[41:66,1],maxsize=40)

