Analyse a published administrative table in one call

The questions asked of a published table are always the same: what is in it, what changed between periods and how sure can one be, what the rates are if there is an exposure, whether a short series trends, and whether this release differs from the one held before. Each has a function in this package; this runs them together, with the pieces a reviewer needs and that are easy to forget on a deadline: exact intervals on every change, multiple-comparison adjustment over the groups scanned, the envelope that rounding and suppression in the release imply, and a drift screen against the prior capsule.

Usage

anltab(
  data,
  value,
  prd,
  by = NULL,
  pop = NULL,
  prior = NULL,
  units = c("count", "continuous", "percent"),
  rnd = NULL,
  rndkind = c("nearest", "random"),
  suplim = NULL,
  dir = c("neutral", "higher", "lower"),
  per = 1000,
  conflvl = 0.95,
  alpha = 0.05,
  adjust = "BH",
  prdord = NULL
)

Arguments

data: A data frame in long form: one row per period and group.
value: Name of the column (a string) with the published count (or measure).
prd: Name of the column with the period (fiscal year, quarter, ...); numeric periods are used as the time axis of the trend tests. Text periods ("2019/20", "2021 Q3", "Mar 2021") are ordered as yoy() reads them (see its prd), or as prdord gives.
by: Optional character vector of grouping column names (institution, region, ...). NULL (the default) treats the table as one series.
pop: Optional name of an exposure column for rates (NULL, the default, skips the rate step).
prior: Optional data frame: the previous capsule of the same table, for the drift screen. NULL (the default) skips it.
units: "count" (the default), "continuous" or "percent", as in yoy().
rnd, rndkind, suplim: How the release rounds or suppresses cells; see pubbnd(). rnd is the rounding base (for example 5), rndkind "nearest" (the default) or "random", suplim the threshold below which cells are suppressed. NULL when the counts are exact. Used only for counts: with other units they are ignored, with a warning.
dir: Which way is an improvement, as in yoy(): "neutral" (the default), "higher" or "lower".
per: Rate denominator, as in rtcalc(); default 1000 (rates per 1,000 of pop).
conflvl: Confidence level for every interval, default 0.95.
alpha: Level for the multiple-comparison decision and the drift screens, default 0.05.
adjust: Multiple-comparison method for scanadj(). The default is "BH" (Benjamini-Hochberg).
prdord: Optional character vector: the period labels in order, for text periods the reader does not know (see yoy()); passed to yoy(), ratechg() and the trend tests.

Value

A list of class bricklayer_analysis (with a print method that summarises it in a few lines):

profile: profcols() of data.
missingness: named numeric from misssmry().
change: the yoy() table; for counts with the added columns p_value, padj and significant, and with env_* and compctlo/compctup when publication bounds were requested.
rates, ratechg: the rtcalc() and ratechg() tables when population is given, otherwise NULL.
trend: data frame with one row per group: the by columns, periods, first, last, tau, trndp, slope, rateratio, rateratiolo, rateratioup.
drift: cpsdrft() result against prior, or NULL.
meta: list of the arguments used, nrows, the sorted periods, prior (logical) and when (a time stamp).

Details

The steps, in order:

profile: profcols() and misssmry() on data;
change: yoy() between consecutive periods within each by group. For units = "count" the exact p-values are then adjusted across all comparisons with scanadj(), and, when rnd or suplim is given, yoybnd() adds the publication envelope (see pubbnd()). For "continuous" and "percent" units neither step runs: rnd and suplim are then ignored, with a warning;
rates (only with pop): rtcalc() per group and period, and ratechg() between periods, adjusted with scanadj();
trend: per group, the values summed within each period, then trndtst() (Mann-Kendall tau, p-value and Theil-Sen slope) and, for counts, cnttrnd() (Poisson rate ratio per period). A group with fewer than three periods gets NA; a test that fails gets NA rather than an error;
drift (only with prior): cpsdrft() of data against prior.

Nothing is written and nothing is fetched; a progress bar for the trend step is drawn on stderr unless options(morie.quiet = TRUE). Errors: data or prior not a data frame; a named column not in data; an invalid units, dir or rndkind; a conflvl outside (0, 1); and any error of the functions called (for example negative counts in yoy()).

Examples