carray 3.0.1 → 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.
@@ -103,8 +103,9 @@ class CACategoricalIterator < CAIterator
       # index): offsets[c] = sum of counts[0...c]. Both come off the shared
       # plan, so the counting sort is not repeated here.
       @elements = cat.category_sizes.int64
-      nvalid    = @elements.sum
+      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,44 +119,35 @@ 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
       # is unrecoverable (preserves the old strict check).  For higher-rank
       # value, defer validation to reduce time — check only that cat.ndim fits
       # one of the 3 axis: cases;
-      # any no-axis reduce called on this iterator will surface the mismatch
-      # because @grouped stays undefined.
+      # A no-axis reduce has no grouped buffer to work from. The reason is
+      # recorded here and raised from wherever one is asked for, so what
+      # surfaces names the mismatch instead of being whatever NoMethodError
+      # the nil produced first.
+      mismatch = "group_by_category: value.elements (#{value.elements}) != " \
+                 "cat.elements (#{cat.elements})"
       if value.ndim == 1 ||
          ! [1, value.ndim - 1, value.ndim].include?(cat.ndim)
         raise ArgumentError,
-              "group_by_category: value.elements (#{value.elements}) != " \
-              "cat.elements (#{cat.elements})" +
+              mismatch +
               (value.ndim == 1 ? "" :
                 ". For per-fiber reduce use `.sum(axis: k)`; cat.ndim=" \
                 "#{cat.ndim} must be 1 (case A), #{value.ndim} (case B), " \
                 "or #{value.ndim - 1} (band-only) for h.ndim=#{value.ndim}.")
       end
+      @no_flat = mismatch + ". This iterator answers only the per-fiber form, " \
+                 "`.<reduce>(axis: k)`."
     end
     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]
@@ -169,16 +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
-    @elements
-  end
-
   # Group-vocabulary alias for {#elements}; reads naturally next to
   # {#ngroups} and mirrors `CACategorical#category_sizes`.
   alias group_sizes elements
@@ -189,552 +171,256 @@ class CACategoricalIterator < CAIterator
   #   internal grouped/value/codes buffers.
   #   @return [String]
   def inspect
-    "#<#{self.class} ngroups=#{@k} labels=#{@labels.inspect} " \
-    "elements=#{@elements.to_a.inspect}>"
-  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_moments(axis)[:count] if axis
-    m = moments
-    m ? m[:count] : 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 ? @elements - 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] : 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] : 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 the single cached 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.
-  #   @param axis [Integer]
-  #   @return [Array<CArray>]
-  def minmax(axis: nil)
-    return [min(axis: axis), max(axis: axis)] if axis
-    [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] : 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] : 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)
+    # An iterator that answers only the per-fiber form has no per-category
+    # counts to show. Saying so beats both raising -- inspect is what you
+    # reach for when something is already puzzling -- and printing an empty
+    # list, which reads as a grouping that classified nothing.
+    tail = @elements ? "elements=#{@elements.to_a.inspect}" : "per-fiber only"
+    "#<#{self.class} ngroups=#{@k} labels=#{@labels.inspect} #{tail}>"
   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
+  # 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.
+  #
+  # @!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]
 
-  # @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
+  private
 
-  # @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) }
+  # 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
 
-  # @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
+  def codes
+    @codes
   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])
+  # Axis-aware count of present cells. Counting how many cells fall in a
+  # 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
+    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))
+    present = h.has_mask? ? h.is_not_masked : nil
+    slot    = [nil] * (band.size + 1)
     @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
+      # a masked code belongs to no group, and eq yields UNDEF there
+      belongs = full_c.eq(c)
+      belongs = belongs.strip_mask(false) if belongs.has_mask?
+      belongs = belongs & present if present
+      slot[0] = c
+      # a boolean sums to a count without widening the whole array first
+      out[*slot] = belongs.sum(axis: axis)
     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 ------------------
