carray 3.0.2 → 3.0.3

data/lib/carray/block_iterator.rb

@@ -167,19 +167,44 @@ class CABlockIterator < CAIterator
   # below a full tile, so `min_count:` marks them UNDEF with no masking.  The
   # output data type is seeded from the first region (all regions share it).
   def assemble
-    outs = nil
+    grids = nil
+    faces = nil
+    single = true
     each_region do |strip_ranges, tiles, out_ranges|
       view = @source[*strip_ranges].block_view(*tiles)
       res  = yield(view, tiles)
-      if res.is_a?(Array)
-        outs ||= res.map { |r| CArray.new(r.data_type, @shape) }
-        res.each_index { |k| outs[k][*out_ranges] = res[k] }
-      else
-        outs ||= CArray.new(res.data_type, @shape)
-        outs[*out_ranges] = res
-      end
+      single = false if res.is_a?(Array)
+      res  = [res] unless res.is_a?(Array)
+      faces ||= res.map { |r| r.face? ? r : nil }
+      parts = res.map { |r| r.face? ? face_grid_part(r) : r }
+      grids ||= parts.map { |r| CArray.new(r.data_type, @shape, bytes: r.bytes) }
+      parts.each_index { |k| grids[k][*out_ranges] = parts[k] }
     end
-    outs
+    unless grids
+      # An empty source has no region.  A view with unit tiles has no cells
+      # either; reducing it gives each output's type for the empty grid.
+      res = yield(@source.block_view(*[1] * @sndim), [1] * @sndim)
+      single = !res.is_a?(Array)
+      res = [res] unless res.is_a?(Array)
+      faces = res.map { |r| r.face? ? r : nil }
+      grids = res.map { |r| r = face_grid_part(r) if r.face?; CArray.new(r.data_type, @shape, bytes: r.bytes) }
+    end
+    outs = grids.each_index.map { |k| faces[k] ? face_grid(grids[k], faces[k]) : grids[k] }
+    single ? outs[0] : outs
+  end
+
+  # A region result that is a Face (a CATime mean, a CATimedelta stddev) is
+  # assembled on its storage and the Face is put back on the whole grid;
+  # assembling the Face itself would copy its surface bytes into an array that
+  # no longer knows it is one.  A CAConstString's storage points into its own
+  # buffer, which the regions do not share, so it is assembled as strings.
+  def face_grid_part (r)
+    r.is_a?(CAConstString) ? r.to_string.parent : r.parent
+  end
+
+  def face_grid (grid, face)
+    return CArray.const_string(grid, encoding: face.encoding) if face.is_a?(CAConstString)
+    grid.face_lift(face)
   end
 
   # Fold every region with a single core reduction `op` (the tier-1 shape).
@@ -255,19 +280,13 @@ class CABlockIterator < CAIterator
   #   @param fill_value [Object, nil] value to put in place of a masked
   #     result instead of leaving it masked.
   #   @return [CArray] tile-grid shaped
-  # @!method all(min_count: nil, fill_value: nil)
+  # @!method all
   #   Whether every cell of each tile is true.
-  #   @param min_count [Integer, nil] fewest cells that must be present
-  #     for a result; a piece with fewer comes back masked.
-  #   @param fill_value [Object, nil] value to put in place of a masked
-  #     result instead of leaving it masked.
+  #   Takes no `min_count:` or `fill_value:`, as the core `all` does not.
   #   @return [CArray] tile-grid shaped
-  # @!method any(min_count: nil, fill_value: nil)
+  # @!method any
   #   Whether any cell of each tile is true.
-  #   @param min_count [Integer, nil] fewest cells that must be present
-  #     for a result; a piece with fewer comes back masked.
-  #   @param fill_value [Object, nil] value to put in place of a masked
-  #     result instead of leaving it masked.
+  #   Takes no `min_count:` or `fill_value:`, as the core `any` does not.
   #   @return [CArray] tile-grid shaped
   # @!method variancep(min_count: nil, fill_value: nil)
   #   Per-tile population variance (divisor `n`).
