Miscellaneous Functions

This documents miscellaneous small functions in Hmisc that may be of interest to users.

clowess runs lowess but if the iter argument exceeds zero, sometimes wild values can result, in which case lowess is re-run with iter=0.

confbar draws multi-level confidence bars using small rectangles that may be of different colors.

getLatestSource fetches and sources the most recent source code for functions in GitHub.

grType retrieves the system option grType, which is forced to be "base" if the plotly package is not installed.

prType retrieves the system option prType, which is set to "plain" if the option is not set. print methods that allow for markdown/html/latex can be automatically invoked by setting options(prType="html") or options(prType='latex').

htmlSpecialType retrieves the system option htmlSpecialType, which is set to "unicode" if the option is not set. htmlSpecialType='unicode' cause html-generating functions in Hmisc and rms to use unicode for special characters, and htmlSpecialType='&' uses the older ampersand 3-digit format.

inverseFunction generates a function to find all inverses of a monotonic or nonmonotonic function that is tabulated at vectors (x,y), typically 1000 points. If the original function is monotonic, simple linear interpolation is used and the result is a vector, otherwise linear interpolation is used within each interval in which the function is monotonic and the result is a matrix with number of columns equal to the number of monotonic intervals. If a requested y is not within any interval, the extreme x that pertains to the nearest extreme y is returned. Specifying what='sample' to the returned function will cause a vector to be returned instead of a matrix, with elements taken as a random choice of the possible inverses.

james.stein computes James-Stein shrunken estimates of cell means given a response variable (which may be binary) and a grouping indicator.

keepHattrib for an input variable or a data frame, creates a list object saving special Hmisc attributes such as label and units that might be lost during certain operations such as running data.table. restoreHattrib restores these attributes.

km.quick provides a fast way to invoke survfitKM in the survival package to efficiently get Kaplan-Meier or Fleming-Harrington estimates for a single stratum for a vector of time points (if times is given) or to get a vector of survival time quantiles (if q is given). If neither is given, the whole curve is returned in a list with objects time and surv, and there is an option to consider an interval as pertaining to greater than or equal to a specific time instead of the traditional greater than. If the censoring is not right censoring, the more general survfit is called by km.quick.

latexBuild takes pairs of character strings and produces a single character string containing concatenation of all of them, plus an attribute "close" which is a character string containing the LaTeX closure that will balance LaTeX code with respect to parentheses, braces, brackets, or begin vs. end. When an even-numbered element of the vector is not a left parenthesis, brace, or bracket, the element is taken as a word that was surrounded by begin and braces, for which the corresponding end is constructed in the returned attribute.

lm.fit.qr.bare is a fast stripped-down function for computing regression coefficients, residuals, \(R^2\), and fitted values. It uses lm.fit.

matxv multiplies a matrix by a vector, handling automatic addition of intercepts if the matrix does not have a column of ones. If the first argument is not a matrix, it will be converted to one. An optional argument allows the second argument to be treated as a matrix, useful when its rows represent bootstrap reps of coefficients. Then ab' is computed. matxv respects the "intercepts" attribute if it is stored on b by the rms package. This is used by orm fits that are bootstrap-repeated by bootcov where only the intercept corresponding to the median is retained. If kint has nonzero length, it is checked for consistency with the attribute.

makeSteps is a copy of the dostep function inside the survival package's plot.survfit function. It expands a series of points to include all the segments needed to plot step functions. This is useful for drawing polygons to shade confidence bands for step functions.

nomiss returns a data frame (if its argument is one) with rows corresponding to NAs removed, or it returns a matrix with rows with any element missing removed.

outerText uses axis() to put right-justified text strings in the right margin. Placement depends on par('mar')[4]

plotlyParm is a list of functions useful for specifying parameters to plotly graphics.

plotp is a generic to handle plotp methods to make plotly graphics.

rendHTML renders HTML in a character vector, first converting to one character string with newline delimeters. If knitr is currently running, runs this string through knitr::asis_output so that the user need not include results='asis' in the chunk header for R Markdown or Quarto. If knitr is not running, uses htmltools::browsable and htmltools::HTML and prints the result so that an RStudio viewer (if running inside RStudio) or separate browser window displays the rendered HTML. The HTML code is surrounded by yaml markup to make Pandoc not fiddle with the HTML. Set the argument html=FALSE to not add this, in case you are really rendering markdown. html=FALSE also invokes rmarkdown::render to convert the character vector to HTML before using htmltools to view, assuming the characters represent RMarkdown/Quarto text other than the YAML header. If options(rawmarkup=TRUE) is in effect, rendHTML will just cat() its first argument. This is useful when rendering is happening inside a Quarto margin, for example.

