Documentation  CRAN
Evolution
rms
is an R package that is a replacement for the
Design
package. The package accompanies
FE Harrell's book
Regression Modeling Strategies.
rms
does not use any C level
interfaces to other packages as
Design
did to the
survival
package. Thus
rms
will be easier to maintain.
rms
has cleaned up graphics routines to make them more modular, to use
lattice
graphics, and to make it easier
to use
ggplot2
graphics. Defaults for confidence bands are now gray scaleshaded polygons. Starting with version 5.00
plotly
interactive graphics and HTML output are implemented for many of the functions.
UserVisible Changes
The most visible change to the user is the replacement of the
plot.Design
function with the
Predict
,
plot.Predict
, and
bplot
functions.
plot.Predict
is used for bivariate graphics (using
lattice
), and
bplot
is used for 3d graphics using base graphics functions
image
,
contour
, and
persp
. Multipanel
lattice
graphics are usually better than 3d graphics for showing the effects of multiple
predictors varying simultaneously. The output of
Predict
is suitable for direct use by
lattice
(e.g., the
xyplot
function) and
ggplot2
if you don't want to use
plot.Predict
.
As of version 2.20, the user will not longer specify predictor=. or predictor=NA when a predictor is varying over its detault range in
Predict, summary, nomogram, survplot, gendata
. Instead, just list the predictor name in the call. There is also a
ggplot
method.
rms
also implements a highlevel interface to the
quantreg
package through the new
Rq
function for quantile regression.
With version 3.10 a significant change is the addition of a
latex
argument to
print
methods for fit objects. This causes the fit object to be typeset using LaTeX.
Unlike
Design
, beginning with version 3.21 the
rms
validate
and
calibrate
functions do not print summaries of which variables were selected if
bw
is
TRUE
. This is left up to the print methods.
The linear predictor stored in
lrm
fit objects now uses the first intercept for proportional odds models and not the middle one.
Other new features include bootstrap nonparametric confidence bands for predicted values, simultaneous confidence bands, and simultaneous contrasts.
Example Changes Needed for Plotting Predicted Values
plot(fit, x1=NA, x2=NA, ...) changed to
p < Predict(fit, x1, x2, ...)
plot(p) # ?plot.Predict for details; produces a lattice object
print(plot(p)) # needed if using Sweave or are inside { }
plot(p, ~ x1  x2)
plot(p, ~ x1  groups='x2')
ggplot(p)
plot(fit, .., method='image' or 'contour' or 'persp') changed to
p < Predict(..., np=50) # type ?Predict for details
bplot(p, ...) # ?bplot for details; uses lattice graphics; can also give a formula

datadensity
is no longer a separate function to use after the predictions are plotted; the user specifies data= to plot.Predict
to get a rug plot, for example.

Legend
was changed to iLegend

nomogram
does not plot by default. You must use plot(nomogram result)
to plot, and the plotting arguments are separated into the arguments for plot.nomogram
.

survplot
defaults to conf='bands' and this now produces shaded confidence bands instead of bands made by pairs of lines

Varcov
is changed to the more Rbase concordant vcov

glmD
is renamed Glm

glsD
is renamed Gls

Rq
allows fitting of quantile regression models with the full complement of rms
capabilities including restricted cubic splines for covariates, restricted interaction surfaces, effect plots, bootstrap covariance estimation, and nomograms
Other Changes
Less visible to the user are the following changes:
 Removed all uses of
single()
or storage.mode
'single'
 Removed all use of
.newSurvival

predictDesign
changed to predictrms
, added ref.zero argument
 There is no longer a generic
nomogram
function, so nomogram.Design
was renamed nomogram
To Do
 When bug fixed in survfit.coxph.null remove n.all stuff
 Make
