| Title: | Statistical Reporting with 'Quarto' |
|---|---|
| Description: | Provides statistical components, tables, and graphs that are useful in 'Quarto' and 'RMarkdown' reports and that produce 'Quarto' elements for special formatting such as tabs and marginal notes and graphs. Some of the functions produce entire report sections with tabs, e.g., the missing data report created by missChk(). Functions for inserting variables and tables inside 'graphviz' and 'mermaid' diagrams are included, and so are special clinical trial graphics for adverse event reporting. |
| Authors: | Frank E Harrell Jr [aut, cre] |
| Maintainer: | Frank E Harrell Jr <[email protected]> |
| License: | GPL (>= 2) |
| Version: | 1.1-0 |
| Built: | 2026-06-06 06:06:58 UTC |
| Source: | https://github.com/cran/qreport |
Add Figure Captions to a Dataset
addCap(label = NULL, cap = NULL, scap = NULL)addCap(label = NULL, cap = NULL, scap = NULL)
label |
figure label to use if not fetched from chunk information |
cap |
caption to use if not from chunk |
scap |
short caption to use if not from chunk |
Fetches the figure caption and optional short caption from the currently running code chunk (under knitr) and appends them to a running caption dataset named .captions. in the global environment. This facilites customizing a table of figures in a report.
invisible list with label, cap, scap
Frank Harrell
## Not run: # Called from inside a knitr chunk and all information pulled from # chunk information addCap() ## End(Not run)## Not run: # Called from inside a knitr chunk and all information pulled from # chunk information addCap() ## End(Not run)
Generates graphics for binary event proportions
aePlot( formula, data = NULL, subset = NULL, na.action = na.retain, exposure = NULL, expunit = "", study = " ", refgroup = NULL, minincidence = 0, conf.int = 0.95, etype = "adverse events", head = NULL, tail = NULL, size = c("regular", "wide"), popts = NULL, label = NULL )aePlot( formula, data = NULL, subset = NULL, na.action = na.retain, exposure = NULL, expunit = "", study = " ", refgroup = NULL, minincidence = 0, conf.int = 0.95, etype = "adverse events", head = NULL, tail = NULL, size = c("regular", "wide"), popts = NULL, label = NULL )
formula |
a formula with one or two left hand variables (the first representing major categorization and the second minor), and 1-2 right hand variables. One of the right hand variables may be enclosed in |
data |
input data frame |
subset |
subsetting criteria |
na.action |
function for handling |
exposure |
a numeric vector whose length is the number of treatments, with names equal to the treatment names |
expunit |
character string specifying the time units for |
study |
character string identifying the study; used in multi-study reports or where distinct patient strata are analyzed separately. Used to fetch the study-specific metadata stored by |
refgroup |
a character string specifying which treatment group is subtracted when computing risk differences. If there are two treatments the default is the first one listed in |
minincidence |
a number between 0 and 1 specifying the minimum incidence in any stratum that must hold before an event is included in the summary. When |
conf.int |
confidence level for difference in proportions (passed to |
etype |
a character string describing the nature of the events, for example |
head |
character string. Specifies initial text in the figure caption, otherwise a default is used. |
tail |
a character string to add to end of automatic caption |
size |
default is standard text body width. Set to |
popts |
a list of additional options to pass to |
label |
label for figure. |
Generates dot charts showing proportions of subjects having events (at any time). Events can be categorized by a single level or by major and minor levels (e.g., body system and preferred terms). When there are two treatments, half-width CLs of treatment differences are drawn, centered at the midpoint of the two proportions, and CLs for differences appear in hover text. Input data must contain one record per event, with this record containing the event name. If there is more than one event of a given type per subject, unique subject ID must be provided. Denominators come from qreport options when computing event incidence proportions. Instead, when a named vector exposure is specified, with names equal to the treatments, exposure is used as the denominator so that the exponential distribution hazard rate is computed, i.e., events per unit of exposure time. When a subject has only one event of each type, the usual interpretation holds. When a subject has multiple events, the estimate is events per person per time unit. A character variable expunit defines the time units. It is assumed that only randomized subjects are included in the dataset. Whenever the number of events of a given type is zero for a group, the event frequency is changed to 0.5 so that one may compute confidence intervals on the log scale as well as hazard ratios.
For an example with output see https://hbiostat.org/rflow/descript.html#adverse-event-chart/
no return value, called for knitting with knitr
Frank Harrell
# See test.Rnw in tests directory# See test.Rnw in tests directory
Convert Vector of Variables Names to a Right-Sided Formula
asForm(x)asForm(x)
x |
character vector |
Given a vector of character strings, turns them into a formula with no left hand side variable.
formula
Frank Harrell
asForm(letters[1:6])asForm(letters[1:6])
Find Continuous Variables
conVars(...)conVars(...)
... |
passed to [varType()] |
Uses [varType()] to type the variables then retrieves the vector of names of continuous ones.
character vector
Frank Harrell
## Not run: conVars(mydata) ## End(Not run)## Not run: conVars(mydata) ## End(Not run)
Run a Series of Data Checks and Report
dataChk( d, checks, id = character(0), html = FALSE, omit0 = FALSE, byid = FALSE, nrows = 500 )dataChk( d, checks, id = character(0), html = FALSE, omit0 = FALSE, byid = FALSE, nrows = 500 )
d |
a data table |
checks |
a vector of expressions that if satisfied causes records to be listed |
id |
option vector of variable names to serve as IDs |
html |
set to |
omit0 |
set to |
byid |
if |
nrows |
maximum number of rows to allow to be printed |
Function to run various data checks on a data table.
Checks are run separately for each part of the expression vector checks. For each single expression, the variables listed in the output are all the variables mentioned in the expression plus optional variables whose names are in the character vector id. %between% c(a,b) in expressions is printed as [a,b]. The output format is plain text unless html=TRUE which also puts each table in a separate Quarto tab. See here for examples.
an invisible data frame containing variables check (the expression checked) and n (the number of records satisfying the expression)
Frank Harrell
## Not run: dataChk(mydata) ## End(Not run)## Not run: dataChk(mydata) ## End(Not run)
Produce a Data Overview Quarto Section
dataOverview( d, d2 = NULL, id = NULL, plot = c("scatter", "dot", "none"), pr = nvar <= 50, which = 1, dec = 3 )dataOverview( d, d2 = NULL, id = NULL, plot = c("scatter", "dot", "none"), pr = nvar <= 50, which = 1, dec = 3 )
d |
a data frame or table |
d2 |
optional second dataset used for analyzing uniqueness of subject IDs |
id |
optional formula providing names of subject identifiers |
plot |
specifies type of plot, defaulting to |
pr |
set to |
which |
when two datasets are given which one should be the focus |
dec |
certain summary statistics are rounded to the nearest |
Produces a multi-tabbed dataset overview as exemplified here. This includes provision of data about data such as variable type, symmetry, missingness, rarest and most common values.
nothing; renders a report with Quarto/RMarkdown
Frank Harrell
## Not run: dataOverview(mydata, secondarydataset) ## End(Not run)## Not run: dataOverview(mydata, secondarydataset) ## End(Not run)
Find Discrete Variables
disVars(...)disVars(...)
... |
passed to [varType()] |
Uses [varType()] to type the variables then retrieves the vector of names of discrete ones.
character vector
Frank Harrell
## Not run: disVars(mydata) ## End(Not run)## Not run: disVars(mydata) ## End(Not run)
Create an html base64 string from a png graphic to draw needles for current sample sizes. Uses colors set by call to setqreportOptions.
dNeedle(sf, study = " ")dNeedle(sf, study = " ")
sf |
output of |
study |
character string specifying study ID |
a base64 representation of a png graphic, suitable for inclusion in html
setqreportOption(tx.var='treatment', denom=c(enrolled=1000, randomized=800, a=398, b=402)) dNeedle(sampleFrac(getqreportOption('denom')))setqreportOption(tx.var='treatment', denom=c(enrolled=1000, randomized=800, a=398, b=402)) dNeedle(sampleFrac(getqreportOption('denom')))
Get qreport options, assigning default values of unspecified options.
getqreportOption(opts = NULL, study = " ")getqreportOption(opts = NULL, study = " ")
opts |
character vector containing list of option names to retrieve. If only one element, the result is a scalar, otherwise a list. If |
study |
character string specifying an optional study designation |
getching qreport options
## Not run: getqreportOption('tx.var') ## End(Not run)## Not run: getqreportOption('tx.var') ## End(Not run)
Set knitr to Automatically Call addCap in Figure-Producing Chunks
hookaddcap(loc = NULL)hookaddcap(loc = NULL)
loc |
if non- |
Adds a knitr hook that takes effect before the chunk is run. The hook function retrieves figure information from the current chunk to give to addCap.
nothing; calls knitr hook and chunk option setting functions
Frank Harrell
## Not run: hookaddcap() ## End(Not run)## Not run: hookaddcap() ## End(Not run)
Create knitr Hook for Reporting Execution Time for Chunks
hooktime(all = FALSE)hooktime(all = FALSE)
all |
set to |
Creates a hook called time that can be activated by including time=TRUE in a chunk header. The chunk's execution time in seconds will be printed in a very small html font at the end of the chunk's output.
nothing
Frank Harrell
Print Named List of Vectors
htmlList(x, dec = 4)htmlList(x, dec = 4)
x |
a named list |
dec |
round to this decimal place |
Function to print a simple named list of vectors in html
Creates a column name from the names of the list
If a vector element of the list is numeric, it is rounded
to dec digits to the right of the decimal place.
a kable
Frank Harrell
set.seed(1) w <- list(A = runif(4), B=rnorm(3)) htmlList(w)set.seed(1) w <- list(A = runif(4), B=rnorm(3)) htmlList(w)
Convert Objects to HTML and View
htmlView(...)htmlView(...)
... |
any number of objects for which an |
Converts a series of objects created to html.
Displays these in the RStudio View pane.
If RStudio is not running displays in an external browser.
Assumes there is an html method for the objects (e.g., objects
are result of Hmisc::describe or Hmisc::contents.
User can page through the different outputs with the arrow keys
in the RStudio View pane
nothing is returned; used to launch a browser on html text
Frank Harrell
## Not run: htmlView(contents(d1), contents(d2)) htmlView(describe(d1), describe(d2, descript='Second Dataset')) htmlView(contents(d), describe(d)) ## End(Not run)## Not run: htmlView(contents(d1), contents(d2)) htmlView(describe(d1), describe(d2, descript='Second Dataset')) htmlView(contents(d), describe(d)) ## End(Not run)
Convert to HTML and Eternally View Objects
htmlViewx(..., tab = c("notfirst", "all", "none"))htmlViewx(..., tab = c("notfirst", "all", "none"))
... |
a series of objects for which an 'html' method exists |
tab |
set to ''all'' to add even the first object to an existing window. |
'htmlViewx' is similar to 'htmlView' except that an external viewer is launched, and the first object is opened in a new window. Subsequent objects are opened in a new tab in the last created window. Set ‘options(vbrowser=’command line to run browser')' to use a browser other than 'Vivaldi'. Defaults to opening a new window for only the first object, and adding tabs after that.
does not return a value; launches a browser
Frank Harrell
## Not run: options(prType='html') htmlViewx(contents(d), describe(d)) ## End(Not run)## Not run: options(prType='html') htmlViewx(contents(d), describe(d)) ## End(Not run)
Front-end to kable and kables
kabl(..., caption = NULL, digits = 4, col.names = NA, row.names = NA)kabl(..., caption = NULL, digits = 4, col.names = NA, row.names = NA)
... |
one or more objects to pass to |
caption |
overall single caption |
digits |
passed to |
col.names |
passed to |
row.names |
passed to |
Calls kable() if only one table is to be printed.
Calls kable() for each table and passes it to kables if more than one.
Accounts for results of tapply not being a vector (is an array)
result of kable or kables
Frank Harrell
kabl(data.frame(a=1:2, b=3:4), data.frame(x=11:13, y=21:23))kabl(data.frame(a=1:2, b=3:4), data.frame(x=11:13, y=21:23))
General Case Handling of Quarto Callouts
makecallout(...)makecallout(...)
... |
can be any of the following
|
This function generates and optionally runs markdown/R code that runs Quarto callouts such as collapsible notes or marginal notes. Before rendering x, options(rawmarkup=TRUE) is set so that Hmisc::rendHTML will not try to protect html in things like margins. Quarto doesn't like the surrounding html protection lines in that context. The option is set back to its original value after rendering.
if code is not executed, returns a character vector with the code to run
Frank Harrell
x <- 1:3 co <- '.callout-note collapse="true' makecallout(x, callout=co, label='# thislabel', type='print') makecallout(thislabel ~ x, callout=co, type='print')x <- 1:3 co <- '.callout-note collapse="true' makecallout(x, callout=co, label='# thislabel', type='print') makecallout(thislabel ~ x, callout=co, type='print')
Print an Object in a Collapsible Note
makecnote( x, label = paste0("`", deparse(substitute(x)), "`"), wide = FALSE, type = c("print", "run", "cat"), ... )makecnote( x, label = paste0("`", deparse(substitute(x)), "`"), wide = FALSE, type = c("print", "run", "cat"), ... )
x |
an object having a suitable |
label |
a character string providing a title for the tab. Default is the name of the argument passed to |
wide |
set to |
type |
default is to |
... |
an optional list of arguments to be passed to |
Prints an object in a Quarto collapsible note.
nothing is returned, used for rendering markup
Frank Harrell
makecnote('This is some text', label='mylab', wide=TRUE)makecnote('This is some text', label='mylab', wide=TRUE)
Create Text for Running Code Chunk
makecodechunk( cmd, opts = NULL, results = "asis", lang = "r", callout = NULL, h = NULL, w = NULL )makecodechunk( cmd, opts = NULL, results = "asis", lang = "r", callout = NULL, h = NULL, w = NULL )
cmd |
character string vector of commands to run inside chunk |
opts |
optional list of chunk options, e.g. |
results |
format of results, default is |
lang |
language for the chunk |
callout |
an optional Quarto callout to include after |
h |
optional height to place after the chunk header after |
w |
optional width |
Creates text strings suitable for running through knitr. The chunk is given a random name because certain operations are not allowed by knitr without it.
character vector
Frank Harrell
makecodechunk('x <- pi; print(x)')makecodechunk('x <- pi; print(x)')
Put an Object in the Margin
makecolmarg(x, type = c("print", "run", "cat"), ...)makecolmarg(x, type = c("print", "run", "cat"), ...)
x |
an object having a suitable |
type |
type of execution |
... |
an optional list of arguments to be passed to |
Prints an object in a Quarto column margin.
nothing is returned, used to render markup
Frank Harrell
makecolmarg(data.frame(x=1:3, y=4:6))makecolmarg(data.frame(x=1:3, y=4:6))
Takes a character string or vector and creates a graphviz dot flowchart from the input.
There are two kinds of input strings or lines. One defines nodes, the syntax being
nodename:string where nodename is any valid graphviz node name and string represents
a character string with possible variable value substitutions of the form {{variablename}}.
string is automatically wrapped by having newline characters inserted to keep lines
within width characters. The second kind of input line is one specifying node
connections with graphviz dot syntax, respecting node names defined in earlier strings.
Unlike makegvflow(), this approach allows a node to connect to any number of other nodes,
and allows any flow direction.
makedot( .object., ..., direction = c("TD", "LR"), shape = "box", fontsize = 24, nodesetup = NULL, file, width = 30, onlyprint = FALSE )makedot( .object., ..., direction = c("TD", "LR"), shape = "box", fontsize = 24, nodesetup = NULL, file, width = 30, onlyprint = FALSE )
.object. |
character string or vector of plain text plus possible $LaTeX$ math delimited by single dollar signs. An empty initial line is ignore, so the user need not worry about having an initial quote mark on a line by itself. |
... |
name=value pairs that makes values replace |
direction |
direction of the flow chart, default is top-down |
shape |
node shape |
fontsize |
text font size |
nodesetup |
extra node setup to include after |
file |
name of file to hold |
width |
text width for word-wrapping |
onlyprint |
set to ```{dot}
//| label: fig-flow1
//| fig-height: 4
//| fig-cap: "Chart caption"
//| file: graphviz.dot
```
|
If a node label contains \\n, all \\n are replaced with \n and ordinary word
wrapping is suppressed. This is how users take control of line splitting.
If a node label ends in //any text, the text in any text will be copied
to inside the node definition after the label is closed with double quote and
after a space is added. This allows node colors and other attributes to be changed.
Preceed single quotes in node labels with a single backslash. Preceed double quotes with double backslashes.
The function uses knitr::knit_expand() to apply variable insertions before the diagram is rendered by Quarto. See this for an example. ##' @title makedot
nothing; used to knitr::knit_expand() graphviz markup
Frank Harrell
x <- ' A:Some string of text for {{jj}} B:Another string of test, this one being longer and needing breaking C:A third string defining a node//style="filled,rounded", fillcolor=lightblue A -> B B -> C [label="some text along connecting arc"] C -> A' # Can also use A -> {B, C} makedot(x, jj='tiger', onlyprint=TRUE)x <- ' A:Some string of text for {{jj}} B:Another string of test, this one being longer and needing breaking C:A third string defining a node//style="filled,rounded", fillcolor=lightblue A -> B B -> C [label="some text along connecting arc"] C -> A' # Can also use A -> {B, C} makedot(x, jj='tiger', onlyprint=TRUE)
Create a Quarto Graphviz dot Diagram Chunk With Variable Insertions
makegraphviz(.object., ..., file)makegraphviz(.object., ..., file)
.object. |
character string or vector with |
... |
name=value pairs that makes values replace |
file |
name of file to hold ```{dot}
//| label: fig-doverview-graphviz
//| fig-height: 4
//| fig-cap: "Consort diagram produced with `graphviz` with detailed exclusion frequencies in a separate node"
//| file: graphviz.dot
```
|
Takes a character string or vector and uses knitr::knit_expand() to apply variable insertions before the diagram is rendered by Quarto. See this for an example. Unlike mermaid, graphviz can include user-defined linkages to specific parts of a node (e.g., a single word in a line of text) to another part of the chart, and can render tables. If an inclusion is ... is a data frame or table, it will be properly rendered inside the diagram.
nothing; used to knitr::knit_expand() graphviz markup
Frank Harrell
makemermaid(), makegvflow(), makedot()
Takes a character string or vector and creates a graphviz flowchart from the
hierarchy indicated by the number of indended spaces in each line. The text
for the root levels is not indented, and major, minor, and tiny levels are indented
2, 4, or 6 spaces, respectively. Default color, font size, and fill color are
chosen so that the chart is suitable for presentations. Simple $LaTeX$ math
markup is converted to simple HTML markup using tth::tth(). Text lines
are automatically wrapped to keep text boxes from being too wide. Text lines
beginning with "+" are combined with the previous major, minor, or tiny text line
but separated by a double line break (single break if lbdouble=FALSE).
makegvflow( .object., ..., direction = c("TD", "LR"), style = "filled", shape = "box", font = "Times-Roman", fontsize = 18, fontcolor = "blue", fillcolor = "azure", penwidth = 0.1, arrowcolor = "blue3", arrowsize = 0.7, width = 30, lbdouble = TRUE, extracon = NULL, file, onlyprint = FALSE )makegvflow( .object., ..., direction = c("TD", "LR"), style = "filled", shape = "box", font = "Times-Roman", fontsize = 18, fontcolor = "blue", fillcolor = "azure", penwidth = 0.1, arrowcolor = "blue3", arrowsize = 0.7, width = 30, lbdouble = TRUE, extracon = NULL, file, onlyprint = FALSE )
.object. |
character string or vector of plain text plus possible $LaTeX$ math delimited by single dollar signs. An empty initial line is ignore, so the user need not worry about having an initial quote mark on a line by itself. |
... |
name=value pairs that makes values replace |
direction |
direction of the flow chart, default is top-down |
style |
node style |
shape |
node shape |
font |
font for text in nodes |
fontsize |
text font size |
fontcolor |
text color |
fillcolor |
node fill color |
penwidth |
thickness of lines for node borders |
arrowcolor |
arrow color |
arrowsize |
arrow size |
width |
text width for word-wrapping |
lbdouble |
set to |
extracon |
one or more text strings specifying extra connections between nodes using node names |
file |
name of file to hold |
onlyprint |
set to ```{dot}
//| label: fig-flow1
//| fig-height: 4
//| fig-cap: "Chart caption"
//| file: graphviz.dot
```
|
The function uses knitr::knit_expand() to apply variable insertions before the diagram is rendered by Quarto. See this for an example. ##' @title makegvflow
nothing; used to knitr::knit_expand() graphviz markup
Frank Harrell
x <- ' Root text Major 1 Minor 11 {{jj}} Minor 12 Major 2 Minor 21 Minor 22 Minor 23 that is very very long and just keeps going tiny 231 and $\\alph + \\sum_{i=1}^{n}X_{i}$ tiny 232 + a second line for tiny 232 that is pretty long + a third line for tiny 232 Major 3 Minor 31 tiny 311' makegvflow(x, extracon='n12 -> n21', jj='tiger', onlyprint=TRUE)x <- ' Root text Major 1 Minor 11 {{jj}} Minor 12 Major 2 Minor 21 Minor 22 Minor 23 that is very very long and just keeps going tiny 231 and $\\alph + \\sum_{i=1}^{n}X_{i}$ tiny 232 + a second line for tiny 232 that is pretty long + a third line for tiny 232 Major 3 Minor 31 tiny 311' makegvflow(x, extracon='n12 -> n21', jj='tiger', onlyprint=TRUE)
Create a Quarto Mermaid Diagram Chunk With Variable Insertions
makemermaid(.object., ..., file)makemermaid(.object., ..., file)
.object. |
character string or vector with |
... |
name=value pairs that makes values replace |
file |
name of file to hold ```{mermaid}
%%| fig-cap: "Consort diagram produced by `mermaid`"
%%| label: fig-mermaid1
%%| file: mermaid1.mer
```
|
Takes a character string or vector and uses knitr::knit_expand() to apply variable insertions before the diagram is rendered by Quarto. See this for an example.
nothing; used to knitr::knit_expand() mermaid markup
Frank Harrell
Make Quarto Tabs
maketabs( ..., wide = FALSE, cwidth = if (wide) "column-page", initblank = FALSE, baselabel = NULL, cap = NULL, basecap = NULL, debug = FALSE )maketabs( ..., wide = FALSE, cwidth = if (wide) "column-page", initblank = FALSE, baselabel = NULL, cap = NULL, basecap = NULL, debug = FALSE )
... |
a series of formulas or a single named list. For formulas the left side is the tab label (if multiple words or other illegal R expressions enclose in backticks) and the right hand side has expressions to evaluate during chunk execution, plus optional |
wide |
set to |
cwidth |
specify a legal |
initblank |
set to |
baselabel |
a one-word character string that provides the base name of |
cap |
applies to the non-formula use of |
basecap |
a single character string providing the base text for captions if |
debug |
set to |
Loops through a series of formulas or elements of a named list and outputs each element into
a separate Quarto tab. wide and column arguments are used to expand the width
of the output outside the usual margins. An initblank argument
creates a first tab that is empty, or you can specify a formula ~ . This allows one to show nothing
until one of the other tabs is clicked. Multiple commands can be run in one chunk by including multiple right hand terms in a formula. A chunk can be marked for producing raw output by including a term raw somewhere in the formula's right side. If can be marked for constructing a label and caption by including + caption(caption string, label string). The tab number is appended to the label string, and if the label is not provided baselabel will be used.
nothing is returned; used to render markup
Frank Harrell
X <- list(A=data.frame(x=1:2), B=data.frame(x=1:2, y=11:12)) maketabs(X)X <- list(A=data.frame(x=1:2), B=data.frame(x=1:2, y=11:12)) maketabs(X)
Produce a Report Section Detailing Missing Values in a Dataset
missChk( data, use = NULL, exclude = NULL, type = c("report", "seq"), maxpat = 15, maxcomb = 25, excl1pat = TRUE, sortpatterns = TRUE, prednmiss = FALSE, omitpred = NULL, baselabel = NULL, ... )missChk( data, use = NULL, exclude = NULL, type = c("report", "seq"), maxpat = 15, maxcomb = 25, excl1pat = TRUE, sortpatterns = TRUE, prednmiss = FALSE, omitpred = NULL, baselabel = NULL, ... )
data |
data frame or table to analyze |
use |
a formula or character vector specifying which variables to consider if not all those in |
exclude |
a formula or character vector specifying which variables to exclude from consideration |
type |
specify |
maxpat |
maximum number of missing data patterns allowed when counting occurrences of all combinations of variables' |
maxcomb |
maximum number of combinations for which to produce a combination dot plot |
excl1pat |
set to |
sortpatterns |
set to |
prednmiss |
set to |
omitpred |
a formula or character vector specifying a list of predictors not to use when predicting number of missing variables |
baselabel |
base label for Quarto tabs made with |
... |
passed to |
Quantifies frequencies of missing observations on a variable and missing variables on an observaton and produces variables tables and (depending on the number of NAs) multiple graphic displays in Quarto tabs. The results are best understood by referring to this.
nothing; outputs Quarto/RMarkdown text and tabs for a full report section
Frank Harrell
## Not run: missChk(mydata) ## End(Not run)## Not run: missChk(mydata) ## End(Not run)
Multiple Dataset Overview
multDataOverview(X, id = NULL)multDataOverview(X, id = NULL)
X |
list object containing any number of data frames/tables |
id |
formula containing a single subject identifier, e.g., |
Provides an overview of the data tables inside a giant list. The result returned (invisible) is a data table containing for each variable a comma-separated list of datasets containing that variable (other than id variables).
invisibly, a data table
Frank Harrell
## Not run: multDataOverview(list(data1=mydata1, data2=mydata2), id = ~ subject.id) ## End(Not run)## Not run: multDataOverview(list(data1=mydata1, data2=mydata2), id = ~ subject.id) ## End(Not run)
If options(dumpfile="...") is set, uses Hmisc::prn() to print objects for debugging
pdumpit(x, txt = as.character(substitute(x)))pdumpit(x, txt = as.character(substitute(x)))
x |
input to |
txt |
text label, defaults to name of |
no result, used only for printing debugging information
Frank Harrell
Pretty Printing of Captions Dataset
printCap(book = FALSE)printCap(book = FALSE)
book |
set to |
Uses kable to print the caption information saved in .captions..
kable object
Frank Harrell
## Not run: princCap() ## End(Not run)## Not run: princCap() ## End(Not run)
Create Quarto Figure Caption
putQcap(..., scap = NULL, label = NULL)putQcap(..., scap = NULL, label = NULL)
... |
one or more character strings to form the caption |
scap |
a character string subcaption |
label |
figure label |
Creates a Quarto label and caption and uses addCap() to add to running list of figures
string vector with YAML components label, fig-cap, fig-scap
Frank Harrell
putQcap('First part of caption', 'second part', scap='subcaption', label='xx')putQcap('First part of caption', 'second part', scap='subcaption', label='xx')
Apply Derived Variable Specifications
runDeriveExpr(d, derv, pr = TRUE)runDeriveExpr(d, derv, pr = TRUE)
d |
a data table |
derv |
a |
pr |
set |
Function to apply derived variable specifications derv to a data table d. Actions on d are done in place, so call the function using runDeriveExpr(d, derv object) and not by running d <- runDeriveExpr(d, derv object).
See this for an example.
nothing; used to print information and add variables to data table
Frank Harrell
require(data.table) d <- data.table(ht=c(68, 60), wt=c(280, 135), chol=c(120, 150)) derived <- list( list(bmi = expression(703 * wt / ht ^ 2), label='Body Mass Index', units='Kg/m^2'), list(bsa=expression(0.007184 * (0.4536 * wt) ^ 0.425 * (2.54 * ht) ^ 0.725), label='Body Surface Area', units='m^2', drop=.q(wt, ht) ) ) runDeriveExpr(d, derived) print(d) contents(d)require(data.table) d <- data.table(ht=c(68, 60), wt=c(280, 135), chol=c(120, 150)) derived <- list( list(bmi = expression(703 * wt / ht ^ 2), label='Body Mass Index', units='Kg/m^2'), list(bsa=expression(0.007184 * (0.4536 * wt) ^ 0.425 * (2.54 * ht) ^ 0.725), label='Body Surface Area', units='m^2', drop=.q(wt, ht) ) ) runDeriveExpr(d, derived) print(d) contents(d)
Protecting Backticks for Illustrating In-line R Code
rwrap(x)rwrap(x)
x |
a character string |
This function pastes back ticks around a string so those extra back ticks don't have to appear in the user's code in a report. This prevents Quarto from intervening.
x surrounded by backtick r and backtick
Frank Harrell
rwrap('pi')rwrap('pi')
Uses denominators stored with setqreportOption along with counts specified to SampleFrac to compute fractions of subjects in current analysis
sampleFrac(n, nobsY = NULL, table = TRUE, study = " ")sampleFrac(n, nobsY = NULL, table = TRUE, study = " ")
n |
integer vector, named with |
nobsY |
a result of the the |
table |
set to |
study |
character string with study ID |
named vector of relative sample sizes with an attribute table with frequency counts
setqreportOption(tx.var='treatment', denom=c(enrolled=1000, randomized=800, a=398, b=402)) sampleFrac(getqreportOption('denom'))setqreportOption(tx.var='treatment', denom=c(enrolled=1000, randomized=800, a=398, b=402)) sampleFrac(getqreportOption('denom'))
Save Caption Dataset in External File
saveCap(basename)saveCap(basename)
basename |
base file name to which |
Uses base::saveRDS() to save the .captions. dataset to a user file.
nothing; used to create a saved RDS dataset of caption information
Frank Harrell
## Not run: saveCap('chapter3') ## End(Not run)## Not run: saveCap('chapter3') ## End(Not run)
Separate Chunk Plot
scplot(command, cap = NULL, scap = NULL, w = 5, h = 4, id = NULL)scplot(command, cap = NULL, scap = NULL, w = 5, h = 4, id = NULL)
command |
an command that causes a plot to be rendered |
cap |
long caption |
scap |
short caption |
w |
width of plot |
h |
height of plot |
id |
a string ID for the plot. Defaults to the current chunk label if |
Runs a plot on its own Rmarkdown/Quarto knitr Chunk. The plot will have its own caption and size, and short captions are placed in the markdown TOC
Expressions cannot be re-used, i.e., each expression must evaluate to the right quantity after the chunk in which the scplot calls are made is finished, and the new constructed chunk is input. To input and run the constructed chunk:
{r child='scplot.Rmd'} preceeded and following by 3 back ticks.
Hmisc::putHcap is used to markup regular and short captions cap, scap. Short caption appears in TOC. If no scap, then cap is used for this. To change the putHcap subsub argument set options(scplot.subsub='## ') for example.
no value return; outputs R Markdown/Quarto markup
Frank Harrell
## Not run: scplot(id='chunkid') # initialize output file scplot.Rmd # or use scplot() to use the current chunk name as the id # scplot(plotting expression, caption, optional short caption, w, h) # scplot(plotting expression ...) ## End(Not run)## Not run: scplot(id='chunkid') # initialize output file scplot.Rmd # or use scplot() to use the current chunk name as the id # scplot(plotting expression, caption, optional short caption, w, h) # scplot(plotting expression ...) ## End(Not run)
Set qreport options, assigning certain defaults
setqreportOption(..., study = " ")setqreportOption(..., study = " ")
... |
a series of options for which non-default values are desired:
|
study |
an optional study mnemonic (character string) needed when multiple studies are being analyzed (or when one study is divided into distinct strata) |
no returned value, used to set options()
setqreportOption(tx.var='treatment', denom=c(enrolled=1000, randomized=800, a=398, b=402))setqreportOption(tx.var='treatment', denom=c(enrolled=1000, randomized=800, a=398, b=402))
Set Nice Defaults for Base Graphics Parameters
spar( mar = if (!axes) c(2.25 + 0.6 + bot - 0.45 * multi, 2 * (las == 1) + 2.2 + left, 0.5 + top + 0.25 * multi, 0.5 + rt) else c(3.25 + 0.6 + bot - 0.45 * multi, 2 * (las == 1) + 3.7 + left, 0.5 + top + 0.25 * multi, 0.5 + rt), lwd = if (multi) 1 else 1.75, mgp = if (!axes) mgp = c(0.75, 0.1, 0) else if (multi) c(1.5 + 0.83, 0.365 - 0.03, 0) else c(2.4 - 0.4 + 0.83, 0.475 - 0.03, 0), tcl = if (multi) -0.25 else -0.4, xpd = FALSE, las = 1, bot = 0, left = 0, top = 0, rt = 0, ps = if (multi) 12 else 15, mfrow = NULL, axes = TRUE, cex.lab = 1.15, cex.axis = 0.8, ... )spar( mar = if (!axes) c(2.25 + 0.6 + bot - 0.45 * multi, 2 * (las == 1) + 2.2 + left, 0.5 + top + 0.25 * multi, 0.5 + rt) else c(3.25 + 0.6 + bot - 0.45 * multi, 2 * (las == 1) + 3.7 + left, 0.5 + top + 0.25 * multi, 0.5 + rt), lwd = if (multi) 1 else 1.75, mgp = if (!axes) mgp = c(0.75, 0.1, 0) else if (multi) c(1.5 + 0.83, 0.365 - 0.03, 0) else c(2.4 - 0.4 + 0.83, 0.475 - 0.03, 0), tcl = if (multi) -0.25 else -0.4, xpd = FALSE, las = 1, bot = 0, left = 0, top = 0, rt = 0, ps = if (multi) 12 else 15, mfrow = NULL, axes = TRUE, cex.lab = 1.15, cex.axis = 0.8, ... )
mar |
see |
lwd |
see |
mgp |
see |
tcl |
see |
xpd |
see |
las |
see |
bot |
additional lines of space to set aside for the bottom of the graph for extra subtitles etc. |
left |
additional lines to set aside at left |
top |
same for top |
rt |
same for right margin |
ps |
see |
mfrow |
see |
axes |
see |
cex.lab |
see |
cex.axis |
see |
... |
other parameters passed as-is to |
This function tries to set graphics::par() to make base graphics look more publication-ready.
nothing; side effect of setting par()
Frank Harrell
## Not run: spar(top=2, bot=1) # leave extra space for titles ## End(Not run)## Not run: spar(top=2, bot=1) # leave extra space for titles ## End(Not run)
Time an Expression and Report in Quarto Margin
timeMar(x)timeMar(x)
x |
an expression to execute |
Function to time an expression, printing the result of base::system.time() in the right margin, and storing the result of system.time in .systime. in the global environment so tha the user can refer to it.
invisibly, the result of the expression
Frank Harrell
## Not run: g <- function(...){} # define a function to run slowly result <- timeMar(g()) ## End(Not run)## Not run: g <- function(...){} # define a function to run slowly result <- timeMar(g()) ## End(Not run)
Determine Types of Variables
varType(data, include = NULL, exclude = NULL, ndistinct = 10, nnonnum = 20)varType(data, include = NULL, exclude = NULL, ndistinct = 10, nnonnum = 20)
data |
data frame or table to analyze |
include |
formula or vector of variable names to attend to |
exclude |
a formula or character vector specifying which variables to exclude from consideration |
ndistinct |
minimum number of distinct numeric values a variable must have to be considered continuous |
nnonnum |
maximum number of distinct values a variable can have to be considered discrete |
For all the variables in a data frame/table, analyzes them to determine types: continuous, nonnumeric, and discrete. include and exclude can be vector or right-side-only formulas.
list of vectors
Frank Harrell
set.seed(1) d <- data.frame(i=1:100, x=runif(100), y=sample(1:3, 100, TRUE), w=sample(c('cat','dog','giraffe'), 100, TRUE), v=sample(letters, 100, TRUE)) varType(d)set.seed(1) d <- data.frame(i=1:100, x=runif(100), y=sample(1:3, 100, TRUE), w=sample(c('cat','dog','giraffe'), 100, TRUE), v=sample(letters, 100, TRUE)) varType(d)
Make Variable Clustering Quarto Report Section
vClus( d, exclude = NULL, corrmatrix = FALSE, redundancy = FALSE, spc = FALSE, trans = FALSE, rexclude = NULL, fracmiss = 0.2, maxlevels = 10, minprev = 0.05, imputed = NULL, horiz = FALSE, label = "fig-varclus", print = TRUE, redunargs = NULL, spcargs = NULL, transaceargs = NULL, transacefile = NULL, spcfile = NULL )vClus( d, exclude = NULL, corrmatrix = FALSE, redundancy = FALSE, spc = FALSE, trans = FALSE, rexclude = NULL, fracmiss = 0.2, maxlevels = 10, minprev = 0.05, imputed = NULL, horiz = FALSE, label = "fig-varclus", print = TRUE, redunargs = NULL, spcargs = NULL, transaceargs = NULL, transacefile = NULL, spcfile = NULL )
d |
a data frame or table |
exclude |
formula or vector of character strings containing variables to exclude from analysis |
corrmatrix |
set to |
redundancy |
set to |
spc |
set to |
trans |
set to |
rexclude |
extra variables to exclude from |
fracmiss |
if the fraction of |
maxlevels |
if the maximum number of distinct values for a categorical variable exceeds this, the variable will be dropped |
minprev |
the minimum proportion of non-missing observations in a category for a binary variable to be retained, and the minimum relative frequency of a category before it will be combined with other small categories |
imputed |
an object created by |
horiz |
set to |
label |
figure label for Quarto |
print |
set to |
redunargs |
a |
spcargs |
a |
transaceargs |
a |
transacefile |
similar to |
spcfile |
a character string specifying an |
Draws a variable clustering dendrogram and optionally graphically depicts a correlation matrix. See this for an example. Uses Hmisc::varclus().
makes Quarto tabs and prints output, returning nothing unless spc=TRUE or trans=TRUE are used, in which case a list with components princmp and/or transace is returned and these components can be passed to special print and plot methods for spc or to ggplot_transace. The user can put scree plots and PC loading plots in separate code chunks that use different figure sizes that way.
Frank Harrell
Hmisc::varclus(), Hmisc::plotCorrM(), Hmisc::dataframeReduce(), Hmisc::redun(), Hmisc::princmp(), Hmisc::transace()
## Not run: vClus(mydata, exclude=.q(country, city)) ## End(Not run)## Not run: vClus(mydata, exclude=.q(country, city)) ## End(Not run)