Package {BKVerify}

BKVerify: Consistency Auditing of Reported Plant Breeding Statistics

Description

Audits published or draft plant breeding tables for internal arithmetic consistency. Analysis of variance tables, precision statistics and genetic variability parameters are jointly over-determined by exact algebraic identities; BKVerify recomputes every derivable quantity using rounding-interval arithmetic and reports a value as inconsistent only when no combination of values inside the reported rounding intervals can satisfy the identity.

Details

The package deliberately restricts itself to relationships that hold irrespective of which variance-component definition an author adopted. Broad-sense heritability is not recomputed from mean squares, because the phenotypic variance is defined in several defensible ways in the plant breeding literature and authors seldom state which they used. The identities used here survive that ambiguity because the phenotypic variance cancels.

The package makes no claim about whether an analysis was appropriate, whether the design was sound, or whether any discrepancy was deliberate. A verdict of "consistent" means only that the printed numbers can be reconciled.

Main functions: bk_check_variability, bk_check_anova, bk_check_precision, bk_check_corr, bk_audit, bk_example, bk_interval, bk_k.

Author(s)

Praveen Kumar bkpraveenars@gmail.com

References

Burton, G. W. and DeVane, E. H. (1953). Estimating heritability in tall fescue from replicated clonal material. Agronomy Journal 45, 478–481.

Johnson, H. W., Robinson, H. F. and Comstock, R. E. (1955). Estimates of genetic and environmental variability in soybeans. Agronomy Journal 47, 314–318.

Nuijten, M. B. and Wicherts, J. M. (2024). Implementing statcheck during peer review is related to a steep decline in statistical-reporting inconsistencies. Advances in Methods and Practices in Psychological Science 7.

Combine audit results

Description

Binds the output of several bk_check_* calls into a single audit object. The print method shows only inconsistent and indeterminate rows, together with a reminder that a "consistent" verdict means the reported values are arithmetically reconcilable, not that the underlying analysis was appropriate.

Usage

bk_audit(...)

## S3 method for class 'bk_result'
print(x, ...)

## S3 method for class 'bk_result'
summary(object, ...)

## S3 method for class 'bk_result'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

Value

bk_audit returns an object of class bk_result carrying an additional module column. The print method returns its input invisibly; summary returns a verdict-by-test table invisibly; as.data.frame returns a plain data frame.

Examples

bk_audit(
  bk_check_variability(bk_example("variability")),
  bk_check_anova(bk_example("anova")),
  bk_check_corr(bk_example("corr"))
)

Audit an analysis of variance table

Description

Checks the internal algebraic structure of a published analysis of variance table: additivity of degrees of freedom and sums of squares, the definition of mean squares (MS = SS/df), and the definition of the variance ratio (F = MS_{source}/MS_{error}).

Usage

bk_check_anova(data, source = "source", df = "df", ss = "ss", ms = "ms",
  f = "f", error_label = "error|residual", total_label = "total",
  decimals = NULL)

Arguments

Details

All comparisons use rounding-interval arithmetic, so a row is flagged only when no combination of values inside the reported rounding intervals can satisfy the identity. Degrees of freedom are treated as exact integers, never as rounded quantities.

Value

An object of class bk_result.

See Also

bk_audit, bk_example

Examples

a <- bk_example("anova")
bk_check_anova(a)

Audit a reported correlation matrix

Description

Checks symmetry, unit diagonal, coefficient range and positive semi-definiteness of a reported correlation matrix. A correlation matrix that is not positive semi-definite cannot arise from any data set; published matrices nevertheless fail this because coefficients are computed pairwise on different subsets, transcribed by hand, or assembled from several sources.

Usage

bk_check_corr(R, decimals = NULL, symmetry_tol = 1e-08)

Arguments

Details

Rounding is handled rigorously. For a symmetric perturbation E with zero diagonal and entries bounded by the rounding half-width \delta, Weyl's inequality bounds the eigenvalue movement by \delta \sqrt{n^2 - n}. Non-definiteness is reported as "INCONSISTENT" only when \lambda_{min}(R) + \delta \sqrt{n^2 - n} < 0, i.e. when no matrix inside the reported rounding box is positive semi-definite. When the minimum eigenvalue is negative but within the rounding allowance, the verdict is "indeterminate".

Value

An object of class bk_result.

See Also

bk_audit, bk_example

Examples

bk_check_corr(bk_example("corr"))
bk_check_corr(bk_example("corr_impossible"))

Audit precision statistics (CV, SEm, CD)

Description