Function.rms
and latex.rms
work when the model contains terms like rcs()*rcs() (thanks: Rob James 30Aug10)
Substantial Correction to Hmisc package fit.mult.impute
function
In May 2013 a correction was made for an upcoming release of the Hmisc package that fixes a major error in covariance matrix calculation when
fit.mult.impute
was used with
glm
. The covariance matrix returned from
vcov
and used in a variety of other
rms
functions was incorrect, not referring to imputationcorrected estimates
Recent Changes
Changes in version 4.00 (20130710)
 Cleaned up label logic in Surv, made it work with interval2 (thanks:Chris Andrews)
 Fixed bug in val.prob  wrong denominator for Brier score if obs removed for logistic calibration
 Fixed inconsistency in predictrms where predict() for Cox models used a design matrix that was centered on medians and modes rather than means (thanks: David van Klaveren <d.vanklaveren.1@erasmusmc.nl>)
 Added mean absolute prediction error to Rq output
 Made pr argument passed to predab.resample more encompassing
 Fixed logLik method for ols
 Made contrast.rms and summary.rms automatically compute bootstrap nonparametric confidence limits if fit was run through bootcov
 Fixed bug in Predict where conf.type='simultaneous' was being ignored if bootstrap coefficients were present
 For plot.Predict made default gray scale shaded confidence bands darker
 For bootcov exposed eps argument to fitters and default to lower value
 Fixed bug in plot.pentrace regarding effective.df plotting
 Added setPb function for popup progress bars for simulations; turn off using options(showprogress=FALSE) or options(showprogress='console')
 Added progress bars for predab.resample (for validate, calibrate) and bootcov
 Added bootBCa function
 Added seed to bootcov object
 Added boot.type='bca' to Predict, contrast.rms, summary.rms
 Improved summary.rms to use t critical values if df.residual defined
 Added simultaneous contrasts to summary.rms
 Fixed calculation of Brier score, g, gp in lrm.fit by handling special case of computing linear predictor when there are no predictors in the model
 Fixed bug in prModFit preventing successful latex'ing of penalized lrms
 Removed \synopsis from two Rd files
 Added prmodsel argument to predab.resample
 Correct Rd files to change Design to rms
 Restricted NAMESPACE to functions expected to be called by users
 Improved Fortran code to use better dimensions for array declarations
 Added the basic bootstrap for confidence limits for bootBCa, contrast, Predict, summary
 Fixed bug in latex.pphsm, neatened pphsm code
 Neatened code in rms.s
 Improved code for bootstrapping ranks of variables in anova.rms help file
 Fixed bug in Function.rms  undefined Nami if strat. Thanks: douglaswilkins@yahoo.com
 Made quantreg be loaded at end of search list in Rq so it doesn't override latex generic in Hmisc
 Improved plot.summary.rms to use blue of varying transparency instead of polygons to show confidence intervals, and to use only three confidence levels by default: 0.9 0.95 0.99
 Changed Surv to Srv; use of Surv in fitting functions will result in lack of time labels and assumption of Day as time unit; no longer override Surv in survival
 Changed calculation of Dxy (and cindex) to use survival package survConcordance service function when analyzing (censored) survival time; very fast
 Changed default dxy to TRUE in validate.cph, validate.psm
 Dxy is now negated if correlating Cox model log relative hazard with survival time
 Removed dxy argument from validate.bj as it always computed
 Added Dxy to standard output of cph, psm
 Added help file for Srv
 Removed reference to ps.slide from survplot help page
 Added the general ordinal regression fitting function orm (and orm.fit) which efficiently handles thousands of intercepts because of sparse matrix representation of the information matrix; implements 5 distribution families
 Added associated functions print.orm, vcov.orm, predict.orm, Mean.orm, Quantile.orm, latex.orm, validate.orm
 Changed predab.resample to allow number of intercepts from resample to resample
 Fixed bug in Mean.cph (thanks: Komal Kapoor <komal.bitsgoa@gmail.com>)
 Removed incl.non.slopes and non.slopes arguments from all predict methods
 Changed all functions to expect predict(..., type='x') to not return intercept columns, and all fitting functions to not store column of ones if x=TRUE
 Changed nomogram argument intercept to kint, used default as fit$interceptRef
 Made bootcov behave in a special way for orm, to use linear interpolation to select a single intercept targeted at median Y
 Revamped all of rms to never store intercepts in design matrices in fit objects and to add intercepts on demand inside predictrms
 Added new function generator ExProb to compute exceedance probabilities from orm fits
