Jonckheere-Terpstra Test: Grouped (x_by)

The x_by implementation tests whether a continuous variable trends monotonically across the levels of one or more grouping variables. It accepts one or more grouping variables via x_by(), running one Jonckheere-Terpstra test per grouping variable.

Arguments

jttest_def_xby's baseline fn passes these straight through to the compiled jonckheere_terpstra_test() C++ backend:

alternative

One of "two.sided", "increasing", or "decreasing". Default "two.sided". Invalid values are rejected by the backend itself.

approximate

Force the normal approximation instead of the exact null distribution. Default FALSE. The backend only uses the exact distribution when there are 50 or fewer observations and this is FALSE.

Grouping requirement

Every grouping variable passed to x_by() must be an ordered factor. Jonckheere-Terpstra tests a directional trend across group levels — unlike Kruskal-Wallis, group order changes what the test means, so an unordered factor or plain character vector is refused rather than silently sorted alphabetically.

Grouped Jonckheere-Terpstra default class

Always returns a class_jt_test object, which inherits statim::class_stat_infer and so picks up statim::auto_tidy() automatically. There is no separate making_tidy() registration needed for this path.

Examples

set.seed(123)
x = rcauchy(50, 1, 1.5)
g = factor(
    sample(letters[1:3], size = 50, replace = TRUE),
    levels = c("a", "b", "c"),
    ordered = TRUE
)
JT_TEST(x_by(x, g))
#> Error: <nullis::jt_test> object properties are invalid:
#> - @p_value p_value must be between 0 and 1 only.

JT_TEST(x_by(x, g), alternative = "increasing")
#> Error: <nullis::jt_test> object properties are invalid:
#> - @p_value p_value must be between 0 and 1 only.

JT_TEST(x_by(x, g), approximate = TRUE)
#> -- Summary ---------------------------------------------------------------------
#> 
#> ─────────────────────────────────────────────────────────────────────
#>   vars   mean    variance  statistic  z_score  p_value  alternative  
#> ─────────────────────────────────────────────────────────────────────
#>    g    414.500  3143.250     462      0.847    0.397    two.sided   
#> ─────────────────────────────────────────────────────────────────────
#> 
#> 
#> -- Details ---------------------------------------------------------------------
#> 
#> Warning: running command 'tput cols' had status 2
#> -------------------------------------------
#>   g: Approximate :                   TRUE
#>   g: Method      :   normal approximation
#> -------------------------------------------
#> 
#>