speccurvieR (version 1.0.0)

plot_sca_test_specs: Plot the specification curve against its per-specification null band

Description

`plot_sca_test_specs()` draws the observed specification curve (each specification's focal coefficient, ranked) together with a shaded band giving that specification's own null distribution under the permutation test. This is the specification-curve view of the joint-inference test of Simonsohn, Simmons, and Nelson (2020): specifications whose observed estimate falls outside their null band are highlighted, so it is easy to see which parts of the curve are more extreme than chance.

When the result carries per-specification family-wise-error-rate-adjusted p-values (i.e. it was computed with `keep_curves = TRUE` and a confound-preserving null, so [sca_minp()] has run -- automatically or explicitly), the points are coloured in three tiers -- within the chance band, beyond it but not significant after correction, and significant after multiple-comparison correction (enlarged) -- so the specifications that survive correction stand out. Otherwise the usual two-tier within/outside-band colouring is used.

It requires an [sca_test()] result computed with `keep_curves = TRUE`.

Usage

plot_sca_test_specs(test_result, level = 0.95, title = "")

Value

A ggplot object.

Arguments

test_result

An object of class `"sca_test"` returned by [sca_test()] with `keep_curves = TRUE`.

level

The width of the null band, as a probability. Defaults to `0.95` (the 2.5th to 97.5th percentile of each specification's null coefficients).

title

A string used as the plot title. Defaults to `""`.

References

Simonsohn, U., Simmons, J. P., & Nelson, L. D. (2020). Specification curve analysis. Nature Human Behaviour, 4, 1208-1214. tools:::Rd_expr_doi("10.1038/s41562-020-0912-z")

Examples

# \donttest{
result <- sca_test(y = "Salnty", x = "T_degC", controls = c("ChlorA", "O2Sat"),
                   data = bottles, n_permutations = 100, keep_curves = TRUE,
                   progress_bar = FALSE)
plot_sca_test_specs(result)
# }