| Title: | Tables, Text and Plot Annotations for Statistical Results |
|---|---|
| Description: | Formats finalized statistical results as tables, text and optional plot annotations. Results follow the common result contract of 'infercalcR'; stored estimates, intervals, p-values and method metadata are reported at full precision and are never recomputed. Optional 'ggplot2' layers annotate plots with the stored results. |
| Authors: | R. Heller [aut, cre, cph] (ORCID: <https://orcid.org/0000-0001-8006-9742>) |
| Maintainer: | R. Heller <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.1.0 |
| Built: | 2026-11-11 18:56:12 UTC |
| Source: | https://github.com/CTTIR/infereportR |
Common display rules used by tables, text and plot annotations. No numerical inference is performed.
format_estimate(x, digits = 3L, decimal_mark = ".", missing = "unavailable") format_interval(low, high, digits = 3L, decimal_mark = ".") format_p(x, digits = 3L, decimal_mark = ".", prefix = TRUE)format_estimate(x, digits = 3L, decimal_mark = ".", missing = "unavailable") format_interval(low, high, digits = 3L, decimal_mark = ".") format_p(x, digits = 3L, decimal_mark = ".", prefix = TRUE)
x |
Numeric values; p-values must be NA or in [0,1]. |
digits |
An integer from 1 to 15. Significant digits for estimates; decimal places and threshold for p-values. |
decimal_mark |
Either |
missing |
Display for missing estimates. |
low, high
|
Equally sized stored interval endpoints. Infinities are retained. |
prefix |
Include |
P-values below 10^-digits, including stored zero, display a strict upper threshold. Missing p-values never display as nonsignificant. A stored zero may represent numerical underflow, and is not labeled as a mathematically zero probability. Intervals are formatted without calculation or changes of scale.
A character vector.
format_p(c(0.03, 1e-20, 0, NA_real_)) format_interval(c(-Inf, 0.1), c(2, 0.5))format_p(c(0.03, 1e-20, 0, NA_real_)) format_interval(c(-Inf, 0.1), c(2, 0.5))
Render stored descriptions or ask infercalcR to compute descriptions without hypothesis tests. Supplied inference is joined only by explicit stable identifiers.
report_descriptive(x, variables = NULL, group = NULL, labels = NULL, units = NULL, types = NULL, inference = NULL, mapping = NULL, inference_population = NULL, p = c("reported", "raw", "adjusted"), digits = 3L, p_digits = 3L, decimal_mark = ".")report_descriptive(x, variables = NULL, group = NULL, labels = NULL, units = NULL, types = NULL, inference = NULL, mapping = NULL, inference_population = NULL, p = c("reported", "raw", "adjusted"), digits = 3L, p_digits = 3L, decimal_mark = ".")
x |
A raw data.frame or a finalized descriptive result. |
variables |
Selected raw-data column names, default all except the grouping variable. |
group |
An optional grouping column name. |
labels, units
|
Optional vectors named by variable ID. |
types |
Named vector of |
inference |
Optional finalized common result or list of results with distinct result IDs. |
mapping |
A data.frame with variable_id, result_id and row_id. At most one inference row per descriptive variable is supported. Every mapping entry must refer to an existing result and variable. |
inference_population |
Required nonempty label when inference is supplied, documenting its analysis population separately from descriptive denominators. |
p |
Which stored p-value to display. |
digits, p_digits, decimal_mark
|
Display settings as in |
The raw route delegates to infercalcR::describe_data. Categorical percentages use nonmissing denominators and missing groups remain explicit. No automatic hypothesis test is selected. The join never matches on display labels, and cannot infer that two differently labeled analysis populations are identical. Group-specific multiple tests per variable require separate explicitly scoped reports.
An ordinary data.frame with full-precision descriptions, n, n.missing, n.total, group/level labels and display columns. No p-value columns exist by default. Optional joined inference fields have an inference_ prefix. Metadata retains descriptive and inferential populations separately.
d <- data.frame(value = c(1, 2, NA, 4), group = c("A", "A", "B", "B")) report_descriptive(d, group = "group", units = c(value = "mm"))d <- data.frame(value = c(1, 2, NA, 4), group = c("A", "A", "B", "B")) report_descriptive(d, group = "group", units = c(value = "mm"))
Read the shared public result accessors and preserve stored numerical quantities and metadata.
report_table(x, rows = NULL, p = c("reported", "raw", "adjusted"), digits = 3L, p_digits = 3L, decimal_mark = ".") report_text(x, rows = NULL, p = c("reported", "raw", "adjusted"), digits = 3L, p_digits = 3L, decimal_mark = ".", style = c("full", "p", "estimate_ci", "estimate_ci_p", "stars"), template = NULL) report_metadata(x)report_table(x, rows = NULL, p = c("reported", "raw", "adjusted"), digits = 3L, p_digits = 3L, decimal_mark = ".") report_text(x, rows = NULL, p = c("reported", "raw", "adjusted"), digits = 3L, p_digits = 3L, decimal_mark = ".", style = c("full", "p", "estimate_ci", "estimate_ci_p", "stars"), template = NULL) report_metadata(x)
x |
A finalized result supporting |
rows |
Unique stored row IDs to display, or NULL for all. |
p |
Select stored reported, raw or adjusted p-values. An adjusted request fails if a selected value is absent. |
digits, p_digits
|
Display precision for estimates and p-values. |
decimal_mark |
Either a dot or comma. |
style |
Full neutral text or a compact label preset. |
template |
Optional string containing approved fields in braces: estimate, ci, p, statistic, method, estimand, contrast, status, n. This is substitution only, without evaluation. |
Filtering changes presentation only; metadata retains the entire adjustment family. No test, model, interval or adjustment is recomputed. Full text preserves estimand, orientation, interval method/scale/scope, confidence level, sample size and unavailable status when supplied. It does not assign clinical meaning or infer equivalence from nonsignificance. Numerical optimization bounds are not interpreted as confidence intervals. Stars use thresholds .05, .01, .001 and .0001; missing or unresolved results never acquire stars or ns. A stored decision conflicting with these display thresholds is shown explicitly. Compact labels for non-ok rows show unavailable status.
report_table returns an ordinary data.frame. Original analytical columns retain full precision, with additional columns ending in _display, and p_selected/p_selection. Metadata is an attribute accessed by report_metadata. report_text returns a named character vector with the same metadata.
x <- infercalcR::new_inference_result( data.frame(row_id = "contrast", estimate = 1.2, conf.low = 0.2, conf.high = 2.2, conf.level = 0.95, p.value = 0.021, estimand = "mean difference", status = "ok"), list(method_id = "example", result_id = "study-1")) report_table(x) report_text(x)x <- infercalcR::new_inference_result( data.frame(row_id = "contrast", estimate = 1.2, conf.low = 0.2, conf.high = 2.2, conf.level = 0.95, p.value = 0.021, estimand = "mean difference", status = "ok"), list(method_id = "example", result_id = "study-1")) report_table(x) report_text(x)
Construct ordinary text and segment layers from stored results; no tests run during plot construction, build or drawing.
stat_inference(x, positions, rows = NULL, label = c("p", "estimate_ci", "estimate_ci_p", "stars"), p = c("reported", "raw", "adjusted"), groups = NULL, facet_vars = NULL, template = NULL, digits = 3L, p_digits = 3L, decimal_mark = ".", unavailable = c("label", "error", "warn"), tip_length = 0.03, label_offset = 0, text_size = 3.5, colour = "black", linewidth = 0.4, text_hjust = 0.5, text_vjust = -0.4) annotate_inference(plot, x, positions, ...)stat_inference(x, positions, rows = NULL, label = c("p", "estimate_ci", "estimate_ci_p", "stars"), p = c("reported", "raw", "adjusted"), groups = NULL, facet_vars = NULL, template = NULL, digits = 3L, p_digits = 3L, decimal_mark = ".", unavailable = c("label", "error", "warn"), tip_length = 0.03, label_offset = 0, text_size = 3.5, colour = "black", linewidth = 0.4, text_hjust = 0.5, text_vjust = -0.4) annotate_inference(plot, x, positions, ...)
x |
A finalized shared result. |
positions |
Data.frame with exactly one row per selected row_id and a finite y_position in original data units. Brackets require numeric xmin/xmax or named group1/group2. Text-only annotations use numeric x. Optional type is bracket or text. Omnibus rows require text. |
rows |
Unique stored row IDs, or NULL for all. |
label |
Compact display preset. |
p |
Stored p-value selection. Missing requested adjusted values are an error. |
groups |
Distinct group labels in the plotted discrete-axis order when named endpoints are used. Supply updated levels after reordering the axis. |
facet_vars |
Facet column names, which must exist and agree in both positions and stored result rows. Defaults to the result metadata's facet_vars contract, if present. |
template |
Approved field substitution as in report_text. |
digits, p_digits, decimal_mark
|
Shared display precision and decimal mark. |
unavailable |
Keep an explicit unavailable label, error, or warn and keep the label. |
tip_length, label_offset
|
Offsets in original y units. Choose positive-scale-compatible coordinates before applying a log scale. |
text_size, colour, linewidth
|
Text and segment appearance. |
text_hjust, text_vjust
|
Text justification. For a horizontal coord_flip path, use -0.1 and 0.5, respectively, and provide adequate scale expansion. |
plot |
Existing ggplot object with Cartesian coordinates or coord_flip. |
... |
Arguments passed to stat_inference. |
ggplot2 is optional for package loading and plain reporting. The function never extracts plotting observations or fits a test. Named group order controls only geometry, not the stored scientific contrast sign. Numeric endpoints support explicit dodge positions. Nonsignificant rows remain visible by default. Selection never changes an adjustment family.
Positions are supplied before scale transformations: y_position=100 becomes 2 under scale_y_log10 exactly once. Cartesian and coord_flip paths are supported. Polar and arbitrary nonlinear coordinates, automatic positioning, automatic dodge detection and automatic free-scale placement are not supported. annotate_inference rejects an existing unsupported coordinate system; later-added coordinates cannot be guarded by a list of layers.
For subgroup results, always supply facet_vars and matching keys; missing requested keys error instead of broadcasting. A layer cannot validate facets added later or infer that an undeclared column represents a subgroup. The caller must maintain that explicit contract.
stat_inference returns a list of ordinary ggplot layers with inherit.aes=FALSE, plus annotation_data and inference_metadata attributes. annotate_inference returns the plot with these layers.
if (requireNamespace("ggplot2", quietly = TRUE)) { x <- infercalcR::new_inference_result( data.frame(row_id = "a-b", p.value = 0.04, status = "ok"), list(method_id = "example")) d <- data.frame(group = rep(c("A", "B"), each = 3), y = 1:6) p <- ggplot2::ggplot(d, ggplot2::aes(group, y)) + ggplot2::geom_point() p + stat_inference(x, data.frame(row_id = "a-b", xmin = 1, xmax = 2, y_position = 7)) }if (requireNamespace("ggplot2", quietly = TRUE)) { x <- infercalcR::new_inference_result( data.frame(row_id = "a-b", p.value = 0.04, status = "ok"), list(method_id = "example")) d <- data.frame(group = rep(c("A", "B"), each = 3), y = 1:6) p <- ggplot2::ggplot(d, ggplot2::aes(group, y)) + ggplot2::geom_point() p + stat_inference(x, data.frame(row_id = "a-b", xmin = 1, xmax = 2, y_position = 7)) }