Hmisc (version 5.3-0)

summaryM: Summarize Mixed Data Types vs. Groups

Description

summaryM summarizes the variables listed in an S formula, computing descriptive statistics and optionally statistical tests for group differences. This function is typically used when there are multiple left-hand-side variables that are independently against by groups marked by a single right-hand-side variable. The summary statistics may be passed to print methods, plot methods for making annotated dot charts and extended box plots, and latex methods for typesetting tables using LaTeX. The html method uses htmlTable::htmlTable to typeset the table in html, by passing information to the latex method with html=TRUE. This is for use with Quarto/RMarkdown. The print methods use the print.char.matrix function to print boxed tables when options(prType=) has not been given or when prType='plain'. For plain tables, print calls the internal function printsummaryM. When prType='latex' the latex method is invoked, and when prType='html' html is rendered. In Quarto/RMarkdown, proper rendering will result even if results='asis' does not appear in the chunk header. When rendering in html at the console due to having options(prType='html') the table will be rendered in a viewer.

The plot method creates plotly graphics if options(grType='plotly'), otherwise base graphics are used. plotly graphics provide extra information such as which quantile is being displayed when hovering the mouse. Test statistics are displayed by hovering over the mean.

Continuous variables are described by three quantiles (quartiles by default) when printing, or by the following quantiles when plotting expended box plots using the bpplt function: 0.05, 0.125, 0.25, 0.375, 0.5, 0.625, 0.75, 0.875, 0.95. The box plots are scaled to the 0.025 and 0.975 quantiles of each continuous left-hand-side variable. Categorical variables are described by counts and percentages.

The left hand side of formula may contain mChoice ("multiple choice") variables. When test=TRUE each choice is tested separately as a binary categorical response.

The plot method for method="reverse" creates a temporary function Key as is done by the xYplot and Ecdf.formula functions. After plot runs, you can type Key() to put a legend in a default location, or e.g. Key(locator(1)) to draw a legend where you click the left mouse button. This key is for categorical variables, so to have the opportunity to put the key on the graph you will probably want to use the command plot(object, which="categorical"). A second function Key2 is created if continuous variables are being plotted. It is used the same as Key. If the which argument is not specified to plot, two pages of plots will be produced. If you don't define par(mfrow=) yourself, plot.summaryM will try to lay out a multi-panel graph to best fit all the individual charts for continuous variables.

Usage

summaryM(formula, groups=NULL, data=NULL, subset, na.action=na.retain,
         overall=FALSE, continuous=10, na.include=FALSE,
         quant=c(0.025, 0.05, 0.125, 0.25, 0.375, 0.5, 0.625,
                 0.75, 0.875, 0.95, 0.975),
         nmin=100, test=FALSE,
         conTest=conTestkw, catTest=catTestchisq,
         ordTest=ordTestpo)
# S3 method for summaryM
print(...)
printsummaryM(x, digits, prn = any(n != N),
      what=c('proportion', '%'), pctdig = if(what == '%') 0 else 2,
      npct = c('numerator', 'both', 'denominator', 'none'),
      exclude1 = TRUE, vnames = c('labels', 'names'), prUnits = TRUE,
      sep = '/', abbreviate.dimnames = FALSE,
      prefix.width = max(nchar(lab)), min.colwidth, formatArgs=NULL, round=NULL,
      prtest = c('P','stat','df','name'), prmsd = FALSE, long = FALSE,
      pdig = 3, eps = 0.001, prob = c(0.25, 0.5, 0.75), prN = FALSE, ...)
# S3 method for summaryM
plot(x, vnames = c('labels', 'names'),
     which = c('both', 'categorical', 'continuous'), vars=NULL,
     xlim = c(0,1),
     xlab = 'Proportion',
     pch = c(16, 1, 2, 17, 15, 3, 4, 5, 0), exclude1 = TRUE,
     main, ncols=2,
     prtest = c('P', 'stat', 'df', 'name'), pdig = 3, eps = 0.001,
     conType = c('bp', 'dot', 'raw'), cex.means = 0.5, cex=par('cex'),
     height='auto', width=700, ...)
