Skip to content

Commit d558200

Browse files
committed
Add weighted percentogram factories for GC, RC, and custom allocation
Use weights for both quantile boundaries and bin totals, defaulting to inverseCDF with explicit support for all weighted quantile algorithms. Reuse percentogram boundary handling and tail normalization. Infer the default bin count from positive-weight rows. Document reweighting and frequency-count examples, and test algorithm selection, strided inputs, zero weights, ownership, and failure cleanup. AI-Assisted-By: Codex (GPT-6 Astra Medium)
1 parent 4fde437 commit d558200

5 files changed

Lines changed: 526 additions & 5 deletions

File tree

‎source/mir/stat/descriptive/histogram/api/custom.d‎

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@ Copyright: 2026 Mir Stat Authors.
77
+/
88
module mir.stat.descriptive.histogram.api.custom;
99

10+
private import mir.stat.descriptive.univariate: WeightedQuantileAlgo;
11+
1012
// Joint numeric batches preserve pairing, numeric types, and axis lifetimes.
1113
version(mir_stat_test)
1214
@safe pure nothrow
@@ -2093,3 +2095,166 @@ unittest
20932095
assert(allocator.allocations == failure && allocator.releases == failure - 1);
20942096
}
20952097
}
2098+
2099+
/++
2100+
Construct a weighted percentogram with caller-selected allocation.
2101+
Uses the algorithms, input requirements, bin-count heuristic, and boundary rules
2102+
of $(REF weightedPercentogram, mir, stat, descriptive, histogram, api, gc).
2103+
The result exposes histogram; call dispose with the same allocator after use.
2104+
Generated probabilities and quantile scratch are released before return.
2105+
Completed allocations are released on exceptions; deallocation must not throw.
2106+
As with makePercentogram, invalid-input assertions are contract violations,
2107+
and recovery through nothrow code is not supported. The full boundary allocation
2108+
is retained for disposal even when duplicate boundaries are compacted.
2109+
2110+
Params:
2111+
Counts = numeric counter type, double by default
2112+
algorithm = weighted quantile definition, inverseCDF by default
2113+
allocator = allocator providing allocation and nonthrowing deallocation
2114+
weights = probability masses, or occurrence counts for frequency algorithms
2115+
data = one-dimensional observations, as an array or Mir slice
2116+
probabilities = positive bin count or probability array/slice
2117+
+/
2118+
auto makeWeightedPercentogram(Counts = double,
2119+
WeightedQuantileAlgo algorithm = WeightedQuantileAlgo.inverseCDF, Allocator, Weights, Data, P)(
2120+
ref Allocator allocator, scope auto ref Weights weights, scope auto ref Data data,
2121+
scope auto ref P probabilities)
2122+
{
2123+
import std.traits: isIntegral;
2124+
import std.experimental.allocator: dispose;
2125+
import mir.ndslice.slice: isSlice, sliced;
2126+
import mir.stat.descriptive.univariate: makeWeightedQuantile;
2127+
import mir.stat.descriptive.histogram.axis: variableAxis, AxisOptions;
2128+
import mir.stat.descriptive.histogram.api.factory: validatePercentogramLevels,
2129+
preparePercentogramEdges, WeightedPercentogramBoundary, fillWeightedPercentogram;
2130+
static if (isIntegral!P)
2131+
{
2132+
assert(probabilities > 0 && probabilities < size_t.max,
2133+
"percentogram: bin count must be positive and leave room for an extra boundary");
2134+
auto levels = allocateCounts!double(allocator, cast(size_t) probabilities + 1);
2135+
scope(exit) allocator.dispose(levels.field);
2136+
foreach (i; 0 .. levels.length) levels[i] = cast(double) i / probabilities;
2137+
return makeWeightedPercentogram!(Counts, algorithm)(allocator, weights, data, levels);
2138+
}
2139+
else
2140+
{
2141+
static if (isSlice!P) scope auto levels = probabilities;
2142+
else scope auto levels = probabilities[].sliced;
2143+
validatePercentogramLevels(levels);
2144+
auto edges = makeWeightedQuantile!(WeightedPercentogramBoundary!Data, algorithm)(
2145+
allocator, weights, data, levels);
2146+
scope(failure) allocator.dispose(edges.field);
2147+
const distinct = preparePercentogramEdges(edges);
2148+
auto axis = variableAxis!(AxisOptions(false, true, true))(edges[0 .. distinct]);
2149+
import mir.stat.descriptive.histogram.accumulator: HistogramAccumulator;
2150+
import mir.stat.descriptive.histogram.relative_frequency: RelativeFrequencyAccumulator;
2151+
auto h = makeHistogram!Counts(allocator, axis);
2152+
scope(failure) releaseCounts(allocator, h.counts);
2153+
static if (is(typeof(h) == HistogramAccumulator!Args, Args...))
2154+
{
2155+
auto f = RelativeFrequencyAccumulator!Args(h.counts, h.axis);
2156+
fillWeightedPercentogram(f, weights, data);
2157+
return AllocatedPercentogram!(typeof(f), typeof(edges), typeof(h.counts))(f, edges, h.counts);
2158+
}
2159+
}
2160+
}
2161+
2162+
/// ditto
2163+
auto makeWeightedPercentogram(Counts = double,
2164+
WeightedQuantileAlgo algorithm = WeightedQuantileAlgo.inverseCDF, Allocator, Weights, Data)(
2165+
ref Allocator allocator, scope auto ref Weights weights, scope auto ref Data data)
2166+
{
2167+
import mir.stat.descriptive.histogram.api.factory: weightedPercentogramBinCount;
2168+
return makeWeightedPercentogram!(Counts, algorithm)(allocator, weights, data,
2169+
weightedPercentogramBinCount(weights));
2170+
}
2171+
2172+
/// Build weighted bins without the GC and release their counts and boundaries together.
2173+
version(mir_stat_test)
2174+
@system pure nothrow @nogc
2175+
unittest
2176+
{
2177+
import std.experimental.allocator.mallocator: Mallocator;
2178+
const int[4] values = [0, 10, 20, 30], weights = [1, 1, 6, 2];
2179+
auto p = makeWeightedPercentogram(Mallocator.instance, weights, values, 2);
2180+
scope(exit) p.dispose(Mallocator.instance);
2181+
assert(p.histogram.bins()[0].bin.high == 20);
2182+
assert(p.histogram.counts == [0.0, 2, 8, 0]);
2183+
assert(p.histogram.relativeFrequency(1) == 0.8);
2184+
}
2185+
2186+
// The full compacted boundary allocation is disposed; every allocation failure cleans up.
2187+
version(mir_stat_test)
2188+
@system pure
2189+
unittest
2190+
{
2191+
import std.exception: assertThrown;
2192+
const int[5] data = [0, 0, 0, 10, 20], weights = [1, 1, 1, 1, 1];
2193+
PercentogramAllocator!() allocator;
2194+
auto p = makeWeightedPercentogram(allocator, weights, data, 4);
2195+
assert(p.histogram.axis.N_bin == 2);
2196+
assert(allocator.allocations == 4 && allocator.releases == 2);
2197+
p.dispose(allocator);
2198+
assert(allocator.releases == 4);
2199+
foreach (failure; 1 .. 5)
2200+
{
2201+
PercentogramAllocator!true failing;
2202+
failing.failAt = failure;
2203+
assertThrown!Exception(makeWeightedPercentogram(failing, weights, data, 4));
2204+
assert(failing.releases == failure - 1);
2205+
}
2206+
}
2207+
2208+
// A lazy observation can throw during validation, copying, or final insertion.
2209+
version(mir_stat_test)
2210+
@system pure
2211+
unittest
2212+
{
2213+
import std.exception: assertThrown;
2214+
import mir.ndslice.slice: sliced;
2215+
import mir.ndslice.topology: map;
2216+
const double[3] values = [0, 10, 20], weights = [1, 2, 1], levels = [0, 0.5, 1];
2217+
foreach (failure; [1, 4, 7])
2218+
{
2219+
PercentogramAllocator!() allocator;
2220+
size_t calls;
2221+
double read(double value)
2222+
{
2223+
if (++calls == failure) throw new Exception("weighted percentogram observation failure");
2224+
return value;
2225+
}
2226+
auto mapped = values[].sliced.map!read;
2227+
assertThrown!Exception(makeWeightedPercentogram(allocator, weights, mapped, levels));
2228+
assert(calls == failure);
2229+
assert(allocator.allocations == (failure == 1 ? 0 : failure == 4 ? 1 : 3));
2230+
assert(allocator.releases == allocator.allocations);
2231+
}
2232+
}
2233+
2234+
// Custom allocator attributes propagate to weighted construction and disposal.
2235+
version(mir_stat_test)
2236+
@safe pure nothrow
2237+
unittest
2238+
{
2239+
SafeAllocator allocator;
2240+
const int[3] values = [0, 10, 20], weights = [1, 1, 1];
2241+
auto p = makeWeightedPercentogram!(double, WeightedQuantileAlgo.type7)(allocator, weights, values);
2242+
assert(p.histogram.total == 3);
2243+
p.dispose(allocator);
2244+
assert(allocator.allocations == allocator.releases);
2245+
}
2246+
2247+
// Custom ownership preserves the common weighted boundary/count semantics.
2248+
version(mir_stat_test)
2249+
@system pure nothrow @nogc
2250+
unittest
2251+
{
2252+
import std.experimental.allocator.mallocator: Mallocator;
2253+
import mir.stat.descriptive.histogram.api.factory: testWeightedPercentograms;
2254+
static auto make(W, D, P...)(scope auto ref W weights, scope auto ref D data, scope auto ref P p)
2255+
{
2256+
return makeWeightedPercentogram(Mallocator.instance, weights, data, p);
2257+
}
2258+
static void release(T)(ref T value) { value.dispose(Mallocator.instance); }
2259+
testWeightedPercentograms!(make, release)();
2260+
}

