Skip to contents

Changelog

Source: NEWS.md

PreciseDist 0.1.0

  • All public machine-facing output fields now use lowercase snake_case. New caches use format version 4; precise_read() normalizes valid version-3 results and ledgers in memory so existing completed work remains readable.
  • KODAMA factory metrics now preserve the caller’s random-number state and suppress the backend’s unconditional progress output.
  • precise_transform() now supports automatic coercion in both directions with to = "distance" or to = "similarity". Converted rows retain their stable metric keys, update type, and record the exact formula in history.

Independent PreciseViz package

  • CRAN vignettes are now static and package-local; cross-package and interactive guides are website-only articles. PreciseDist no longer lists PreciseViz or visualization engines used only by the website in Suggests.
  • Visualization, Trelliscope browsing, and GraphML export now live in the independent PreciseViz package under the same repository. PreciseViz does not import PreciseDist; the packages interoperate through the documented typed-matrix protocol.
  • precise_correlations() now returns additive parameters provenance (method, permutations, seed, and input type). PreciseViz consumes this precomputed result through its explicit agreement= argument rather than calling back into PreciseDist.
  • PreciseDist no longer hard-imports ggplot2, igraph, or uwot, and the obsolete GitHub Remotes entry for the now-CRAN trelliscopejs package is gone.

Numerical-contract re-baseline

  • Registry input_class is now enforced for non-negative, probability, unit-interval, and binary metrics. Incompatible requests become explicit errored/input_domain ledger rows while compatible metrics continue; input data are never transformed silently.
  • The producer boundary now requires numeric, finite, square, symmetric matrices, and additionally requires non-negative, zero-diagonal output for type = "distance". precise_transform() applies the same validation before an operation can mask an invalid input.
  • Removed asymmetric kullback_leibler, k_divergence, and neyman rows. Their mean-symmetric forms duplicate existing Jeffreys, Jensen-Shannon, and additive symmetric chi-square measures. Removed proxy’s directional fager and non-finite stiles implementations. Corrected Gower to emit distance rather than diagonal-masked similarity, and made LCSS explicitly bidirectional.
  • Seed validation now accepts only 0 through .Machine$integer.max; per-task L’Ecuyer states use six domain-separated hash words instead of one 28-bit seed, removing practical stream collisions. Seeded stochastic results are intentionally re-baselined.
  • Version-2 caches predate the numerical contract and are rejected with an actionable recomputation error.
  • Per-metric timeout cleanup is transient, preserving still-live caller limits; timeout accounting now requires the elapsed-limit condition rather than only wall-clock duration.

PreciseDist has been rebuilt around a typed four-function computational spine: precise_dist() -> precise_transform() -> precise_fusion() -> precise_graph(), each consuming the typed output of the last. PreciseViz can render the resulting typed matrices without a runtime dependency between the packages.

  • Every relatedness matrix now carries an explicit type (distance or similarity); the package never infers type from values and never silently converts one to the other.
  • Distance family keywords now accept short aliases in both precise_dist_list() and precise_dist(): for example, static is equivalent to static_dists.
  • precise_diagnostics() adds per-matrix quantitative diagnostics for spread, degeneracy, nearest-neighbour contrast, hubness, graph fragmentation, and optional label separation. It is a companion to visualization, not a ranking or clustering wrapper.
  • precise_stability() adds metric-set stability diagnostics: leave-one-metric-out and bootstrap resampling of whole typed matrix rows, returning replicate fused consensuses that compose with precise_correlations() and typed-matrix consumers such as PreciseViz.
  • The clustering, supervised-analysis, and one-off visualization satellites of earlier development have been removed in favour of the lean spine.
  • The retired partitions and time_series arguments have been removed from precise_dist(); stability now lives downstream of matrix construction rather than inside the raw data front door.
  • Heavy optional backends are now gated through Suggests: SNFtool, DistatisR, analogue, KODAMA, future and doFuture are not required for the default spine.
  • precise_dist(parallel=) is now documented and validated as a TRUE/FALSE backend flag, not a core-count argument.

precise_dist() execution engine and persistence redesign

  • Failure accounting: every requested metric now terminates in exactly one row of a run ledger (completed / errored / skipped / unavailable, with reason slugs, error messages, and timings) attached as the "precise_dist_run" attribute and retrievable with the new precise_run_report(). Failed metrics no longer vanish silently; a consolidated warning names each one. Metrics whose backend package is not installed are recorded as unavailable instead of stopping the run (unknown metric names still error).
  • The engine was rewritten from two duplicated foreach loops to one task function dispatched with future.apply::future_lapply() (parallel = TRUE, on the user’s future::plan()) or plain lapply() (default). foreach is no longer used by precise_dist(); registerDoFuture() is still needed for precise_graph() when its parallel flag is enabled.
  • New run controls: plan_only (inspect the resolved plan and resource estimate without computing), max_memory (user-defined GB cap, checked against the estimate before dispatch; without it, runs estimated above getOption("PreciseDist.large_run_gb", 8) GB warn and proceed), max_time_per_metric (per-metric limit; local_timeout is a deprecated alias), max_time_total (between-batch deadline; remainder is skipped), and batch_size (checkpoint/deadline granularity, auto by default).
  • New seed argument: seed = NULL keeps ordinary randomness (parallel runs use future.seed = TRUE); an integer seed gives per-metric RNG streams keyed by metric name — identical results across sequential and parallel plans and stable under request-set edits. BREAKING (numeric): stochastic metrics (random_forest_*, rbf_*, laplace_*) draw from a different stream position than historical unseeded sequential runs, because the old engine’s microbenchmark timing wrappers each consumed one hidden RNG draw and are gone. Deterministic metrics are numerically unchanged.
  • BREAKING: file= now writes a versioned RDS envelope instead of a bare matrix list. During a run it holds state = "partial" (completed native matrices plus the ledger, rewritten atomically by the master after every batch); on normal return it is rewritten once as state = "complete", holding the exact returned object. Read it with the new precise_read() (pre-2.0 caches are rejected with a clear message). file= now combines with parallel = TRUE; an existing path errors unless overwrite = TRUE. Interrupts checkpoint before re-signalling; a crashed parallel worker aborts with a "precise_dist_crash" error carrying the ledger.
  • BREAKING: a dists/dist_funcs display-key collision (for example dists = "cosine" with dist_funcs = list(cosine = ...)) is now an error — keys join the ledger and precise_read(metrics=). Duplicate dists after alias/family expansion collapse to one row with a message; unnamed dist_funcs are keyed user_func_<i>.
  • data may now be a dataframe/tibble with numeric columns, as documented (non-numeric columns are dropped with a message); previously every data.frame was rejected.
  • Progress: if progressr is installed, precise_dist() signals one step per metric (enable with progressr::with_progress()); verbose narration now uses message() and is suppressable.
  • The example workflow and parallel vignette document the revised contract: plan, seed, limits, checkpoint/recovery, and progress.

precise_correlations() reproducibility

  • precise_correlations() now uses future.apply for parallel = TRUE and adds seed = NULL | integer. Integer seeds give reproducible permutation p-values across sequential and future-backed parallel runs; seed = NULL keeps ordinary session RNG for sequential calls and uses statistically sound Future streams for parallel calls.
  • Failed or undefined pairwise comparisons now return NA statistic/significance cells with one consolidated warning and a "correlation_failures" attribute instead of crashing or leaking raw correlation warnings during result assembly. The main return shape remains output, statistic, and signif.
  • microbenchmark is no longer imported.