carray 3.0.2 → 3.0.3

data/lib/carray/categorical_iterator.rb

@@ -35,8 +35,8 @@
 #      max / min                    -> value data type, empty/all-masked = MASKED
 #      mean                         -> float64,     empty/all-masked = MASKED
 #      median / percentile          -> float64,     empty/all-masked = MASKED
-#      variance / stddev (sample, ddof=1) -> float64, empty/all-masked = MASKED,
-#                                                   single value = 0.0 (n=1 contract)
+#      variance / stddev (sample, ddof=1) -> float64, fewer than two present
+#                                                   values = MASKED
 #      all / any                    -> boolean (boolean value data type only)
 #      labels                       -> cat.labels
 #
@@ -60,17 +60,17 @@
 # ----------------------------------------------------------------------------
 
 require "carray"
-
-# A CAIterator over the categories of a CACategorical.  CAIterator is the
-# family base (the built-in iterators like CAWindowIterator / CABlockIterator
-# are defined in C); a Ruby `Foo < CAIterator` supplies its own behaviour and
-# does not lean on the base machinery.  Like CASlabIterator, this class defines
-# its own `each` (over the k categories, yielding each category's member slice),
-# which drives the inherited Enumerable surface; the reduction methods (sum /
-# mean / median / ...) aggregate the groups into length-k arrays.  The kernels
-# are per-category slices of an eager, category-contiguous grouped copy.  This
-# supersedes the older CAClassIterator.
-class CACategoricalIterator < CAIterator
+require "carray/segment_iterator"
+
+# A CAIterator over the categories of a CACategorical.  It is a
+# CASegmentIterator over a category-sorted copy of the value: construction
+# gathers the value through the categorical's cached grouping plan, so each
+# category is one contiguous segment, and every reduction without `axis:` is
+# the segment reduction over that copy (one value per category, in {#labels}
+# order).  This class adds the construction, the labels, and the per-fiber
+# form (`axis:`), which classifies each fiber along an axis and keeps the
+# other axes.
+class CACategoricalIterator < CASegmentIterator
 
   # value : the payload CArray to reduce, one cell per categorical cell.
   # cat   : the CACategorical carrying the classification.
@@ -105,6 +105,7 @@ class CACategoricalIterator < CAIterator
       @elements = cat.category_sizes.int64
       nvalid    = counts.sum
       @offsets  = cat.reduceat_index                # cached segment STARTS (int64[k])
+      @bounds   = CArray.segment_offsets(lengths: @elements)  # every boundary (int64[k+1])
       # Group-major source indices = the valid prefix of the cached sort_addr.
       # With no classified cell the prefix is empty (and slicing a length-0
       # sort_addr would be out of range), so take the empty permutation directly.
@@ -118,8 +119,8 @@ class CACategoricalIterator < CAIterator
       # is nothing to gather — an empty index into an empty source is out of
       # range — so build the empty grouped buffer directly.
       @grouped  = nvalid > 0 ? value.reshape(value.elements)[@perm].copy
-                             : CArray.new(value.data_type, [0])
-      @empty    = CArray.new(grouped.data_type, [0])
+                             : CArray.new(value.data_type, [0], bytes: value.bytes)
+      @empty    = CArray.new(grouped.data_type, [0], bytes: grouped.bytes)
     else
       # Shape mismatch: only per-fiber axis: dispatch could still work.  With a
       # 1-D value there is no fiber structure to broadcast into, so a mismatch
@@ -147,20 +148,6 @@ class CACategoricalIterator < CAIterator
     self
   end
 
-  # @overload each { |members| ... }
-  #   Yields each category's members (a CArray slice of the grouped copy, in
-  #   {#labels} order; an empty category yields an empty array).  Without a
-  #   block, returns an Enumerator.  This is the own iteration that drives the
-  #   inherited Enumerable methods (map / count / to_a / ...); it does not use
-  #   the CAIterator base each / kernel_at_addr path.
-  #   @yieldparam members [CArray]
-  #   @return [Enumerator, self]
-  def each
-    return to_enum(:each) unless block_given?
-    @k.times { |c| yield group_slice(c) }
-    self
-  end
-
   # @overload labels
   #   Returns the category vocabulary the results are aligned to.
   #   @return [Array]
@@ -174,21 +161,6 @@ class CACategoricalIterator < CAIterator
     @k
   end
 
-  # @overload elements
-  #   Returns per-group cell counts (classified cells, including value-masked
-  #   ones; = `cat.category_sizes`), a length-ngroups CArray aligned to
-  #   {#labels}. The CAIterator count-family member — `CArray#elements`
-  #   (structural, mask-independent) lifted per group.
-  #   @return [CArray]
-  def elements
-    # A copy, like every other member that reads off a memo: the memo is the
-    # iterator's own state, and handing out the array itself lets a caller
-    # write into it and change what the iterator answers from then on. This
-    # one invites it -- the docs point at its prefix sum for splitting a
-    # column apart, which reads as scratch.
-    counts.copy
-  end
-
   # Group-vocabulary alias for {#elements}; reads naturally next to
   # {#ngroups} and mirrors `CACategorical#category_sizes`.
   alias group_sizes elements
@@ -207,543 +179,144 @@ class CACategoricalIterator < CAIterator
     "#<#{self.class} ngroups=#{@k} labels=#{@labels.inspect} #{tail}>"
   end
 
