# Fit partial one-dimensional, or POD models, based on a linear model

### Description

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.

### Usage

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 | ```
## 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=1: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=1:nlevels(x$group),
pch=1:nlevels(x$group), key="topleft", identify=FALSE,
xlab="Linear Predictor", ylab=as.character(c(formula(x)[[2]])),
...)
``` |

### Arguments

`formula` |
A linear regression formula, as used in lm, or the results of a call to pod or a lm fit. 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 |

`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 |

`...` |
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 |

`xlab` |
Horizontal label, optional |

`ylab` |
Vertical label, optional |

### Details

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.

### Value

If `mean.function="pod"`

, a list of class pod, with the following components

`nls.fit` |
The usual output from a |

`linear.part ` |
The estimated linear predictor |

`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.

### Author(s)

Sanford Weisberg, sandy@stat.umn.edu

### References

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

Weisberg, S. (2005) *Applied Linear Regression*, third edition. New York:
Wiley.

### See Also

See Also `nls`

, `lm`

, `nls.control`

### Examples

1 2 3 4 5 6 |