pod                   package:alr3                   R Documentation

_F_i_t _p_a_r_t_i_a_l _o_n_e-_d_i_m_e_n_s_i_o_n_a_l, _o_r _P_O_D _m_o_d_e_l_s, _b_a_s_e_d _o_n _a _l_i_n_e_a_r _m_o_d_e_l

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

     A partial one-dimensional model, or a POD model, provides a
     concise description of a regression model with many predictors and
     one grouping variable.  It requires a  nonlinear regression fit.

_U_s_a_g_e:

     ## This is a generic function with different arguments depending on the class of the
     ## first argument.  The generic form is

     pod (x, ...)

     ## If the first argument to pod is a formula suitable for defining a linear model,

     ## S3 method for class 'formula':
     pod(formula, data = sys.parent(), group, subset, weights, 
         na.action, mean.function = c("pod", "common", "parallel", 
             "general"), singular.ok = FALSE, contrasts = NULL, offset, 
         control = nls.control(), ...) 

     ## If the first argument to pod is the result of a linear model fit, the following
     ## function call is used.  All the arguments for pod.formula can also be passed to
     ## pod.lm.

     ## S3 method for class 'lm':
     pod (x, group, mean.function, control, ...)   
         
     ## The following related function require a pod fit as the first argument:
         
     ## S3 method for class 'pod':
     anova(object,scale=0,test="F",...)

     ## S3 method for class 'pod':
     plot(x, colors=rainbow(nlevels(x$group)),
       pch=1:nlevels(x$group),key="topleft",identify=FALSE,
       xlab="Linear Predictor", ylab=as.character(c(formula(x)[[2]])),
       ...)
      
     ## S3 method for class 'pod.lm':
     plot(x, colors=rainbow(nlevels(x$group)),
           pch=1:nlevels(x$group),key="topleft",identify=FALSE,
           xlab="Linear Predictor", ylab=as.character(c(formula(x)[[2]])),
           ...) 

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

 formula: A linear regression formula, as used in lm, or the results of
          a call to pod.  See details below.

       x: The result of a lm fit from which the formula and the
          arguments data, subset, weights, na.action, singular.ok,
          contrasts and offset will be taken.

    data: An optional data frame for the data to be used

   group: The name of a grouping variable (not quoted) that defines the
          groups; see details below.

mean.function: Which mean function should be fit?   The default is
          "pod", that fits the partial one-dimensional mean function. 
          The other options are  "common", which fits a linear model
          with no grouping effects; "parallel" fits a parallel
          within-group regression, and "general", available in pod but
          not plot.pod, fits a separate coefficeint for each term in
          the model for each level of the grouping variable.

  subset: As in lm, the subset of cases to be used in the analysis 

 weights: Weights will be used in fitting non-pod models.  Since this
          argument is not supported for nls models, weights are ignored
          for fitting pod models.  If nls is ever updated, then pod
          models will correctly use the weights.

na.action: At present, only na.omit is likely to work. 

singular.ok: The default equal to 'FALSE' is recommended.

contrasts: Same as in lm 

  offset: Same as in lm 

 control: A pod model is fit using the nonlinear least squares routine
          nls. This routine is very sensitive to starting values and
          other parameters set in the algorithm.  This routine selects
          starting values for you that will often work very well, but
          in some problems the user may want to change the defaults to
          nls program  using the 'nls.control' function.

     ...: In pod, other arguments passed to nls, such as control 
          parameters. In pod.anova, there are two additional arguments 

  object: The result of a call to pod.

   scale: Used for test in anova

    test: Default is to compute F tests.

  colors: Colors for groups in the pod plot

     pch: Ploting symbol for the groups in the pod plot

identify: If TRUE, clicking the mouse on a graph will print the case
          name of the nearest point.  This continues until turned off
          (by pushing the escape key, among other ways of doing this).

     key: The default is '"topleft"', in which case a legend is added
          to the top left corner of the plot; other choices include
          '"bottomright"'. If 'key' is a vector of two coordinates, the
          legend is drawn at the coordinates specified. If 'key' is
          FALSE, no key is drawn; if TRUE, you can place the key
          interactively by clicking on the plot.

    xlab: Horizontal label, optional

    ylab: Vertical label, optional

_D_e_t_a_i_l_s:

     Suppose we start with a linear mean function specified by
     'y~x1+x2+x3', where the right-side variables can be any valid R
     variables, such as transformations, but NOT factors or
     interactions (if you want to include these, you need to create the
     dummy variables yourself).  The right-hand side variables must
     also be linearly independent.  We also specify a grouping variable
     z with, say, g levels.  Let  Gi be a dummy variable with values
     equal to 1 when z=i, and  zero otherwise.  The pod mean function
     is then has the nonlinear mean function

              b0+ b'x + sum(j=2,g) Gj(th0j + th1j(b'x))

     This is a nonlinear mean function that specifies that the response
     depends on the predictors only through one linear combination,
     that the dependence is linear, but the slope and intercept may be
     different for each group.

     The pod mean function is easily fit using 'nls'.  For example, if
     z has two levels, a nonlinear mean function that would work is
     'y~b0+b1*x1+b2*x2+b3*x3+G2*(th02+th12*(b1*x1+b2*x2+b3*x3))'.
     Starting values can be determined by fitting the parallel mean
     function, for this is a linear mean function and easily fit.

     The function 'pod' automates this process; you need only input the
     linear part of the mean function, and 'pod' does the rest.

     The function 'anova.pod' is a little different from the generic
     anova  function.  It   fits and compares all four mean functions
     that can be fit with the pod function:  (1) no group effect; (2)
     parallel within group method; (3) pod mean function; (4) mean
     function with all main effects and  two-factor interactions with
     the grouping variable.

     The function 'plot' will plot the response versus the fitted
     linear  combination for either the common, parallel or pod models.
      There is no 2D plot for the general model.

     Objects of class pod have methods defined for the generic
     functions 'print', 'summary', 'coef', 'anova', 'deviance', 'vcov',
     'resid', 'formula', 'fitted', 'df.residual' and 'predict'. 
     'podresponse' returns the values of the response.

_V_a_l_u_e:

     If 'mean.function="pod"', a list of class pod, with the following
     components 

 nls.fit: The usual output from a 'nls' fit.

linear.part : The estimated linear predictor bhat'x.

    call: The original call to pod

   group: The grouping variable


     If 'mean.function' has any other value, an object of class
     c("pod.lm", "lm") is returned.  Since the only method for pod.lm
     objects is a plotting method,  except for plotting these objects
     behave like lm objects.

_A_u_t_h_o_r(_s):

     Sanford Weisberg, sandy@stat.umn.edu

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

     Cook, R. D. and Weisberg, S. (2004).  Partial-one dimensinal
     models. \em{American Statistician}, 58, 110-116.

     Weisberg, S. (2005) \em{Applied Linear Regression}, third edition.
      New York:  Wiley.

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

     See Also 'nls', 'lm', 'nls.control'

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

     data(ais)
     m1 <- pod(LBM ~ Ht + Wt + RCC, data= ais, group= Sex)
     anova(m1) # compare four models
     plot(m1) # draw the plot
     m2 <- update(m1, mean.function="parallel")
     plot(m2,key=c(55,95))

