\HeaderA{residuals.coxph}{Calculate Residuals for a `coxph' Fit}{residuals.coxph}
\methaliasA{residuals.coxph.null}{residuals.coxph}{residuals.coxph.null}
\methaliasA{residuals.coxph.penal}{residuals.coxph}{residuals.coxph.penal}
\keyword{survival}{residuals.coxph}
\begin{Description}\relax
Calculates martingale, deviance, score or Schoenfeld residuals for a
Cox proportional hazards model.
\end{Description}
\begin{Usage}
\begin{verbatim}
## S3 method for class 'coxph':
residuals(object,
       type=c("martingale", "deviance", "score", "schoenfeld",
              "dfbeta", "dfbetas", "scaledsch","partial"),
       collapse=FALSE, weighted=FALSE, ...)
## S3 method for class 'coxph.null':
residuals(object,
       type=c("martingale", "deviance","score","schoenfeld"),
       collapse=FALSE, weighted=FALSE, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{object}] an object inheriting from class \code{coxph}, representing a fitted Cox
regression model.
Typically this is the output from the \code{coxph} function.

\item[\code{type}] character string indicating the type of residual desired.
Possible values are \code{"martingale"}, \code{"deviance"}, \code{"score"}, \code{"schoenfeld"},
"dfbeta"', \code{"dfbetas"}, and \code{"scaledsch"}.
Only enough of the string to determine a unique match is required.

\item[\code{collapse}] vector indicating which rows to collapse (sum) over.
In time-dependent models more than one row data can pertain
to a single individual.
If there were 4 individuals represented by 3, 1, 2 and 4 rows of data
respectively, then \code{collapse=c(1,1,1, 2, 3,3, 4,4,4,4)} could be used to
obtain per subject rather than per observation residuals.

\item[\code{weighted}] if \code{TRUE} and the model was fit with case weights, then the weighted
residuals are returned.

\item[\code{...}] other unused arguments
\end{ldescription}
\end{Arguments}
\begin{Value}
For martingale and deviance residuals, the returned object is a vector
with one element for each subject (without \code{collapse}).
For score residuals it is a matrix
with one row per subject and one column per variable.
The row order will match the input data for the original fit.
For Schoenfeld residuals, the returned object is a matrix with one row
for each event and one column per variable.  The rows are ordered by time
within strata, and an attribute \code{strata} is attached that contains the
number of observations in each strata.
The scaled Schoenfeld residuals are used in the \code{cox.zph} function.


The score residuals are each individual's contribution to the score vector.
Two transformations of
this are often more useful: \code{dfbeta} is the approximate change in the
coefficient vector if that observation were dropped,
and \code{dfbetas} is the approximate change in the coefficients, scaled by
the standard error for the coefficients.
\end{Value}
\begin{Section}{NOTE}
For deviance residuals, the status variable may need to be reconstructed.
For score and Schoenfeld residuals, the X matrix will need to be reconstructed.
\end{Section}
\begin{References}\relax
T. Therneau, P. Grambsch, and T. Fleming. "Martingale based residuals
for survival models", \emph{Biometrika}, March 1990.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{coxph}{coxph}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}

 fit <- coxph(Surv(start, stop, event) ~ (age + surgery)* transplant,
               data=heart)
 mresid <- resid(fit, collapse=heart$id)
\end{ExampleCode}
\end{Examples}