<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!-- saved from url=(0060)http://hesweb1.med.virginia.edu/biostat/s/help/nomogram.html -->
<HTML><HEAD><TITLE>Draw a Nomogram</TITLE>
<META content="text/html; charset=windows-1252" http-equiv=Content-Type>
<META content="MSHTML 5.00.2314.1000" name=GENERATOR></HEAD>
<BODY aLink=#ff0000 background="" bgColor=#ffffff link=#0000f0 text=#000000
vLink=#660066>
<OBJECT classid=clsid:1e2a7bd0-dab9-11d0-b93a-00c04fc99f9e
type=application/x-oleobject><PARAM NAME="Keyword" VALUE="R: nomogram"></OBJECT>
<H2 align=center><FONT color=#999999 face="Courier New,Courier">Draw a
Nomogram</FONT></H2>
<H3><FONT color=#666666 face="Courier New,Courier">Usage</FONT></H3><PRE>nomogram(fit, ..., adj.to, interact,
lp=T, lp.at, lplabel="Linear Predictor",
fun, fun.at, fun.lp.at, fun.side,
funlabel="Predicted Value",
conf.int=F,
col.conf=if(under.unix)c(1,.3) else c(1,12),
conf.space=c(.08,.2),
conf.lp=c("representative","all", "none"),
intercept=1, est.all=T, abbrev=F, minlength=4,
maxscale=100, nint=10, label.every=1, force.label=T,
xfrac=0.35, cex.axis=0.85, cex.var=1, col.grid=F,
vnames=c("labels","names"), varname.label=T,
varname.label.sep="=",
ia.space=.7, tck=-.009, lmgp=.4, omit, naxes,
points.label='Points', total.points.label='Total Points',
total.sep.page=F, total.fun, verbose=F)
print(object, dec=0)
legend.nomabbrev(object, which, x, y, ncol=3, ...)
</PRE>
<H3><FONT color=#666666 face="Courier New,Courier">Arguments</FONT></H3>
<TABLE>
<TBODY>
<TR vAlign=top>
<TD><CODE>fit</CODE></TD>
<TD>a regression model fit that was created with
<CODE>library(Design)</CODE> in effect, and (usually) with
<CODE>options(datadist="object.name")</CODE> in effect. </TD></TR>
<TR vAlign=top>
<TD><CODE>object</CODE></TD>
<TD>the result returned from <CODE>nomogram</CODE> </TD></TR>
<TR vAlign=top>
<TD><CODE>which</CODE></TD>
<TD>a character string giving the name of a variable for which to draw a
legend with abbreviations of factor levels </TD></TR>
<TR vAlign=top>
<TD><CODE>x,y</CODE></TD>
<TD>coordinates to pass to the <CODE>legend</CODE> function. This is the
upper left corner of the legend box. You can omit <CODE>y</CODE> if
<CODE>x</CODE> is a list with named elements <CODE>x</CODE> and
<CODE>y</CODE>. To use the mouse to locate the legend, specify
<CODE>locator(1)</CODE> for <CODE>x</CODE>. </TD></TR>
<TR vAlign=top>
<TD><CODE>...</CODE></TD>
<TD>settings of variables to use in constructing axes. If
<CODE>datadist</CODE> was in effect, the default is to use
<CODE>pretty(total range, nint)</CODE> for continuous variables, and the
class levels for discrete ones. For <CODE>legend.nomabbrev</CODE>,
<CODE>...{}</CODE> specifies optional parameters to pass to
<CODE>legend</CODE>. Common ones are <CODE>bty="n"</CODE> to suppress
drawing the box. You may want to specify a non-proportionally spaced font
(e.g., courier) number if abbreviations are more than one letter long.
This will make the abbreviation definitions line up (e.g., specify
<CODE>font=2</CODE>, the default for courier). </TD></TR>
<TR vAlign=top>
<TD><CODE>adj.to</CODE></TD>
<TD>If you didn't define <CODE>datadist</CODE> for all predictors, you
will have to define adjustment settings for the undefined ones, e.g.
<CODE>adj.to=list(age=50, sex="female")</CODE>. </TD></TR>
<TR vAlign=top>
<TD><CODE>interact</CODE></TD>
<TD>When a continuous variable interacts with a discrete one, axes are
constructed so that the continuous variable moves within the axis, and
separate axes represent levels of interacting factors. For interactions
between two continuous variables, all but the axis variable must have
discrete levels defined in <CODE>interact</CODE>. For discrete interacting
factors, you may specify levels to use in constructing the multiple axes.
For continuous interacting factors, you must do this. Examples:
`interact=list(age=seq(10,70,by=10), treat=c("A","B","D"))'. </TD></TR>
<TR vAlign=top>
<TD><CODE>lp</CODE></TD>
<TD>Set to <CODE>F</CODE> to suppress creation of an axis for scoring X
beta. </TD></TR>
<TR vAlign=top>
<TD><CODE>lp.at</CODE></TD>
<TD>If <CODE>lp=T</CODE>, <CODE>lp.at</CODE> may specify a vector of
settings of X beta. Default is to use <CODE>pretty(range of linear
predictors, nint)</CODE>. </TD></TR>
<TR vAlign=top>
<TD><CODE>lplabel</CODE></TD>
<TD>label for linear predictor axis. Default is <CODE>"Linear
Predictor"</CODE>. </TD></TR>
<TR vAlign=top>
<TD><CODE>fun</CODE></TD>
<TD>an optional function to transform the linear predictors, and to plot
on another axis. If more than one transformation is plotted, put them in a
list, e.g. <CODE>list(function(x)x/2, function(x)2*x)</CODE>. Any function
values equal to NA will be ignored. </TD></TR>
<TR vAlign=top>
<TD><CODE>fun.at</CODE></TD>
<TD>function values to label on axis. Default <CODE>fun</CODE> evaluated
at <CODE>lp.at</CODE>. If more than one <CODE>fun</CODE> was specified,
using a vector for <CODE>fun.at</CODE> will cause all functions to be
evaluated at the same argument values. To use different values, specify a
list of vectors for <CODE>fun.at</CODE>, with elements corresponding to
the different functions (lists of vectors also applies to
<CODE>fun.lp.at</CODE> and <CODE>fun.side</CODE>). </TD></TR>
<TR vAlign=top>
<TD><CODE>fun.lp.at</CODE></TD>
<TD>If you want to evaluate one of the functions at a different set of
linear predictor values than may have been used in constructing the linear
predictor axis, specify a vector or list of vectors of linear predictor
values at which to evaluate the function. This is especially useful for
discrete functions. The presence of this attribute also does away with the
need for <CODE>nomogram</CODE> to compute numerical approximations of the
inverse of the function. It also allows the user-supplied function to
return <CODE>factor</CODE> objects, which is useful when e.g. a single
tick mark position actually represents a range. If the
<CODE>fun.lp.at</CODE> parameter is present, the <CODE>fun.at</CODE>
vector for that function is ignored. </TD></TR>
<TR vAlign=top>
<TD><CODE>fun.side</CODE></TD>
<TD>a vector or list of vectors of <CODE>side</CODE> parameters for the
<CODE>axis</CODE> function for labeling function values. Values may be 1
to position a tick mark label below the axis (the default), or 3 for above
the axis. If for example an axis has 5 tick mark labels and the second and
third will run into each other, specify <CODE>fun.side=c(1,1,3,1,1)</CODE>
(assuming only one function is specified as <CODE>fun</CODE>). </TD></TR>
<TR vAlign=top>
<TD><CODE>funlabel</CODE></TD>
<TD>label for <CODE>fun</CODE> axis. If more than one function was given
but funlabel is of length one, it will be duplicated as needed. If
<CODE>fun</CODE> is a list of functions for which you specified names (see
the final example below), these names will be used as labels. </TD></TR>
<TR vAlign=top>
<TD><CODE>conf.int</CODE></TD>
<TD>confidence levels to display for each scoring. Default is
<CODE>F</CODE> to display no confidence limits. Setting
<CODE>conf.int</CODE> to <CODE>T</CODE> is the same as setting it to
<CODE>c(0.7, 0.9)</CODE>, with the line segment between the 0.7 and 0.9
levels shaded using gray scale. </TD></TR>
<TR vAlign=top>
<TD><CODE>col.conf</CODE></TD>
<TD>colors corresponding to <CODE>conf.int</CODE>. Use fractions for gray
scale (for UNIX S-PLUS). </TD></TR>
<TR vAlign=top>
<TD><CODE>conf.space</CODE></TD>
<TD>a 2-element vector with the vertical range within which to draw
confidence bars, in units of 1=spacing between main bars. Four heights are
used within this range (8 for the linear predictor if more than 16 unique
values were evaluated), cycling them among separate confidence intervals
to reduce overlapping. </TD></TR>
<TR vAlign=top>
<TD><CODE>conf.lp</CODE></TD>
<TD>default is <CODE>"representative"</CODE> to group all linear
predictors evaluated into deciles, and to show, for the linear predictor
confidence intervals, only the mean linear predictor within the deciles
along with the median standard error within the deciles. Set
<CODE>conf.lp="none"</CODE> to suppress confidence limits for the linear
predictors, and to <CODE>"all"</CODE> to show all confidence limits.
</TD></TR>
<TR vAlign=top>
<TD><CODE>intercept</CODE></TD>
<TD>for models such as the ordinal logistic model with multiple
intercepts, specifies which one to use in evaluating the linear predictor.
</TD></TR>
<TR vAlign=top>
<TD><CODE>est.all</CODE></TD>
<TD>To plot axes for only the subset of variables named in
<CODE>...{}</CODE>, set <CODE>est.all=F</CODE>. </TD></TR>
<TR vAlign=top>
<TD><CODE>abbrev</CODE></TD>
<TD>Set to <CODE>T</CODE> to use the <CODE>abbreviate</CODE> function to
abbreviate levels of categorical factors, both for labeling tick marks and
for axis titles. If you only want to abbreviate certain predictor
variables, set <CODE>abbrev</CODE> to a vector of character strings
containing their names. </TD></TR>
<TR vAlign=top>
<TD><CODE>minlength</CODE></TD>
<TD>applies if <CODE>abbrev=T</CODE>. Is the minimum abbreviation length
passed to the <CODE>abbreviate</CODE> function. If you set
<CODE>minlength=1</CODE>, the letters of the alphabet are used to label
tick marks for categorical predictors, and all letters are drawn no matter
how close together they are. For labeling axes (interaction settings),
<CODE>minlength=1</CODE> causes <CODE>minlength=4</CODE> to be used.
</TD></TR>
<TR vAlign=top>
<TD><CODE>maxscale</CODE></TD>
<TD>default maximum point score is 100 </TD></TR>
<TR vAlign=top>
<TD><CODE>nint</CODE></TD>
<TD>number of intervals to label for axes representing continuous
variables. See <CODE>pretty</CODE>. </TD></TR>
<TR vAlign=top>
<TD><CODE>label.every</CODE></TD>
<TD>Specify <CODE>label.every=i</CODE> to label on every <CODE>i</CODE>th
tick mark. </TD></TR>
<TR vAlign=top>
<TD><CODE>force.label</CODE></TD>
<TD>set to <CODE>T</CODE> to force every tick mark intended to be labeled
to have a label plotted (whether the labels run into each other or not)
</TD></TR>
<TR vAlign=top>
<TD><CODE>xfrac</CODE></TD>
<TD>fraction of horizontal plot to set aside for axis titles </TD></TR>
<TR vAlign=top>
<TD><CODE>cex.axis</CODE></TD>
<TD>character size for tick mark labels </TD></TR>
<TR vAlign=top>
<TD><CODE>cex.var</CODE></TD>
<TD>character size for axis titles (variable names) </TD></TR>
<TR vAlign=top>
<TD><CODE>col.grid</CODE></TD>
<TD>If <CODE>col.grid=1</CODE>, no gray scale is used, but an ordinary
line is drawn. If <CODE>0<col.grid<1</CODE>, a <CODE>col</CODE>
(gray scale) of <CODE>col.grid</CODE> is used to draw vertical reference
lines for major axis divisions and <CODE>col.grid/2</CODE> for minor
divisions. The default is <CODE>col.grid=F</CODE>, i.e., reference lines
are omitted. Specifying <CODE>col.grid=T</CODE> is the same as specifying
a gray scale level of <CODE>col.grid=.2</CODE> (5 for Windows S-PLUS).
</TD></TR>
<TR vAlign=top>
<TD><CODE>vnames</CODE></TD>
<TD>By default, variable labels are used to label axes. Set
<CODE>vnames="names"</CODE> to instead use variable names. </TD></TR>
<TR vAlign=top>
<TD><CODE>varname.label</CODE></TD>
<TD>In constructing axis titles for interactions, the default is to add
<CODE>"(interacting.varname=level)</CODE> on the right. Specify
<CODE>varname.label=F</CODE> to instead use <CODE>"(level)"</CODE>. </TD></TR>
<TR vAlign=top>
<TD><CODE>varname.label.sep</CODE></TD>
<TD>If <CODE>varname.label=T</CODE>, you can change the separator to
something other than <CODE>=</CODE> by specifying this parameter. </TD></TR>
<TR vAlign=top>
<TD><CODE>ia.space</CODE></TD>
<TD>When multiple axes are draw for levels of interacting factors, the
default is to group combinations related to a main effect. This is done by
spacing the axes for the second to last of these within a group only 0.7
(by default) of the way down as compared with normal space of 1 unit.
</TD></TR>
<TR vAlign=top>
<TD><CODE>tck</CODE></TD>
<TD>see <CODE>tck</CODE> under <CODE>par</CODE> </TD></TR>
<TR vAlign=top>
<TD><CODE>lmgp</CODE></TD>
<TD>spacing between numeric axis labels and axis (see <CODE>par</CODE> for
<CODE>mgp</CODE>) </TD></TR>
<TR vAlign=top>
<TD><CODE>omit</CODE></TD>
<TD>vector of character strings containing names of variables for which to
suppress drawing axes. Default is to show all variables. </TD></TR>
<TR vAlign=top>
<TD><CODE>naxes</CODE></TD>
<TD>maximum number of axes to allow on one plot. If the nomogram requires
more than one "page", the "Points" axis will be repeated at the top of
each page when necessary. </TD></TR>
<TR vAlign=top>
<TD><CODE>points.label</CODE></TD>
<TD>a character string giving the axis label for the points scale </TD></TR>
<TR vAlign=top>
<TD><CODE>total.points.label</CODE></TD>
<TD>a character string giving the axis label for the total points scale
</TD></TR>
<TR vAlign=top>
<TD><CODE>total.sep.page</CODE></TD>
<TD>set to <CODE>T</CODE> to force the total points and later axes to be
placed on a separate page </TD></TR>
<TR vAlign=top>
<TD><CODE>total.fun</CODE></TD>
<TD>a user-provided function that will be executed before the total points
axis is drawn. Default is not to execute a function. This is useful e.g.
when <CODE>total.sep.page=T</CODE> and you wish to use
<CODE>locator</CODE> to find the coordinates for positioning an
abbreviation legend before it's too late and a new page is started (i.e.,
<CODE>total.fun=function()print(locator(1))</CODE>). </TD></TR>
<TR vAlign=top>
<TD><CODE>verbose</CODE></TD>
<TD>set to <CODE>T</CODE> to get printed output detailing how tick marks
are chosen and labeled for function axes. This is useful in seeing how
certain linear predictor values cannot be solved for using inverse linear
interpolation on the (requested linear predictor values, function values
at these lp values). When this happens you will see <CODE>NA</CODE>s in
the <CODE>verbose</CODE> output, and the corresponding tick marks will not
appear in the nomogram. </TD></TR>
<TR vAlign=top>
<TD><CODE>dec</CODE></TD>
<TD>number of digits to the right of the decimal point, for rounding point
scores in <CODE>print.nomogram</CODE>. Default is to round to the nearest
whole number of points. </TD></TR>
<TR vAlign=top>
<TD><CODE>ncol</CODE></TD>
<TD>the number of columns to form in drawing the legend.
</TD></TR></TBODY></TABLE>
<P></P>
<H3><FONT color=#666666 face="Courier New,Courier">Description</FONT></H3>
<P>Draws a partial nomogram that can be used to manually obtain predicted values
from a regression model that was fitted with <CODE>Design</CODE> in effect. The
nomogram does not have lines representing sums, but it has a reference line for
reading scoring points (default range 0-100). Once the reader manually totals
the points, the predicted values can be read at the bottom. Non-monotonic
transformations of continuous variables are handled (scales wrap around), as are
transformations which have flat sections (tick marks are labeled with ranges).
If interactions are in the model, one variable is picked as the "axis variable",
and separate axes are constructed for each level of the interacting factors
(preference is given automatically to using any discrete factors to construct
separate axes) and levels of factors which are indirectly related to interacting
factors (see DETAILS). Thus the nomogram is designed so that only one axis is
actually read for each variable, since the variable combinations are disjoint.
For categorical interacting factors, the default is to construct axes for all
levels. The user may specify coordinates of each predictor to label on its axis,
or use default values. If a factor interacts with other factors, settings for
one or more of the interacting factors may be specified separately (this is
mandatory for continuous variables). Optional confidence intervals will be drawn
for individual scores as well as for the linear predictor. If more than one
confidence level is chosen, multiple levels may be displayed using different
colors or gray scales. Functions of the linear predictors may be added to the
nomogram.
<P><CODE>print.nomogram</CODE> prints axis information stored in an object
returned by <CODE>nomogram</CODE>. This is useful in producing tables of point
assignments by levels of predictors. It also prints how many linear predictor
units there are per point and the number of points per unit change in the linear
predictor.
<P><CODE>legend.nomabbrev</CODE> draws legends describing abbreviations used for
labeling tick marks for levels of categorical predictors.</P>
<H3><FONT color=#666666 face="Courier New,Courier">Details</FONT></H3>
<P>A variable is considered to be discrete if it is categorical or ordered or if
<CODE>datadist</CODE> stored <CODE>values</CODE> for it (meaning it had
<CODE><11</CODE> unique values). A variable is said to be indirectly related
to another variable if the two are related by some interaction. For example, if
a model has variables a, b, c, d, and the interactions are a:c and c:d, variable
d is indirectly related to variable a. The complete list of variables related to
a is c, d. If an axis is made for variable a, several axes will actually be
drawn, one for each combination of c and d specified in <CODE>interact</CODE>.
<P>Note that with a caliper, it is easy to continually add point scores for
individual predictors, and then to place the caliper on the upper
<CODE>Points</CODE> axis (with extrapolation if needed). Then transfer these
points to the <CODE>Total Points</CODE> axis. In this way, points can be added
without without writing them down.
<P>Confidence limits for an individual predictor score are really confidence
limits for the entire linear predictor, with other predictors set to adjustment
values. If <CODE>lp=T</CODE>, all confidence bars for all linear predictor
values evaluated are drawn. The extent to which multiple confidence bars of
differing widths appear at the same linear predictor value means that precision
depended on how the linear predictor was arrived at (e.g., a certain value may
be realized from a setting of a certain predictor that was associated with a
large standard error on the regression coefficients for that predictor).
<P>On occasion, you may want to reverse the regression coefficients of a model
to make the "points" scales reverse direction. For parametric survival models,
which are stated in terms of increasing regression effects meaning longer
survival (the opposite of a Cox model), just do something like
<CODE>fit$coefficients <- -fit$coefficients</CODE> before invoking
<CODE>nomogram</CODE>, and if you add function axes, negate the function
arguments. For the Cox model, you also need to negate <CODE>fit$center</CODE>.
If you omit <CODE>lp.at</CODE>, also negate
<CODE>fit$linear.predictors</CODE>.</P>
<H3><FONT color=#666666 face="Courier New,Courier">Value</FONT></H3>
<P>a list of class <CODE>"nomogram"</CODE> that contains information used in
plotting the axes. If you specified <CODE>abbrev=T</CODE>, a list called
<CODE>abbrev</CODE> is also returned that gives the abbreviations used for tick
mark labels, if any. This list is useful for making legends and is used by
<CODE>legend.nomabbrev</CODE> (see the last example). The returned list also has
components called <CODE>total.points</CODE>, <CODE>lp</CODE>, and the function
axis names. These components have components <CODE>x</CODE> (<CODE>at</CODE>
argument vector given to <CODE>axis</CODE>), <CODE>y</CODE> (<CODE>pos</CODE>
for <CODE>axis</CODE>), and <CODE>x.real</CODE>, the x-coordinates appearing on
tick mark labels. An often useful result is stored in the list of data for each
axis variable, namely the exact number of points that correspond to each tick
mark on that variable's axis.</P>
<H3><FONT color=#666666 face="Courier New,Courier">AUTHOR</FONT></H3>
<P>Frank Harrell
<P>Division of Biostatistics and Epidemiology
<P>University of Virginia
<P>fharrell@virginia.edu</P>
<H3><FONT color=#666666 face="Courier New,Courier">References</FONT></H3>
<P>Banks J: Nomograms. Encylopedia of Statistical Sciences, Vol 6. Editors: S
Kotz and NL Johnson. New York: Wiley; 1985.
<P>Lubsen J, Pool J, van der Does, E: A practical device for the application of
a diagnostic or prognostic function. Meth. Inform. Med. 17:127-129; 1978.</P>
<H3><FONT color=#666666 face="Courier New,Courier">See Also</FONT></H3>
<P><CODE><A
href="http://hesweb1.med.virginia.edu/biostat/s/help/Design.html">Design</A></CODE>,
<CODE><A
href="http://hesweb1.med.virginia.edu/biostat/s/help/plot.Design.html">plot.Design</A></CODE>,
<CODE><A
href="http://hesweb1.med.virginia.edu/biostat/s/help/summary.Design.html">plot.summary.Design</A></CODE>,
<CODE>axis</CODE>, <CODE>pretty</CODE>, <CODE>approx</CODE>, <CODE><A
href="http://hesweb1.med.virginia.edu/biostat/s/help/latex.Design.html">latex.Design</A></CODE>,
<CODE><A
href="http://hesweb1.med.virginia.edu/biostat/s/help/Design.Misc.html">Design.Misc</A></CODE></P>
<H3><FONT color=#666666 face="Courier New,Courier">Examples</FONT></H3><PRE>library(Design, T)
ddist <- datadist(sex, treatment, age)
options(datadist="ddist")
f <- lrm(y ~ treatment*age + sex)
nomogram(f, fun=function(x)1/(1+exp(-x)),
fun.at=c(.001,.01,.05,seq(.1,.9,by=.1),.95,.99,.999),
funlabel="Risk of Death")
#Instead of fun.at, could have specified fun.lp.at=logit of
#sequence above - faster and slightly more accurate
nomogram(f, age=seq(10,90,by=10))
g <- lrm(y ~ rcs(age,5)*rcs(cholesterol,3))
nomogram(g, interact=list(age=c(20,40,60)),
conf.int=c(.7,.9,.95), col.conf=c(1,.5,.2))
f <- psm(Surv(d.time,death) ~ treatment*age, dist="gaussian")
med <- Quantile(f)
surv <- Survival(f) # This would also work if f was from cph
nomogram(f, fun=function(x) med(lp=x), funlabel="Median Survival Time")
nomogram(f, fun=list(function(x) surv(3, x), function(x) surv(6, x)),
funlabel=c("3-Month Survival Probability",
"6-month Survival Probability"), xfrac=.42)
nom <- nomogram(fit.with.categorical.predictors, abbrev=T, minlength=1)
nom$x1$points # print points assigned to each level of x1 for its axis
#Add legend for abbreviations for category levels
abb <- nom$abbrev$treatment
legend(locator(1), abb$full, pch=paste(abb$abbrev,collapse=''),
ncol=2, bty='n') # this only works for 1-letter abbreviations
#Or use the legend.nomabbrev function:
legend.nomabbrev(nom, 'treatment', locator(1), ncol=2, bty='n')
#Make a nomogram with axes predicting probabilities Y>=j for all j=1-3
#in an ordinal logistic model, where Y=0,1,2,3
g <- lrm(Y ~ rcs(age,4)*sex)
fun2 <- function(x) plogis(x-g$coef[1]+g$coef[2])
fun3 <- function(x) plogis(x-g$coef[1]+g$coef[3])
postscript('nomogram.ps')
f <- Newlabels(f, c(age='Age in Years'))
#see Design.Misc, which also has Newlevels to change
#labels for levels of categorical variables
nomogram(f, fun=list('Prob Y>=1'=plogis, 'Prob Y>=2'=fun2,
'Prob Y=3'=fun3),
fun.at=c(.01,.05,seq(.1,.9,by=.1),.95,.99),
lmgp=.2, cex.axis=.6)
</PRE>
<P align=center>
<HR>
<DIV align=center><A
href="http://hesweb1.med.virginia.edu/biostat/s/help/00Index.html">[Contents]</A></DIV></BODY></HTML>