@@ -283,9 +302,12 @@ class CABlockIterator < CAIterator
   #   @param fill_value [Object, nil] value to put in place of a masked
   #     result instead of leaving it masked.
   #   @return [CArray] tile-grid shaped
-  [:sum, :accumulate, :prod, :mean, :min, :max, :variance, :stddev, :all, :any,
+  [:sum, :accumulate, :prod, :mean, :min, :max, :variance, :stddev,
    :variancep, :stddevp].each do |op|
     define_method(op) do |min_count: nil, fill_value: nil|
+      if FACE_WINNER_INDEX.key?(op) && @source.face?
+        return face_winner(FACE_WINNER_INDEX[op], min_count, fill_value)
+      end
       kw = {}
       kw[:min_count]  = min_count  unless min_count.nil?
       kw[:fill_value] = fill_value unless fill_value.nil?
@@ -293,6 +315,17 @@ class CABlockIterator < CAIterator
     end
   end
 
+  [:all, :any].each do |op|
+    define_method(op) { |**kw| fold(op, **CAIterator.reduce_keywords(op, kw)) }
+  end
+
+  # A Face's minimum and maximum are cells of the Face, so they are gathered
+  # from the source by the winner's address.  Assembling the per-region results
+  # instead copies the Face's storage into an array that no longer knows it is
+  # one: a CATime came back as 8-byte strings.
+  FACE_WINNER_INDEX = { min: :min_index, max: :max_index }.freeze
+  private_constant :FACE_WINNER_INDEX
+
   # ---- count family and elements ----------------------------------------
 
   # @overload count(v = <none>)
@@ -300,15 +333,16 @@ class CABlockIterator < CAIterator
   #   partial edge tile); `count(UNDEF)` counts masked cells; `count(v)` counts
   #   cells equal to `v`.
   #   @return [CArray] tile-grid shaped
-  def count (*args)
-    return count_not_masked if args.empty?
+  def count (*args, **kw)
+    return count_not_masked(**kw) if args.empty?
+    kw = CAIterator.reduce_keywords(:count, kw)
     out = nil
     each_region do |strip_ranges, tiles, out_ranges|
       view = @source[*strip_ranges].block_view(*tiles)
       # block_view is a CAStride, so #count is not shadowed; dispatch
       # CArray#count explicitly anyway, matching the family regularity.
-      red = CArray.instance_method(:count).bind_call(view, *args, axis: @tile_axes)
-      out ||= CArray.new(red.data_type, @shape)
+      red = CArray.instance_method(:count).bind_call(view, *args, axis: @tile_axes, **kw)
+      out ||= CArray.new(red.data_type, @shape, bytes: red.bytes)
       out[*out_ranges] = red
     end
     out
@@ -318,16 +352,21 @@ class CABlockIterator < CAIterator
   #   Per-tile count of present (non-masked) cells.  For a partial edge tile
   #   this is the real cell count (the OOB cells are not present).
   #   @return [CArray]
-  def count_not_masked
-    fold(:count_not_masked)
+  def count_not_masked (**kw)
+    fold(:count_not_masked, **CAIterator.reduce_keywords(:count_not_masked, kw))
   end
 
   # @overload count_masked
   #   Per-tile count of masked cells.  Equals `elements - count_not_masked`;
   #   the OOB cells of a partial edge tile count here.
   #   @return [CArray]
-  def count_masked
-    elements - count_not_masked
+  def count_masked (**kw)
+    kw   = CAIterator.reduce_keywords(:count_masked, kw)
+    need = CArray.__min_count_need__(:count_masked, kw[:min_count], 0)
+    out  = elements - count_not_masked
+    # A count of the mask reads every cell of the tile.
+    out[elements.lt(need)] = UNDEF if need > 0
+    CArray.__reduce_fill__(out, kw[:fill_value])
   end
 
   # @overload elements
@@ -349,6 +388,10 @@ class CABlockIterator < CAIterator
   #   Per-tile `[min, max]` (two tile-grid-shaped CArrays, a single fused pass).
   #   @return [Array<CArray>]
   def minmax (min_count: nil, fill_value: nil)
+    if @source.face?
+      return [min(min_count: min_count, fill_value: fill_value),
+              max(min_count: min_count, fill_value: fill_value)]
+    end
     kw = {}
     kw[:min_count]  = min_count  unless min_count.nil?
     kw[:fill_value] = fill_value unless fill_value.nil?
@@ -364,8 +407,9 @@ class CABlockIterator < CAIterator
   #   @return [CArray]
   [:min_index, :max_index].each do |op|
     class_eval <<~RUBY, __FILE__, __LINE__ + 1
-      def #{op}
-        assemble { |view, _| view.#{op}(axis: @tile_axes) }
+      def #{op} (**kw)
+        kw = CAIterator.reduce_keywords(:#{op}, kw)
+        assemble { |view, _| view.#{op}(axis: @tile_axes, **kw) }
       end
     RUBY
   end
@@ -376,26 +420,49 @@ class CABlockIterator < CAIterator
   #   minima. Unlike `min_index` (the tile-local position) this indexes back
   #   into the original array. An all-masked tile is a masked cell.
   #   @return [CArray] tile-grid shaped int64
-  def min_addr; winner_addr(:min_index); end
+  def min_addr (**kw); winner_addr(:min_index, kw); end
 
   # @overload max_addr
   #   Per-tile flat source address of the maximum. See {#min_addr}.
   #   @return [CArray] tile-grid shaped int64
-  def max_addr; winner_addr(:max_index); end
+  def max_addr (**kw); winner_addr(:max_index, kw); end
 
   private
 
+  # Per-tile minimum or maximum of a Face source, gathered from the source by
+  # the winner's address so the result is the Face itself.  An all-masked tile,
+  # and with `min_count` a tile with too few present cells, is a masked cell.
+  def face_winner (idx_op, min_count, fill_value)
+    addr = winner_addr(idx_op)
+    need = CArray.__min_count_need__(idx_op == :min_index ? :min : :max, min_count, 0)
+    addr[count_not_masked.lt(need)] = UNDEF if need > 0
+    src   = @source.reshape(@source.elements)
+    empty = addr.is_masked
+    return src[addr].copy unless empty.any
+    # A masked index drops the cell rather than masking it, so an empty tile
+    # needs a placeholder address.  Pointing it at a masked cell of the source
+    # carries the mask through the gather, which a read-only Face (whose copy
+    # cannot be written) needs.  Otherwise mask the placeholder afterwards.
+    if fill_value.nil? && src.has_mask? && (hole = src.is_masked.where).elements > 0
+      return src[addr.strip_mask(hole[0])].copy
+    end
+    out = src[addr.strip_mask(0)].copy
+    out[empty] = fill_value.nil? ? UNDEF : fill_value
+    out
+  end
+
   # Per-tile source address of the winner. The tile-local flat index (min_index /
   # max_index) is looked up in a source-address companion tiled the same way, so
   # the tile geometry is reused rather than recomputed. An all-masked tile yields
   # a masked index; it is gathered at 0 and re-masked in the result.
-  def winner_addr (idx_op)
+  def winner_addr (idx_op, kw = {})
+    kw    = CAIterator.reduce_keywords(idx_op, kw)
     saddr = CArray.int64(*@source.shape).seq!
     out = nil
     each_region do |strip_ranges, tiles, out_ranges|
       vview = @source[*strip_ranges].block_view(*tiles)
       sview = saddr[*strip_ranges].block_view(*tiles)
-      mi    = vview.public_send(idx_op, axis: @tile_axes)  # tile-local flat index
+      mi    = vview.public_send(idx_op, axis: @tile_axes, **kw.slice(:min_count))  # tile-local flat index
       grid  = (0...@sndim).map { |i| vview.shape[i] }
       cells = tiles.inject(1) { |p, t| p * t }
       safe  = mi.copy
@@ -407,7 +474,7 @@ class CABlockIterator < CAIterator
       out ||= CArray.int64(*@shape)
       out[*out_ranges] = picked
     end
-    out
+    CArray.__reduce_fill__(out || CArray.int64(*@shape), kw[:fill_value])
   end
 
   public
@@ -441,15 +508,17 @@ class CABlockIterator < CAIterator
   #   Per-tile weighted sum; `weights` is shaped like one full tile (`Π b_i`).
   #   At a partial edge tile the weight kernel is sliced to the present cells.
   #   @return [CArray]
-  def wsum (weights)
-    weighted(weights) { |view, w| view.wsum(w, axis: @tile_axes) }
+  def wsum (weights, **kw)
+    kw = CAIterator.reduce_keywords(:wsum, kw)
+    weighted(weights) { |view, w| view.wsum(w, axis: @tile_axes, **kw) }
   end
 
   # @overload wmean(weights)
   #   Per-tile weighted mean; `weights` shaped like one full tile.
   #   @return [CArray]
-  def wmean (weights)
-    weighted(weights) { |view, w| view.wmean(w, axis: @tile_axes) }
+  def wmean (weights, **kw)
+    kw = CAIterator.reduce_keywords(:wmean, kw)
+    weighted(weights) { |view, w| view.wmean(w, axis: @tile_axes, **kw) }
   end
 
   private
@@ -479,21 +548,22 @@ class CABlockIterator < CAIterator
   # Core per-axis order statistics take a single integer axis, so a 1-D tile
   # delegates straight to the C path; a multi-axis tile is materialized per
   # region and its tile axes flattened into one before the single-axis core
-  # order-stat.  A masked source raises (the known per-axis masked limitation);
-  # strip the mask with `ca.value` first if needed.
+  # order-stat.  Masked cells are left out, as in `CArray#median(axis:)`.
 
   # @overload median
   #   Per-tile median.  @return [CArray]
-  def median
-    order_stat { |v, axis| v.median(axis: axis) }
+  def median (**kw)
+    kw = CAIterator.reduce_keywords(:median, kw)
+    order_stat { |v, axis| v.median(axis: axis, **kw) }
   end
 
   # @overload percentile(*pers)
   #   Per-tile percentile(s).  One argument returns one CArray, several an array
   #   of CArrays (as `CArray#percentile`).
   #   @return [CArray, Array<CArray>]
-  def percentile (*pers)
-    order_stat { |v, axis| v.percentile(*pers, axis: axis) }
+  def percentile (*pers, **kw)
+    kw = CAIterator.reduce_keywords(:percentile, kw)
+    order_stat { |v, axis| v.percentile(*pers, axis: axis, **kw) }
   end
 
   # @overload quantile
@@ -585,7 +655,7 @@ class CABlockIterator < CAIterator
   #   @return [CArray, Enumerator] source-shaped
   def map
     return to_enum(:map) unless block_given?
-    pout = CArray.new(padded_source.data_type, padded_source.shape)
+    pout = CArray.new(padded_source.data_type, padded_source.shape, bytes: padded_source.bytes)
     pgv  = pout.block_view(*@sizes)
     tgv  = tile_grid_view
     nils = Array.new(@sndim, nil)
@@ -640,7 +710,7 @@ class CABlockIterator < CAIterator
       tile    = tgv[*g, *nils]
       scanned = tile.copy.reshape(tile.elements).public_send(op).reshape(*@sizes)
       unless pout
-        pout = CArray.new(scanned.data_type, padded_source.shape)
+        pout = CArray.new(scanned.data_type, padded_source.shape, bytes: scanned.bytes)
         pout[] = UNDEF
         pgv  = pout.block_view(*@sizes)
       end
@@ -659,7 +729,7 @@ class CABlockIterator < CAIterator
       if pshape == @source.shape.to_a
         @source
       else
-        pad = CArray.new(@source.data_type, pshape)
+        pad = CArray.new(@source.data_type, pshape, bytes: @source.bytes)
         pad[] = UNDEF
         pad[*@sndim.times.map { |i| 0...@source.shape[i] }] = @source
         pad

data/lib/carray/boolean_reduce.rb

@@ -69,41 +69,33 @@ class CArray
   # @return [Boolean, CArray] a scalar, or an array when an axis is given.
   def none (skip_masked: true, **opts)
     return __none_skipna__(**opts) if skip_masked
-    # none = not any (Kleene): not(true)=false, not(false)=true, not(UNDEF)=UNDEF
-    r = __kleene_fold(:any, opts)
-    r.is_a?(CArray) ? r.not : (r.equal?(UNDEF) ? UNDEF : !r)
+    __kleene_fold(:none, opts)
   end
 
   private
 
-  # Three-valued fold via counts.  `kind` is :any (OR) or :all (AND).
-  # `opts` carries axis: / keep_axis: (same surface as the skipna reduction).
+  # Three-valued fold.  `kind` is :any, :all or :none.  The available-case
+  # reduction answers wherever an unmasked cell settles the fold (a true for
+  # any, a false for all, a true for none); elsewhere a masked cell leaves the
+  # answer undetermined.  Going through that reduction checks the data type,
+  # the axes and the keywords exactly as `skip_masked: true` does.
   def __kleene_fold (kind, opts)
-    axis = opts[:axis]
-    if axis.nil?
-      if kind == :any
-        return true  if count(true)  > 0     # a known TRUE settles OR
-      else
-        return false if count(false) > 0     # a known FALSE settles AND
-      end
-      return UNDEF if count_masked > 0        # undetermined
-      return( kind == :any ? false : true )
+    r = case kind
+        when :any then __any_skipna__(**opts)
+        when :all then __all_skipna__(**opts)
+        else           __none_skipna__(**opts)
+        end
+    cm = count_masked(**opts)
+    if r.is_a?(CArray)
+      settled = ( kind == :any ) ? r : r.not
+      out = r.copy
+      out[settled.not & (cm > 0)] = UNDEF
+      out
+    else
+      settled = ( kind == :any ) ? r : !r
+      return r if settled
+      ( cm > 0 ) ? UNDEF : r
     end
-
-    keep = opts[:keep_axis]
-    cnt_kw = keep ? { axis: axis, keep_axis: keep } : { axis: axis }
-    ck = ( kind == :any ) ? count(true, **cnt_kw) : count(false, **cnt_kw)
-    cm = count_masked(axis: axis)               # count_masked has no keep_axis
-    cm = cm.reshape(*ck.shape) unless cm.shape == ck.shape
-
-    # A cell is undetermined only where it is masked AND the known side does
-    # not settle it (ck counts the settling value: true for OR, false for AND).
-    # Masking only those cells avoids leaving an all-zero mask behind.
-    out = CArray.boolean(*ck.shape)
-    out[] = ( kind == :any ) ? 0 : 1            # OR default false / AND default true
-    out[ck.eq(0) & (cm > 0)] = UNDEF             # genuinely undetermined
-    out[ck > 0] = ( kind == :any ) ? 1 : 0       # known side dominates
-    out
   end
 
 end

data/lib/carray/categorical.rb

@@ -297,7 +297,7 @@ class CACategorical < CAObject
 
   # Face hook: decode a per-cell code into its category label, through the one
   # decode every code-to-label path shares (see #label_at).
-  def storage_to_scalar(raw)
+  def storage_to_element(raw)
     code = raw.is_a?(String) ? raw.unpack1(UNPACK_FORMAT.fetch(parent.data_type)) : raw
     label_at(code)
   end
@@ -317,6 +317,27 @@ class CACategorical < CAObject
   #   an all-false result.
   #   @param label [Object] category to match.
   #   @return [CArray]
+  # @overload resize(*newdim, fill_value: UNDEF)
+  #   Returns a categorical resized to `newdim` (see {CArray#resize}).
+  #   The new cells are excluded (UNDEF) unless `fill_value` names one of
+  #   the labels, since a zero code would read as the first label.
+  #   @raise [ArgumentError] when `fill_value` is not a label.
+  def resize (*newdim, fill_value: UNDEF)
+    CACategorical.from_codes(codes.resize(*newdim, fill_value: code_for_fill(fill_value)),
+                             labels)
+  end
+
+  # @overload insert_block(offset, bsize, &block)
+  #   Returns a categorical with a block inserted (see
+  #   {CArray#insert_block}). The inserted cells are excluded (UNDEF)
+  #   unless the block returns one of the labels.
+  #   @raise [ArgumentError] when the block returns something that is not
+  #     a label.
+  def insert_block (offset, bsize, &block)
+    fill = block ? code_for_fill(block.call) : UNDEF
+    CACategorical.from_codes(codes.insert_block(offset, bsize) { fill }, labels)
+  end
+
   def eq(label)
     codes.eq(@labels.index(label) || @labels.size)
   end
@@ -356,11 +377,11 @@ class CACategorical < CAObject
   #   so `labels.zip(category_sizes.to_a)` always pairs up.
   #   @return [CArray]
   def category_sizes
-    return @_category_sizes if @_category_sizes
+    return @category_sizes if @category_sizes
     bc  = codes.bincount
-    out = CArray.new(bc.data_type, [@labels.size])   # new zero-fills
+    out = CArray.new(bc.data_type, [@labels.size], bytes: bc.bytes)   # new zero-fills
     out[0...bc.elements] = bc if bc.elements > 0
-    @_category_sizes = out
+    @category_sizes = out
     out
   end
 
@@ -463,6 +484,14 @@ class CACategorical < CAObject
   # that has none. Every code-to-label path goes through here rather than
   # indexing @labels itself, because two decodes are two chances to disagree,
   # and disagreeing is how #unique came to contradict #to_a on the same cell.
+  # The code a fill value stands for: UNDEF stays UNDEF, a label is its code.
+  def code_for_fill (value)
+    return UNDEF if UNDEF.equal?(value)
+    code = labels.index(value)
+    raise ArgumentError, "#{value.inspect} is not one of the labels #{labels.inspect}" unless code
+    code
+  end
+
   def label_at (code)
     (code < 0 || code >= @labels.size) ? nil : @labels[code]
   end
@@ -541,13 +570,11 @@ class CACategorical < CAObject
   #   addresses that order the cells by category (excluded cells last).
   #   @return [CArray]
   def sort_addr
-    return @_sort_addr if @_sort_addr
+    return @sort_addr if @sort_addr
     n      = elements
     k      = @labels.size
-    cs     = category_sizes                       # per-category counts
-    nvalid = cs.sum
-    cur    = CArray.int64(k > 0 ? k : 0)          # segment starts, consumed as cursor
-    cur[1..-1] = cs.cumsum.int64[0..-2] if k > 1
+    nvalid = category_sizes.sum
+    cur    = reduceat_index.copy                  # segment starts, consumed as cursor
     flat   = codes.reshape(n)
     seq    = CArray.int64(n).seq!                 # source indices, scattered as payload
     out    = CArray.int64(n)
@@ -566,7 +593,7 @@ class CACategorical < CAObject
       excluded = excluded.or(flat.is_masked) if flat.has_mask?
       out[nvalid..-1] = seq[excluded]             # excluded cells, source order
     end
-    @_sort_addr = out
+    @sort_addr = out
     out
   end
 
@@ -581,17 +608,26 @@ class CACategorical < CAObject
   #   offsets aligned to {#labels}. Pair with {#category_sizes} for lengths.
   #   @return [CArray]
   def reduceat_index
-    return @_reduceat_index if @_reduceat_index
-    k = @labels.size
-    out = CArray.int64(k > 0 ? k : 0)
-    if k > 1
-      out[0] = 0
-      out[1..-1] = category_sizes.cumsum.int64[0..-2]
-    elsif k == 1
-      out[0] = 0
+    return @reduceat_index if @reduceat_index
+    # Every boundary but the last; the copy makes it an entity the
+    # reduceat kernels can read directly.
+    @reduceat_index = CArray.segment_offsets(lengths: category_sizes)[0...-1].copy
+  end
+
+  # @overload categorize(labels: nil, sort_labels: false)
+  #   Returns a {CACategorical} keyed on the labels, as categorizing any
+  #   key array does: the labels that occur, in first-appearance order (or
+  #   sorted with `sort_labels:`), or the fixed `labels:` vocabulary.  A
+  #   category of `self` with no cells does not carry over; a masked cell
+  #   is excluded.
+  #   @return [CACategorical]
+  def categorize (labels: nil, sort_labels: false)
+    if labels || sort_labels
+      return label_values.categorize(labels: labels, sort_labels: sort_labels)
     end
-    @_reduceat_index = out
-    out
+    # Distinctness rides the codes; only the k labels cross the surface.
+    recoded = codes.categorize
+    CACategorical.from_codes(recoded.codes, recoded.labels.map { |c| label_at(c) })
   end
 
   # @overload inspect
@@ -629,6 +665,24 @@ class CArray
   #   @return [CACategorical]
   #   @raise [ArgumentError] when explicit `labels` contain
   #     duplicates.
+  #   @raise [CArray::DataTypeError] when `sort_labels: true` discovers
+  #     the labels of a complex array, which have no order.
+  # The order sort_labels: puts two labels in: as sort orders the cells of an
+  # array, a Float NaN after every other value; two labels <=> cannot order
+  # are refused, by name.
+  private def label_order(a, b)
+    na = a.is_a?(Float) && a.nan?
+    nb = b.is_a?(Float) && b.nan?
+    return (na ? 1 : 0) - (nb ? 1 : 0) if na || nb
+    c = a <=> b
+    if c.nil?
+      raise ArgumentError,
+            "categorize(sort_labels: true): cannot order the labels " \
+            "#{a.inspect} and #{b.inspect}"
+    end
+    c
+  end
+
   def categorize(labels: nil, sort_labels: false)
     # Automatic appearance-order vocabulary: one linear pass (C
     # __factorize_appearance__) returns both codes and levels directly, over the
@@ -636,12 +690,26 @@ class CArray
     # lane). Distinctness is the hash-key judgement shared with the discovery
     # family: Float NaN collapses to one category and -0.0 == +0.0, while mixed
     # Integer / Float keys stay distinct (eql?, so 1 and 1.0 are separate
-    # categories). The discovery path below is reserved for sort_labels (which
-    # reorders the vocabulary, desyncing the appearance-order codes), an explicit
-    # labels list, and the data types the factorize kernel does not take (complex).
-    if labels.nil? && !sort_labels && (integer? || float? || object? || fixlen? || boolean?)
+    # categories). Complex values are distinct by value with the same NaN and
+    # -0.0 rules, and have no order, so sort_labels refuses them. The discovery
+    # path below is reserved for an explicit labels list.
+    if labels.nil? && sort_labels && complex?
+      raise CArray::DataTypeError,
+            "categorize(sort_labels: true): a #{data_type_name} value has no " \
+            "order (complex numbers are not ordered); without sort_labels: the " \
+            "labels are in first-appearance order"
+    end
+    if labels.nil? && (integer? || float? || complex? || object? || fixlen? || boolean?)
       codes, levels = __factorize_appearance__
-      return CACategorical.from_codes(codes, levels.to_a)
+      levels = levels.to_a
+      return CACategorical.from_codes(codes, levels) unless sort_labels
+      # Sort the k levels as Ruby sorts them, then renumber every code through
+      # the rank in one gather. The sentinel of an excluded cell is out of the
+      # rank's range, so project makes it UNDEF and from_codes writes it back.
+      order = (0...levels.size).sort { |i, j| label_order(levels[i], levels[j]) }
+      rank = CArray.new(codes.data_type, [levels.size])
+      order.each_with_index { |old, new_code| rank[old] = new_code }
+      return CACategorical.from_codes(rank.project(codes), order.map { |i| levels[i] })
     end
 
     if labels.nil?
@@ -650,7 +718,7 @@ class CArray
       # masked keys stay excluded), so the non-masked cells are the levels.
       # Only the final list is Ruby, since labels are Ruby objects.
       labels_arr = mask_duplicates[:is_not_masked].to_a
-      labels_arr.sort! if sort_labels
+      labels_arr.sort! { |a, b| label_order(a, b) } if sort_labels
     else
       labels_arr = labels.respond_to?(:to_a) ? labels.to_a : Array(labels)
       if labels_arr.uniq.size != labels_arr.size