Compare fitted Sigma-table rows with a known truth matrix

compare_Sigma_table() joins report-ready extract_Sigma_table() rows to a known covariance or correlation matrix. It is designed for simulation and teaching articles that need estimate-vs-truth tables without hand-indexing matrices inside the article.

Usage

compare_Sigma_table(
  x,
  truth,
  level = "unit",
  part = c("total", "shared", "unique"),
  measure = c("covariance", "correlation"),
  entries = c("unique", "all", "upper", "lower", "offdiag", "diag"),
  link_residual = c("auto", "none")
)

Arguments

x

A fit returned by gllvmTMB(), an admitted engine = "julia" bridge fit, or a data frame returned by extract_Sigma_table().

truth

Square numeric covariance or correlation matrix. Row and column names should match the trait names in x; unnamed matrices are accepted only when their dimension matches the traits in x.

level, part, measure, entries, link_residual

Passed to extract_Sigma_table() when x is a fitted model.

Value

A data frame with the columns from extract_Sigma_table() plus truth, error, abs_error, and comparison_status.

Details

Scope: the helper compares fitted or precomputed extract_Sigma_table() rows against one supplied truth matrix (covered by the package's Sigma-table validation tests). It is a table helper only: it does not compute uncertainty, simulate data, or validate calibration. For the first visual comparison layer, use plot_Sigma_comparison(); richer article-specific calibration summaries remain future visualization work.

See also

extract_Sigma_table(), plot_Sigma_comparison(), plot_Sigma_table().

Examples

rows <- data.frame(
  estimand = "R_unit[length,mass]",
  trait_i = "length",
  trait_j = "mass",
  i = 1L,
  j = 2L,
  level = "unit",
  component = "total",
  matrix = "R",
  estimate = 0.62,
  lower = NA_real_,
  upper = NA_real_,
  interval_method = "none",
  interval_status = "none",
  scale = "correlation",
  diagonal = FALSE,
  triangle = "upper"
)
truth_R <- matrix(c(1, 0.6, 0.6, 1), 2,
  dimnames = list(c("length", "mass"), c("length", "mass"))
)
compare_Sigma_table(rows, truth_R, measure = "correlation")
#>              estimand trait_i trait_j i j level component matrix estimate lower
#> 1 R_unit[length,mass]  length    mass 1 2  unit     total      R     0.62    NA
#>   upper interval_method interval_status       scale diagonal triangle truth
#> 1    NA            none            none correlation    FALSE    upper   0.6
#>   error abs_error comparison_status
#> 1  0.02      0.02          compared