recommended_estimator: Kernel estimator settings by dimensionality

In phontrast: Contrast and Separation Metrics for Phonological Categories

Kernel estimator settings by dimensionality

Description

Returns the kernel-density estimator configuration that the simulation study behind rank_contrasts() used at each dimensionality (Berry, under review, Table III), so that a contrast measured with phontrast is scored with the settings the safe-use envelope was calibrated on. Three settings switch together with the number of features d:

Usage

recommended_estimator(d)

Arguments

d	Positive integer; the number of acoustic features (dimensions).

Details

d <= 4

Plug-in bandwidth (bw = "Hpi"), the "ks" engine, densities evaluated at every token, and the partial leave-one-out correction on. Calibrated at d = 2 and 4.

5 <= d <= 13

Diagonal Scott bandwidth (bw = "scott.diag"), the "fast_diag" engine, densities evaluated at 200 subsampled tokens per category, leave-one-out on. Calibrated at d = 8 and 13; dimensionalities between the calibrated ones take the settings of the next higher calibrated dimensionality.

d >= 14

As above but with no leave-one-out correction, reproducing the log-space path the study used at d = 32 and 64. phontrast's "fast_diag" engine evaluates kernels in log space, so this tier runs natively. Above eight dimensions the study gives ordering evidence only.

Value

A list with elements d, tier (a label for the row of Table III applied), calibrated_at (the dimensionalities the row was calibrated on), bw, engine, eval_n, loo, and note. The bw, engine, eval_n, and loo elements can be passed straight to jsd_kde_nd(), estimate_jsd(), or phontrast().

Examples

recommended_estimator(2)
recommended_estimator(13)$engine

set.seed(2026)
vowels <- data.frame(
  vowel = rep(c("ih", "eh"), each = 40),
  f1 = c(rnorm(40, 500, 55), rnorm(40, 565, 60)),
  f2 = c(rnorm(40, 1980, 150), rnorm(40, 1870, 155))
)
est <- recommended_estimator(2)
jsd_kde_nd(vowels, c("f1", "f2"), "vowel",
           bw = est$bw, engine = est$engine, loo = est$loo)

phontrast documentation built on Oct. 7, 2026, 5:06 p.m.