Finalized statistical result contract — result-contract • infercalcR

Construct, validate and access plain-data statistical results. Numerical inference is finalized before presentation.

Usage

new_inference_result(data, metadata, kind = "inference", payload = list())
validate_inference(x)
result_data(x, ...)
result_metadata(x, ...)
as_inference(x, ...)
adjust_inference(x, method = "holm", family_id, rows = NULL)

Arguments

data: A data frame of finalized numerical rows, with unique row IDs.
metadata: A named list including method_id; optional variant_id, result_id, provenance, population, settings and validation evidence.
kind: One of inference, planning, classification or descriptive.
payload: Method-specific finalized quantities that do not fit scalar columns. No raw data are required.
x: An existing result.
...: Arguments to a documented adapter or accessor method.
method: A method supported by stats::p.adjust.
family_id: A unique identifier that has not already been used in this result. An explicit identifier of the complete declared hypothesis family.
rows: Unique row IDs comprising the complete family; all rows by default.

Details

Rows distinguish estimate, statistic, degrees of freedom, confidence limits and their level/method/scale/scope, raw p.value, p.adjusted and p.reported, family metadata, null/alternative, sample and exclusion counts, status and reason. NA means unavailable; legitimate unbounded confidence limits remain infinite. A numerical p-value bound is a separate method-specific quantity and is never a sampling confidence interval.

A finalized conf.level is NA when unavailable or a finite attained/reported level in (0, 1]. Conservative discrete intervals can attain level 1, including intervals with infinite endpoints. The native-reported level, endpoints and diagnostics are preserved. Requested confidence levels in method_spec() remain strictly between zero and one; the requested level must not replace a different native-reported level. For Wilcoxon intervals, older R versions may report nominal or rounded confidence attributes; the legacy payload field attained_confidence_level preserves that attribute verbatim. Common interval labels identify the convention, and imported objects have unknown originating R provenance.

Adjustment rejects missing raw p-values and already adjusted families. It is performed once on the declared complete family before display filtering. It does not adjust confidence intervals. Results retain computation status separately from validation evidence. Result IDs are stable labels, not cryptographic hashes. RDS round trips are suitable only for trusted objects.

Value

Constructors and adapters return an S3 inference_result; result_data returns a data.frame, result_metadata a list. Validation returns the object invisibly.

Examples

x <- new_inference_result(data.frame(row_id = c("a", "b"),
  p.value = c(.01, .04)), list(method_id = "example"))
result_data(adjust_inference(x, family_id = "primary"))
#>   row_id p.value variable_id component estimand contrast estimate statistic df
#> 1      a    0.01        <NA>      <NA>     <NA>     <NA>       NA        NA NA
#> 2      b    0.04        <NA>      <NA>     <NA>     <NA>       NA        NA NA
#>   conf.low conf.high conf.level interval.method interval.scale interval.scope
#> 1       NA        NA         NA            <NA>           <NA>           <NA>
#> 2       NA        NA         NA            <NA>           <NA>           <NA>
#>   p.adjusted p.reported p.method family_id family_size null.value alternative
#> 1       0.02       0.02     holm   primary           2         NA        <NA>
#> 2       0.04       0.04     holm   primary           2         NA        <NA>
#>    n n.excluded status reason
#> 1 NA         NA     ok   <NA>
#> 2 NA         NA     ok   <NA>