# S3 method for summaryM
latex(object, title =
      first.word(deparse(substitute(object))),
      file=paste(title, 'tex', sep='.'), append=FALSE, digits, 
      prn = any(n != N), what=c('proportion', '%'),
      pctdig = if(what == '%') 0 else 2,
      npct = c('numerator', 'both', 'denominator', 'slash', 'none'),
      npct.size = if(html) mspecs$html$smaller else 'scriptsize',
      Nsize = if(html) mspecs$html$smaller else 'scriptsize',
      exclude1 = TRUE,
      vnames=c("labels", "names"), prUnits = TRUE, middle.bold = FALSE,
      outer.size = if(html) mspecs$html$smaller else "scriptsize",
      caption, rowlabel = "", rowsep=html,
      insert.bottom = TRUE, dcolumn = FALSE, formatArgs=NULL, round=NULL,
      prtest = c('P', 'stat', 'df', 'name'), prmsd = FALSE,
      msdsize = if(html) function(x) x else NULL, brmsd=FALSE,
      long = FALSE, pdig = 3, eps = 0.001,
      auxCol = NULL, table.env=TRUE, tabenv1=FALSE, prob=c(0.25, 0.5, 0.75),
      prN=FALSE, legend.bottom=FALSE, html=FALSE,
      mspecs=markupSpecs, ...)
# S3 method for summaryM
html(object, ...)

Value

a list. plot.summaryM returns the number of pages of plots that were made if using base graphics, or

plotly objects created by plotly::subplot otherwise. If both categorical and continuous variables were plotted, the returned object is a list with two named elements Categorical

and Continuous each containing plotly objects. Otherwise a plotly object is returned. The latex method returns attributes legend and

nstrata.

References

Harrell FE (2004): Statistical tables and plots using S and LaTeX. Document available from https://hbiostat.org/R/Hmisc/summary.pdf.

See Also

mChoice, label, dotchart3, print.char.matrix, update, formula, format.default, latex, latexTranslate, bpplt, tabulr, bpplotM, summaryP

Examples

options(digits=3)
set.seed(173)
sex <- factor(sample(c("m","f"), 500, rep=TRUE))
country <- factor(sample(c('US', 'Canada'), 500, rep=TRUE))
age <- rnorm(500, 50, 5)
sbp <- rnorm(500, 120, 12)
label(sbp) <- 'Systolic BP'
units(sbp) <- 'mmHg'
treatment <- factor(sample(c("Drug","Placebo"), 500, rep=TRUE))
treatment[1]
sbp[1] <- NA

# Generate a 3-choice variable; each of 3 variables has 5 possible levels
symp <- c('Headache','Stomach Ache','Hangnail',
          'Muscle Ache','Depressed')
symptom1 <- sample(symp, 500,TRUE)
symptom2 <- sample(symp, 500,TRUE)
symptom3 <- sample(symp, 500,TRUE)
Symptoms <- mChoice(symptom1, symptom2, symptom3, label='Primary Symptoms')
table(as.character(Symptoms))

# Note: In this example, some subjects have the same symptom checked
# multiple times; in practice these redundant selections would be NAs
# mChoice will ignore these redundant selections

f <- summaryM(age + sex + sbp + Symptoms ~ treatment, test=TRUE)
f
# trio of numbers represent 25th, 50th, 75th percentile
print(f, long=TRUE)
plot(f)    # first specify options(grType='plotly') to use plotly
plot(f, conType='dot', prtest='P')
bpplt()    # annotated example showing layout of bp plot

# Produce separate tables by country
f <- summaryM(age + sex + sbp + Symptoms ~ treatment + country,
              groups='treatment', test=TRUE)
f

if (FALSE) {
getHdata(pbc)
s5 <- summaryM(bili + albumin + stage + protime + sex + 
               age + spiders ~ drug, data=pbc)

print(s5, npct='both')
# npct='both' : print both numerators and denominators
plot(s5, which='categorical')
Key(locator(1))  # draw legend at mouse click
par(oma=c(3,0,0,0))  # leave outer margin at bottom
plot(s5, which='continuous')  # see also bpplotM
Key2()           # draw legend at lower left corner of plot
                 # oma= above makes this default key fit the page better

options(digits=3)
w <- latex(s5, npct='both', here=TRUE, file='')

options(grType='plotly')
pbc <- upData(pbc, moveUnits = TRUE)
s <- summaryM(bili + albumin + alk.phos + copper + spiders + sex ~
              drug, data=pbc, test=TRUE)
# Render html
options(prType='html')
s   # invokes print.summaryM
a <- plot(s)
a$Categorical
a$Continuous
plot(s, which='con')
}