sepUnitsTrans converts character vectors containing values such as c("3 days","3day","4month","2 years","2weeks","7") to numeric vectors (here c(3,3,122,730,14,7)) in a flexible fashion. The user can specify a vector of units of measurements and conversion factors. The units with a conversion factor of 1 are taken as the target units, and if those units are present in the character strings they are ignored. The target units are added to the resulting vector as the "units" attribute.

strgraphwrap is like strwrap but is for the current graphics environment.

tobase64image is a function written by Dirk Eddelbuettel that uses the base64enc package to convert a png graphic file to base64 encoding to include as an inline image in an html file.

trap.rule computes the area under a curve using the trapezoidal rule, assuming x is sorted.

trellis.strip.blank sets up Trellis or Lattice graphs to have a clear background on the strips for panel labels.

unPaste provides a version of the S-Plus unpaste that works for R and S-Plus.

whichClosePW is a very fast function using weighted multinomial sampling to determine which element of a vector is "closest" to each element of another vector. whichClosest quickly finds the closest element without any randomness.

whichClosek is a slow function that finds, after jittering the lookup table, the k closest matchest to each element of the other vector, and chooses from among these one at random.

xless is a function for Linux/Unix users to invoke the system xless command to pop up a window to display the result of printing an object. For MacOS xless uses the system open command to pop up a TextEdit window.

Usage

confbar(at, est, se, width, q = c(0.7, 0.8, 0.9, 0.95, 0.99), 
        col = gray(c(0, 0.25, 0.5, 0.75, 1)),
        type = c("v", "h"), labels = TRUE, ticks = FALSE,
        cex = 0.5, side = "l", lwd = 5, clip = c(-1e+30, 1e+30),
        fun = function(x) x,
        qfun = function(x) ifelse(x == 0.5, qnorm(x),
                            ifelse(x < 0.5, qnorm(x/2),
                            qnorm((1 +  x)/2))))
getLatestSource(x=NULL, package='Hmisc', recent=NULL, avail=FALSE)
grType()
prType()
htmlSpecialType()
inverseFunction(x, y)
james.stein(y, group)
keepHattrib(obj)
km.quick(S, times, q,
        type = c("kaplan-meier", "fleming-harrington", "fh2"),
        interval = c(">", ">="), method=c('constant', 'linear'), fapprox=0, n.risk=FALSE)
latexBuild(..., insert, sep='')
lm.fit.qr.bare(x, y, tolerance, intercept=TRUE, xpxi=FALSE, singzero=FALSE)
matxv(a, b, kint=1, bmat=FALSE)
nomiss(x)
outerText(string, y, cex=par('cex'), ...)
plotlyParm
plotp(data, ...)
rendHTML(x, html=TRUE)
restoreHattrib(obj, attribs)
sepUnitsTrans(x, conversion=c(day=1, month=365.25/12, year=365.25, week=7),
              round=FALSE, digits=0)
strgraphwrap(x, width = 0.9 * getOption("width"),
             indent = 0, exdent = 0,
             prefix = "", simplify = TRUE, units='user', cex=NULL)
tobase64image(file, Rd = FALSE, alt = "image")
trap.rule(x, y)
trellis.strip.blank()
unPaste(str, sep="/")
whichClosest(x, w)
whichClosePW(x, w, f=0.2)
whichClosek(x, w, k)
xless(x, ..., title)

Arguments

a

a numeric matrix or vector

alt,Rd

see base64::img

at

x-coordinate for vertical confidence intervals, y-coordinate for horizontal

attribs

an object returned by keepHattrib

avail

set to TRUE to have getLatestSource return a data frame of available files and latest versions instead of fetching any

b

a numeric vector

cex

character expansion factor

clip

interval to truncate limits

col

vector of colors

conversion

a named numeric vector

data

an object having a plotp method

digits

number of digits used for round

est

vector of point estimates for confidence limits

f

a scaling constant

file

a file name

fun

function to transform scale

group

a categorical grouping variable

html

set to FALSE to tell rendHTML to not surround HTML code with yaml

insert

a list of 3-element lists for latexBuild. The first of each 3-element list is a character string with an environment name. The second specifies the order: "before" or "after", the former indicating that when the environment is found, the third element of the list is inserted before or after it, according to the second element.

intercept

set to FALSE to not automatically add a column of ones to the x matrix

k

get the k closest matches

kint

which element of b to add to the result if a does not contain a column for intercepts

bmat

set to TRUE to consider b a matrix of repeated coefficients, usually resampled estimates with rows corresponding to resamples

labels

set to FALSE to omit drawing confidence coefficients

lwd

line widths

package

name of package for getLatestSource, default is 'Hmisc'

obj

a variable, data frame, or data table

q

vector of confidence coefficients or quantiles

qfun

