From 0482c716dd4c6c4d96451e91875de663e5402242 Mon Sep 17 00:00:00 2001 From: jmh530 Date: Tue, 20 Oct 2026 23:12:23 -0400 Subject: [PATCH] Deprecate variance APIs in favor of mir-stat Deprecate variance, standardDeviation, VarianceAccumulator, and VarianceAlgo, directing callers to mir.stat.descriptive. Cover all function overloads and accumulator specializations while preserving the legacy implementations and online defaults. Document the mir-stat dependency and replacement import, its hybrid default, and potential rounding differences. Explain that enum types are distinct and code using accumulator state or constructors needs separate migration review. AI-Assisted-By: Codex (GPT-6 Astra Medium) --- source/mir/math/stat.d | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/source/mir/math/stat.d b/source/mir/math/stat.d index 72db9a0e..f6f416c8 100644 --- a/source/mir/math/stat.d +++ b/source/mir/math/stat.d @@ -1,6 +1,23 @@ /++ This module contains base statistical algorithms. +$(LREF variance), $(LREF standardDeviation), $(LREF VarianceAccumulator), and +$(LREF VarianceAlgo) are deprecated. Use the corresponding symbols exported by +`mir.stat.descriptive` in the $(WEB github.com/libmir/mir-stat, mir-stat) package. +Add mir-stat as a dependency and replace the selective import, for example: + +--- +import mir.stat.descriptive: variance, standardDeviation, + VarianceAccumulator, VarianceAlgo; +--- + +The legacy implementations and their `online` defaults are unchanged. +Mir-stat defaults to `hybrid` for variance and standard deviation; select its +`VarianceAlgo.online` explicitly when online calculation is required. Rounding +can differ between algorithms. The enum types are distinct, and accumulator +internals are not interchangeable; migrate code using public accumulator state +or constructors separately rather than assuming an import-only replacement. + Note that used specialized summing algorithms execute more primitive operations than vanilla summation. Therefore, if in certain cases maximum speed is required at expense of precision, one can use $(REF_ALTTEXT $(TT Summation.fast), Summation.fast, mir, math, sum)$(NBSP). @@ -2022,6 +2039,7 @@ Variance algorithms. See Also: $(WEB en.wikipedia.org/wiki/Algorithms_for_calculating_variance, Algorithms for calculating variance). +/ +deprecated("Use VarianceAlgo from mir.stat.descriptive (mir-stat) instead.") enum VarianceAlgo { /++ @@ -2050,6 +2068,7 @@ enum VarianceAlgo } /// +deprecated("Use VarianceAccumulator from mir.stat.descriptive (mir-stat) instead.") struct VarianceAccumulator(T, VarianceAlgo varianceAlgo, Summation summation) if (isMutable!T && varianceAlgo == VarianceAlgo.naive) { @@ -2145,6 +2164,7 @@ unittest } /// +deprecated("Use VarianceAccumulator from mir.stat.descriptive (mir-stat) instead.") struct VarianceAccumulator(T, VarianceAlgo varianceAlgo, Summation summation) if (isMutable!T && varianceAlgo == VarianceAlgo.online) @@ -2370,6 +2390,7 @@ unittest } /// +deprecated("Use VarianceAccumulator from mir.stat.descriptive (mir-stat) instead.") struct VarianceAccumulator(T, VarianceAlgo varianceAlgo, Summation summation) if (isMutable!T && varianceAlgo == VarianceAlgo.twoPass) { @@ -2494,6 +2515,7 @@ unittest } /// +deprecated("Use VarianceAccumulator from mir.stat.descriptive (mir-stat) instead.") struct VarianceAccumulator(T, VarianceAlgo varianceAlgo, Summation summation) if (isMutable!T && varianceAlgo == VarianceAlgo.assumeZeroMean) { @@ -2734,6 +2756,7 @@ Params: Returns: The variance of the input, must be floating point or complex type +/ +deprecated("Use variance from mir.stat.descriptive (mir-stat) instead.") template variance( F, VarianceAlgo varianceAlgo = VarianceAlgo.online, @@ -2767,6 +2790,7 @@ template variance( } /// ditto +deprecated("Use variance from mir.stat.descriptive (mir-stat) instead.") template variance( VarianceAlgo varianceAlgo = VarianceAlgo.online, Summation summation = Summation.appropriate) @@ -2797,12 +2821,14 @@ template variance( } /// ditto +deprecated("Use variance from mir.stat.descriptive (mir-stat) instead.") template variance(F, string varianceAlgo, string summation = "appropriate") { mixin("alias variance = .variance!(F, VarianceAlgo." ~ varianceAlgo ~ ", Summation." ~ summation ~ ");"); } /// ditto +deprecated("Use variance from mir.stat.descriptive (mir-stat) instead.") template variance(string varianceAlgo, string summation = "appropriate") { mixin("alias variance = .variance!(VarianceAlgo." ~ varianceAlgo ~ ", Summation." ~ summation ~ ");"); @@ -3117,6 +3143,7 @@ Params: Returns: The standard deviation of the input, must be floating point type type +/ +deprecated("Use standardDeviation from mir.stat.descriptive (mir-stat) instead.") template standardDeviation( F, VarianceAlgo varianceAlgo = VarianceAlgo.online, @@ -3149,6 +3176,7 @@ template standardDeviation( } /// ditto +deprecated("Use standardDeviation from mir.stat.descriptive (mir-stat) instead.") template standardDeviation( VarianceAlgo varianceAlgo = VarianceAlgo.online, Summation summation = Summation.appropriate) @@ -3179,12 +3207,14 @@ template standardDeviation( } /// ditto +deprecated("Use standardDeviation from mir.stat.descriptive (mir-stat) instead.") template standardDeviation(F, string varianceAlgo, string summation = "appropriate") { mixin("alias standardDeviation = .standardDeviation!(F, VarianceAlgo." ~ varianceAlgo ~ ", Summation." ~ summation ~ ");"); } /// ditto +deprecated("Use standardDeviation from mir.stat.descriptive (mir-stat) instead.") template standardDeviation(string varianceAlgo, string summation = "appropriate") { mixin("alias standardDeviation = .standardDeviation!(VarianceAlgo." ~ varianceAlgo ~ ", Summation." ~ summation ~ ");");