Pragmastat

This release is about correctness and currency. Five cross-language correctness fixes make the estimators return the right number on more inputs and behave identically across all seven implementations: overflow no longer corrupts spread on large samples or shift/ratio bounds near the floating-point ceiling, the pairwise-margin binomial is now computed with exact integer arithmetic instead of drifting in floating point, C#'s center/spread seed their randomness deterministically from the input like the other six ports, and uniform_int is exact for large ranges with a single, explicit overflow contract everywhere. Alongside the fixes, every language's toolchain moves to a current baseline, and the manual gains an opening Introduction chapter. The correctness fixes and the raised runtime floors are breaking; the migration guide below covers every change per language.

Highlights

• Correct results on more inputs. spread no longer overflows its internal counter on samples of 65537+ elements; shift and ratio bounds no longer overflow to infinity on finite inputs near the floating-point ceiling; uniform_int is now exact for large ranges. Every in-range result that was already correct is unchanged.
• Exact pairwise margins. The binomial coefficient behind pairwise_margin is now computed with exact integer arithmetic in every language (a native 64-bit helper in R, whose built-in choose() is inexact even below 2^53). Margins that previously drifted — e.g. 784 where the correct value is 782 — are now exact and identical across all seven ports.
• Deterministic randomness across languages. C#'s center and spread now seed their internal RNG from the input via FNV-1a, matching the other six ports byte-for-byte. Previously C# fell back to a clock-seeded System.Random, so its results were non-deterministic and could disagree with the other languages.
• Unified uniform_int overflow contract. All seven ports now reject ranges larger than 2^52 — the largest range a double-based implementation can sample exactly — with a language-native error, instead of the previous inconsistent behavior.
• Modernized toolchains. Runtime floors move to a current baseline where it matters (Python, Go, Rust, Node); the .NET and Kotlin runtime floors are unchanged.
• New Introduction chapter. The manual now opens with an Introduction that motivates the toolkit before the Synopsis, on the site and in the PDF.
• Confirmatory comparison in every demo. Each language's demo now exercises Compare1/Compare2 against practical thresholds, with a canonical lowercase verdict.

Migration guide

Callers on the typed Sample API with default arguments need no source changes except where a raised runtime floor or a removed C# member applies. Two estimators return different (still deterministic) numbers by design — see "Reference values" below; assert against the shipped reference fixtures rather than hardcoded literals.

Runtime requirements

The minimum supported runtime rises for four languages and is unchanged for the other three:

uniform_int overflow contract (all languages)