-  # @overload count_not_masked
-  #   Returns the per-category count of present (non-masked) values as int64
-  #   — the denominator the value reductions actually divide by.  Equals
-  #   {#elements} unless the value carries a mask.  A count is always defined,
-  #   so an empty category is `0` (never masked).
-  #   @return [CArray]
-  # @overload count_not_masked(axis:)
-  #   Per-fiber per-category count of present (non-masked) values along `axis`
-  #   (int64, shape [K, ...band]).  Empty cells are `0`.
-  #   @param axis [Integer]
-  #   @return [CArray]
-  def count_not_masked(axis: nil)
-    return axis_counts(axis) if axis
-    m = moments
-    m ? m[:count].copy : per_category(CA_INT64) { |s| s.count_not_masked }
-  end
-
-  # @overload count(v = <none>)
-  #   Per-category count, mirroring `CArray#count` per group. No argument
-  #   returns {#count_not_masked} (present cells); `count(UNDEF)` returns
-  #   {#count_masked}; `count(v)` counts cells whose value equals `v`.
-  #   @return [CArray] length-k int64, aligned to {#labels}
-  # @overload count(axis:)
-  #   No-arg + axis: = per-fiber per-category count_not_masked (shape [K, ...band]).
-  #   `count(v, axis:)` (value equality) and `count(UNDEF, axis:)` are not
-  #   implemented; use them without `axis:`.
-  #   @param axis [Integer]
-  #   @return [CArray]
-  def count (*args, axis: nil)
-    if axis
-      return count_not_masked(axis: axis) if args.empty?
-      raise NotImplementedError,
-            "CACategoricalIterator#count(v, axis:) is not implemented — " \
-            "value-equality count is available without axis:."
-    end
-    return count_not_masked if args.empty?
-    # Delegate per group to CArray#count (handles count(UNDEF) -> masked count and
-    # count(v) alike, with core's exact data type equality). The group slice is a
-    # CABlock, whose own #count is the block geometry accessor, so dispatch
-    # CArray#count explicitly. (Not fused: a value-equality reduceat would have
-    # to reproduce core's cross-type / out-of-range equality exactly.)
-    cnt = CArray.instance_method(:count)
-    per_category(CA_INT64) { |s| cnt.bind_call(s, *args) }
-  end
-
-  # @overload count_masked
-  #   Returns the per-category count of masked (missing) values as int64.
-  #   Empty categories are `0`.
-  #   @return [CArray]
-  # @overload count_masked(axis:)
-  #   Not implemented; call it without `axis:`.
-  #   @param axis [Integer]
-  #   @return [CArray]
-  def count_masked(axis: nil)
-    if axis
-      raise NotImplementedError,
-            "CACategoricalIterator#count_masked(axis:) is not implemented — " \
-            "call it without axis:."
-    end
-    m = moments
-    m ? counts - m[:count] : per_category(CA_INT64) { |s| s.count_masked }
-  end
-
-  # @overload sum
-  #   Returns per-category sums in the data type `CArray#sum` promotes the value
-  #   to (float64 for an integer value).  `accumulate` is the same fold kept in
-  #   the value's own type.  An empty or fully-masked category sums the empty
-  #   set, which is the additive identity `0` (unmasked) — the same contract as
-  #   `CArray#sum` on an empty / all-masked array.
-  #   @return [CArray]
-  # @overload sum(axis:)
-  #   Returns per-category sums per fiber along `axis`.  Cat may be 1-D (case
-  #   A, broadcasts across band axes), same rank as source (case B, per-fiber
-  #   independent classifier), or one rank less (band-only, constant along
-  #   reduce axis).  Output shape = `[K, ...source.shape without axis]`.
-  #   @param axis [Integer] reduce axis of the source value.
-  #   @return [CArray]
-  def sum(axis: nil)
-    return axis_sum(axis) if axis
-    m = moments
-    return per_category(core_reduce_type(:sum)) { |s| s.sum } unless m
-    m[:sum].copy                    # the moments sum IS the core fold (empty -> 0.0)
-  end
-
-  # @overload accumulate
-  #   Returns per-category sums folded in the value's own data type, wrapping at
-  #   its width, as the core `accumulate` does.  This is the exact in-type fold:
-  #   `sum` reads its answer off a float64 moment and casts back, so it loses
-  #   the low bits of a wide integer payload and does not wrap.  An empty or
-  #   fully-masked category accumulates the empty set, the additive identity `0`
-  #   (unmasked).
-  #   @return [CArray]
-  # @overload accumulate(axis:)
-  #   Per-fiber per-category in-type sums along `axis`.  Output shape =
-  #   `[K, ...source.shape without axis]`.
-  #   @param axis [Integer] reduce axis of the source value.
-  #   @return [CArray]
-  def accumulate(axis: nil)
-    return axis_by_masked_copy(axis, :accumulate, core_reduce_type(:accumulate)) if axis
-    per_category(core_reduce_type(:accumulate)) { |s| s.accumulate }
-  end
-
-  # @overload max
-  #   Returns per-category maxima in the value data type.  Empty categories are
-  #   MASKED.
-  #   @return [CArray]
-  # @overload max(axis:)
-  #   Per-fiber per-category maxima along `axis` (h's data type, masked where empty).
-  #   @param axis [Integer]
-  #   @return [CArray]
-  def max(axis: nil)
-    return axis_moments(axis)[:max] if axis
-    m = moments
-    m ? m[:max].copy : per_category(core_reduce_type(:max)) { |s| s.max }
-  end
-
-  # @overload min
-  #   Returns per-category minima in the value data type.  Empty categories are
-  #   MASKED.
-  #   @return [CArray]
-  # @overload min(axis:)
-  #   Per-fiber per-category minima along `axis` (h's data type, masked where empty).
-  #   @param axis [Integer]
-  #   @return [CArray]
-  def min(axis: nil)
-    return axis_moments(axis)[:min] if axis
-    m = moments
-    m ? m[:min].copy : per_category(core_reduce_type(:min)) { |s| s.min }
-  end
-
-  # @overload mean
-  #   Returns per-category means as float64.  Empty categories are MASKED.
-  #   @return [CArray]
-  # @overload mean(axis:)
-  #   Per-fiber per-category means (float64, empty group cells MASKED).
-  #   @param axis [Integer]
-  #   @return [CArray]
-  def mean(axis: nil)
-    return axis_mean(axis) if axis
-    m = moments
-    return per_category(core_reduce_type(:mean)) { |s| s.mean } unless m
-    cnt = m[:count]
-    out = m[:sum] / cnt.float64      # count 0 -> NaN, masked next
-    out[cnt.eq(0)] = UNDEF           # empty / all-masked category -> MASKED
-    out
-  end
-
-  # @overload median
-  #   Returns per-category medians as float64.  Empty categories are MASKED.
-  #   @return [CArray]
-  def median(axis: nil)
-    axis_order_stat_defer!(:median) if axis
-    percentile(50.0)
-  end
-
-  # @overload percentile(p)
-  #   Returns the per-category `p`-th percentile as float64 (`p` in 0..100,
-  #   `:linear` interpolation, matching `CArray#percentile`).  Empty categories
-  #   are MASKED.  Order statistics need every value of a group held together —
-  #   this is the reduceat that only the eager grouped copy can serve.
-  #   @param p [Numeric] percentile in 0..100.
-  #   @return [CArray]
-  def percentile (p, axis: nil)
-    axis_order_stat_defer!(:percentile) if axis
-    unless MONOID_TYPES.include?(grouped.data_type)
-      return per_category(core_reduce_type(:percentile, p)) { |s| s.percentile(p) }
-    end
-    out = CArray.float64(@k)
-    grouped.send(:__reduceat_percentile__, @offsets, p.to_f, out)
-    out
-  end
-
-  # @overload quantile
-  #   Returns the per-category five-number summary `[min, Q1, median, Q3, max]`
-  #   as five length-k float64 CArrays (matching `CArray#quantile`): the
-  #   percentiles at 0 / 25 / 50 / 75 / 100. Empty / all-masked categories are
-  #   MASKED. For a single fraction q in 0..1 use `percentile(q * 100)`.
-  #   @return [Array<CArray>]
-  def quantile
-    unless MONOID_TYPES.include?(grouped.data_type)
-      return [0, 25, 50, 75, 100].map { |p| percentile(p) }
-    end
-    outs = Array.new(5) { CArray.float64(@k) }
-    grouped.send(:__reduceat_quantile__, @offsets, *outs)
-    outs
-  end
-
-  # @overload variance
-  #   Returns per-category SAMPLE variance (ddof=1) as float64.  Matches
-  #   `CArray#variance` per group: an empty or fully-masked category is MASKED,
-  #   a single-value category is `0.0` (CArray's n=1 contract), n>=2 is the
-  #   sample variance.
-  #   @return [CArray]
-  def variance(axis: nil)
-    return axis_by_masked_copy(axis, :variance) if axis
-    m = moments
-    return per_category(core_reduce_type(:variance)) { |s| s.variance } unless m
-    cnt   = m[:count]
-    means = m[:sum] / cnt.float64    # per-segment mean (garbage where count 0/1,
-    out   = CArray.float64(@k)       #   ignored by the kernel's n<2 guards)
-    grouped.send(:__reduceat_variance__, @offsets, means, cnt, out)
-    out
-  end
-
-  # @overload stddev
-  #   Returns per-category SAMPLE standard deviation (ddof=1) as float64.
-  #   Matches `CArray#stddev` per group (empty / all-masked MASKED,
-  #   single-value `0.0`).
-  #   @return [CArray]
-  def stddev(axis: nil)
-    return axis_by_masked_copy(axis, :stddev) if axis
-    m = moments
-    return per_category(core_reduce_type(:stddev)) { |s| s.stddev } unless m
-    variance.sqrt                    # sqrt propagates the n=0 mask
-  end
-
-  # @overload prod
-  #   Returns per-category products as float64 (matching `CArray#prod`). An
-  #   empty / fully-masked category is `1.0` (the multiplicative identity).
-  #   Single-pass reduceat for numeric values; per-group fallback otherwise.
-  #   @return [CArray]
-  # @overload prod(axis:)
-  #   Per-fiber per-category products (float64, shape [K, ...band]).  Empty
-  #   group cells `1.0` (identity).
-  #   @param axis [Integer]
-  #   @return [CArray]
-  def prod(axis: nil)
-    return axis_prod(axis) if axis
-    return per_category(core_reduce_type(:prod)) { |s| s.prod } unless MONOID_TYPES.include?(grouped.data_type)
-    out = CArray.float64(@k)
-    grouped.send(:__reduceat_prod__, @offsets, out)
-    out
-  end
-
-  # @overload all
-  #   Returns the per-category `all` as boolean (matching `CArray#all`): true
-  #   iff every present value is truthy (empty category -> true, vacuously).
-  #   The value data type must be boolean, as for `CArray#all`.
-  #   @return [CArray]
-  def all
-    aa = all_any
-    aa ? aa[:all] : per_category(CA_BOOLEAN) { |s| s.all }
-  end
-
-  # @overload any
-  #   Returns the per-category `any` as boolean (matching `CArray#any`): true
-  #   iff some present value is truthy (empty category -> false). The value
-  #   data type must be boolean, as for `CArray#any`.
-  #   @return [CArray]
-  def any
-    aa = all_any
-    aa ? aa[:any] : per_category(CA_BOOLEAN) { |s| s.any }
-  end
-
-  # ---- tier 2 (fused / population / position) ------------------------------
-
-  # @overload minmax
-  #   Returns the per-category `[min, max]` pair (each a length-k CArray in the
-  #   value data type; empty categories MASKED), matching `CArray#minmax`. Both come
-  #   from one moments pass.
-  #   @return [Array<CArray>]
-  # @overload minmax(axis:)
-  #   Per-fiber `[min_ca, max_ca]` along `axis` (each shape [K, ...band], h's data type,
-  #   empty group cells MASKED).  Ruby Array of two CArrays, not stacked.
-  #   Both come from one kernel run.
-  #   @param axis [Integer]
-  #   @return [Array<CArray>]
-  def minmax(axis: nil)
-    if axis
-      # take both off one pass rather than asking min and max separately,
-      # which would run the kernel twice now that nothing is kept between
-      # calls -- this is the "keep the result" the axis: family expects
-      m = axis_moments(axis)
-      return [m[:min], m[:max]]
-    end
-    [min, max]
-  end
-
-  # @overload variancep
-  #   Per-category POPULATION variance (ddof=0) as float64, matching
-  #   `CArray#variancep`: empty / all-masked -> MASKED, single value -> 0.0.
-  #   Derived from the sample variance (variancep = variance * (n-1) / n), so it
-  #   reuses the centred two-pass kernel with no extra walk.
-  #   @return [CArray]
-  def variancep(axis: nil)
-    return axis_by_masked_copy(axis, :variancep) if axis
-    m = moments
-    return per_category(core_reduce_type(:variancep)) { |s| s.variancep } unless m
-    cnt = m[:count]
-    vp  = variance * (cnt - 1).float64 / cnt.float64
-    vp[cnt.eq(0)] = UNDEF                 # empty / all-masked stays masked
-    vp
-  end
-
-  # @overload stddevp
-  #   Per-category POPULATION standard deviation (ddof=0) as float64.
-  #   @return [CArray]
-  # @overload stddevp(axis:)
-  #   Per-fiber per-category population stddev (float64, empty group cells MASKED).
-  #   @param axis [Integer]
-  #   @return [CArray]
-  def stddevp(axis: nil)
-    return axis_by_masked_copy(axis, :stddevp) if axis
-    m = moments
-    return per_category(core_reduce_type(:stddevp)) { |s| s.stddevp } unless m
-    variancep.sqrt
-  end
-
-  # @overload min_index
-  #   Per-category group-local index of the minimum — the position within the
-  #   category's members (source order) — matching `CArray#min_index` per group.
-  #   Empty / all-masked categories are MASKED. Single-pass fused reduceat for
-  #   numeric values; per-group fallback otherwise.
-  #   @return [CArray] length-k int64
-  def min_index
-    am = arg_minmax
-    am ? am[:min].copy : per_category(CA_INT64) { |s| s.min_index }
-  end
-
-  # @overload max_index
-  #   Per-category group-local index of the maximum. See {#min_index}.
-  #   @return [CArray] length-k int64
-  def max_index
-    am = arg_minmax
-    am ? am[:max].copy : per_category(CA_INT64) { |s| s.max_index }
-  end
-
-  # @overload min_addr
-  #   Per-category flat source address of the minimum — which cell of the source
-  #   value holds it, matching `CArray#min_addr` per group. Unlike {#min_index}
-  #   (the group-local rank) this indexes back into the original array
-  #   (`value.reshape(value.elements)[grp.min_addr]`). Empty categories MASKED.
-  #   @return [CArray] length-k int64
-  def min_addr
-    group_addr(min_index)
-  end
-
-  # @overload max_addr
-  #   Per-category flat source address of the maximum. See {#min_addr}.
-  #   @return [CArray] length-k int64
-  def max_addr
-    group_addr(max_index)
-  end
-
-  # @overload sort_addr
-  #   Per-category sort by flat source address. Returns a length-nvalid
-  #   (= `elements.sum`) int64 CArray of the flat SOURCE addresses that sort each
-  #   category's members, in group-major order: segment `c` holds category `c`'s
-  #   source addresses in ascending-value order, segments concatenated in
-  #   {#labels} order. So `value.reshape(value.elements)[grp.sort_addr]` yields
-  #   the values grouped and sorted within each group, and splitting by the
-  #   {#elements} prefix sum gives per-group. Excluded cells (in no category) are
-  #   omitted. A masked value sorts to the tail of its segment (as `CArray#sort`
-  #   sends masked cells to the end), so with a mask the first address is the
-  #   minimum but the last is the masked cell, not the maximum.
+  # ---- the per-fiber form ---------------------------------------------------
   #