quantiles on transformed scale

recent

an integer telling getLatestSource to get the recent most recently modified files from the package

round

set to TRUE to round converted values

S

a Surv object

se

vector of standard errors

sep

a single character string specifying the delimiter. For latexBuild the default is "".

side

for confbar is "b","l","t","r" for bottom, left, top, right.

str

a character string vector

string

a character string vector

ticks

set to TRUE to draw lines between rectangles

times

a numeric vector of times

title

a character string to title a window or plot. Ignored for xless under MacOs.

tolerance

tolerance for judging singularity in matrix

type

"v" for vertical, "h" for horizontal. For km.quick specifies the type of survival estimator.

w

a numeric vector

width

width of confidence rectanges in user units, or see strwrap

x

a numeric vector (matrix for lm.fit.qr.bare) or data frame. For xless may be any object that is sensible to print. For sepUnitsTrans is a character or factor variable. For getLatestSource is a character string or vector of character strings containing base file names to retrieve from CVS. Set x='all' to retrieve all source files. For clowess, x may also be a list with x and y components. For inverseFunction, x and y contain evaluations of the function whose inverse is needed. x is typically an equally-spaced grid of 1000 points. For strgraphwrap is a character vector. For rendHTML x is a character vector.

xpxi

set to TRUE to add an element to the result containing the inverse of \(X'X\)

singzero

set to TRUE to set coefficients corresponding to singular variables to zero instead of NA.

y

a numeric vector. For inverseFunction y is the evaluated function values at x.

indent, exdent, prefix

see strwrap

simplify

see sapply

units

see par

interval

specifies whether to deal with probabilities of exceeding a value (the default) or of exceeding or equalling the value

method,fapprox

see approx

n.risk

set to TRUE to include the number at risk in the result

...

arguments passed through to another function. For latexBuild represents pairs, with odd numbered elements being character strings containing LaTeX code or a zero-length object to ignore, and even-numbered elements representing LaTeX left parenthesis, left brace, or left bracket, or environment name.

Author

Frank Harrell and Charles Dupont

Examples

trap.rule(1:100,1:100)
#> [1] 4999.5

unPaste(c('a;b or c','ab;d','qr;s'), ';')
#> [[1]]
#> [1] "a"  "ab" "qr"
#> 
#> [[2]]
#> [1] "b or c" "d"      "s"     
#> 

sepUnitsTrans(c('3 days','4 months','2 years','7'))
#> [1]   3.00 121.75 730.50   7.00
#> attr(,"units")
#> [1] "day"

set.seed(1)
whichClosest(1:100, 3:5)
#> [1] 3 4 5
whichClosest(1:100, rep(3,20))
#>  [1] 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3

whichClosePW(1:100, rep(3,20))
#>  [1]  3  3  5  8  2  8  9  6  6  1  2  2  6  4  7  5  6 11  4  7
whichClosePW(1:100, rep(3,20), f=.05)
#>  [1] 4 2 3 2 2 3 1 3 4 3 3 3 3 2 4 3 4 2 4 3
whichClosePW(1:100, rep(3,20), f=1e-10)
#>  [1] 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3

x <- seq(-1, 1, by=.01)
y <- x^2
h <- inverseFunction(x,y)
formals(h)$turns   # vertex
#> [1] 0.005
a <- seq(0, 1, by=.01)
plot(0, 0, type='n', xlim=c(-.5,1.5))
lines(a, h(a)[,1])            ## first inverse
lines(a, h(a)[,2], col='red') ## second inverse
a <- c(-.1, 1.01, 1.1, 1.2)
points(a, h(a)[,1])


d <- data.frame(x=1:2, y=3:4, z=5:6)
d <- upData(d, labels=c(x='X', z='Z lab'), units=c(z='mm'))
#> Input object size:	 1008 bytes;	 3 variables	 2 observations
#> New object size:	2272 bytes;	3 variables	2 observations
a <- keepHattrib(d)

d <- data.frame(x=1:2, y=3:4, z=5:6)
d2 <- restoreHattrib(d, a)
sapply(d2, attributes)
#> $x
#> $x$label
#> [1] "X"
#> 
#> $x$class
#> [1] "labelled" "integer" 
#> 
#> 
#> $y
#> NULL
#> 
#> $z
#> $z$label
#> [1] "Z lab"
#> 
#> $z$class
#> [1] "labelled" "integer" 
#> 
#> $z$units
#> [1] "mm"
#> 
#> 

if (FALSE) { # \dontrun{
getLatestSource(recent=5)  # source() most recent 5 revised files in Hmisc
getLatestSource('cut2')    # fetch and source latest cut2.s
getLatestSource('all')     # get everything
getLatestSource(avail=TRUE) # list available files and latest versions
} # }