Recomputes the coefficient of variation (CV\% = 100 \sqrt{MSe} / \bar{x}), standard error of the mean (SEm = \sqrt{MSe/r}) and critical difference (CD = t \sqrt{2 MSe / r}) from the error mean square, and additionally checks the relation CD = t \times SEm \times \sqrt{2}, which requires only the two printed values and the error degrees of freedom.

Usage

bk_check_precision(mse = NULL, r = NULL, grand_mean = NULL,
  df_error = NULL, cv = NULL, sem = NULL, cd = NULL, alpha = 0.05,
  label = NULL, decimals = NULL)

Arguments

Details

All arguments may be vectors of equal length, one element per trait. The CD = t \, SEm \sqrt{2} relation is useful in practice because many papers print CD and SEm but not the error mean square.

Value

An object of class bk_result.

See Also

bk_audit

Examples

bk_check_precision(mse = "10.03", r = 3, grand_mean = "45.16",
                   df_error = 38, cv = "7.01", sem = "1.83", cd = "5.24")

Audit a genetic variability table

Description

Tests the internal arithmetic of a genotypic/phenotypic coefficient of variation, heritability and genetic advance table using rounding-interval arithmetic. The identities used are h^2 = (GCV/PCV)^2, GAM = K h^2 PCV, GAM = K \, GCV^2 / PCV and GCV \le PCV.

Usage

bk_check_variability(data, trait = "trait", gcv = "gcv", pcv = "pcv",
  h2 = "h2", gam = "gam", k = "auto",
  h2_scale = c("percent", "fraction"), decimals = NULL)

Arguments

Details

The identities hold irrespective of which phenotypic variance definition the author used, because \sigma^2_p cancels. A flagged row therefore indicates arithmetic inconsistency, not methodological disagreement. Values are declared inconsistent only when no combination of values inside the reported rounding intervals satisfies the identity.

Supplying the columns as character vectors is strongly preferred: it preserves trailing zeros and hence the true reporting precision. Numeric input loses them and yields wider intervals, which is conservative.

Because the identities overlap, the pattern of failures localises the fault: a wrong heritability fails h2_from_cv and gam_identity while gam_from_cv passes; a wrong genetic advance fails both genetic advance tests while h2_from_cv passes.

Value

An object of class bk_result: a data frame with one row per trait per test, carrying the reported interval, the implied interval and a verdict of "consistent", "INCONSISTENT" or "not_applicable".

See Also

bk_audit, bk_k, bk_example

Examples

v <- bk_example("variability")
bk_check_variability(v)

Example tables for auditing

Description

Returns small worked examples in the shape the bk_check_* functions expect. Values are stored as character strings so that trailing zeros, and therefore the true reporting precision, are preserved. The tables derive from simulated randomised complete block trials (24 genotypes, 3 replications) rounded to typical published precision.

Usage

bk_example(what = c("variability", "anova", "precision", "corr",
  "corr_impossible"))

Arguments

Details

The "variability" table carries two planted errors, useful for teaching error localisation:

Grains per spike

heritability inflated by 4 points. The h2_from_cv and gam_identity tests fail while gam_from_cv passes, localising the fault to the heritability column.

Grain yield per plant

genetic advance inflated by 15 percent. Here h2_from_cv passes and both genetic advance tests fail, localising the fault to the genetic advance column.

Value

A data frame, matrix or list, depending on what.

Examples

bk_example("variability")
bk_check_variability(bk_example("variability"))

Rounding interval of a reported value

Description

Converts reported values into the closed intervals they actually assert. A value printed to d decimals implies a half-width of 0.5 * 10^(-d). Every check in BKVerify is decided on these intervals, never on point values.

Usage

bk_interval(x, decimals = NULL)

Arguments

Value

A two-column matrix with columns lo and hi.

Examples

bk_interval(c("11.04", "11.76"))
bk_interval(88.14, decimals = 2)

Selection differential constants (K) used in genetic advance

Description

Genetic advance is computed as GA = K \sigma_p h^2, where K is the standardised selection differential for the chosen selection intensity (Johnson, Robinson and Comstock 1955). Authors overwhelmingly report the conventional rounded values (2.64, 2.06, 1.76, 1.40) rather than exact normal-curve quantiles, so those conventional values are what BKVerify tests against.

Usage

bk_k(intensity = NULL)

Arguments

Details

Because a paper that omits its selection intensity is indistinguishable from one that used a different intensity, k = "auto" in bk_check_variability tests the whole family and reports which member reconciles the table.

Value

A named numeric vector, or a single value if intensity is given.

References

Johnson, H. W., Robinson, H. F. and Comstock, R. E. (1955). Estimates of genetic and environmental variability in soybeans. Agronomy Journal 47, 314–318.

Examples

bk_k()
bk_k("5%")