-  #   Unlike {#min_index} / {#max_index} (group-local rank), this indexes back
-  #   into the original array. There is no group-local sort surface: a
-  #   group-local rank order is weak (the grouped copy is already
-  #   category-contiguous), so only the source-address form is offered, mirroring
-  #   {#min_addr} vs the skipped group-local min_index-into-source.
-  #   @return [CArray] length-nvalid int64
-  def sort_addr
-    out = CArray.int64(grouped.elements)
-    @k.times do |c|
-      lo = @offsets[c]
-      hi = (c + 1 < @k) ? @offsets[c + 1] : grouped.elements
-      next unless hi > lo
-      # View-local sort order of the segment (0..size-1), lifted to grouped
-      # slots, then mapped back to source addresses via perm.
-      out[lo...hi] = perm[grouped[lo...hi].sort_addr + lo]
-    end
-    out
-  end
-
-  # @overload wsum(weights)
-  #   Per-category weighted sum as float64, matching `CArray#wsum`. `weights` is
-  #   a per-cell weight CArray in the source order (same elements as the value).
-  #   Empty / all-masked category -> 0.0 (the additive identity). A cell is
-  #   skipped iff its value OR its weight is masked (core's contract).
-  #   @param weights [CArray]
-  #   @return [CArray]
-  # @overload wsum(weights, axis:)
-  #   Per-fiber per-category weighted sum along `axis`.  `weights` must have
-  #   shape == source.shape (rev3 requires explicit broadcast; wrap 1-D or
-  #   band-shape weights via `.broadcast_to(*source.shape)` at the call site).
-  #   Empty group cell → `0.0` (identity).  Mask contract: cell contributes iff
-  #   value AND weight are present.
-  #   @param weights [CArray]
-  #   @param axis [Integer]
-  #   @return [CArray]
-  def wsum (weights, axis: nil)
-    return axis_wsum_wmean(weights, axis)[0] if axis
-    wg = scatter_weights(weights)
-    return kernel_weighted(wg)[0] if MONOID_TYPES.include?(grouped.data_type)
-    fold_weighted(wg, 0.0) { |v, ws| v.wsum(ws) }
-  end
-
-  # @overload wmean(weights)
-  #   Per-category weighted mean as float64, matching `CArray#wmean`. Empty
-  #   category -> MASKED; a present category whose weights sum to zero -> NaN
-  #   (core's 0/0 contract).
-  #   @param weights [CArray]
-  #   @return [CArray]
-  # @overload wmean(weights, axis:)
-  #   Per-fiber per-category weighted mean along `axis`.  Same weights-shape
-  #   contract as {#wsum} (weights.shape == source.shape).  Empty cell → MASKED;
-  #   a present cell whose weights sum to zero → NaN (0/0 core contract).
-  #   @param weights [CArray]
-  #   @param axis [Integer]
-  #   @return [CArray]
-  def wmean (weights, axis: nil)
-    return axis_wsum_wmean(weights, axis)[1] if axis
-    wg = scatter_weights(weights)
-    return kernel_weighted(wg)[1] if MONOID_TYPES.include?(grouped.data_type)
-    fold_weighted(wg, UNDEF) { |v, ws| v.wmean(ws) }
-  end
-
-  # @overload reduce { |members| ... }
-  #   Custom per-category reduction (the escape hatch for statistics not in the
-  #   named surface), mirroring `CArray#reduce_slab`. The block receives each
-  #   category's members (a CArray) and returns one value per category.
-  #   @yieldparam members [CArray]
-  #   @return [CArray] length-k, aligned to {#labels}
-  # @overload reduce(init) { |acc, elem| ... }
-  #   Per-category fiber fold: each category's members are folded element by
-  #   element starting from `init`.
-  #   @param init [Object] initial accumulator.
-  #   @return [CArray] length-k
-  def reduce (*args, data_type: nil, &blk)
-    raise LocalJumpError, "no block given (yield)" unless blk
-    dt = data_type || CA_OBJECT
-    if args.empty?
-      per_category(dt) { |s| blk.call(s) }
-    else
-      init = args[0]
-      per_category(dt) { |s|
-        acc = init
-        s.each { |e| acc = blk.call(acc, e) }
-        acc
-      }
-    end
-  end
-
-  # @overload map(data_type: nil) { |members| ... }
-  #   Group-wise element-wise transform, mirroring `CArray#map_slab`. The block
-  #   receives each category's members and returns either a same-length CArray
-  #   (scattered back cell for cell) or a scalar (broadcast over the group's
-  #   cells). Returns a NEW CArray shaped like the source `value`; the original
-  #   is not modified (`value[] = grp.map { ... }` for in-place). Excluded cells
-  #   (in no category) are UNDEF in the result.
-  #   @yieldparam members [CArray]
-  #   @return [CArray] shaped like the source value
-  def map (data_type: nil)
-    raise LocalJumpError, "no block given (yield)" unless block_given?
-    dt = data_type || grouped.data_type
-    # Apply the block per category, assembled in grouped (category-contiguous)
-    # order: a same-length result scatters cell for cell, a scalar broadcasts.
-    transformed = CArray.new(dt, [grouped.elements])
-    @k.times do |c|
-      lo = @offsets[c]
-      hi = (c + 1 < @k) ? @offsets[c + 1] : grouped.elements
-      transformed[lo...hi] = yield(grouped[lo...hi]) if hi > lo
-    end
-    # Scatter back to source positions via the permutation (grouped-order source
-    # indices). Excluded cells are absent from perm and stay UNDEF.
-    out = CArray.new(dt, @src_shape)
-    out[] = UNDEF
-    out.reshape(@codes.elements)[perm] = transformed
-    out
-  end
-
-  # ---- segment scan: within-category running statistics ------------------
+  # These reductions also take `axis:` on a categorical.  Without it each is
+  # the CASegmentIterator reduction of the same name, over the category-sorted
+  # copy: one value per category, in {#labels} order.
   #
