Look up prevalence-conditioned reference values for agreement metrics

Returns the prevalence-conditioned reference values for Cohen's kappa, PABAK, and Gwet's AC1 at a given prevalence and a chosen rater-quality band. The reference is the analytical Youden-J-optimal metric value on the Se = Sp diagonal at the chosen reference_level, under conditional independence of the two raters given the true class.

Usage

grass_reference(prevalence, reference_level = 0.85, quality = NULL)

Arguments

prevalence: Numeric in [0, 1]. Values outside [0.01, 0.99] are clamped with a warning.
reference_level: One of 0.70, 0.80, 0.85, 0.90. Default 0.85.
quality: Deprecated alias. "high" -> reference_level = 0.85, "medium" -> 0.70. Emits a one-time soft deprecation warning.

Value

A grass_reference S3 object containing a 3-row data.frame (one row per metric) with columns metric, reference, J, reference_level, quality, prevalence. The quality column retains the legacy "high"/"medium" label for 0.85 and 0.70 bands and is NA_character_ for the new 0.80 / 0.90 bands.

Details

In the paper these are called the prevalence-conditioned thresholds. The package uses the name reference because its API reports the values alongside prevalence index and bias index rather than applying them as cutoffs.

Deprecated

grass_reference() is deprecated in grass 0.2.0. The percentile machinery in position_on_surface() and the new grass_report() supersede the fixed reference-curve lookup. See vignette("reporting-card") for the v0.2.0 surface-position workflow.

Examples

grass_reference(0.5)
#> `grass_reference()` is deprecated in grass 0.2.0. The new headline API is `grass_report(ratings = Y)`; for percentile lookups use `position_on_surface(ratings = Y, metric = ...)`. See `vignette('reporting-card')` and `?grass_report`.
#> grass reference curve at prevalence = 0.5000 (Se = Sp = 0.85)
#>   kappa     reference = 0.4900    (Youden's J = 0.7000)
#>   PABAK     reference = 0.4900    (Youden's J = 0.7000)
#>   AC1       reference = 0.4900    (Youden's J = 0.7000)
grass_reference(0.1, reference_level = 0.70)
#> grass reference curve at prevalence = 0.1000 (Se = Sp = 0.70)
#>   kappa     reference = 0.0642    (Youden's J = 0.4000)
#>   PABAK     reference = 0.1600    (Youden's J = 0.4000)
#>   AC1       reference = 0.2380    (Youden's J = 0.4000)