carray 3.0.1 → 3.0.2

data/lib/carray/autoload_method_extension.rb

@@ -32,6 +32,7 @@ module AutoloadMethodExtension
   private
 
   def autoload_define (target, name, library, original_spec)
+    stub = nil
     target.define_method(name) do |*args, **kwargs, &block|
       begin
         require library
@@ -39,7 +40,18 @@ module AutoloadMethodExtension
         raise "error in autoloading '#{library}' hooked by method " \
               "'#{original_spec}', check gem installation."
       end
+      # The require is supposed to have replaced this stub with the real
+      # definition. If it has not, the method does not exist anywhere, and
+      # forwarding would land straight back here and keep doing so until the
+      # stack gave out -- naming neither the method nor the library. Say
+      # which, once.
+      if target.instance_method(name) == stub
+        raise NoMethodError,
+              "'#{original_spec}' is registered for autoload from " \
+              "'#{library}', but that library defines no such method"
+      end
       send(name, *args, **kwargs, &block)
     end
+    stub = target.instance_method(name)
   end
 end

data/lib/carray/axis_group.rb

@@ -308,7 +308,72 @@ end
 # / min / max / variance / stddev / variancep / stddevp / count /
 # count_not_masked / all / any) bind in C to one driver; the rest of the common
 # iterator surface that composes cheaply from those is added here.
+# CAGroupIterator subclasses CAIterator, but the class itself is created in
+# C, so the reopening below carries no superclass for YARD to read.
+# @!parse class CAGroupIterator < CAIterator; end
 class CAGroupIterator
+  # The shape one value per piece comes back in: a group slot contributes its
+  # category count, a band slot its length, in slot order. The base declares
+  # these and every other member answers them; this one inherited the readers
+  # without anything ever setting the ivars, so it answered nil -- which the
+  # base's own rule calls out as the one thing a member must not do ("a clean
+  # NotImplementedError, never a wrong answer").
+  def shape
+    spec.slot_meta.map { |m| m[:kind] == :group ? m[:k] : m[:len] }
+  end
+  alias dim shape
+
+  def ndim
+    spec.nslots
+  end
+
+  # The C dispatcher every reduction shares takes keywords only, so the
+  # value-equality and masked forms the base declares -- count(v), count(UNDEF)
+  # -- arrived as "wrong number of arguments", which reads as a method that
+  # does not take one rather than one whose engine has no such fold. Both are
+  # composed here instead, out of folds the engine does have.
+  alias __count_present__ count
+
+  # @overload count
+  #   Per-group count of present (non-masked) cells.
+  # @overload count(UNDEF)
+  #   Per-group count of masked cells, as {#count_masked}.
+  # @overload count(v)
+  #   Per-group count of cells equal to `v`.
+  #   @return [CArray]
+  def count (*args, **kw)
+    return __count_present__(**kw) if args.empty?
+    if args.size > 1
+      raise ArgumentError, "wrong number of arguments (given #{args.size}, expected 0..1)"
+    end
+    v = args.first
+    return count_masked(**kw) if v.equal?(UNDEF)
+    # a masked cell equals nothing, and eq marks it UNDEF; drop that to false
+    # so it is simply not counted
+    hit = value.eq(v)
+    hit = hit.strip_mask(false) if hit.has_mask?
+    self.class.__build__(hit.int64, spec).sum(**kw).int64
+  end
+
+  alias __all_folded__ all
+  alias __any_folded__ any
+
+  # @overload all
+  #   Per-group `all` over a boolean payload.
+  #   @return [CArray]
+  def all (**kw)
+    boolean_payload!(:all)
+    __all_folded__(**kw)
+  end
+
+  # @overload any
+  #   Per-group `any` over a boolean payload.
+  #   @return [CArray]
+  def any (**kw)
+    boolean_payload!(:any)
+    __any_folded__(**kw)
+  end
+
   # Per-group classified cell count (mask-independent) = count on the
   # mask-stripped value, so every classified cell is counted regardless of the
   # value mask (unlike count / count_not_masked, which count present cells).
@@ -549,6 +614,18 @@ class CAGroupIterator
   # (the shape a length-K result reshapes to). This is the classification the C
   # scatter kernel computes on the fly, materialised once so the order
   # statistics / iterate / sort_addr can hold each group's members together.
+  # Whether a payload folds with all / any is the core's call, not this
+  # engine's. The engine counts any non-zero numeric cell as true, which made
+  # the group the one member of the family that answered where CArray#all and
+  # every sibling refuse -- so `data.all` and `data[g].all(axis: :group)` on
+  # the same float array disagreed about whether the question was even
+  # askable. Asking a one-cell array of the same data type lets the core's own
+  # refusal through, unworded by us.
+  def boolean_payload! (op)
+    CArray.new(value.data_type, [1]).public_send(op)
+    nil
+  end
+
   def composite_layout
     gslots = spec.slot_meta.select { |m| m[:kind] == :group }
     bslots = spec.slot_meta.select { |m| m[:kind] == :band }

data/lib/carray/basics.rb

@@ -159,6 +159,10 @@ end
   #   @raise [ArgumentError] when `offset.length != self.ndim`.
   def paste (offset, src)
     raise ArgumentError, "offset length must equal ndim" if offset.length != ndim
+    # A zero-length source covers no cell, so there is nothing to write --
+    # and the empty range it would ask for is not a window CAWindow can
+    # build.  This is what lets concatenate / mosaic take an empty piece.
+    return self if src.elements.zero?
     ranges = offset.each_with_index.map { |o, i| o...(o + src.shape[i]) }
     self.window(*ranges)[] = src
     self

data/lib/carray/block_iterator.rb

@@ -197,16 +197,92 @@ class CABlockIterator < CAIterator
   # 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
-  # @overload 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), so a tile count over `uint8` cells
-  #   stays one byte wide instead of eight.
+  # @!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
-  # The rest are analogous: prod / mean / min / max, sample and population
-  # variance / stddev, all / any.
   [: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|
@@ -279,11 +355,11 @@ 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|
@@ -530,19 +606,19 @@ class CABlockIterator < CAIterator
   # 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
+  # @!method cummax
   #   Per-tile inclusive running maximum (value data type), source-shaped.
   #   @return [CArray]
-  # @overload cummin
+  # @!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|

data/lib/carray/categorical.rb

@@ -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
@@ -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.