commensura.uncertain — com.github.crinklywrappr/commensura 1.0.39

Measurement uncertainty over conforming Quantities — a value paired with a 1σ (sigma) spread that propagates through the arithmetic. An Uncertain is the epistemic sibling of Interval (commensura.interval): an interval denotes every value between two endpoints; an uncertain is one best estimate with a standard deviation. It is about how well the value is known, and rides the core verbs the way intervals do.

(require '[commensura.uncertain :as un :refer [plus-minus]] '[commensura.units :as u] '[commensura.core :refer [by per plus minus pow]])

(plus-minus (u/meter 5) (u/cm 2)) ;=> 5 meter ± 2 centimeter [length] (by (plus-minus (u/meter 5) (u/cm 2)) (plus-minus (u/meter 3) (u/cm 1))) ; area, with the spread propagated in quadrature

Propagation is algebraic — no calculus. Errors combine as independent Gaussians:

• plus/minus — absolute σ in quadrature: σ = √(σx² + σy²).
• by/per/ratio — relative σ in quadrature: (σ/v) = √((σx/x)² + (σy/y)²).
• pow — relative σ scales by |exponent|; so sqrt (exponent ½) halves it and pow/sqrt round-trip. These are the only nonlinear verbs, and since commensura excludes transcendentals, that's the whole story — no derivatives needed.
• to — a linear re-expression: value and σ both move to the target basis.

The central value stays a normal exact quantity; σ is likewise an ordinary quantity carried through the standard tower (it typically goes approximate under a quadrature √, exactly as any irrational magnitude does). A plain quantity/number entering a verb is treated as σ=0 (an exact value), so uncertain and plain operands mix freely — but an uncertain and an Interval do not (they are different notions of spread): the core verbs throw on that mix.

Caveat — independence assumed. Quadrature presumes the operands are uncorrelated, so (by x x) mis-propagates (it treats the two xs as independent); use (pow x 2) for that.

Like Interval, an Uncertain has no reader tag — pr emits the raw record (its value/ sigma fields are their own #commensura/quantity literals, so it round-trips), while str gives the friendly value ± sigma [dimension] form.

combined-sigma clj

(combined-sigma x y)

Quadrature of the two spreads, √(σx² + σy²) — the 1σ scale for comparing x and y.

consistent? clj

(consistent? x y)

Agreement at the conventional 2σ (~95%) level — (within? x y 2). Use within? for another threshold (1σ ≈ 68%, 3σ ≈ 99.7%).

IUncertain clj protocol

sigma clj

(sigma x)

The 1σ spread — a non-negative quantity conforming to the value.

value clj

(value x)

The central best-estimate quantity.

plus-minus clj

(plus-minus value spread)

Pair a central value with a 1σ absolute spread: (plus-minus (u/meter 5) (u/cm 2)) ⇒ 5 meter ± 2 centimeter. The spread must conform to the value and be non-negative; both are kept exact (bare numbers are wrapped as dimensionless quantities).

plus-minus-rel clj

(plus-minus-rel value frac)

Like plus-minus, but the spread is a dimensionless relative uncertainty: σ = |value|·frac. (plus-minus-rel (u/meter 5) 1/100) ⇒ a 1%-uncertain 5 meter.

relative clj

(relative x)

The relative (fractional) uncertainty |σ / value| — a non-negative dimensionless quantity.

sigma-or-zero clj

(sigma-or-zero x)

An uncertain's spread; for a plain quantity/number, a zero spread carrying its dimension.

uby clj

(uby x y)

uminus clj

(uminus x y)

uncertain? clj

(uncertain? x)

unegate clj

(unegate x)

uper clj

(uper x y)

uplus clj

(uplus x y)

upow clj

(upow x n)

uratio clj

(uratio x target)

uto clj

(uto x target)

value-or-identity clj

(value-or-identity x)

An uncertain's central value; any other value is returned as-is (it's exactly known).

within? clj

(within? x y n)

Do x and y agree to within n combined standard deviations? |value x − value y| ≤ n · √(σx² + σy²). Plain quantities carry σ=0, so this also compares a measurement against an exact reference.