-  # The per-element-emit siblings of the reductions: unlike a reduction (which
-  # collapses each category to one value) a scan preserves the source shape,
-  # each cell holding its category's running statistic up to and including that
-  # cell, in source (row-major) order.  A category is a partition (each cell is
-  # in exactly one category), so the running value is single-valued.  The flat
-  # categorical grouping is the one-band case of the axis-group scan, so each
-  # routes straight through the fused C kernel __axis_group_scan__ (the same one
-  # CAGroupIterator drives) with the whole source as a single grouped axis and
-  # the categorical's codes as the single bundle -- which yields SOURCE-ORDER
-  # output directly, so no counting-sort inverse permutation is needed.
-  # Excluded (out-of-vocabulary / masked-code) and source-masked cells join no
-  # running total and are UNDEF.  Mirroring the reductions (sum / mean), a scan
-  # takes no axis argument.  cumsum / cumprod -> float64, cummax / cummin
-  # preserve the value data type, cumcount -> int64 (1-based within-category
-  # ordinal); an object value data type is carried by the kernel's object branch.
-
-  # @!method cumsum
-  #   Per-category inclusive running sum (float64), source-shaped.
-  #   @return [CArray]
-  # @!method cumprod
-  #   Per-category inclusive running product (float64), source-shaped.
-  #   @return [CArray]
-  # @!method cummax
-  #   Per-category inclusive running maximum (value data type), source-shaped.
-  #   @return [CArray]
-  # @!method cummin
-  #   Per-category inclusive running minimum (value data type), source-shaped.
-  #   @return [CArray]
-  # @!method cumcount
-  #   Per-category 1-based within-category ordinal (int64), source-shaped.
-  #   @return [CArray]
-  [:cumsum, :cumprod, :cummax, :cummin, :cumcount].each do |op|
-    define_method(op) { scan(op) }
-  end
+  # @!method accumulate(axis: nil)
+  #   @overload accumulate
+  #     The per-category form: {CASegmentIterator#accumulate}, one value per category.
+  #   @overload accumulate(axis:)
+  #     Per-fiber per-category in-type sums along `axis`.  Output shape =
+  #     `[K, ...source.shape without axis]`.
+  #     @param axis [Integer] reduce axis of the source value.
+  #     @return [CArray]
+  # @!method count(*args, axis: nil)
+  #   @overload count
+  #     The per-category form: {CASegmentIterator#count}, one value per category.
+  #   @overload count(axis:)
+  #     No-arg + axis: = per-fiber per-category count_not_masked (shape [K, ...band]).
+  #     `count(v, axis:)` (value equality) and `count(UNDEF, axis:)` are not
+  #     implemented; use them without `axis:`.
+  #     @param axis [Integer]
+  #     @return [CArray]
+  # @!method count_masked(axis: nil)
+  #   @overload count_masked
+  #     The per-category form: {CASegmentIterator#count_masked}, one value per category.
+  #   @overload count_masked(axis:)
+  #     Not implemented; call it without `axis:`.
+  #     @param axis [Integer]
+  #     @return [CArray]
+  # @!method count_not_masked(axis: nil)
+  #   @overload count_not_masked
+  #     The per-category form: {CASegmentIterator#count_not_masked}, one value per category.
+  #   @overload count_not_masked(axis:)
+  #     Per-fiber per-category count of present (non-masked) values along `axis`
+  #     (int64, shape [K, ...band]).  Empty cells are `0`.
+  #     @param axis [Integer]
+  #     @return [CArray]
+  # @!method max(axis: nil)
+  #   @overload max
+  #     The per-category form: {CASegmentIterator#max}, one value per category.
+  #   @overload max(axis:)
+  #     Per-fiber per-category maxima along `axis` (h's data type, masked where empty).
+  #     @param axis [Integer]
+  #     @return [CArray]
+  # @!method mean(axis: nil)
+  #   @overload mean
+  #     The per-category form: {CASegmentIterator#mean}, one value per category.
+  #   @overload mean(axis:)
+  #     Per-fiber per-category means (float64, empty group cells MASKED).
+  #     @param axis [Integer]
+  #     @return [CArray]
+  # @!method min(axis: nil)
+  #   @overload min
+  #     The per-category form: {CASegmentIterator#min}, one value per category.
+  #   @overload min(axis:)
+  #     Per-fiber per-category minima along `axis` (h's data type, masked where empty).
+  #     @param axis [Integer]
+  #     @return [CArray]
+  # @!method minmax(axis: nil)
+  #   @overload minmax
+  #     The per-category form: {CASegmentIterator#minmax}, one value per category.
+  #   @overload minmax(axis:)
+  #     Per-fiber `[min_ca, max_ca]` along `axis` (each shape [K, ...band], h's data type,
+  #     empty group cells MASKED).  Ruby Array of two CArrays, not stacked.
+  #     Both come from one kernel run.
+  #     @param axis [Integer]
+  #     @return [Array<CArray>]
+  # @!method prod(axis: nil)
+  #   @overload prod
+  #     The per-category form: {CASegmentIterator#prod}, one value per category.
+  #   @overload prod(axis:)
+  #     Per-fiber per-category products (float64, shape [K, ...band]).  Empty
+  #     group cells `1.0` (identity).
+  #     @param axis [Integer]
+  #     @return [CArray]
+  # @!method stddevp(axis: nil)
+  #   @overload stddevp
+  #     The per-category form: {CASegmentIterator#stddevp}, one value per category.
+  #   @overload stddevp(axis:)
+  #     Per-fiber per-category population stddev (float64, empty group cells MASKED).
+  #     @param axis [Integer]
+  #     @return [CArray]
+  # @!method sum(axis: nil)
+  #   @overload sum
+  #     The per-category form: {CASegmentIterator#sum}, one value per category.
+  #   @overload sum(axis:)
+  #     Returns per-category sums per fiber along `axis`.  Cat may be 1-D (case
+  #     A, broadcasts across band axes), same rank as source (case B, per-fiber
+  #     independent classifier), or one rank less (band-only, constant along
+  #     reduce axis).  Output shape = `[K, ...source.shape without axis]`.
+  #     @param axis [Integer] reduce axis of the source value.
+  #     @return [CArray]
+  # @!method wmean(weights, axis: nil)
+  #   @overload wmean
+  #     The per-category form: {CASegmentIterator#wmean}, one value per category.
+  #   @overload wmean(weights, axis:)
+  #     Per-fiber per-category weighted mean along `axis`.  Same weights-shape
+  #     contract as {#wsum} (weights.shape == source.shape).  Empty cell → MASKED;
+  #     a present cell whose weights sum to zero → NaN (0/0 core contract).
+  #     @param weights [CArray]
+  #     @param axis [Integer]
+  #     @return [CArray]
+  # @!method wsum(weights, axis: nil)
+  #   @overload wsum
+  #     The per-category form: {CASegmentIterator#wsum}, one value per category.
+  #   @overload wsum(weights, axis:)
+  #     Per-fiber per-category weighted sum along `axis`.  `weights` must have
+  #     shape == source.shape (rev3 requires explicit broadcast; wrap 1-D or
+  #     band-shape weights via `.broadcast_to(*source.shape)` at the call site).
+  #     Empty group cell → `0.0` (identity).  Mask contract: cell contributes iff
+  #     value AND weight are present.
+  #     @param weights [CArray]
+  #     @param axis [Integer]
+  #     @return [CArray]
 
   private
 