Changes in version 3.70 (20130318)
 Cleaned up label logic in Surv, made it work with interval2 (thanks:Chris Andrews)
 Fixed bug in val.prob  wrong denominator for Brier score if obs removed for logistic calibration
 Fixed inconsistency in predictrms where predict() for Cox models used a design matrix that was centered on medians and modes rather than means (thanks: David van Klaveren <d.vanklaveren.1@erasmusmc.nl>)
 Added mean absolute prediction error to Rq output
 Made pr argument passed to predab.resample more encompassing
 Fixed logLik method for ols
 Made contrast.rms and summary.rms automatically compute bootstrap nonparametric confidence limits if fit was run through bootcov
 Fixed bug in Predict where conf.type='simultaneous' was being ignored if bootstrap coefficients were present
 For plot.Predict made default gray scale shaded confidence bands darker
 For bootcov exposed eps argument to fitters and default to lower value
 Fixed bug in plot.pentrace regarding effective.df plotting
 Added setPb function for popup progress bars for simulations
 Added progress bars for predab.resample (for validate, calibrate) and bootcov
 Added bootBCa function
 Added seed to bootcov object
 Added boot.type='bca' to Predict, contrast.rms, summary.rms
 Improved summary.rms to use t critical values if df.residual defined
 Added simultaneous contrasts to summary.rms
 Fixed calculation of Brier score, g, gp in lrm.fit by handling special case of computing linear predictor when there are no predictors in the model
 Fixed bug in prModFit preventing successful latex'ing of penalized lrms
 Removed \synopsis from two Rd files
 Added prmodsel argument to predab.resample
 Correct Rd files to change Design to rms
 Restricted NAMESPACE to functions expected to be called by users
 Improved Fortran code to use better dimensions for array declarations
 Added the basic bootstrap for confidence limits for bootBCa, contrast, Predict, summary
Changes in version 3.63 (20130111)
 Added LiShepherd residuals in residuals.lrm.s, become new default (same as ordinary residuals for binary models)
 Remove glm null fit usage as this is no longer in R
Changes for version 3.62 (10 Dec 12)
 bootcov, predab.resample: captured errors in all fits (to ignore bootstrap rep) using tryCatch. Thanks: Max Gordoin <max@gforge.se>
 predab.resample: made as.matrix(y) conditional to handle change in the survival package whereby the "type" attribute did not exist for a matrix
 anova.rms: added new parameter vnames to allow use of variable labels instead of names in anova table; added vinfo attribute
 residuals.lrm: removed intercept from partial residuals for binary models
 moved comprehensive examples in rmsOverview to ~/rms/demo/all.R; greatly speeds up package checking but demo needs to be run separately for better checking, using demo(all, 'rms')
 Fixed survfit.formula to not use .Global environment
Changes for version 3.61 (5 Nov 12)
 bootcov: set loglik to default to FALSE and added code to fill in missing intercepts in coef vector for prop. odds model when levels of Y not resampled; see coef.reps to default to TRUE
 Predict: implemented fun='mean' to get proper penalty for estimating the mean function for proportional odds models
 Added usebootcov argument to Predict to allow the user to force the use of bootstrap covariance matrix even when coef.reps=TRUE was in effect for bootcov
Changes for version 3.60 (27 Oct 12)
 Gls: Updated optimization calls  had become inconsistent with gls and failed if > 1 correlation parameter (thanks: Mark Seeto <markseeto@gmail.com>); removed opmeth argument
 print.fastbw: added argument: estimates
 survplot.survfit: handled fact that survival:::summary.survfit may not preserve order of strata levels. Also fixed survit.cph and cph; Thanks: William.Fulp@moffitt.org
 plot.Predict: added example showing how to rename variables in plot
 print(fit object, latex=TRUE): added latex.naprint.delete, used new Hmisc latexDotchart function to make a dot chart of number of NAs due to each model variable if at least 4 variables have NAs
 added trans argument to plot.anova.rms to allow transformed scales
 Corrected cph to use model.offset(); thanks: Simon Thornley <s.thornley@auckland.ac.nz>
 Changed latex.anova.rms to use REGRESSION instead of TOTAL label
 Changed gendata, contrast.rms to allow expand=FALSE to prevent expand.grid from being called to generate all combinations of predictors
 Added type= to plot.Predict to allow user to specify a different default line/point type (especially useful when x is categorical)
 Corrected bug in offset in psm  made default offset the length of X
 Corrected bug in calibrate.psm (fixed > parms)
 predab.resample, calibrate.cph, calibrate.default, calibrate.psm: stopped putting results from overall initial fit into .Global and instead had predab.resample put them in attribute keepinfo, obtained from measure()
