R: Miscellaneous Functions

Misc {Hmisc} | R Documentation

## Miscellaneous Functions

### Description

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 `source`s the most recent source code for functions in packages in the Vanderbilty University CVS repository.

`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.

`km.quick` provides a fast way to invoke `survfitKM` in the `survival` package to get Kaplan-Meier 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).

`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 `NA`s 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.

`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 `print`ing an object.

### 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,
                    type=c('svn','cvs'))
    grType()
    prType()
    htmlSpecialType()
    inverseFunction(x, y)
    james.stein(y, group)
    km.quick(S, times, q)
    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, ...)
    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
`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
`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'`
`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
`tolerance` | tolerance for judging singularity in matrix
`type` | `"v"` for vertical, `"h"` for horizontal. For `getLatestSource` this specifies the type of source code repository, `'svn'` (the default) or `'cvs'`, which is now outdated as Subversion has replaced CVS in the Vanderbilt Biostatistics server.
`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.
`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`
`...` | 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(s)

Frank Harrell and Charles Dupont

### Examples

    trap.rule(1:100,1:100)

    unPaste(c('a;b or c','ab;d','qr;s'), ';')

    sepUnitsTrans(c('3 days','4 months','2 years','7'))

    set.seed(1)
    whichClosest(1:100, 3:5)
    whichClosest(1:100, rep(3,20))

    whichClosePW(1:100, rep(3,20))
    whichClosePW(1:100, rep(3,20), f=.05)
    whichClosePW(1:100, rep(3,20), f=1e-10)

    x <- seq(-1, 1, by=.01)
    y <- x^2
    h <- inverseFunction(x,y)
    formals(h)$turns   # vertex
    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])

    ## Not run:
    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

    ## End(Not run)

[Package Hmisc version 4.3-0 Index]