-  # The category-major copy every no-axis reduction works from. It does not
-  # exist when the classifier does not line up cell-for-cell with the value;
-  # such an iterator answers the per-fiber form only, and says so here rather
-  # than letting a nil surface as whatever NoMethodError it reaches first.
-  def grouped
-    @grouped || raise(ArgumentError, @no_flat)
+  # Both are built with the grouping plan, and only on the flat path; the
+  # per-fiber form has neither and must not build a segment's.
+  def perm
+    @perm
   end
 
-  # Per-category cell counts, alongside #grouped and unavailable for the same
-  # reason.
-  def counts
-    @elements || raise(ArgumentError, @no_flat)
+  def codes
+    @codes
   end
 
   # Axis-aware count of present cells. Counting how many cells fall in a
-  # group does not look at what is in them, so it is taken from the codes and
-  # the value's mask rather than from the fused moments kernel, which is
-  # numeric-only and refused a complex, boolean or object payload for an
-  # answer that never depended on the payload.
-  def axis_counts (axis)
+  # group does not look at what is in them. An integer or float payload goes
+  # through the fused moments kernel, which counts in the same pass that
+  # sums. Any other payload -- complex, boolean, object, a Face -- the kernel
+  # refuses, for an answer that never depended on the payload, so it is
+  # counted from the codes and the value's mask, one group at a time.
+  def axis_counts (axis, op)
     h = @value
-    unless axis.is_a?(Integer) && axis >= 0 && axis < h.ndim
-      raise ArgumentError,
-            "group_by_category.count(axis: #{axis.inspect}): axis must be an " \
-            "Integer in [0, #{h.ndim}) for source h with shape #{h.shape}"
-    end
+    return axis_moments(axis, op)[:count] if h.integer? || h.float?
+    axis = checked_axis(axis, op)
     full_c  = resolve_axis_codes(@cat.codes, h.shape, axis)
     band    = h.shape.dup; band.delete_at(axis)
     out     = CArray.int64(*([@k] + band))
@@ -755,7 +328,8 @@ class CACategoricalIterator < CAIterator
       belongs = belongs.strip_mask(false) if belongs.has_mask?
       belongs = belongs & present if present
       slot[0] = c
-      out[*slot] = belongs.int64.sum(axis: axis)
+      # a boolean sums to a count without widening the whole array first
+      out[*slot] = belongs.sum(axis: axis)
     end
     out
   end
@@ -774,35 +348,79 @@ class CACategoricalIterator < CAIterator
   # data can produce.  The axis: path materialises nothing else, so holding
   # this one thing was the odd choice; a caller who wants a fused kernel's
   # four answers shares them by keeping the result.
-  def axis_moments (axis)
+  def axis_moments (axis, op)
+    return axis_moments_by_core(axis, op) unless MONOID_TYPES.include?(@value.data_type)
     h = @value
-    unless axis.is_a?(Integer) && axis >= 0 && axis < h.ndim
-      raise ArgumentError,
-            "group_by_category.<reduce>(axis: #{axis.inspect}): axis must be an " \
-            "Integer in [0, #{h.ndim}) for source h with shape #{h.shape}"
-    end
+    axis = checked_axis(axis, op)
+    band = h.shape.dup; band.delete_at(axis)
+    return band_only_moments(h, axis, band, op) if band_only?(@cat.codes, h.shape, axis)
     codes_h_shape = resolve_axis_codes(@cat.codes, h.shape, axis)
-    band          = h.shape.dup; band.delete_at(axis)
     out_shape     = [@k] + band
     counts        = CArray.int64(*out_shape)
     sums          = CArray.float64(*out_shape)
-    mins          = CArray.new(h.data_type, out_shape)
-    maxs          = CArray.new(h.data_type, out_shape)
+    mins          = CArray.new(h.data_type, out_shape, bytes: h.bytes)
+    maxs          = CArray.new(h.data_type, out_shape, bytes: h.bytes)
     h.__send__(:__fiber_scatter_moments__, codes_h_shape, axis, @k,
                counts, sums, mins, maxs)
     {count: counts, sum: sums, min: mins, max: maxs}
   end
 
