carray 3.0.0 → 3.0.2

data/lib/carray/block_iterator.rb

@@ -19,7 +19,7 @@
 #  is a `block_view` (a CAStride: zero-copy over the source via compose-fold),
 #  reduced over the trailing tile axes by a core reduction and scattered into the
 #  ceil-shaped tile grid.  One core reduction per region; the named reductions
-#  delegate straight to the core, so their dtype / mask / empty (ERI) / epsilon
+#  delegate straight to the core, so their data type / mask / empty (ERI) / epsilon
 #  contracts are the core's, unchanged.  Because tiles do not overlap, no
 #  padded entity is built (unlike CAWindowIterator) and the interior stays on
 #  the source buffer.
@@ -165,7 +165,7 @@ class CABlockIterator < CAIterator
   # quantile) which are assembled into that many grids.  Boundary regions use a
   # smaller (unmasked, ragged) block_view whose present cell count is naturally
   # below a full tile, so `min_count:` marks them UNDEF with no masking.  The
-  # output dtype is seeded from the first region (all regions share it).
+  # output data type is seeded from the first region (all regions share it).
   def assemble
     outs = nil
     each_region do |strip_ranges, tiles, out_ranges|
@@ -184,7 +184,7 @@ class CABlockIterator < CAIterator
 
   # Fold every region with a single core reduction `op` (the tier-1 shape).
   def fold (op, **kw)
-    assemble { |view, _tiles| view.send(op, axis: @tile_axes, **kw) }
+    assemble { |view, _tiles| view.public_send(op, axis: @tile_axes, **kw) }
   end
 
   public
@@ -194,14 +194,96 @@ class CABlockIterator < CAIterator
   # A per-tile fold to one value over the trailing tile axes is exactly a core
   # per-axis reduction over those axes, so every reduction delegates to
   # `block_view.<op>(axis: tile_axes, ...)` per region.  This inherits the core
-  # dtype, mask, empty / all-masked (identity vs UNDEF) and epsilon-close
+  # data type, mask, empty / all-masked (identity vs UNDEF) and epsilon-close
   # contracts unchanged.  `min_count:` / `fill_value:` pass straight to the core.
 