Changes in version 3.50 (20120324)
 contrast.rms: saved conf.type and conf.int in returned object, added to print method
 Added debug= to predab.resample so user can see all the training and test sample subscripts
 Added validate.Rq function
 Fixed bug in Rq that caused 2 copies of fitted.values to be in fit object, which caused fit.mult.impute to double fitted.values
 Added how to reorder predictors if using plot(Predict(fit))
 Added new function perlcode written by Jeremy Stephens and Thomas Dupont; converts result of Function to Perl code
 Fixed partial argument matches in many functions to pass new R checks
 Changed matrx and DesignAssign to allow validate.Rq to consider null models; neatened code
Changes for version 3.50 (24 Mar 12)
 contrast.rms: saved conf.type and conf.int in returned object, added to print method
 Added debug= to predab.resample so user can see all the training and test sample subscripts
 Added validate.Rq function
 Fixed bug in Rq that caused 2 copies of fitted.values to be in fit object, which caused fit.mult.impute to double fitted.values
 Added how to reorder predictors if using plot(Predict(fit))
 Added new function perlcode written by Jeremy Stephens and Thomas Dupont; converts result of Function to Perl code
 Fixed partial argument matches in many functions to pass new R checks
 Changed matrx and DesignAssign to allow validate.Rq to consider null models; neatened code
Changes for version 3.40 (17 Jan 12)
 psm: fixed logcorrect logic (thanks: Rob Kushler)
 Added suggested package multcomp (required for simultaneous CLs)
 Implemented simultaneous confidence intervals in Predict, predictrms, contrast.rms, all specific model predict methods
 Add multiplicity adjustment for individual confidence limits computed by contrast.rms, to preserve familywise coverage using multcomp package
 Improved rbind.Predict to preserve order of groups as presented, as levels of .set.
 Added example for plot.Predict showing how to suppress predictions for certain intervals/groups from being plotted
 Added example in plot.Predict help file for graphing multiple types of confidence bands simultaneously
Changes for version 3.33 (6 Dec 11)
 robcov: used vcov to get varcov matrix
 vcov.Glm: gave precedence to $var object in fit
 Added residuals.Glm to force call to residuals.glm, and make robcov fail as type="score" is not implemented for glm
 Fixed bootcov for Glm to sense NA in coefficients and skip that iteration
 Fixed digit > digits error in latex.rms
 Fixed f$coef error in pentrace; thanks christopher.hane@optum.com
 Added new feature for Predict() to plot bootstrap nonparametric confidence limits if fit was run through bootcov with coef.reps=TRUE
 Added ylim argument to plot.residuals.lrm
Changes for version 3.32 (9 Nov 11)
 calibrate.default: add varcov matrix to ols objects
 print.lrtest: discarded two formula attributes before printing
 Added digits, size, and after arguments for latex methods for model fits, made before argument work with inline=TRUE, changed \needspace to \Needspace in latex.validate and prModFit
 latex: fixed to consider digits for main effects
 plot.xmean.ordinaly: added new argument cex.points
 print.lrm: improved printing of 2 LL overall penalty
 plot.calibrate.default: invisibly return prediction errors
 plot.Predict: added cex.axis argument to pass to x scales; added subdata
 print.pentrace: neatened up output
 added title as an argument to all highlevel function print methods
 prModFit: fixed bug where Score chi2 was not translated to LaTeX
 prModFit: changed to use LaTeX longtable style for coefficients etc.
 prModFit: added arguments long and needspace
 prModFit: suppressed title if title=""
 rmsMisc: added nobs.rms and added nobs to object returned by logLik.rms
 Added new argument cex.points to plot.xmean.ordinaly
 Changed example in anova.rms to use reorder instead of reorder.factor
 Added new argument cex.points to plot.xmean.ordinaly
 Changed example in anova.rms to use reorder instead of reorder.factor