+  # The classifier is band-only, as resolve_axis_codes decides it (case A
+  # wins when both shapes fit).
+  def band_only? (codes, h_shape, axis)
+    band = h_shape.dup; band.delete_at(axis)
+    !band.empty? && codes.shape == band && codes.shape != [h_shape[axis]]
+  end
+
+  # Moments for a band-only classifier. Every cell of a fiber has the same
+  # code, so a fiber falls into one group whole: the core's own reductions
+  # along the axis answer for it, and each answer is placed in its code's
+  # row. A fiber whose code is masked belongs to no group. A group no fiber
+  # falls in, or one whose fibers are all masked, has count 0, sum 0.0 and
+  # masked min and max, as the fused kernel leaves it. Only the answers the
+  # caller reads are computed; each is a pass of its own here, where the
+  # kernel had all four from one.
+  BAND_ONLY_KEYS = { sum: [:sum], mean: [:sum, :count], min: [:min],
+                     max: [:max], minmax: [:min, :max] }.freeze
+  private_constant :BAND_ONLY_KEYS
+
+  def band_only_moments (h, axis, band, op)
+    nb      = band.inject(1, :*)
+    shape   = [@k] + band
+    codes   = @cat.codes
+    valid   = codes.lt(@k).flatten
+    valid   = valid.strip_mask(false) if valid.has_mask?
+    addr    = (codes.value.int64.flatten * nb + CArray.int64(nb).seq)[valid]
+    out     = {}
+    BAND_ONLY_KEYS.fetch(op, [:count]).each do |key|
+      res = case key
+            when :count then CArray.int64(*shape)
+            when :sum   then CArray.float64(*shape)
+            else             CArray.new(h.data_type, shape, bytes: h.bytes).tap { |a| a[] = UNDEF }
+            end
+      per_fiber = case key
+                  when :count then h.count_not_masked(axis: axis)
+                  when :sum   then h.sum(axis: axis)
+                  when :min   then h.min(axis: axis)
+                  when :max   then h.max(axis: axis)
+                  end
+      res.reshape(@k * nb)[addr] = per_fiber.flatten[valid]
+      out[key] = res
+    end
+    out
+  end
+
   # Axis-aware sum: the moments sum is already the core fold in the core's own
   # type, so it is handed back as is (an empty group cell carries identity 0.0).
   def axis_sum (axis)
-    axis_moments(axis)[:sum]
+    axis_moments(axis, :sum)[:sum]
   end
 
   # Axis-aware mean: sums / counts (float64); empty group cells (count=0) MASKED.
   # Matches flat #mean per fiber.
   def axis_mean (axis)
-    m   = axis_moments(axis)
+    return axis_by_core(axis, :mean) unless MONOID_TYPES.include?(@value.data_type)
+    m   = axis_moments(axis, :mean)
     cnt = m[:count]
     out = m[:sum] / cnt.float64      # count 0 -> NaN
     out[cnt.eq(0)] = UNDEF           # empty / all-masked -> MASKED
@@ -821,13 +439,9 @@ class CACategoricalIterator < CAIterator
   # Cost: K axis-reductions over an h-shaped local (most cells masked away for
   # each c) — bounded by K, typically small.  A fused per-fiber variance
   # kernel is a natural follow-on if bench demands it.
-  def axis_by_masked_copy (axis, op, out_data_type = CA_FLOAT64)
+  def axis_by_masked_copy (axis, op, out_data_type = core_reduce_type(op))
     h = @value
-    unless axis.is_a?(Integer) && axis >= 0 && axis < h.ndim
-      raise ArgumentError,
-            "group_by_category.#{op}(axis: #{axis.inspect}): axis must be an " \
-            "Integer in [0, #{h.ndim}) for source h with shape #{h.shape}"
-    end
+    axis = checked_axis(axis, op)
     full_c    = resolve_axis_codes(@cat.codes, h.shape, axis)
     band      = h.shape.dup; band.delete_at(axis)
     out       = CArray.new(out_data_type, [@k] + band)
@@ -842,27 +456,128 @@ class CACategoricalIterator < CAIterator
       exclude = in_c.not
       exclude = exclude | codes_bad if codes_bad
       h_local[exclude] = UNDEF
-      slice = h_local.__send__(op, axis: axis)   # float64, band shape, mask carries n<contract
+      slice = h_local.__send__(op, axis: axis)   # band shape, mask carries n<contract
       slot_idx[0] = c
       out[*slot_idx] = slice
     end
     out
   end
 
+  # The axis: reductions for a value the fused kernels cannot read (boolean,
+  # object, a Face): each group's cells are reduced by the core's own
+  # reduction along the axis and the answers stacked, so the data type, the
+  # refusals and the empty-group answer are the core's -- a time column's mean
+  # is a time, its sum is refused, an empty group's sum is the identity.
+  # Classified along the axis (case A), a group is its positions on the axis,
+  # taken by index; otherwise its cells are kept by masking the rest of a copy.
+  # A read-only Face's answers (a const string's records index a pool of
+  # their own) cannot be put together, so they are collected as the surface
+  # values they are, as the flat form does.
+  def axis_by_core (axis, op, *args)
+    h    = @value
+    axis = checked_axis(axis, op)
+    groups  = (0...[@k, 1].max).map { |c| group_cells(h, axis, c, @k.zero?) }
+    answers = groups.map { |g| g.__send__(op, *args, axis: axis) }
+    if answers.first.face? && answers.first.read_only?
+      answers = answers.map { |a| CArray.object(*a.shape) { a.to_a } }
+    end
+    out = CArray.stack(answers, axis: 0).copy
+    @k.zero? ? out[0...0, *([nil] * (out.ndim - 1))].copy : out
+  end
+
+  def axis_moments_by_core (axis, op)
+    BAND_ONLY_KEYS.fetch(op, [:count]).to_h do |key|
+      [key, axis_by_core(axis, key == :count ? :count_not_masked : key)]
+    end
+  end
+
+  def group_cells (h, axis, c, none)
+    codes = @cat.codes
+    if codes.shape == [h.shape[axis]]
+      sel = none ? CArray.boolean(codes.elements) { false } : codes.eq(c)
+      sel = sel.strip_mask(false) if sel.has_mask?
+      idx = [nil] * h.ndim
+      idx[axis] = sel.where
+      h[*idx]
+    else
+      full_c  = resolve_axis_codes(codes, h.shape, axis)
+      exclude = none ? CArray.boolean(*h.shape) { true } : full_c.eq(c).not
+      exclude = exclude | full_c.is_masked if full_c.has_mask?
+      local = h.copy
+      local[exclude] = UNDEF
+      local
+    end
+  end
+  private :axis_by_core, :axis_moments_by_core, :group_cells
+
+  # A running statistic along an axis, for a categorical that classifies the
+  # positions along it (case A): each cell holds its group's running value up
+  # to it along the axis, per fiber. The answer is the core's, as the flat
+  # form's is; the kernel runs when it answers in the core's data type, and
+  # otherwise each group's positions are scanned by the core along the axis.
+  # Read when called, as the other axis: members are.
+  def axis_scan (op, axis)
+    h    = @value
+    axis = checked_axis(axis, op)
+    classified_along!(op, axis)
+    answer = core_scan_answer(op)
+    if kernel_scans?(op, answer)
+      bundle = @k > 0 ? [@cat.codes, @k, [axis]]
+                      : [CArray.int64(h.shape[axis]).fill(-1), 1, [axis]]
+      return h.__axis_group_scan__([axis], [bundle], op)
+    end
+    each_group_along(axis, ->(shape) { blank_like(answer, shape) }) do |g|
+      g.public_send(op, axis: axis)
+    end
+  end
+
+  # #map along an axis (case A): the block receives each group's positions
+  # along the axis, every other axis kept, and its answer goes back to them.
+  def axis_map (axis, data_type, &block)
+    axis = checked_axis(axis, :map)
+    classified_along!(:map, axis)
+    each_group_along(axis, ->(shape) { blank_output(shape, data_type) }, &block)
+  end
+
+  # Yields each group's positions along +axis+ as a view of the value and
+  # writes the block's answer back to them; a position in no group is UNDEF.
+  def each_group_along (axis, blank)
+    h   = @value
+    out = blank.call(h.shape)
+    out[] = UNDEF
+    @k.times do |c|
+      sel = @cat.codes.eq(c)
+      sel = sel.strip_mask(false) if sel.has_mask?
+      next if sel.count(true).zero?
+      idx = [nil] * h.ndim
+      idx[axis] = sel.where
+      out[*idx] = surface_for(out, yield(h[*idx]))
+    end
+    out
+  end
+
+  # A running value or a transform along an axis follows the positions along
+  # it, so the categorical has to classify those positions.
+  def classified_along! (op, axis)
+    n = @value.shape[axis]
+    return if @cat.codes.shape == [n]
+    raise ArgumentError,
+          "#{op}(axis: #{axis}): needs a categorical that classifies the " \
+          "positions along axis #{axis} (shape [#{n}]); got shape " \
+          "#{@cat.codes.shape.inspect}"
+  end
+  private :axis_scan, :axis_map, :each_group_along, :classified_along!
+
   # Axis-aware wsum + wmean fused (single kernel call, both outputs).  Returns
   # [wsum_ca, wmean_ca].  Weights must match source shape exactly (explicit
   # broadcast on the call site for 1-D or band-shape weights).  A cell
   # contributes iff its value AND its weight are present.
