movStats — movStats • Hmisc

Moving Estimates Using Overlapping Windows

Usage

movStats(
  formula,
  stat = NULL,
  discrete = FALSE,
  space = c("n", "x"),
  eps = if (space == "n") 15,
  varyeps = FALSE,
  nignore = 10,
  xinc = NULL,
  xlim = NULL,
  times = NULL,
  tunits = "year",
  msmooth = c("smoothed", "raw", "both"),
  tsmooth = c("supsmu", "lowess"),
  bass = 8,
  span = 1/4,
  maxdim = 6,
  penalty = NULL,
  trans = function(x) x,
  itrans = function(x) x,
  loess = FALSE,
  ols = FALSE,
  qreg = FALSE,
  lrm = FALSE,
  orm = FALSE,
  hare = FALSE,
  ordsurv = FALSE,
  lrm_args = NULL,
  family = "logistic",
  k = 5,
  tau = (1:3)/4,
  melt = FALSE,
  data = environment(formula),
  pr = c("none", "kable", "plain", "margin")
)

Arguments

formula: a formula with the analysis variable on the left and the x-variable on the right, following by optional stratification variables
stat: function of one argument that returns a named list of computed values. Defaults to computing mean and quartiles + N except when y is binary in which case it computes moving proportions. If y has two columns the default statistics are Kaplan-Meier estimates of cumulative incidence at a vector of times.
discrete: set to TRUE if x-axis variable is discrete and no intervals should be created for windows
space: defines whether intervals used fixed width or fixed sample size
eps: tolerance for window (half width of window). For space='x' is in data units, otherwise is the sample size for half the window, not counting the middle target point.
varyeps: applies to space='n' and causes a smaller eps to be used in strata with fewer than “ observations so as to arrive at three x points
nignore: see description, default is to exclude nignore=10 points on the left and right tails from estimation and plotting
xinc: increment in x to evaluate stats, default is xlim range/100 for space='x'. For space='n' xinc defaults to m observations, where m = max(n/200, 1).
xlim: 2-vector of limits to evaluate if space='x' (default is nignore smallest to nignore largest)
times: vector of times for evaluating one minus Kaplan-Meier estimates
tunits: time units when times is given
msmooth: set to 'smoothed' or 'both' to compute lowess-smooth moving estimates. msmooth='both' will display both. 'raw' will display only the moving statistics. msmooth='smoothed' (the default) will display only he smoothed moving estimates.
tsmooth: defaults to the super-smoother 'supsmu' for after-moving smoothing. Use tsmooth='lowess' to instead use lowess.
bass: the supsmu bass parameter used to smooth the moving statistics if tsmooth='supsmu'. The default of 8 represents quite heavy smoothing.
span: the lowess span used to smooth the moving statistics
maxdim: passed to hare, default is 6
penalty: passed to hare, default is to use BIC. Specify 2 to use AIC.
trans: transformation to apply to x
itrans: inverse transformation
loess: set to TRUE to also compute loess estimates
ols: set to TRUE to include rcspline estimate of mean using ols
qreg: set to TRUE to include quantile regression estimates w rcspline
lrm: set to TRUE to include logistic regression estimates w rcspline
orm: set to TRUE to include ordinal logistic regression estimates w rcspline (mean + quantiles in tau)
hare: set to TRUE to include hazard regression estimtes of incidence at times, using the polspline package
ordsurv: set to TRUE to include ordinal regression estimates of incidence at times, using the rms package adapt_orm and survest.orm functions
lrm_args: a list of optional arguments to pass to lrm when lrm=TRUE, e.g., list(maxit=20)
family: link function for ordinal regression (see rms::orm)
k: number of knots to use for ols, lrm, qreg restricted cubic splines. Linearity is forced for binary y when the minimum of the number of events and number of non-events is below 10 for a by-group. For ordsurv=TRUE is the maximum number of knots tried and is passed as argument maxk to the rms adapt_orm function.
tau: quantile numbers to estimate with quantile regression
melt: set to TRUE to melt data table and derive Type and Statistic
data: data.table or data.frame, default is calling frame
pr: defaults to no printing of window information. Use pr='plain' to print in the ordinary way, pr='kable to convert the object to knitr::kable and print, or pr='margin' to convert to kable and place in the Quarto right margin. For the latter two results='asis' must be in the chunk header.

Value

a data table, with attribute infon which is a data frame with rows corresponding to strata and columns N, Wmean, Wmin, Wmax if stat computed N. These summarize the number of observations used in the windows. If varyeps=TRUE there is an additional column eps with the computed per-stratum eps. When space='n' and xinc is not given, the computed xinc also appears as a column. An additional attribute info is a kable object ready for printing to describe the window characteristics.

Details

Function to compute moving averages and other statistics as a function of a continuous variable, possibly stratified by other variables. Estimates are made by creating overlapping moving windows and computing the statistics defined in the stat function for each window. The default method, space='n' creates varying-width intervals each having a sample size of 2*eps +1, and the smooth estimates are made every xinc observations. Outer intervals are not symmetric in sample size (but the mean x in those intervals will reflect that) unless eps=nignore, as outer intervals are centered at observations nignore and n - nignore + 1 where the default for nignore is 10. The mean x-variable within each windows is taken to represent that window. If trans and itrans are given, x means are computed on the trans(x) scale and then itrans'd. For space='x', by default estimates are made on to the nignore smallest to the nignore largest observed values of the x variable to avoid extrapolation and to help getting the moving statistics off on an adequate start for the left tail. Also by default the moving estimates are smoothed using supsmu. When melt=TRUE you can feed the result into ggplot like this: ggplot(w, aes(x=age, y=crea, col=Type)) + geom_line() + facet_wrap(~ Statistic)

See here for several examples.

Author

Frank Harrell