Changes for version 3.31 (1 Jun 11)
 Added new example for anova.rms for making dot plots of partial R^2 of predictors
 Defined logLik.ols (calls logLik.lm)
 Fixed and cleaned up logLik.rms, AIC.rms
 Fixed residuals.psm to allow other type= values used by residuals.survreg
 Fixed Predict and survplot.rms to allow for case where no covariates present
 Fixed bug in val.prob where Eavg wasn't being defined if pl=FALSE (thanks: Ben Haller)
 Fixed bug in Predict so that it could get a list or vector from predictrms
 Fixed latex.rms to not treat * as a wild card in various contexts (may be interaction)
 Fixed predictrms to temporarily get std.err if conf.int requested even it std.err not; omitted std.err in returned object if not wanted
 Enhanced plot.Predict to allow plots for different predictors to be combined, after running rbind.Predict (varypred argument)
 Also enhanced to allow groups= and cond= when varying the predictors
 Corrected bug where sometimes would try to plot confidence limits when conf.int=FALSE was given to Predict
 Added india, indnl arguments to anova.rms to suppress printing individual tests of interaction/nonlinearity
 Changed anova.rms so that if all nonsummary terms have (Factor+Higher Order Factor) in their labels, this part of the labels is suppressed (useful with india and indnl)
Changes for version 3.30 (28 Feb 11)
 In survplot.rms, fixed bug (curves were undefined if conf='bands' and labelc was FALSE)
 In survfit.cph, fixed bug by which n wasn't always defined
 In cph, put survival::: on exact fit call
 Quit ignoring zlim argument in bplot; added xlabrot argument
 Added caption argument for latex.anova.rms
 Changed predab to not print summaries of variables selected if bw=TRUE
 Changed predab to pass force argument to fastbw
 fastbw: implemented force argument
 Added force argument to validate.lrm, validate.bj, calibrate.default, calibrate.cph, calibrate.psm, validate.bj, validate.cph, validate.ols
 print.validate: added B argument to limit how many resamples are printed summarizing variables selected if BW=TRUE
 print.calibrate, print.calibrate.default: added B argument
 Added latex method for results produced by validate functions
 Fixed survest.cph to convert summary.survfit std.err to log S(t) scale
 Fixed val.surv by pulling surv object from survest result
 Clarified in predict.lrm help file that doesn't always use the first intercept
 lrm.fit, lrm: linear predictor stored in fit object now uses first intercept and not middle one (NOT DOWNWARD COMPATIBLE but makes predict work when using stored linear.predictors)
 Fixed argument consistency with validate methods
Changes for version 3.20 (14 Feb 11)
 Changed to be compatible with survival 2.363 which is now required
 Added logLik.rms and AIC.rms functions to be compatible with standard R
 Fixed oos.loglik.Glm
 Fixed bootcov related to nfit='Glm'
 Fixed (probably) old bug in latexrms with strat predictors
Changes for Version 3.10 (12 Sep10)
 Fixed gIndex to not use scale for labeling unless character
 Changed default na.action in Gls to na.omit and added a note in the help file that na.delete does not work with Gls
 Added terms component to Gls fit object (latex was not working)
 Added examples in robcov help file testing sandwich covariance estimator
 Added reference related to the effects package under help file for plot.Predict
 Added more examples and simulations to gIndex
 Fixed ancient bug in lrm.fit Fortran code to handle case where initial estimates are nearly perfect (was trying to step halve); thanks: Dan Hogan
 Changed survdiffplot to use gray(.85) for bands instead of gray(.95)
 Fixed formatting problem in print.psm
 Added prStats and reVector functions to rmsMisc.s
 Changed formatting of all print.* functions for model fits to use new prStats function
 Added latex=TRUE option to all model fit print methods; requires LaTeX package needspace
 Rewrote printing routines to make use of more general model
 Removed long and scale options from cph printingrelated routines
 Prepare for version 2.361 of survival package by adding censor=FALSE argument to survfit.coxph
 Added type="ccterms" to various predict methods
 Made type="ccterms" the default for partial gindexes in gIndex, i.e., combine all indirectly related (through interactions) terms
 Added Spiegelhalter calibration test to val.prob
 Added a check in cph to trigger an error if strata() is used in formula
 Fixed drawing of polygon for shaded confidence bands for survplot.survfit (thanks to Patrick Breheny <patrick.breheny@uky.edu>)
 Changed default adjust.subtitle in bplot to depend on ref.zero, thanks to David Winsemius <dwinsemius@comcast.net>
 Used a namespace and simplified referenced to a few survival package functions that survival actually exports