-  def axis_wsum_wmean (weights, axis)
+  def axis_wsum_wmean (weights, axis, op)
     h = @value
-    unless axis.is_a?(Integer) && axis >= 0 && axis < h.ndim
-      raise ArgumentError,
-            "group_by_category.wsum/wmean(axis: #{axis.inspect}): axis must " \
-            "be an Integer in [0, #{h.ndim}) for source h with shape #{h.shape}"
-    end
+    axis = checked_axis(axis, op)
     unless weights.is_a?(CArray) && weights.shape == h.shape
       raise ArgumentError,
-            "group_by_category.wsum/wmean(axis: #{axis}): weights.shape " \
+            "#{op}(axis: #{axis}): weights.shape " \
             "#{weights.respond_to?(:shape) ? weights.shape.inspect : weights.class} " \
             "must equal source.shape #{h.shape.inspect}. Wrap 1-D / band-shape " \
             "weights via `.broadcast_to(*source.shape)` before passing."
@@ -880,12 +595,9 @@ class CACategoricalIterator < CAIterator
   # Axis-aware prod: dedicated kernel (identity 1.0, separate from moments to
   # avoid conflating with sum's zero-identity memset).
   def axis_prod (axis)
+    return axis_by_core(axis, :prod) unless MONOID_TYPES.include?(@value.data_type)
     h = @value
-    unless axis.is_a?(Integer) && axis >= 0 && axis < h.ndim
-      raise ArgumentError,
-            "group_by_category.prod(axis: #{axis.inspect}): axis must be an " \
-            "Integer in [0, #{h.ndim}) for source h with shape #{h.shape}"
-    end
+    axis = checked_axis(axis, :prod)
     codes_h_shape = resolve_axis_codes(@cat.codes, h.shape, axis)
     band          = h.shape.dup; band.delete_at(axis)
     out           = CArray.float64(*([@k] + band))
@@ -896,6 +608,12 @@ class CACategoricalIterator < CAIterator
   # Broadcast `codes` to `h_shape` per PROPOSAL §2.2 3-case positional rule.
   # Returns a broadcast view of codes at h_shape (or codes itself for case B).
   # Raises ArgumentError with a message that enumerates all 3 accepted shapes.
+  # The axis of an axis: reduction, normalised against the source: a
+  # negative axis counts from the end, as everywhere else.
+  def checked_axis (axis, op)
+    @value.normalize_axis(axis, op.to_s)
+  end
+
   def resolve_axis_codes (codes, h_shape, axis)
     ndim = h_shape.size
     band = h_shape.dup; band.delete_at(axis)
@@ -932,225 +650,10 @@ class CACategoricalIterator < CAIterator
           "band-only cat.shape=#{band.inspect}."
   end
 