‎source/mir/stat/descriptive/histogram/api/factory.d‎

Lines changed: 136 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1574,6 +1574,16 @@ package void testPercentogramDuplicates(alias factory)()
15741574
}
15751575

15761576
// Keep statistical rules shared without coupling custom allocation to GC/RC ownership.
1577+
package void validatePercentogramLevels(Levels)(scope Levels levels)
1578+
{
1579+
static assert(Levels.N == 1, "percentogram: probabilities must be one-dimensional");
1580+
assert(levels.length >= 2, "percentogram: at least two probabilities are required");
1581+
assert(levels[0] >= 0 && levels[$ - 1] <= 1,
1582+
"percentogram: probabilities must lie between zero and one");
1583+
foreach (i; 1 .. levels.length)
1584+
assert(levels[i] > levels[i - 1], "percentogram: probabilities must strictly increase");
1585+
}
1586+
15771587
package void validatePercentogramInputs(Observations, Levels)(scope Observations observations, scope Levels levels)
15781588
{
15791589
import std.traits: isIntegral;
@@ -1586,12 +1596,133 @@ package void validatePercentogramInputs(Observations, Levels)(scope Observations
15861596
static if (!isIntegral!(typeof(x)))
15871597
assert(isFinite(x), "percentogram: observations must be finite");
15881598
}
1589-
assert(levels.length >= 2, "percentogram: at least two probabilities are required");
1590-
assert(levels[0] >= 0 && levels[$ - 1] <= 1,
1591-
"percentogram: probabilities must lie between zero and one");
1592-
foreach (i; 1 .. levels.length)
1593-
assert(levels[i] > levels[i - 1], "percentogram: probabilities must strictly increase");
1599+
validatePercentogramLevels(levels);
1600+
}
1601+
1602+
// Preserve floating observation precision; integral quantiles need floating
1603+
// boundaries for widths and the final nextUp endpoint, even for inverseCDF.
1604+
package template WeightedPercentogramBoundary(Data)
1605+
{
1606+
import mir.primitives: DeepElementType;
1607+
import std.traits: Unqual, isFloatingPoint;
1608+
alias Element = Unqual!(DeepElementType!Data);
1609+
static if (isFloatingPoint!Element) alias WeightedPercentogramBoundary = Element;
1610+
else alias WeightedPercentogramBoundary = double;
1611+
}
1612+
1613+
// The automatic-bin heuristic counts positive-weight rows, not their total
1614+
// weight. It is therefore unchanged by rescaling probability weights.
1615+
package size_t weightedPercentogramBinCount(Weights)(scope auto ref Weights weights)
1616+
{
1617+
import mir.ndslice.slice: isSlice, sliced;
1618+
import std.math: isFinite;
1619+
static if (isSlice!Weights) scope auto masses = weights;
1620+
else scope auto masses = weights[].sliced;
1621+
static assert(typeof(masses).N == 1, "percentogram: weights must be one-dimensional");
1622+
size_t n;
1623+
foreach (w; masses)
1624+
{
1625+
assert(isFinite(cast(real) w) && w >= 0, "percentogram: invalid weight");
1626+
if (w > 0) ++n;
1627+
}
1628+
return defaultPercentogramBinCount(n);
1629+
}
1630+
1631+
// Quantile validation has already checked shapes, weights, and positive-weight
1632+
// values. Skip zero weights before reading their possibly nonfinite values.
1633+
package void fillWeightedPercentogram(H, Weights, Data)(ref H histogram,
1634+
scope auto ref Weights weights, scope auto ref Data data)
1635+
{
1636+
import mir.ndslice.slice: isSlice, sliced;
1637+
static if (isSlice!Weights) scope auto masses = weights;
1638+
else scope auto masses = weights[].sliced;
1639+
static if (isSlice!Data) scope auto values = data;
1640+
else scope auto values = data[].sliced;
1641+
alias Boundary = WeightedPercentogramBoundary!Data;
1642+
foreach (i; 0 .. masses.length)
1643+
if (masses[i] > 0)
1644+
histogram.putWeighted(masses[i], cast(Boundary) values[i]);
1645+
}
15941646

