Package 'infereportR'

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

Help Index


Format stored numerical values

Description

Common display rules used by tables, text and plot annotations. No numerical inference is performed.

Usage

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)

Arguments

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 "." or ","; presentation only.

missing

Display for missing estimates.

low, high

Equally sized stored interval endpoints. Infinities are retained.

prefix

Include p = or p < when TRUE.

Details

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.

Value

A character vector.

Examples

format_p(c(0.03, 1e-20, 0, NA_real_))
format_interval(c(-Inf, 0.1), c(2, 0.5))

Describe selected variables with explicit populations

Description

Render stored descriptions or ask infercalcR to compute descriptions without hypothesis tests. Supplied inference is joined only by explicit stable identifiers.

Usage

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 = ".")

Arguments

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 continuous or categorical. Factors, including ordered factors, remain categorical by default.

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

Details

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.

Value

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.

Examples

d <- data.frame(value = c(1, 2, NA, 4), group = c("A", "A", "B", "B"))
report_descriptive(d, group = "group", units = c(value = "mm"))

Tables and neutral text from finalized results

Description

Read the shared public result accessors and preserve stored numerical quantities and metadata.

Usage

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)

Arguments

x

A finalized result supporting infercalcR::result_data() and result_metadata(); for report_metadata, a reporting output or native import.

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.

Details

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.

Value

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.

Examples

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)

Annotate ggplot with finalized inference

Description

Construct ordinary text and segment layers from stored results; no tests run during plot construction, build or drawing.

Usage

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, ...)

Arguments

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.

Details

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.

Value

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.

Examples

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))
}