-  #
-  # 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.
-
-  # @overload cumsum
-  #   Per-category inclusive running sum (float64), source-shaped.
-  #   @return [CArray]
-  # @overload cumprod
-  #   Per-category inclusive running product (float64), source-shaped.
-  #   @return [CArray]
-  # @overload cummax
-  #   Per-category inclusive running maximum (value data type), source-shaped.
-  #   @return [CArray]
-  # @overload cummin
-  #   Per-category inclusive running minimum (value data type), source-shaped.
-  #   @return [CArray]
-  # @overload 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
-
-  private
-
-  # Axis-aware moments (count / sum / min / max) — computed once per axis via
-  # the fused per-fiber scatter-reduce C kernel and cached (matches the flat
-  # #moments caching in spirit: pay one kernel per {iterator, axis} pair, share
-  # across sum / mean / min / max / minmax / count* consumers).  Returns
+  # Axis-aware moments (count / sum / min / max) via the fused per-fiber
+  # scatter-reduce C kernel.  Returns
   # `{count: <int64>, sum: <float64>, min: <h's type, masked>, max: <h's type, masked>}`,
   # all shape [K, ...band].
-  def axis_moments (axis)
-    @axis_moments_cache ||= {}
-    cached = @axis_moments_cache[axis]
-    return cached if cached
+  #
+  # Read fresh on every call, deliberately.  It used to be kept per axis, and
+  # since the rest of the axis: family (prod, the variance family, wsum /
+  # wmean) reads the source when asked, half of the family answered about the
+  # values as they were and half about the values as they are.  Writing
+  # through another view of the source between two calls got you a mean of 2.0
+  # beside a variance of 4704.5 for the same cell, which is not a pair any
+  # 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, 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)
-    @axis_moments_cache[axis] = {count: counts, sum: sums, min: mins, max: 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].copy
+    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
@@ -753,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)
@@ -774,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."
@@ -812,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))
@@ -828,25 +608,29 @@ 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)
-    case codes.ndim
-    when 1
-      unless codes.shape == [h_shape[axis]]
-        axis_shape_mismatch!(codes.shape, h_shape, axis, band)
-      end
+    # Chosen by shape, not by rank. For a 2-D source the case A shape and the
+    # band-only shape are both rank 1, so choosing by rank took case A every
+    # time and band-only could never be reached there -- while the refusal
+    # went on to list the very shape it was refusing among the ones it
+    # accepts. When both fit, which a square source makes possible, case A
+    # wins: classifying along the reduce axis is the reading that holds at
+    # every rank.
+    case
+    when codes.shape == [h_shape[axis]]                      # case A
       view_shape = Array.new(ndim, 1); view_shape[axis] = h_shape[axis]
       codes.reshape(*view_shape).broadcast_to(*h_shape)
-    when ndim
-      unless codes.shape == h_shape
-        axis_shape_mismatch!(codes.shape, h_shape, axis, band)
-      end
+    when codes.shape == h_shape                              # case B
       codes
-    when ndim - 1
-      unless codes.shape == band
-        axis_shape_mismatch!(codes.shape, h_shape, axis, band)
-      end
+    when codes.shape == band                                 # band-only
       view_shape = h_shape.dup; view_shape[axis] = 1
       codes.reshape(*view_shape).broadcast_to(*h_shape)
     else
@@ -855,175 +639,21 @@ class CACategoricalIterator < CAIterator
   end
 
   def axis_shape_mismatch! (cat_shape, h_shape, axis, band)
+    # No method name: the one place that resolves this serves sum, mean, min,
+    # max, count and the rest alike, and naming one of them would be wrong for
+    # the others. The backtrace says which was called.
     raise ArgumentError,
-          "group_by_category.sum(axis: #{axis}): cat.shape=#{cat_shape.inspect} " \
+          "group_by_category (axis: #{axis}): cat.shape=#{cat_shape.inspect} " \
           "does not fit any of the 3 accepted forms for h.shape=#{h_shape.inspect}: " \
           "case A cat.shape=[#{h_shape[axis]}], " \
           "case B cat.shape=#{h_shape.inspect}, " \
           "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)
-    @value.reshape(@value.elements)
-          .__axis_group_scan__([0], [[@codes, @k, [0]]], op)
-          .reshape(*@src_shape)
-  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.
-  def core_reduce_type (op, *args)
-    (@core_reduce_type ||= {})[[op, args]] ||=
-      CArray.new(@grouped.data_type, [1, 1]).public_send(op, *args, axis: 1).data_type
-  end
-
-  def per_category (data_type)
-    out = CArray.new(data_type, [@k])
-    @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
 
@@ -1034,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
 
@@ -1060,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