1647+
package auto buildWeightedPercentogram(alias allocate, alias quantiles, alias histogram,
1648+
Counts, alias algorithm, Weights, Data, P)(scope auto ref Weights weights,
1649+
scope auto ref Data data, scope auto ref P probabilities)
1650+
{
1651+
import mir.ndslice.slice: isSlice, sliced;
1652+
import mir.stat.descriptive.histogram.axis: variableAxis, AxisOptions;
1653+
import std.traits: isIntegral;
1654+
static if (isIntegral!P)
1655+
{
1656+
assert(probabilities > 0 && probabilities < size_t.max,
1657+
"percentogram: bin count must be positive and leave room for an extra boundary");
1658+
NoAllocationContext context;
1659+
auto levels = allocate!double(context, cast(size_t) probabilities + 1);
1660+
foreach (i; 0 .. levels.length) levels[i] = cast(double) i / probabilities;
1661+
return buildWeightedPercentogram!(allocate, quantiles, histogram, Counts, algorithm)(weights, data, levels);
1662+
}
1663+
else
1664+
{
1665+
static if (isSlice!P) scope auto levels = probabilities;
1666+
else scope auto levels = probabilities[].sliced;
1667+
validatePercentogramLevels(levels);
1668+
auto edges = quantiles!(WeightedPercentogramBoundary!Data, algorithm)(weights, data, levels);
1669+
const distinct = preparePercentogramEdges(edges);
1670+
auto axis = variableAxis!(AxisOptions(false, true, true))(edges[0 .. distinct]);
1671+
auto result = histogram!Counts(axis);
1672+
fillWeightedPercentogram(result, weights, data);
1673+
return result;
1674+
}
1675+
}
1676+
1677+
// Exercise the same weighted distribution across all allocation policies.
1678+
version(mir_stat_test)
1679+
package void testWeightedPercentograms(alias factory, alias release = null)()
1680+
{
1681+
import mir.ndslice.slice: sliced;
1682+
import mir.ndslice.topology: stride;
1683+
import mir.stat.descriptive.histogram.relative_frequency: Normalization;
1684+
import std.math: nextUp;
1685+
static ref auto histogramOf(T)(return ref T value)
1686+
{
1687+
static if (__traits(hasMember, T, "histogram")) return value.histogram;
1688+
else return value;
1689+
}
1690+
// A zero-weight nonfinite value neither affects boundaries nor gets indexed.
1691+
const double[5] data = [double.nan, 0, 10, 20, 30];
1692+
const double[5] weights = [0, 1, 1, 6, 2], scaled = [0, 2, 2, 12, 4];
1693+
const double[3] levels = [0, 0.5, 1];
1694+
auto result = factory(weights, data, levels);
1695+
scope(exit) { static if (!is(typeof(release) == typeof(null))) release(result); }
1696+
auto p = histogramOf(result);
1697+
assert(p.counts == [0.0, 2, 8, 0] && p.total == 10);
1698+
assert(p.bins()[0].bin.high == 20 && p.bins()[1].bin.high == nextUp(30.0));
1699+
assert(p.density(0) * 20 == 0.2);
1700+
auto rescaled = factory(scaled, data, 2);
1701+
scope(exit) { static if (!is(typeof(release) == typeof(null))) release(rescaled); }
1702+
assert(histogramOf(rescaled).bins()[0].bin.high == 20);
1703+
assert(histogramOf(rescaled).relativeFrequency(1) == p.relativeFrequency(1));
1704+
auto automatic = factory(weights, data);
1705+
scope(exit) { static if (!is(typeof(release) == typeof(null))) release(automatic); }
1706+
assert(histogramOf(automatic).counts == p.counts);
1707+
// Restrict the quantile interval: both tails retain their weights.
1708+
const int[5] x = [0, 1, 2, 3, 4], w = [1, 1, 1, 1, 1];
1709+
const double[3] middle = [0.25, 0.5, 0.75];
1710+
auto trimmed = factory(w, x, middle);
1711+
scope(exit) { static if (!is(typeof(release) == typeof(null))) release(trimmed); }
1712+
auto t = histogramOf(trimmed);
1713+
assert(t.counts == [1.0, 1, 2, 1]);
1714+
assert(t.relativeFrequency!(double, Normalization.ordinary)(1) == 2.0 / 3);
1715+
// Ties compact boundaries while preserving all weighted observations.
1716+
const int[5] tied = [0, 0, 0, 10, 20];
1717+
auto compact = factory(w, tied, 4);
1718+
scope(exit) { static if (!is(typeof(release) == typeof(null))) release(compact); }
1719+
assert(histogramOf(compact).axis.N_bin == 2);
1720+
assert(histogramOf(compact).counts == [0.0, 3, 2, 0]);
1721+
const double[8] backing = [0, -1, 10, -1, 20, -1, 30, -1];
1722+
const double[8] massBacking = [1, -1, 1, -1, 6, -1, 2, -1];
1723+
auto strided = factory(massBacking[].sliced.stride(2), backing[].sliced.stride(2), levels[].sliced);
1724+
scope(exit) { static if (!is(typeof(release) == typeof(null))) release(strided); }
1725+
assert(histogramOf(strided).counts == p.counts);
15951726
}
15961727

15971728
// Compact in place but retain the complete allocation handle for manual cleanup.

0 commit comments

Comments
 (0)