-  # @overload sum(min_count: nil, fill_value: nil)
-  #   Per-tile sum.  @return [CArray] tile-grid shaped
-  # The rest are analogous: prod / mean / min / max, sample and population
-  # variance / stddev, all / any.
-  [:sum, :prod, :mean, :min, :max, :variance, :stddev, :all, :any,
+  # @!method sum(min_count: nil, fill_value: nil)
+  #   Per-tile sum.
+  #   @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.
+  #   @return [CArray] tile-grid shaped
+  # @!method accumulate(min_count: nil, fill_value: nil)
+  #   Per-tile sum kept in the source's own data type, wrapping at its
+  #   width, as the core `accumulate` does -- `sum` answers in the type
+  #   the core promotes to (float64 for integers).
+  #   @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.
+  #   @return [CArray] tile-grid shaped
+  # @!method prod(min_count: nil, fill_value: nil)
+  #   Per-tile product.
+  #   @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.
+  #   @return [CArray] tile-grid shaped
+  # @!method mean(min_count: nil, fill_value: nil)
+  #   Per-tile arithmetic mean.
+  #   @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.
+  #   @return [CArray] tile-grid shaped
+  # @!method min(min_count: nil, fill_value: nil)
+  #   Per-tile minimum.
+  #   @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.
+  #   @return [CArray] tile-grid shaped
+  # @!method max(min_count: nil, fill_value: nil)
+  #   Per-tile maximum.
+  #   @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.
+  #   @return [CArray] tile-grid shaped
+  # @!method variance(min_count: nil, fill_value: nil)
+  #   Per-tile sample variance (divisor `n - 1`).
+  #   @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.
+  #   @return [CArray] tile-grid shaped
+  # @!method stddev(min_count: nil, fill_value: nil)
+  #   Per-tile sample standard deviation (divisor `n - 1`).
+  #   @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.
+  #   @return [CArray] tile-grid shaped
+  # @!method all(min_count: nil, fill_value: nil)
+  #   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.
+  #   @return [CArray] tile-grid shaped
+  # @!method any(min_count: nil, fill_value: nil)
+  #   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.
+  #   @return [CArray] tile-grid shaped
+  # @!method variancep(min_count: nil, fill_value: nil)
+  #   Per-tile population variance (divisor `n`).
+  #   @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.
+  #   @return [CArray] tile-grid shaped
+  # @!method stddevp(min_count: nil, fill_value: nil)
+  #   Per-tile population standard deviation (divisor `n`).
+  #   @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.
+  #   @return [CArray] tile-grid shaped
+  [:sum, :accumulate, :prod, :mean, :min, :max, :variance, :stddev, :all, :any,
    :variancep, :stddevp].each do |op|
     define_method(op) do |min_count: nil, fill_value: nil|
       kw = {}
@@ -273,15 +355,19 @@ class CABlockIterator < CAIterator
     assemble { |view, _| view.minmax(axis: @tile_axes, **kw) }
   end
 
-  # @overload min_index
+  # @!method min_index
   #   Per-tile position of the minimum, as a flat index within the tile (a
   #   partial edge tile indexes within its own present cells).
   #   @return [CArray] tile-grid shaped
-  # @overload max_index
+  # @!method max_index
   #   Per-tile position of the maximum (tile-local flat index).
   #   @return [CArray]
   [:min_index, :max_index].each do |op|
-    define_method(op) { assemble { |view, _| view.send(op, axis: @tile_axes) } }
+    class_eval <<~RUBY, __FILE__, __LINE__ + 1
+      def #{op}
+        assemble { |view, _| view.#{op}(axis: @tile_axes) }
+      end
+    RUBY
   end
 
   # @overload min_addr
@@ -309,7 +395,7 @@ class CABlockIterator < CAIterator
     each_region do |strip_ranges, tiles, out_ranges|
       vview = @source[*strip_ranges].block_view(*tiles)
       sview = saddr[*strip_ranges].block_view(*tiles)
-      mi    = vview.send(idx_op, axis: @tile_axes)         # tile-local flat index
+      mi    = vview.public_send(idx_op, axis: @tile_axes)  # tile-local flat index
       grid  = (0...@sndim).map { |i| vview.shape[i] }
       cells = tiles.inject(1) { |p, t| p * t }
       safe  = mi.copy
@@ -380,7 +466,7 @@ class CABlockIterator < CAIterator
       wt     = tiles == @sizes ? weights : weights[*tiles.map { |t| 0...t }]
       wshape = ([1] * @sndim) + tiles
       # Pass the weights through unchanged, like the window iterator: core wsum /
-      # wmean own weight/dtype coercion, so do not pre-coerce the weights here.
+      # wmean own weight / type coercion, so do not pre-coerce the weights here.
       wfull  = wt.reshape(*wshape).broadcast_to(*view.shape)
       yield view, wfull
     end
@@ -516,23 +602,23 @@ class CABlockIterator < CAIterator
   # reusing the same padded (masked-margin) entity as the iterate escape
   # hatches, so this is the slow path (a per-tile materialize), and the
   # out-of-bounds cells of a partial edge tile are dropped from the result.
-  # cumsum / cumprod -> float64, cummax / cummin preserve the value dtype,
-  # cumcount -> int64 running count of present cells; the output dtype is seeded
+  # cumsum / cumprod -> float64, cummax / cummin preserve the value data type,
+  # cumcount -> int64 running count of present cells; the output data type is seeded
   # from the first tile's scan.
 
-  # @overload cumsum
+  # @!method cumsum
   #   Per-tile inclusive running sum (float64), source-shaped.
   #   @return [CArray]
-  # @overload cumprod
+  # @!method cumprod
   #   Per-tile inclusive running product (float64), source-shaped.
   #   @return [CArray]
-  # @overload cummax
-  #   Per-tile inclusive running maximum (value dtype), source-shaped.
+  # @!method cummax
+  #   Per-tile inclusive running maximum (value data type), source-shaped.
   #   @return [CArray]
-  # @overload cummin
-  #   Per-tile inclusive running minimum (value dtype), source-shaped.
+  # @!method cummin
+  #   Per-tile inclusive running minimum (value data type), source-shaped.
   #   @return [CArray]
-  # @overload cumcount
+  # @!method cumcount
   #   Per-tile running count of present cells (int64), source-shaped.
   #   @return [CArray]
   [:cumsum, :cumprod, :cummax, :cummin, :cumcount].each do |op|
@@ -542,7 +628,7 @@ class CABlockIterator < CAIterator
   private
 
   # Drive a within-tile segment scan: scan each tile flattened row-major and
-  # scatter back to a source-shaped result.  The output dtype is taken from the
+  # scatter back to a source-shaped result.  The output data type is taken from the
   # first tile's scan (all tiles share it); the padded margin is UNDEF and the
   # OOB cells of a partial edge tile are cropped from the result.
   def block_scan (op)
@@ -552,7 +638,7 @@ class CABlockIterator < CAIterator
     pgv  = nil
     CArray.each_index(*@shape) do |*g|
       tile    = tgv[*g, *nils]
-      scanned = tile.copy.reshape(tile.elements).send(op).reshape(*@sizes)
+      scanned = tile.copy.reshape(tile.elements).public_send(op).reshape(*@sizes)
       unless pout
         pout = CArray.new(scanned.data_type, padded_source.shape)
         pout[] = UNDEF

data/lib/carray/categorical.rb

@@ -2,7 +2,7 @@
 #
 #  carray/categorical.rb
 #
-#  CACategorical — a categorical dtype: dense integer codes (the storage) plus
+#  CACategorical — a categorical data type: dense integer codes (the storage) plus
 #  a label vocabulary. Structurally the same as a pandas Categorical or an
 #  Arrow dictionary: each element is an index into a small set of categories.
 #
@@ -17,8 +17,12 @@
 #                         (per-category counts), `cat.codes.count(code)`, etc.
 #    - per-cell access  = decode the code into its label (`cat[i]` -> category)
 #
-#  Exclusion (missing / out-of-vocabulary) is encoded two ways at once, and
-#  because the Face is READONLY they can never desync:
+#  Exclusion (missing / out-of-vocabulary) is encoded two ways at once. Both
+#  are written when the categorical is built — categorize produces them, and
+#  from_codes normalises whatever it receives into them — and the Face is
+#  READONLY afterwards, so they stay in step. Both are needed because they have
+#  different readers: the axis-group kernel classifies on the code byte, the
+#  materialising paths classify on the mask.
 #
 #    - the cell is MASKED                  -> CArray-native idiom: `cat[i]` is
 #                                             UNDEF, `is_masked` / mask-aware
@@ -66,7 +70,7 @@ class CACategorical < CAObject
   }.freeze
 
   # The exclusion sentinel per codes data_type: the all-ones bit pattern, read
-  # as type-max for an unsigned dtype and as -1 for a signed one. Either way it
+  # as type-max for an unsigned data type and as -1 for a signed one. Either way it
   # is out of every valid [0, k) range and byte-identical to a pandas / Arrow
   # missing code.
   SENTINEL = {
@@ -76,46 +80,148 @@ class CACategorical < CAObject
     CA_UINT64 => 0xFFFFFFFFFFFFFFFF, CA_INT64 => -1,
   }.freeze
 
+  # The largest vocabulary each codes data type can carry: every valid code in
+  # 0...k has to be representable AND distinct from the exclusion sentinel.  An
+  # unsigned type spends its top value on the sentinel; a signed one spends -1,
+  # which was never a valid index, so a signed type carries one more label than
+  # the unsigned type of the same width.  categorize picks a width by this rule
+  # when it builds codes; from_codes has to check it when it receives them.
+  MAX_LABELS = {
+    CA_UINT8  => 0xFF,               CA_INT8  => 0x80,
+    CA_UINT16 => 0xFFFF,             CA_INT16 => 0x8000,
+    CA_UINT32 => 0xFFFFFFFF,         CA_INT32 => 0x80000000,
+    CA_UINT64 => 0xFFFFFFFFFFFFFFFF, CA_INT64 => 0x8000000000000000,
+  }.freeze
+
   class << self
     # Wrap already-dense codes + labels with no discovery — the import receiver
-    # for a pandas Categorical or an Arrow dictionary. `codes` becomes the
-    # Face's storage parent verbatim (zero-copy when it is a wrapped memory
-    # view), and from_codes takes ownership of it.
+    # for a pandas Categorical or an Arrow dictionary. from_codes takes
+    # ownership of `codes`, which becomes the Face's storage parent: verbatim
+    # when it is an entity that needs no rewriting, so a wrapped memory view
+    # stays a view, and materialised when it is a view over an array the caller
+    # still holds, since a view owns no bytes to take ownership of.
+    #
+    # This is the one door through which an already-built encoding enters, so
+    # it validates rather than assumes, and it normalises before handing over:
+    # a cell is excluded when it arrives masked OR holds the all-ones sentinel
+    # (type-max for unsigned codes, -1 for signed — both the pandas / Arrow
+    # missing code), and every excluded cell leaves here holding the sentinel
+    # AND masked. Writing both matters because the two encodings have different
+    # readers: the axis-group kernel classifies on the code byte, the
+    # materialising paths classify on the mask. A categorical that carries only
+    # one of them answers membership two ways, silently. An Arrow dictionary
+    # carries its missingness in a validity bitmap with arbitrary code bytes —
+    # frequently 0 — so arriving masked-only is the normal import, not an edge.
     #
-    # Excluded cells are identified by the all-ones sentinel value (type-max
-    # for unsigned codes, -1 for signed — both the pandas / Arrow missing code)
-    # and masked here, so the categorical is well-formed regardless of whether
-    # the caller pre-masked. Only the mask buffer is touched; the code bytes
-    # are left intact (so a pandas byte-reinterpret round-trips).
+    # #initialize marks the codes read-only, so this is also the last point at
+    # which they can be written; a read-only argument is copied rather than
+    # refused.
     # @overload from_codes(codes, labels)
     #   Returns a {CACategorical} wrapping already-dense integer
     #   `codes` with the given `labels`, without discovery. `codes`
-    #   becomes the Face's storage parent; excluded cells (identified
-    #   by the type-max sentinel value) are masked automatically.
+    #   becomes the Face's storage parent, materialised first if it is
+    #   a view. A cell that is masked or holds the type-max sentinel is
+    #   excluded, and leaves as both.
     #   @param codes [CArray] integer code storage.
     #   @param labels [Array, CArray] category vocabulary indexed by
-    #     code.
+    #     code. Must be unique, and must fit the codes data type with
+    #     the sentinel reserved.
     #   @return [CACategorical]
-    #   @raise [ArgumentError] when `codes` is not an integer CArray.
+    #   @raise [ArgumentError] when `codes` is not an integer CArray,
+    #     when `labels` holds duplicates or is too large for the codes
+    #     data type, or when an unmasked code is outside `0...labels.size`
+    #     and is not the sentinel.
     def from_codes(codes, labels)
       unless codes.is_a?(CArray) && SENTINEL.key?(codes.data_type)
         got = codes.is_a?(CArray) ? codes.data_type : codes.class
         raise ArgumentError, "from_codes: codes must be an integer CArray (got #{got})"
       end
-      excluded = codes.eq(SENTINEL[codes.data_type])
-      if excluded.count(true) > 0
-        codes.mask = codes.has_mask? ? (codes.mask | excluded) : excluded
+
+      labels_arr = labels.respond_to?(:to_a) ? labels.to_a : Array(labels)
+      if labels_arr.uniq.size != labels_arr.size
+        raise ArgumentError, "from_codes: labels must be unique (got duplicates)"
+      end
+      k        = labels_arr.size
+      sentinel = SENTINEL[codes.data_type]
+      max      = MAX_LABELS[codes.data_type]
+      if k > max
+        raise ArgumentError,
+              "from_codes: #{k} labels do not fit #{CArray.data_type_name(codes.data_type)} " \
+              "codes, which carry at most #{max} (the top value is reserved as the " \
+              "exclusion sentinel); widen the codes data type"
+      end
+
+      # Classify on the code bytes with the mask set aside (`.value`): a
+      # comparison against a masked cell yields UNDEF, which would read as
+      # "not excluded" and let the cell through carrying a valid-looking code.
+      raw = codes.value
+      if sentinel == -1                 # signed codes: -1 is the sentinel
+        out = raw.lt(0)
+        # Only test the upper bound when k is representable in the codes data
+        # type. At the very top of the range (k == max) no value can reach k
+        # anyway, and comparing against an unrepresentable literal would wrap
+        # and flag every cell as out of range.
+        out = out | raw.ge(k) if k <= max - 1
+      else                              # unsigned codes: type-max is the sentinel
+        out = raw.ge(k)                 # k <= max here, so always representable
+      end
+      masked   = codes.has_mask? ? codes.is_masked : nil
+      excluded = masked ? (out | masked) : out
+      # A masked cell may hold any byte at all — that is the CArray contract —
+      # so it is never corrupt, only in need of normalising. An *unmasked* cell
+      # holding an out-of-range code that is not the sentinel is neither a
+      # category nor missingness; refuse it here, where the input is still in
+      # the caller's hands, instead of letting it surface later as an IndexError
+      # from the grouping plan or as a wrong label from a decode.
+      corrupt = out & raw.ne(sentinel)
+      corrupt = corrupt & masked.not if masked
+      if corrupt.any
+        bad = raw[corrupt].to_a.uniq.sort
+        shown = bad.first(4).join(", ") + (bad.size > 4 ? ", ..." : "")
+        raise ArgumentError,
+              "from_codes: code#{bad.size == 1 ? "" : "s"} #{shown} outside " \
+              "0...#{k} for #{k} label#{k == 1 ? "" : "s"} " \
+              "(use #{sentinel} to exclude a cell, or mask it)"
+      end
+
+      # Take real ownership, then normalise so the byte reader and the mask
+      # reader agree from here on.
+      #
+      # A view owns no bytes — its root does, and the caller still holds that
+      # root. #initialize marks what it is given read-only, which would stop
+      # `cat.codes[i] = x` but not `root[i] = x`, so the codes could still
+      # change underneath a Face that is supposed to be immutable (and
+      # underneath the grouping plan memoised against them). Marking the root
+      # instead is worse: it would freeze bytes outside the window the caller
+      # handed over. So a view is materialised. Read-only codes are copied for
+      # the adjacent reason — the normalising writes need somewhere to land.
+      #
+      # An entity that needs no rewriting is adopted verbatim, which is what
+      # keeps a wrapped memory view a view. That buffer's producer can still
+      # write it; that is the borrowed-buffer bargain, and not something this
+      # constructor can close.
+      needs_mask = masked ? (excluded & masked.not).any : excluded.any
+      needs_byte = (excluded & raw.ne(sentinel)).any
+      if !codes.entity? || ((needs_mask || needs_byte) && codes.read_only?)
+        codes = codes.copy
       end
-      new(codes, labels)
+      if needs_mask || needs_byte
+        codes.value[excluded] = sentinel if needs_byte
+        codes.mask = excluded
+      end
+
+      new(codes, labels_arr)
     end
   end
 
-  # codes : integer CArray, the storage parent. Excluded cells are both
-  #         masked AND store the type-max sentinel value (= the all-ones bit
-  #         pattern, which is signed -1 byte-for-byte — the pandas / Arrow
-  #         missing code). Because the Face is READONLY the two never desync,
-  #         so consumers may rely on either: the mask (CArray-native) or the
-  #         sentinel (axis-group's out-of-range skip, zero-copy export).
+  # codes : integer CArray, the storage parent, already normalised by the
+  #         caller (categorize builds it that way; from_codes rewrites what it
+  #         receives). Excluded cells are both masked AND store the type-max
+  #         sentinel value (= the all-ones bit pattern, which is signed -1
+  #         byte-for-byte — the pandas / Arrow missing code). Marking the codes
+  #         read-only below keeps the two in step from here on, so consumers may
+  #         rely on either: the mask (CArray-native) or the sentinel
+  #         (axis-group's out-of-range skip, zero-copy export).
   # labels: Array | CArray, the vocabulary; labels[code] = category.
   # @overload initialize(codes, labels)
   #   Allocates a READONLY {CACategorical} Face whose storage is
@@ -143,8 +249,9 @@ class CACategorical < CAObject
     # through views/Faces (a reshape of frozen codes is frozen) and would block
     # the grouping cache from memoising. The flag gives the same write protection
     # (mutations raise) while keeping the object non-frozen. One-way: it takes
-    # ownership of `codes` (categorize / from_codes build or receive it, mask
-    # already derived above); a caller keeping a mutable array must pass `.copy`.
+    # ownership of `codes`, which from_codes has already validated, materialised
+    # if it was a view, and normalised; a caller keeping a mutable entity of its
+    # own must pass `.copy`.
     codes.set_read_only_flag
   end
 
@@ -188,12 +295,11 @@ class CACategorical < CAObject
     other.is_a?(CACategorical) && @labels == other.labels
   end
 
-  # Face hook: decode a per-cell code into its category label. An out-of-range
-  # code (e.g. an unmasked external sentinel) decodes to nil rather than a
-  # wrong category via Ruby negative indexing.
+  # 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)
     code = raw.is_a?(String) ? raw.unpack1(UNPACK_FORMAT.fetch(parent.data_type)) : raw
-    (code < 0 || code >= @labels.size) ? nil : @labels[code]
+    label_at(code)
   end
 
   # ---- category-space operations (by label, not code) -------------------
@@ -350,10 +456,21 @@ class CACategorical < CAObject
 
   private
 
-  # Labels for a code array (the discovery kernels skip masked cells, so the
-  # code arrays reaching here hold real codes only).
+  # The one decode from a code to its label. An out-of-range code — a negative
+  # one, or an unmasked sentinel that reached us from outside — has no label,
+  # so it decodes to nil. Writing `@labels[code]` instead would read a negative
+  # code from the *end* of the vocabulary and hand back a real label for a cell
+  # 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.
+  def label_at (code)
+    (code < 0 || code >= @labels.size) ? nil : @labels[code]
+  end
+
+  # Labels for a code array. The discovery kernels skip masked cells, so what
+  # reaches here is real codes — but it is decoded like any other code.
   def labels_for (code_array)
-    CA_OBJECT(code_array.to_a.map { |c| @labels[c] })
+    CA_OBJECT(code_array.to_a.map { |c| label_at(c) })
   end
 
   # This categorical's cells as their labels; a masked cell stays masked.
@@ -521,7 +638,7 @@ class CArray
     # 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 dtypes the factorize kernel does not take (complex).
+    # labels list, and the data types the factorize kernel does not take (complex).
     if labels.nil? && !sort_labels && (integer? || float? || object? || fixlen? || boolean?)
       codes, levels = __factorize_appearance__
       return CACategorical.from_codes(codes, levels.to_a)
@@ -541,7 +658,7 @@ class CArray
       end
     end
 
-    # Choose a narrow unsigned code dtype, reserving its top value as the
+    # Choose a narrow unsigned code type, reserving its top value as the
     # exclusion sentinel so it never collides with a real code 0..k-1.
     k = labels_arr.size
     code_type, sentinel =