phontrast 2.3.1
CRAN resubmission fixes
- Replaced the non-running
extract_mfcc() example with a
fast, executable example that creates and removes a short WAV file in
the R session’s temporary directory. The optional tuneR
dependency is guarded with requireNamespace() as
recommended for packages in Suggests.
- Unwrapped the short
phontrast() and
hier_boot_jsd_model() bootstrap examples after confirming
that they run well under five seconds. Reduced the illustrative
estimate_jsd() bootstrap count so that example is also
under five seconds and can be unwrapped. No examples now use
\dontrun{} or \donttest{}.
- Removed all direct access to
.GlobalEnv. Seeded KDE
subsampling and multivariate-normal Monte Carlo now use a private
deterministic generator, retaining reproducibility without reading,
writing, or replacing the user’s .Random.seed. Unseeded
stochastic calls retain their previous behavior.
phontrast 2.3.0
Distribution-aware,
accountable plotting
- New flagship visualization
plot_contrast(). Draws the same density model
the distributional metrics are computed from: under
density = "kde" it shows highest-density regions of each
category’s kernel density estimate (same bandwidth selection and ks
evaluation as the metrics); under density = "mvnorm" it
shows coverage ellipses of the fitted Gaussians used by the parametric
backend. The pointwise minimum of the two densities – the mass the
proportional-overlap metric integrates – is shaded directly (a ribbon in
1-D, a soft raster in 2-D, normalized across panels so fainter panels
genuinely overlap less).
- Accountability by default. Panels are annotated
with the Jensen-Shannon divergence and proportional overlap computed by
phontrast() under the plotted density model (optionally
with bootstrap intervals via n_boot); the caption records
the estimator configuration (backend, bandwidth, mc_n,
seed, n); and the full annotation table is attached to the plot as
attr(p, "contrast_metrics").
- Results plot themselves.
phontrast()
output now carries class "phontrast_contrast", so
plot() and ggplot2::autoplot() draw the metric
comparison directly via plot_overlap_metrics().
- A shared visual identity. New exported
theme_phontrast(), scale_colour_phontrast() /
scale_color_phontrast() /
scale_fill_phontrast(), and
phontrast_palette() (a colorblind-safe Okabe-Ito palette
ordered so the leading pair maximizes contrast for two-category plots).
All plotting functions – including the existing
plot_overlap_metrics(), plot_category_space(),
and plot_category_pca(), whose arguments and behavior are
otherwise unchanged – now share this theme and palette.
- Plotting remains optional:
ggplot2 stays in
Suggests.
phontrast 2.2.0
Pluggable
density backend for the distributional metrics
- Added a
density argument to decouple the
density estimator from the metric. The
distributional metrics (Jensen-Shannon divergence and proportional
overlap) previously always used kernel density estimation. They now
accept density = "kde" (the default, unchanged) or
density = "mvnorm", which fits one multivariate normal per
category and estimates the metric between the two Gaussians. This lets
the estimator behind JSD and overlap be matched to the same
multivariate-normal assumptions the Pillai, Bhattacharyya, and
Mahalanobis metrics already make, and makes the metric x estimator
interaction a controlled choice rather than hard-wired to KDE.
- Jensen-Shannon divergence between two Gaussians has no closed form
(the mixture is a Gaussian mixture), so the
"mvnorm"
backend estimates it by fresh-sample Monte-Carlo: it
draws mc_n points (default 10000) from each
fitted Gaussian and averages the log density ratio. The estimand is the
JSD / overlap between the fitted Gaussians; eval_seed makes
the draw reproducible without disturbing the caller’s random-number
stream. The Gaussian fit has no self-kernel, so the KDE-specific
leave-one-out correction does not apply.
density (and mc_n) are threaded through
phontrast(), compare_overlap_metrics(),
estimate_jsd(), estimate_overlap(),
jsd_summary(), global_boot_jsd(),
jsd_kde_nd(), and percent_overlap_kde(). In
phontrast() the argument affects only the Jensen-Shannon
and overlap columns; the Pillai, Bhattacharyya, and Mahalanobis columns
are parametric by construction and are unchanged.- The multivariate-normal log-density and sampler are implemented in
base R via a Cholesky solve, adding no new package dependency.
Rank-deficient category covariances are regularized with a small ridge
before factorization.
- Fully backward compatible: the default remains
density = "kde" and all existing results are
unchanged.
phontrast 2.1.0
Monte-Carlo
JSD no longer floors small divergences to exactly 0
- Fixed
method = "mc" (the default KDE JSD
estimator) flooring small but real divergences to exactly 0.
The full leave-one-out correction could collapse a category’s
self-density at isolated points, driving the raw plug-in mean negative,
which the final clamp then floored to 0 – while
method = "legacy" still reported a nonzero contrast. The
estimator now uses a partial leave-one-out correction that
removes a sample-size-scaled fraction n / (n + 20) of each
point’s own kernel: half at 20 tokens per category (the
min_tokens default), approaching the full correction as the
category grows. The corrected density stays strictly positive, so
near-merged categories yield small positive estimates instead of exact
0.
- Validated against grid-integrated JSD of the same KDEs: on 44 real
speaker contrasts (20 tokens per phase, 2-D formant space) the previous
estimator returned exactly 0 for 24 speakers; the corrected one returns
0 for none, tracks the grid reference more closely than either the
previous default or
method = "legacy", and still passes the
package’s grid-calibration test at n = 200 within the original
tolerance.
- This changes
method = "mc" results relative to
2.0.x, most visibly for small divergences and small samples
(estimates that were floored at 0 become small positive values; others
typically shift upward slightly). method = "legacy" is
unchanged, and loo = FALSE is unchanged.
CRAN preparation
- Replaced the relative
ROADMAP.md link in the README
with a plain reference, since ROADMAP.md is excluded from
the built package; this resolves the “invalid file URI” flagged by the
CRAN incoming checks.
phontrast 2.0.2
CRAN preparation
- Kept non-package content out of the built tarball: the (untracked)
local
OSF/ reproducibility-data directory and the top-level
ROADMAP.md are now listed in .Rbuildignore,
resolving the non-portable-paths and non-standard-top-level-files NOTEs
from R CMD check. Added “mel” to
inst/WORDLIST.
- Trimmed the
estimate_jsd() example to a fast point
estimate and moved the bootstrap demonstrations into
\donttest{}, keeping every example under CRAN’s
execution-time limit.
phontrast 2.0.1
CRAN preparation
- Prepared the package for CRAN submission: expanded acronyms and
added a Jensen-Shannon divergence reference (Lin, 1991) to the
Description, normalized non-ASCII characters in the R
sources, added inst/WORDLIST and
cran-comments.md, and removed the AI assistant from
Authors@R (the AI-use acknowledgment remains in the
README). No user-facing code changes.
phontrast 2.0.0
Package renamed:
phonJSD is now phontrast
- The package has been renamed from
phonJSD to
phontrast and reoriented around comparing
multiple category contrast and separation metrics rather than
Jensen-Shannon divergence alone. Update your code from
library(phonJSD) to library(phontrast).
Function names are unchanged except as noted below, and no metric
estimates change relative to 1.2.0 – this release is a rename and API
reframe, not a numerical change.
- The GitHub repository moved to https://github.com/berrygrant/phontrast (old links
redirect), and the Zenodo concept DOI (10.5281/zenodo.20816585) is
unchanged, so existing citations continue to resolve.
New unified entry point:
phontrast()
- Added
phontrast(), the package’s
headline function: compute and compare any subset of the contrast
metrics – Jensen-Shannon divergence and distance, Pillai-Bartlett trace,
Bhattacharyya distance and affinity, Mahalanobis distance, and
proportional overlap – for a two-category contrast in one call, globally
or by group, wide or tidy long, with optional bootstrap intervals.
- The new
metrics argument selects which metrics to
compute (default: all),
e.g. phontrast(data, features, "vowel", metrics = c("jsd", "pillai")).
compare_overlap_metrics() is
deprecated in favor of phontrast(). It still works
(it calls phontrast() with output = "wide")
and emits a deprecation message; it will be removed in a future
release.
Roadmap
- The next priority (P1) is a full architectural redesign around a
metric registry with a uniform per-metric interface, a generalized
bootstrap that works for any metric, and first-class metric orientation.
See
ROADMAP.md.
phonJSD 1.2.0
Corrected KDE estimator
(changes results)
- KDE-based JSD and percent overlap now use a consistent
Monte-Carlo plug-in estimator by default
(
method = "mc"). Each category’s KDE is evaluated
at that category’s own observations and the true log density ratio
against the mixture is averaged (with a leave-one-out bias correction,
loo = TRUE). This estimates the continuous Jensen-Shannon
divergence in any dimension, replacing the previous self-normalized
sample-point index, which was a bounded relative separation measure
rather than the JSD integral and depended on eval_on.
- This changes the numbers relative to phonJSD 1.0.0.
To reproduce 1.0.0 results exactly, pass
method = "legacy"
to jsd_kde_nd(), percent_overlap_kde(),
estimate_jsd(), estimate_overlap(),
jsd_summary(), global_boot_jsd(), or
compare_overlap_metrics(). The eval_on control
applies to method = "legacy" only.
- The
fast_diag engine now evaluates true (normalized)
densities, matching ks::kde() to machine precision for
diagonal bandwidths.
API
- Aligned defaults across the estimation API:
min_tokens = 20 and n_boot = 1000 everywhere
(previously estimate_jsd() defaulted to
min_tokens = 5, and
jsd_summary()/boot_jsd()/hier_boot_jsd_model()
to min_tokens = 30 / n_boot = 300).
- Standardized the
estimate_*/global_*
wrappers to return tibbles uniformly.
- Documented the
pillai_p_value (wide) and
p_value (long) columns returned by
compare_overlap_metrics().
Metrics
- Added opt-in high-dimensional KDE speed controls:
bw = "scott.diag", evaluation-point subsampling via
eval_n/eval_seed, and
engine = "fast_diag" for chunked diagonal-Gaussian KDE
evaluation.
- Added
engine = "fast_diagonal" as an alias for
engine = "fast_diag".
- Extended the same KDE controls across JSD, percent overlap, and
compare_overlap_metrics() so separation and overlap
estimates use aligned density-estimation settings.
- Exposed the same KDE controls in lower-level JSD wrappers including
speaker_jsd(), boot_jsd(),
jsd_summary(), and global_boot_jsd().
- Allowed grouped metric wrappers to use multiple grouping columns via
group_col = c("Sex", "Style"); grouped outputs retain a
single labeled group column.
- Switched
extract_mfcc() to tuneR::melfcc()
and removed the stale seewave::mfcc() reference.
Documentation
- Documented the high-dimensional fast KDE path in the README and
generated function manuals.
- Updated the GitHub Actions checkout step to a current Node runtime
action.
Bug fixes
- Clamped
jsd() output to the mathematical range
[0, 1], so floating-point rounding on near-identical
categories can no longer yield NaN Jensen-Shannon distances
(est_distance = TRUE) or abort
hier_boot_jsd_model() through
prepare_jsd_beta().
- Fixed a latent
sample() edge case in
hier_boot_jsd_model() that could misdraw a single numeric
group identifier.
Robustness
- Grouped metric wrappers now keep a group as
NA when its
metric cannot be computed and emit a single summarizing warning, instead
of the previous inconsistent behavior where
speaker_pillai()/speaker_bhatt() silently
dropped failed groups (so estimate_pillai() and
estimate_jsd() could return different rows for the same
data) while other metrics returned a silent NA.
- Added input validation at the main entry points:
data
must be a data frame, category_col a single column name,
features a non-empty character vector, and
features may not overlap with
category_col/group_col.
Package quality
- Removed the unused
LazyData field (no
data/ directory), the unused lme4 suggestion,
and dead dplyr imports (filter,
n, ungroup); added URL and
BugReports; standardized the author name to “Grant M.
Berry”; and scoped the CI workflow to the existing main
branch.
phonJSD 1.0.0
Visualization
- Added ggplot2-backed
plot_overlap_metrics() and
plot_category_space() helpers for visualizing metric
comparisons and one- or two-dimensional phonological category
spaces.
- Added
plot_category_pca() for two-dimensional PCA
diagnostics of arbitrary multidimensional feature spaces.
Metrics
- Added
compare_overlap_metrics() to compute Pillai
trace, Bhattacharyya distance and affinity, Jensen-Shannon divergence
and distance, Mahalanobis distance, and percent overlap in one global or
grouped comparison table.
- Added one-dimensional KDE support for JSD and percent-overlap
estimates.
- Aligned KDE bandwidth/evaluation controls across JSD and percent
overlap.
- Made grouped JSD bootstrap intervals respect
conf_level.
- Improved empty grouped outputs and small-sample diagnostics across
metric wrappers.
- Made two-category metric checks ignore unused factor levels after
filtering, so filtered factor data such as PB52
I/i
contrasts work without manually calling droplevels().
- Clarified that percent-overlap outputs are 0–1 proportions, not
0–100 percentages.
Documentation
- Added quick-start and multidimensional-workflow vignettes.
- Added a README quick start that starts from a vowel token table and
moves to metric output.
- Added metric-choice guidance and PB52 small-sample notes.
- Added preferred-path and metric-direction guidance to the package
manual.
- Added runnable examples for the main metric comparison, JSD
estimation, direct KDE JSD, beta-regression preparation, MFCC
extraction, and hierarchical bootstrap modeling workflows.
- Standardized JSD bootstrap outputs with
conf_level,
ci_lower, and ci_upper columns while retaining
jsd_low and jsd_high as aliases.
- Added optional bootstrapping to
compare_overlap_metrics() with progress messages and
metric-specific confidence intervals.
Maintenance
- Aligned DESCRIPTION metadata with the v1.0.0 README/DOI
release.
- Added explicit Author and Maintainer fields for source-package
checks on current R tooling.
- Removed old draft analysis scripts from the main package branch; the
final LabPhon 2026 poster and reproducibility bundle live on
labphon_2026.
phonJSD 0.5.0
Package Quality
- Added testthat coverage for the discrete JSD core, grouped classical
metrics, KDE-based JSD wrappers, and grouped bootstrap summaries.
- Added
.Rbuildignore entries so local analysis,
load-test, and manuscript artifacts are excluded from package
builds.
- Fixed the MIT license stub expected by R package tooling.
Metrics
- Centralized column validation, complete-case filtering, and
two-category checks across metric functions.
- Corrected discrete KL/JSD handling of zero-probability events.
- Made grouped bootstrap JSD report the number of successful bootstrap
replicates.
- Replaced bootstrap
replicate() control-flow edge cases
with explicit vapply() iteration.
- Removed deprecated tidyselect usage in grouped JSD summaries.
Documentation
- Updated generated Rd documentation for KL/JSD and bootstrap JSD
outputs.
- Updated README release metadata and feature summary for v0.5.0.