-  # Order-stat axis: is deferred to Phase 4 (per-fiber counting-sort C kernel).
-  # Called from median / percentile / variance / stddev when axis: is given.
-  def axis_order_stat_defer! (op)
-    raise NotImplementedError,
-          "CACategoricalIterator##{op}(axis:) is not implemented — order " \
-          "statistics are available without axis:."
-  end
-
-  # Drive a segment scan through the axis-group scan kernel: the whole value as
-  # one grouped axis, the flat codes as the single bundle.  The kernel emits in
-  # source order, so the flat result reshapes straight back to the source shape.
-  def scan (op)
-    scan_source.reshape(@value.elements)
-               .__axis_group_scan__([0], [[@codes, @k, [0]]], op)
-               .reshape(*@src_shape)
-  end
-
-  # The values as they were when the iterator was built, in source order.
-  # Every no-axis reduction works from the category-major copy taken then; the
-  # scans read @value, so a write through the source between two calls used to
-  # be visible to a cumsum and not to a sum, off one iterator.
-  #
-  # Rebuilt rather than copied a second time: @perm is exactly the classified
-  # cells and @grouped holds their values and their masks, which is everything
-  # a scan reads -- a cell classified by nothing is skipped on its code, before
-  # its value is looked at. So this costs nothing until a scan asks for it, and
-  # nothing at all for an iterator that never scans.
-  def scan_source
-    @scan_source ||=
-      begin
-        snap = @value.template
-        snap.reshape(snap.elements)[perm] = grouped
-        snap
-      end
-  end
-
-
-  # Permutation: perm[slot] = the source index whose value sits at that grouped
-  # slot. This is the valid prefix of the categorical's cached sort_addr, sliced
-  # at construction (the same counting sort that lays out @grouped), so #map /
-  # #sort_addr / the *_addr reductions read it for free.
-  def perm
-    @perm
-  end
-
-  # Lay a per-cell weight array out in category-contiguous order (same layout as
-  # @grouped), so wsum / wmean can pair each group's values with its weights.
-  # Weights are coerced to float64; the same counting-sort scatter propagates
-  # the weight mask and skips excluded cells, so wg lines up with @grouped.
-  def scatter_weights (weights)
-    unless weights.elements == @codes.elements
-      raise ArgumentError,
-            "wsum/wmean: weights.elements (#{weights.elements}) != " \
-            "value.elements (#{@codes.elements})"
-    end
-    wf = weights.float64
-    wg = CArray.float64(grouped.elements)
-    @codes.send(:__categorical_scatter__, wf.reshape(wf.elements),
-                @offsets.copy, wg, @k)
-    wg
-  end
-
-  # Map a per-category group-local index to the flat source address via the
-  # permutation (grouped slot -> source index). The min/max sits at grouped slot
-  # offsets[c] + local_index[c]; perm carries it back to the source. Empty
-  # categories (masked local index) stay masked.
-  def group_addr (local_index)
-    out = CArray.int64(@k)
-    @k.times do |c|
-      out[c] = local_index.is_masked[c] ? UNDEF
-                                        : perm[@offsets[c] + local_index[c]]
-    end
-    out
-  end
-
-  # Fused per-segment weighted sum + weighted mean (one C pass over the grouped
-  # copy, weights in group order). Returns [wsum, wmean]; wmean is masked where a
-  # segment has no present (value AND weight) pair. Numeric value data types only.
-  def kernel_weighted (wg)
-    ws = CArray.float64(@k)
-    wm = CArray.float64(@k)
-    grouped.send(:__reduceat_wsum_wmean__, @offsets, wg, ws, wm)
-    [ws, wm]
-  end
-
-  # Per-group weighted fallback for non-numeric value data types (complex): delegate
-  # each group to CArray#wsum / #wmean. Empty segments take the given identity.
-  def fold_weighted (wg, empty)
-    out = CArray.float64(@k)
-    @k.times do |c|
-      lo = @offsets[c]
-      hi = (c + 1 < @k) ? @offsets[c + 1] : grouped.elements
-      out[c] = hi > lo ? yield(grouped[lo...hi], wg[lo...hi]) : empty
-    end
-    out
-  end
-
-  # The members of category `c` as a CArray slice of the grouped copy.  An empty
-  # category (zero-width segment) yields the shared empty array — a zero-length
-  # slice cannot be taken directly, and an empty array carries the same reduction
-  # contract we want (identity for sum, UNDEF for ratios).
-  def group_slice (c)
-    lo = @offsets[c]
-    hi = (c + 1 < @k) ? @offsets[c + 1] : grouped.elements
-    hi > lo ? grouped[lo...hi] : @empty
-  end
-
-  # Single-pass reduceat moments (count / sum / min / max per category), computed
-  # once over the grouped copy and cached — the whole point of the eager copy is
-  # that one scatter is followed by cheap single-pass reductions with no
-  # per-segment views.  Nil for a non-numeric value data type (complex / object /
-  # bool), where the monoid reductions fall back to per_category.
-  # numeric value data types the C moments kernel handles (int8..float64); bool /
-  # complex / object fall back to per_category.
-  MONOID_TYPES = %i[int8 uint8 int16 uint16 int32 uint32
-                    int64 uint64 float32 float64].freeze
-
-  def moments
-    return @moments if defined?(@moments)
-    @moments =
-      if MONOID_TYPES.include?(grouped.data_type)
-        dt     = grouped.data_type
-        counts = CArray.int64(@k)
-        sums   = CArray.float64(@k)
-        mins   = CArray.new(dt, [@k])
-        maxs   = CArray.new(dt, [@k])
-        grouped.send(:__reduceat_moments__, @offsets, counts, sums, mins, maxs)
-        { count: counts, sum: sums, min: mins, max: maxs }
-      end
-  end
-
-  # Single-pass fused group-local argmin / argmax (min_index / max_index),
-  # cached. Nil for a non-numeric value data type (fall back to per_category).
-  def arg_minmax
-    return @arg_minmax if defined?(@arg_minmax)
-    @arg_minmax =
-      if MONOID_TYPES.include?(grouped.data_type)
-        mn = CArray.int64(@k)
-        mx = CArray.int64(@k)
-        grouped.send(:__reduceat_argminmax__, @offsets, mn, mx)
-        { min: mn, max: mx }
-      end
-  end
-
-  # Single-pass fused per-category boolean all / any, cached. Nil unless the
-  # value data type is boolean (fall back to per_category, which raises like
-  # CArray#all on a non-boolean).
-  def all_any
-    return @all_any if defined?(@all_any)
-    @all_any =
-      if grouped.data_type == CA_BOOLEAN
-        a = CArray.boolean(@k)
-        o = CArray.boolean(@k)
-        grouped.send(:__reduceat_all_any__, @offsets, a, o)
-        { all: a, any: o }
-      end
-  end
-
-  # Build a length-k typed output by folding each category's members with the
-  # given reduction block.  Fallback path (order statistics, and monoids on a
-  # non-numeric value data type): each group is delegated to the same CArray
-  # reduction, so the per-group result matches `CArray#<reduction>` over that
-  # group's members — the mask carries the "insufficient present data" contract
-  # for free (an all-masked group reduces like an empty one; identity-bearing
-  # reductions return their identity, ratios return UNDEF; see ext ERI).
-  # The data type the core reduction `op` promotes this value to.  Asked of the
-  # core itself -- a one-cell reduction of the value's type -- rather than
-  # restated here, so a per-category answer cannot drift from `CArray#<op>`
-  # (`sum` on an integer promotes, `accumulate` stays, `min` / `max` keep the
-  # type but a boolean widens, `prod` on an object stays an object).  A payload
-  # the core refuses to fold this way raises here, with the core's own error.
-  # Probes the core with a one-cell array of the value's data type and takes
-  # the answer's. Asks @value rather than the grouped copy, which has the same
-  # data type but does not exist on an iterator that answers only the
-  # per-fiber form -- and `accumulate(axis:)`, the one axis: member that needs
-  # this, is exactly the case that would have found it missing.
-  def core_reduce_type (op, *args)
-    (@core_reduce_type ||= {})[[op, args]] ||=
-      @value.face? && @value.elements.zero? ?
-        CA_OBJECT : core_probe.public_send(op, *args, axis: 1).data_type
-  end
-
-  # A one-cell array of the same kind as the values, so the core answers about
-  # the same thing the group slices will hand back. For a Face that is a view
-  # of the values themselves rather than a blank: a Face cannot be allocated
-  # from its surface data type alone, and a blank storage array is not a valid
-  # Face for every one of them -- a const string's record indexes a shared
-  # pool, so a zeroed record points nowhere.
-  def core_probe
-    return CArray.new(@value.data_type, [1, 1]) unless @value.face?
-    @value.reshape(@value.elements)[[0]].reshape(1, 1)
-  end
-
-  # Whether an output can be built by lifting one. A Face is filled by writing
-  # surface values into storage, so this needs a Face that can be written
-  # into; a read-only one -- a const string's records index a shared pool, a
-  # categorical's codes index a vocabulary -- has no blank form to fill.
-  def face_output?
-    @value.face? && ! @value.read_only?
-  end
-
-  def per_category (data_type)
-    out = if ! @value.face? || data_type != @value.data_type
-            CArray.new(data_type, [@k])
-          elsif face_output?
-            # the core answered in the values' own Face, so the output is one
-            # too: CATime#min hands back a CATime::Element, which only a
-            # CATime has anywhere to put
-            CArray.new(@value.parent.data_type, [@k],
-                       bytes: @value.parent.bytes).face_lift(@value)
-          else
-            # a read-only Face cannot be filled, so its answers are collected
-            # as the surface objects they already are
-            CArray.new(CA_OBJECT, [@k])
-          end
-    # A member the core refuses for this Face still refuses: the group slice is
-    # the Face, so the refusal comes from there, in the core's own words.
-    @k.times { |c| out[c] = yield(group_slice(c)) }
-    out
+  # median / percentile along an axis: the core's own order statistic of each
+  # group's cells, stacked -- the axis_by_core path, one core call per group.
+  def axis_order_stat (axis, op, *args)
+    axis_by_core(axis, op, *args)
   end
 end
 
@@ -1161,8 +664,14 @@ class CArray
   #   per category of `cat`.  Requires `self.elements == cat.elements`.
   #   @param cat [CACategorical] the classifier.
   #   @return [CACategoricalIterator]
+  #   @raise [TypeError] when `cat` is not a CACategorical.
   #   @raise [ArgumentError] when element counts differ.
   def group_by_category (cat)
+    unless cat.is_a?(CACategorical)
+      raise TypeError,
+            "group_by_category: expects a CACategorical (got #{cat.class}); " \
+            "classify the values first with .categorize"
+    end
     CACategoricalIterator.new(self, cat)
   end
 
@@ -1187,18 +696,16 @@ class CArray
   #   `grp.labels` is `[0, 1, ...]` in position order.
   #
   #   @return [CACategoricalIterator] one category per run, in order.
-  #   @raise [RuntimeError] when `self` is not 1-D.
+  #   @raise [ArgumentError] when `self` is not 1-D.
   def group_by_run
-    raise "group_by_run: 1-D only (got #{ndim}-D)" unless ndim == 1
+    raise ArgumentError, "group_by_run: 1-D only (got #{ndim}-D)" unless ndim == 1
     if elements == 0
       code = CArray.int64(0)
     else
       present = is_not_masked
       edge    = present & present.shift(1).not   # rising edge = run start
-      # feed cumsum via a zero-copy int8 reinterpret of the 1-byte booleans
-      # rather than widening to int64; cumsum promotes to float64, so the
-      # running count never overflows int8.
-      code    = edge.refer(:int8).cumsum.int64 - 1   # 0-based run index per cell
+      # a boolean cumsum counts in uint64, exactly
+      code    = edge.cumsum.int64 - 1               # 0-based run index per cell
       code[present.not] = UNDEF                  # masked cells join no run
     end
     # categorize turns the dense run indices into the run categories: it derives