Department of Biostatistics Vanderbilt University School of Medicine
April 28, 2025
NOTE: remove the csl and bibliography lines above if you don’t have any bibliographic citations.
Introduction
This is a set of reproducible examples for the R1Hmisc package2, put together in an rmarkdown html document using RStudio and knitr. When viewing the resulting html file you can see all the code, and there exist options to download the entire rmarkdown script, which is especially helpful for seeing how knitr chunks are specified. Graphics that have a plotly method for them are rendered using plotly instead of using defaults such as base graphics, lattice, or ggplot2. That way the plots are somewhat interactive, e.g., allow for drill-down for more information without the viewer needing to install R.
Much of the tabular output produced here was created using html methods, which are especially easy to implement with rmarkdown and make for output that can be directly opened using word processors. Jump to Computing Environment for a list of packages used here, and their version numbers.
Rmarkdown themes such as bookdown and rmdformats::readthedown (the latter is used here) allow one to number figures and the symbolically reference them. The knitrSetcapfile='captions.md' argument below capitalizes on this to make it easy for the user to insert a table of figures anywhere in the report. Here we place it at the end. A caption listed in the table of figures is the short caption (scap= or fig.scap in the chunk header) if there is one, otherwise the long caption is used. If neither caption is used, that figure will not appear in the table of figures.
The full script for this report may be found here.
Setup
Code
require(Hmisc)knitrSet(lang='markdown', h=4.5, fig.path='png/', fig.align='left',capfile='captions.md') # + sometimes ,cache=TRUE# knitrSet redirects all messages to messages.txtoptions(grType='plotly') # for certain graphics functionsmu <- markupSpecs$html # markupSpecs is in Hmisccap <- mu$cap # function to output html captionlcap <- mu$lcap # for continuation for long caption# These last 2 functions are used by the putHfig function in Hmisccat('', file='captions.md') # initialize table of short captions
The following (r mu$styles()) defines HTML styles and javascript functions, such as ffig, smg and the function for expanding and collapsing text as done by the expcoll function. `
`{=html}
Here is an example using expcoll. Click on the down arrow to expand; it turns to an up arrow which can be clicked to contract.
To make the html output use the entire wide screen run the R command mu$widescreen().
Fetching Data, Modifying Variables, and Printing Data Dictionary
The getHdata function is used to fetch a dataset from the Vanderbilt DataSets web site hbiostat.org/data. The upData function is used to
create a new variable from an old one
add labels to 2 variables
add units to the new variable
remove the old variable
automatically move units of measurements from parenthetical expressions in labels to separate units attributed used by Hmisc and rms functions for table making and graphics
contents is used to print a data dictionary, run through an html method for nicer output. Information about the data source may be found here. Click on the number of levels in the contents table to jump to the value labels for the variable.
Code
getHdata(pbc)# Have upData move units from labels to separate attributepbc <-upData(pbc,fu.yrs = fu.days /365.25,labels =c(fu.yrs ='Follow-up Time',status ='Death or Liver Transplantation'),units =c(fu.yrs ='year'),drop ='fu.days',moveUnits=TRUE, html=TRUE)
Input object size: 80952 bytes; 19 variables 418 observations
Label for bili changed from Serum Bilirubin (mg/dl) to Serum Bilirubin
units set to mg/dl
Label for albumin changed from Albumin (gm/dl) to Albumin
units set to gm/dl
Label for protime changed from Prothrombin Time (sec.) to Prothrombin Time
units set to sec.
Label for alk.phos changed from Alkaline Phosphatase (U/liter) to Alkaline Phosphatase
units set to U/liter
Label for sgot changed from SGOT (U/ml) to SGOT
units set to U/ml
Label for chol changed from Cholesterol (mg/dl) to Cholesterol
units set to mg/dl
Label for trig changed from Triglycerides (mg/dl) to Triglycerides
units set to mg/dl
Label for platelet changed from Platelets (per cm^3/1000) to Platelets
units set to per cm^3/1000
Label for copper changed from Urine Copper (ug/day) to Urine Copper
units set to ug/day
Added variable fu.yrs
Dropped variable fu.days
New object size: 84744 bytes; 19 variables 418 observations
Code
# The following can also be done by running this command# to put the results in a new browser tab:# getHdata(pbc, 'contents')html(contents(pbc), maxlevels=10, levelType='table')
pbc Contents
Data frame:pbc
418 observations and 19 variables, maximum # NAs:136
The html method is used for the describe function, and the output is put in a scrollable box. Other than for the overall title and variable names and labels, the output size used here is 80 (0.8 × the usual font size1). But the graphical display of the descriptives statistics that follows this is probably better.
1 The default is 75% size.
Code
# did have results='asis' aboved <-describe(pbc)html(d, size=80, scroll=TRUE)
# prList is in Hmisc; useful for plotting or printing a list of objects# Can just use plot(d) if don't care about the mess# If using html output these 2 images would not be rendered no matter whatp <-plot(d)# The option htmlfig=2 causes markupSpecs$html$cap() to be used to# HTML-typeset as a figure caption and to put the sub-sub section# marker ### in front of the caption. htmlfig is the only reason# results='asis' was needed in the chunk header# We define a long caption for one of the plots, which does not appear# in the table of contents# prList works for html notebooks but not html documents# prList(p, lcap=c('', 'These are spike histograms'), htmlfig=2)
You can also re-form multiple plotly graphs into a single HTML object. If you want to have total control over long and short figure captions, use the Hmisc putHfig function to render the result, with a caption and a short caption for the table of contents. That would have fixed a problem with the chunk below: when plotly graphics are not rendered in the usual way, the figure is not numbered and no caption appears.
You can also create figure captions outside of R code by using the smg, fcap HTML tags defined in markupSpecs. The long caption not appearing in the table of contents will be in a separate line without ###.
Stratified Descriptive Statistics
Produce stratified quantiles, means/SD, and proportions by treatment group. Plot the results before rendering as an advanced html table:
categorical variables: a single dot chart
continuous variables: a series of extended box plots
Code
s <-summaryM(bili + albumin + stage + protime + sex + age + spiders + alk.phos + sgot + chol ~ drug, data=pbc,overall=FALSE, test=TRUE)plot(s, which='categorical')
Proportions and \(\chi^{2}\) tests for categorical variables
To construct the caption outside of the code chunk use e.g. ### r cap(‘Proportions and’, mu$chisq(), ‘tests for categorical variables’) where a backtick is placed before r and after the last ).
Code
plot(s, which='continuous', vars=1:4)
Extended box plots for the first 4 continuous variables
Code
plot(s, which='continuous', vars=5:7)
Extended box plots for the remaining continuous variables
abc represent the lower quartile a, the median b, and the upper quartile c for continuous variables. x ± s represents X ± 1 SD. N is the number of non-missing values.
Tests used: 1Kruskal-Wallis test; 2Pearson test; 3Wilcoxon test .
Now show almost the full raw data for one continuous variable stratified by treatment. This display spike histograms using at most 100 bins, and also shows the mean and quantiles similar to what is in an extended box plot: 0.05, 0.25, 0.5, 0.75, 0.95. Measures of spread are also shown if the user clicks on their legend entries: Gini’s mean difference (mean absolute difference between any two values) and the SD. These can be seen as horizontal lines up against the minimum x-value.
Code
with(pbc, histboxp(x=sgot, group=drug, sd=TRUE))
Spike histograms, means, quantiles, Gini’s mean difference, and SD stratified by treatment
The following is a better way to display proportions, for categorical variables. If computing marginal statistics by running the dataset through the HmiscaddMarginal function, the plot method with options(grType='plotly') is especially useful.
Code
pbcm <-addMarginal(pbc, drug)s <-summaryP(stage + sex + spiders ~ drug, data=pbc)# putHcap('Proportions stratified by treatment')plot(s, groups='drug')
Proportions (large symbols) and proportions stratified by treatment (small symbols)
Code
s <-summaryP(stage + sex + spiders ~ drug, data=pbcm)plot(s, marginVal='All', marginLabel='All Treatment Groups')
Proportions (large symbols) and proportions stratified by treatment (small symbols)
Spike histograms, means, quantiles, Gini’s mean difference, and SD for MAP stratified by diagnosis
Changing Size of Figure Captions
As explained here, one can place captions under figures using ordinary knitr capabilities, and one can change the size of captions. The following example defines a CSS style to make captions small (here 0.6em), and produces a plot with a caption. Unlike using putHfig captions given in knitr chunks do not also appear in the table of contents.
Code
# Note: in the chunk header cap is an alias for fig.cap defined by knitrSetplot(runif(10))
We used R version 4.4.23 and the following R packages: Hmisc v. 5.2.42.
The code was run on macOS Sequoia 15.4.1 on a Macbook Pro M2 Max.
2mu is a copy of the part of the Hmisc package object markupSpecs that is for html. It includes a function session that renders the session environment (including package versions) in html.
Bibliographic File Managament
Find and Install .csl Reference Style Files
Code
# Note: mu was defined in an earlier code chunk# Only need to install .csl file once.mu$installcsl(rec=TRUE) # get list of recommended stylesmu$installcsl() # web search of styles meeting your criteria# Install a .csl file to your project directory:mu$installcsl('american-medical-association')
List of Figures
Figure
Description
@ref(fig:plotlym)
Two plotly graphics combined into one
@ref(fig:summaryM)
Proportions and \(\chi^{2}\) tests for categorical variables
@ref(fig:summaryM2)
Extended box plots for the first 4 continuous variables
@ref(fig:summaryM3)
Extended box plots for the remaining continuous variables
@ref(fig:histbox)
Stratified spike histograms and quantiles
@ref(fig:summaryM5)
Proportions with and without stratification by treatment
@ref(fig:support)
Stratified spike histograms and quantiles for MAP
@ref(fig:simplecap)
This is a simple figure caption
Note: the hidden R command that rendered the table of figures (including short captions) was markupSpecs$markdown$tof().
References
1.
R Development Team. R: A Language and Environment for Statistical Computing. R Foundation for Statistical Computing; www.r-project.org; 2020. http://www.R-project.org
R Core Team. R: A Language and Environment for Statistical Computing. R Foundation for Statistical Computing; 2024. https://www.R-project.org/
Source Code
---title: "Hmisc Examples"author: - name: Frank Harrell url: https://hbiostat.org affiliation: Department of Biostatistics<br>Vanderbilt University School of Medicineauthor-title: ""affiliation-title: ""published-title: ""date: last-modifiedformat: html: embed-resources: true anchor-sections: true code-tools: true code-fold: true fig-width: 6 fig-height: 4 code-block-bg: "#f1f3f5" code-block-border-left: "#31BAE9" mainfont: Source Sans Pro theme: journal toc: true toc-depth: 3 toc-location: left captions: true cap-location: margin table-captions: true tbl-cap-location: margin reference-location: marginbibliography: - grateful-refs.bib - /Users/harrelfe/web/bib/harrelfe.bibcsl: /Users/harrelfe/web/bib/american-medical-association.csldescription: "Hmisc examples using plotly interactive graphics in an html report"execute: warning: false message: false---<!-- Usage: quarto render examples.qmd -->**NOTE**: remove the `csl` and `bibliography` lines above if you don't have any bibliographic citations.# IntroductionThis is a set of reproducible examples for the R[@R]`Hmisc` package[@Hmisc], put together in an `rmarkdown` html document using `RStudio` and `knitr`. When viewing the resulting [html file](https://hbiostat.org/R/Hmisc/examples.html) you can see all the code, and there exist options to download the entire `rmarkdown` script, which is especially helpful for seeing how `knitr` chunks are specified. Graphics that have a [plotly](http://plot.ly/r) method for them are rendered using `plotly` instead of using defaults such as base graphics, `lattice`, or `ggplot2`. That way the plots are somewhat interactive, e.g., allow for drill-down for more information without the viewer needing to install `R`.Much of the tabular output produced here was created using `html` methods, which are especially easy to implement with `rmarkdown` and make for output that can be directly opened using word processors. Jump to [Computing Environment](#compenv) for a list of packages used here, and their version numbers.`Rmarkdown` themes such as `bookdown` and [rmdformats::readthedown](https://github.com/juba/rmdformats) (the latter is used here) allow one to number figures and the symbolically reference them. The `knitrSet``capfile='captions.md'` argument below capitalizes on this to make it easy for the user to insert a table of figures anywhere in the report. Here we place it at the end. A caption listed in the table of figures is the short caption (`scap=` or `fig.scap` in the chunk header) if there is one, otherwise the long caption is used. If neither caption is used, that figure will not appear in the table of figures.The full script for this report may be found [here](https://github.com/harrelfe/Hmisc/blob/master/inst/tests/examples.Rmd).# Setup```{r setup,results='hide'}require(Hmisc)knitrSet(lang='markdown', h=4.5, fig.path='png/', fig.align='left',capfile='captions.md') # + sometimes ,cache=TRUE# knitrSet redirects all messages to messages.txtoptions(grType='plotly') # for certain graphics functionsmu <- markupSpecs$html # markupSpecs is in Hmisccap <- mu$cap # function to output html captionlcap <- mu$lcap # for continuation for long caption# These last 2 functions are used by the putHfig function in Hmisccat('', file='captions.md') # initialize table of short captions```The following (<code>r mu$styles()</code>) defines HTML styles and javascript functions, such as <code>ffig, smg</code> and the function for expanding and collapsing text as done by the <code>expcoll</code> function. `r mu$styles()`Here is an example using <code>expcoll</code>. Click on the down arrow to expand; it turns to an up arrow which can be clicked to contract.`r mu$expcoll('Example table<br>', html(data.frame(x1=runif(10), x2=letters[1:10]),file=FALSE))`Here is an example using a `knitr` hook function `markupSpec$html$uncover` which is communicated to `knitr` by `knitrSet`.<script>functionuncover(id) {var x =document.getElementById(id); x.style.display='block';}</script>```{r, uncover=TRUE, label='Press Here', id='script'}1+1```To make the html output use the entire wide screen run the R command `mu$widescreen()`.# Fetching Data, Modifying Variables, and Printing Data DictionaryThe `getHdata` function is used to fetch a dataset from the Vanderbilt `DataSets` web site `hbiostat.org/data`. The `upData` function is used to- create a new variable from an old one- add labels to 2 variables- add units to the new variable- remove the old variable- automatically move units of measurements from parenthetical expressions in labels to separate `units` attributed used by `Hmisc` and `rms` functions for table making and graphics`contents` is used to print a data dictionary, run through an `html` method for nicer output. Information about the data source may be found [here](https://hbiostat.org/data/repo/pbc.html). Click on the number of levels in the `contents` table to jump to the value labels for the variable.```{r metadata,results='asis'}getHdata(pbc)# Have upData move units from labels to separate attributepbc <-upData(pbc,fu.yrs = fu.days /365.25,labels =c(fu.yrs ='Follow-up Time',status ='Death or Liver Transplantation'),units =c(fu.yrs ='year'),drop ='fu.days',moveUnits=TRUE, html=TRUE)# The following can also be done by running this command# to put the results in a new browser tab:# getHdata(pbc, 'contents')html(contents(pbc), maxlevels=10, levelType='table')```# Descriptive Statistics Without StratificationThe html method is used for the `describe` function, and the output is put in a scrollable box. Other than for the overall title and variable names and labels, the output size used here is 80 (0.8 × the usual font size[^1]). But the graphical display of the descriptives statistics that follows this is probably better.[^1]: The default is 75% size.```{r describe,results='asis'}# did have results='asis' aboved <-describe(pbc)html(d, size=80, scroll=TRUE)# prList is in Hmisc; useful for plotting or printing a list of objects# Can just use plot(d) if don't care about the mess# If using html output these 2 images would not be rendered no matter whatp <-plot(d)# The option htmlfig=2 causes markupSpecs$html$cap() to be used to# HTML-typeset as a figure caption and to put the sub-sub section# marker ### in front of the caption. htmlfig is the only reason# results='asis' was needed in the chunk header# We define a long caption for one of the plots, which does not appear# in the table of contents# prList works for html notebooks but not html documents# prList(p, lcap=c('', 'These are spike histograms'), htmlfig=2)```You can also re-form multiple `plotly` graphs into a [single HTML object](http://stackoverflow.com/questions/35193612). If you want to have total control over long and short figure captions, use the Hmisc `putHfig` function to render the result, with a caption and a short caption for the table of contents. That would have fixed a problem with the chunk below: when `plotly` graphics are not rendered in the usual way, the figure is not numbered and no caption appears.```{r plotlym,cap='This used the <code>htmltools tagList</code> function.',scap='Two <code>plotly</code> graphics combined into one'}htmltools::tagList(p) # lapply(p, plotly::as.widget)```You can also create figure captions outside of R code by using the <code>smg, fcap</code> HTML tags defined in <code>markupSpecs</code>. The long caption not appearing in the table of contents will be in a separate line without ###.# Stratified Descriptive StatisticsProduce stratified quantiles, means/SD, and proportions by treatment group. Plot the results before rendering as an advanced html table:- categorical variables: a single dot chart- continuous variables: a series of extended box plots```{r summaryM,cap='Proportions and $\\chi^{2}$ tests for categorical variables'}s <-summaryM(bili + albumin + stage + protime + sex + age + spiders + alk.phos + sgot + chol ~ drug, data=pbc,overall=FALSE, test=TRUE)plot(s, which='categorical')```To construct the caption outside of the code chunk use e.g. ### r cap('Proportions and', mu$chisq(), 'tests for categorical variables') where a backtick is placed before r and after the last ).```{r summaryM2,results='asis',cap='Extended box plots for the first 4 continuous variables'}plot(s, which='continuous', vars=1:4)``````{r summaryM3,cap='Extended box plots for the remaining continuous variables'}plot(s, which='continuous', vars=5:7)``````{r summaryM4}html(s, caption='Baseline characteristics by randomized treatment',exclude1=TRUE, npct='both', digits=3, middle.bold=TRUE,prmsd=TRUE, brmsd=TRUE, msdsize=mu$smaller2)```Now show almost the full raw data for one continuous variable stratified by treatment. This display spike histograms using at most 100 bins, and also shows the mean and quantiles similar to what is in an extended box plot: 0.05, 0.25, 0.5, 0.75, 0.95. Measures of spread are also shown if the user clicks on their legend entries: Gini's mean difference (mean absolute difference between any two values) and the SD. These can be seen as horizontal lines up against the minimum x-value.```{r histbox,cap="Spike histograms, means, quantiles, Gini's mean difference, and SD stratified by treatment",scap="Stratified spike histograms and quantiles"}with(pbc, histboxp(x=sgot, group=drug, sd=TRUE))```The following is a better way to display proportions, for categorical variables. If computing marginal statistics by running the dataset through the `Hmisc``addMarginal` function, the `plot` method with `options(grType='plotly')` is especially useful.```{r summaryM5,cap='Proportions (large symbols) and proportions stratified by treatment (small symbols)',scap='Proportions with and without stratification by treatment'}pbcm <-addMarginal(pbc, drug)s <-summaryP(stage + sex + spiders ~ drug, data=pbc)# putHcap('Proportions stratified by treatment')plot(s, groups='drug')s <-summaryP(stage + sex + spiders ~ drug, data=pbcm)plot(s, marginVal='All', marginLabel='All Treatment Groups')```# Better Demonstration of Boxplot Replacement```{r support,cap="Spike histograms, means, quantiles, Gini's mean difference, and SD for MAP stratified by diagnosis",scap="Stratified spike histograms and quantiles for MAP"}getHdata(support2)with(support2, histboxp(x=meanbp, group=dzgroup, sd=TRUE, bins=200))```# Changing Size of Figure CaptionsAs explained [here](https://stackoverflow.com/questions/45018397), one can place captions under figures using ordinary `knitr` capabilities, and one can change the size of captions. The following example defines a `CSS` style to make captions small (here `0.6em`), and produces a plot with a caption. Unlike using `putHfig` captions given in `knitr` chunks do not also appear in the table of contents.<style>p.caption {font-size:0.6em;}</style>```{r simplecap,cap='This is a simple figure caption'}# Note: in the chunk header cap is an alias for fig.cap defined by knitrSetplot(runif(10))```# Computing Environment[^2] {#compenv}```{r}grateful::cite_packages(pkgs='Session', output='paragraph', out.dir='.',cite.tidyverse=FALSE, omit=c('grateful', 'ggplot2'))```The code was run on `r sessionInfo()$running` on a Macbook Pro M2 Max.# Bibliographic File Managament## Find and Install `.csl` Reference Style Files```{r findbib,eval=FALSE}# Note: mu was defined in an earlier code chunk# Only need to install .csl file once.mu$installcsl(rec=TRUE) # get list of recommended stylesmu$installcsl() # web search of styles meeting your criteria# Install a .csl file to your project directory:mu$installcsl('american-medical-association')````r markupSpecs$markdown$tof()`Note: the hidden R command that rendered the table of figures (including short captions) was `markupSpecs$markdown$tof()`.[^2]: `mu` is a copy of the part of the `Hmisc` package object `markupSpecs` that is for html. It includes a function `session` that renders the session environment (including package versions) in html.# References