uniform_int / UniformInt64 now throws when the requested range exceeds 2^52 (4503599627370496), using the language-native error type: OverflowError (Python), RangeError (TypeScript), OverflowException (C#), ArithmeticException (Kotlin), a panic (Go, Rust), and stop() (R). Previously the threshold was inconsistent across ports — Go/Python/TypeScript accepted ranges up to 2^64 but returned imprecise values above 2^52, while Rust/C#/Kotlin threw only at i64 overflow. 2^52 is the largest range any implementation can sample exactly; ranges this large are far beyond any real sample. If you relied on the old behavior, clamp your range to <= 2^52.

Reference values changed by design

Two fixes change numeric outputs deterministically:

• pairwise_margin now uses exact integer arithmetic, correcting a handful of previously-drifting margins (e.g. 784 -> 782). All seven languages now agree bit-for-bit.
• C# center / spread seed their RNG from the input instead of a clock, so their results are now deterministic and match the other six ports. If you captured C# outputs from v13, regenerate them.

If you assert against these estimators, compare against the shipped reference fixtures rather than pinned literals.

C#

• Estimate dropped its Random? parameter. CenterImpl.Estimate(values, Random? random = null, bool assumeSorted = false) is now Estimate(values, bool assumeSorted = false) (same for SpreadImpl); randomness is derived deterministically from the input. Remove the argument from any call site that passed one — call sites using defaults are unaffected.
• The protected serialization constructor was removed from WeightedSampleNotSupportedException (the obsolete SerializationInfo/StreamingContext ctor, SYSLIB0051). Binary serialization of exceptions is dead in modern .NET; no replacement is needed.
• A net10.0 target was added; net6.0 and netstandard2.0 remain, so existing consumers do not need to change target framework.

Kotlin

ComparisonVerdict gains toId(), returning the canonical lowercase identifier ("greater" / "less" / "inconclusive") that matches the other ports and the reference JSON. This is an addition; existing code is unaffected.

Go, Python, TypeScript, Rust, R

No source-level API changes beyond the runtime floor (above) and the shared uniform_int overflow contract. The pairwise-margin correction may change a margin value if you pinned one; use the reference fixtures.

A patch release. The only change is a CI fix: v13.0.0 failed to publish to the npm registry, so no library code or public API changed since v13.0.0.

npm: 13.0.1 is the first 13.x release on npm — v13.0.0 never reached the registry. Upgrading from 12.1.0 therefore brings the full set of 13.0.0 breaking changes; see the v13.0.0 release notes for the per-language migration guide.

crates.io, NuGet, PyPI, Maven Central, Go, GitHub: unchanged from v13.0.0 — 13.0.1 is behavior-identical and needs no action.

What's Changed

• fix(ci): publish npm via tokenless trusted publishing by @jn8128 in #56

Full Changelog: v13.0.0...v13.0.1

This release makes the estimator kernels' sorted-input contract explicit and safe across all seven language implementations. The internal Hodges-Lehmann (center), spread, shift, and their bounds only ever run on sorted data, but that precondition used to be implicit and unguarded. It is now a first-class part of the API: every implementation gains a raw native-array entry point with an assume_sorted fast path, the central pairwise midpoints are computed overflow-safely, the selection loops are bounded so misuse fails fast instead of hanging, and Sample is defensively immutable where it was not. These improvements came with public API changes in every language. The typed Sample-based API stays the recommended entry point and is largely unchanged; the migration guide below covers every breaking change per language.

Highlights

• Raw native-array API in every language. Estimators now accept plain arrays / slices / lists directly and return bare numbers, so computing an estimate no longer requires constructing a Sample.
• assume_sorted fast path. Passing already-ascending data skips the internal sort; the typed Sample API uses a cached sorted view, so repeated estimators on the same sample sort only once.
• Correct answers at extreme magnitudes. center and spread no longer overflow to infinity on finite inputs near the floating-point ceiling; every in-range result is bit-identical to before.
• No hangs on misuse. The selection loops are bounded: setting assume_sorted on unsorted data fails with a deterministic convergence error instead of spinning forever.
• Immutable Sample. In C#, Go, Python, and TypeScript, Sample copies its input on construction and no longer hands out a mutable view of its internal buffers.

Migration guide

Nothing needs to change for callers who stay on the typed Sample API and its default arguments, except in Kotlin and C# where a value-type change forces a recompile (details below). Everything else is opt-in surface that only affected code must touch.

C#

Pragmastat.Algorithms.FastShift / FastRatio removed. Both public classes became internal (ShiftImpl / RatioImpl). Use the new native-array overloads for the median shift/ratio; there is no public replacement for arbitrary pairwise-quantile arrays.

// before
double s = FastShift.Estimate(x, y, new[] { 0.5 })[0];
// after
double s = Toolkit.Shift(x, y);   // new double[] overload

Probability.Zero / Half / One / NaN removed. Construct the value instead. NaN has no replacement — a NaN probability is now rejected (see below).

Probability.Half   // before
(Probability)0.5   // after

Probability from NaN now throws. new Probability(double.NaN), the implicit double→Probability conversion, and Probability.Of(double.NaN) now throw ArgumentOutOfRangeException instead of storing a NaN. Filter NaN misrate/probability values before passing them in. In-range values are unaffected.

Sample constructors dropped the optional Subject? validationSubject. Remove the argument. The two IReadOnlyList<double>-based constructors are binary-incompatible for all callers (C# binds optional-argument call sites to the full signature), so recompile against 13.0.0.

new Sample(values, unit, Subject.X)          // before
new Sample(values, unit)                      // after
new Sample(values, weights, unit, Subject.X)  // before
new Sample(values, weights, unit)             // after

Minor: on a degenerate single-element sample, SpreadBounds may now report the Sparity violation where it previously reported Domain (the input was already an error either way; only matters if you branch on the violation subject).

Go

Package-level estimator functions became the raw-slice fast path. Center, Spread, Shift, Ratio, Disparity, all *Bounds, and SpreadBoundsWithSeed / DisparityBoundsWithSeed changed from taking *Sample and returning Measurement to taking []float64 plus a required assumeSorted bool and returning float64 / Bounds. The identically-named Sample methods kept their exact signatures — switch to those to preserve behavior and the measurement unit.

// before
m, err := pragmastat.Center(sample)
b, err := pragmastat.ShiftBounds(sx, sy, 1e-3)
// after (recommended: method form, unit preserved)
m, err := sample.Center()
b, err := sx.ShiftBounds(sy, 1e-3)
// or the raw path (returns float64 / NumberUnit-tagged Bounds)
v, err := pragmastat.Center(sample.Values(), false)

SpreadBoundsWithSeed / DisparityBoundsWithSeed now also exist as Sample methods (sample.SpreadBoundsWithSeed(1e-3, "seed")); the raw free functions gained the trailing assumeSorted argument.

Sample fields became accessor methods. Values, Weights, Unit, IsWeighted, TotalWeight, WeightedSize are now methods. Append (). Values() / Weights() now return a defensive copy, so mutating the result no longer mutates the sample.

u := sample.Unit      // before
u := sample.Unit()    // after

Kotlin

The typed misrate is now a Probability value class, not Double. This affects the Threshold data class and the five Sample-based bounds functions (centerBounds, spreadBounds, shiftBounds, ratioBounds, disparityBounds). Wrap the rate at construction and unwrap at read. Because Probability is a @JvmInline value class, the change is binary-incompatible for all callers (including those that omit the misrate) — recompile against 13.0.0.

// before
centerBounds(sample, 0.05)
Threshold(Metric.Center, value, 0.01)
val d: Double = threshold.misrate
// after
centerBounds(sample, Probability(0.05))
Threshold(Metric.Center, value, Probability(0.01))
val d: Double = threshold.misrate.value

Calls that omit the misrate (centerBounds(sample)) still compile unchanged at source level. Destructuring a Threshold now yields a Probability for the third component, and copy(misrate = Probability(...)) must wrap.

Minor: on a single-element sample, spreadBounds now throws AssumptionId.SPARITY where it previously threw DOMAIN (subject stays X); only matters if you catch AssumptionException and branch on the violation id.

Python

Sample.log() removed. Rebuild from logged values.

ls = sample.log()                     # before
import numpy as np
ls = Sample(np.log(sample.values))    # after

Note: the old method ran a positivity pre-check; np.log of a non-positive value yields nan/-inf and the Sample constructor then raises a validity error. Guard positivity yourself if you relied on that specific error.

Sample arrays are copied and frozen. values, weights, and sorted_values are now read-only NumPy arrays, and construction copies its input (no more aliasing the caller's array). In-place mutation raises ValueError: assignment destination is read-only. Copy first.

s.values[0] = 42.0          # before (worked)
v = s.values.copy()         # after
v[0] = 42.0

Point estimators' return type widened. center, spread, shift, ratio, disparity are now annotated Measurement | float (to support native-array input). Runtime is unchanged — a Sample argument still returns a Measurement; only static type-checkers (mypy/pyright) see the difference. Narrow the result if a checker complains:

m = center(s)
assert isinstance(m, Measurement)   # or cast(Measurement, center(s))

R

Sample$new() dropped the subject argument; with_subject() and sample$subject are gone. The Sample R6 class no longer carries a subject label — estimators assign the "x"/"y" role by argument position, so standard error messages are preserved without any action.

Sample$new(x, subject = "y")   # before -> error: unused argument
Sample$new(x)                  # after

s2 <- s$with_subject("y")      # before -> removed; drop the call
lbl <- s$subject               # before -> now silently returns NULL

The last one is the trap: reading s$subject no longer errors, it returns NULL. If you branched on it, key off argument position at the call site instead.

Rust

Every estimators::raw::* function gained a required trailing assume_sorted: bool. This covers center, spread, shift, ratio, disparity, all *_bounds, and the seeded variants. Rust has no default arguments, so each call site must add the argument. v12.1.0 always sorted internally — pass false to reproduce the old behavior:

raw::center(&x)              // before
raw::center(&x, false)       // after
raw::shift_bounds(&x, &y, m) // before
raw::shift_bounds(&x, &y, m, false)  // after

Pass true only when the input is already ascending-sorted. The typed Sample-based estimators (pragmastat::center(&sample), …) are unchanged. Bonus: Sample is now Send + Sync, so it can be shared across threads.

TypeScript

Sample.sortedValues narrowed from number[] to readonly number[]. Compile-time only; the emitted JS is unchanged. If you assign it to a mutable number[] or call a mutating method on it, copy first:

const sorted: number[] = sample.sortedValues;      // before
const sorted: number[] = [...sample.sortedValues]; // after
// or widen the annotation for read-only use:
const sorted: readonly number[] = sample.sortedValues;

What's Changed

• Make the estimator kernels' sorted-input contract explicit and safe by @jn8128 in #53
• fix: point homepage language links to per-language pages by @jn8128 in #54
• chore: allow *.local dev hosts for network preview by @jn8128 in #55

New Contributors

• @jn8128 made their first contribution in #53

Full Changelog: v12.1.0...v13.0.0

What's Changed

• fix: prevent Loeffler loop hang caused by int64 overflow for n+m in [62, 64] by @egor-click in #51

New Contributors

• @egor-click made their first contribution in #51

Full Changelog: v12.0.1...v12.1.0