Changes for Version 3.00 (16May10)
Note: This is a major release because of the addition of new functions gIndex and GiniMd and of the addition of the gindex to all of the regression fitters, in addition to adding type="cterms" to predict.rms
 Made Gls not store data label() in residuals object, instead storing a label of 'Residuals'
 Fixed handling of na.action and check for presence of offsets in Glm
 Added type="cterms" to predict methods; computes combined terms for main effects + any interaction terms involving that main effect; in preparation for new geffects function
 Added GiniMd and gIndex functions
 Change lrm (lrm.fit) to use the middle intercept in computing Brier score
 Added 3 gindexes to lrm fits
 Added 1 gindex to ols, Rq, Glm, Gls fits
 Added 2 gindexes to cph, psm fits
 Added g to validate.ols, .lrm, .cph, .psm, but not to validate.bj
 Added print.validate to set default digits to 4
 Changed validate.lrm to compute 3 indexes even on ordinal response data
Changes for Version 2.20 (23Feb10)
 Added levels.only option to survplot.* to remove variablename= from curve labels
 Added digits argument to calibrate.default
 Added new ref in val.prob help page
 Corrected location of dataset in residuals.lrm help page (thanks frederic.holzwarth@bgcjena.mpg.de)
 Fixed latex.rms to latexescape percent signs inside value labels
 Added scat1d.opts to plot.Predict
 Changed method of specifying variables to vary by not requiring an equals sign and a dot after the variable name, for Predict, summary, nomogram, gendata, survplot.rms
 Added factors argument to Predict to handle the above for survplot
 Made gendata a nongeneric function, changed the order of its arguments, removed editor options, relying on R de function always
 Thanks to Kevin Thorpe <kevin.thorpe@utoronto.ca> to make latex.summary.rms and latex.anova.rms respect the table.env argument
 Fixed bug in calibrate.default related to digits argument
 Rewrote bplot to use lattice graphics (e.g., levelplot contourplot wireframe), allowing for multiple panels for 3d plots
Changes for Version 2.10
 Made Predict not return invisibly if predictors not specified
 New option nlines for plot.Predict for getting line plots with 2 categorical predictors
 Added rename option to rbind.Predict to handle case where predictor name has changed between models
 Added ties=mean to approx( ) calls that did not have ties= specified
 Added nlevels argument to bplot to pass to contour
 Added par argument to iLegend  list to pass to par().
 Redirected ... argument to iLegend to image( ).
 Fixed groupkm  was printing warning messages wrongly
 Added new semiparametric survival prediction calibration curve method in val.surv for external validation; this is the first implementation of smooth calibration curves for survival probability validation with rightcensored data
 Fixed calibrate confidence limits from groupkm
 Added smooth calibration curve using hare (polspline package) for calibrate.cph and calibrate.psm
 Added display of predicted risks for cph and psm models even for the stratified KM method (old default)
 Full Regression Modeling Strategies course featuring the
rms
package
 Syllabus for a 3day short course on the
rms
package and associated statistical methodology.
 Datasets for use in learning how to use
Hmisc, rms
, logistic regression, survival analysis, ordinary regression, penalized estimation, missing value imputation, data reduction, etc. (R save()
formats)
 An Introduction to S and the Hmisc and Design Packages; CF Alzola and FE Harrell (308 pages, PDF, 2004). For a list of recent changes to this document click here.
 Examples of use of rms functions and of adapting them for special uses
Go to the home page for the text REGRESSION MODELING STRATEGIES
Bug Reports
Please see the bug reporting
page