carray 3.0.2 → 3.0.4

data/lib/carray/frame/frame.rb

@@ -11,13 +11,38 @@
 # storage, and +copy+ is the way to an independent frame.
 
 class CAFrame
+  # Raised when the contents of a column cannot be read as asked: a cell
+  # that does not read as the type a +cast+ (or +from_csv+'s +types:+) asks
+  # for under on_error: :raise, a cell +parse_to_time+ cannot read, a column
+  # whose time format +infer_time_format+ / parse_to_time(name, :infer)
+  # cannot find, or a float column +to_time+ cannot read as whole counts.
+  # The message names the column and the cell. The arguments were fine; the
+  # column's contents are what did not read.
+  class UnreadableColumn < StandardError; end
+
+  # Raised when +infer_time_format+ / parse_to_time(name, :infer) finds more
+  # than one format every cell fits ("01/02/2024" and "03/04/2024" are both
+  # day-first and month-first). The text reads in each of them, so it is
+  # not an UnreadableColumn; +formats+ gives the candidates, to choose one and
+  # pass it as the format.
+  class AmbiguousTimeFormat < StandardError
+    attr_reader :formats
+
+    def initialize(message = nil, formats: [])
+      @formats = formats
+      super(message)
+    end
+  end
+
   # Integer data_types that select rows positionally when used as a df[] key.
   INTEGER_TYPES = [:int8, :int16, :int32, :int64,
                    :uint8, :uint16, :uint32, :uint64].freeze
+  Ractor.make_shareable(INTEGER_TYPES)
   private_constant :INTEGER_TYPES
 
   # @!visibility private
   DEFAULT_AXIS_NAME = "row"
+  Ractor.make_shareable(DEFAULT_AXIS_NAME)
 
   # Build a frame from a Hash of +name => column+. Columns may be CArrays or
   # anything that answers +to_ca+ (Ruby Array, lazy view). All columns must
@@ -28,22 +53,34 @@ class CAFrame
   # y)+). +:axis_name+ / +:index+ are control options; any remaining
   # (string-keyed) options are treated as columns.
   #
-  # Column names are normalized to Strings, so a Symbol key in an explicit
-  # column hash is stringified. The Symbol rejection below applies only to the
-  # keyword channel, which doubles as the +:axis_name+ / +:index+ control-option
-  # channel: a stray Symbol there is a mistyped control option, not a column.
+  # Column names are Strings, in an explicit column hash as in inline pairs.
+  # A stray Symbol among the keywords is a mistyped control option
+  # (+:axis_name+ / +:index+), not a column, and is named as such.
+  #
+  # +types:+ casts the built frame as +from_records+ does: it takes anything
+  # +cast+ takes as a map (a name => type map, :infer, or a map with
+  # +default:+), with +on_error:+ as for +cast+. A cast column is a new array,
+  # so a CArray given for it is no longer shared with the frame.
   def initialize(columns = {}, **opts)
     axis_name = opts.delete(:axis_name)
     index     = opts.delete(:index)
-    stray = opts.keys.reject { |k| k.is_a?(String) }
-    unless stray.empty?
-      raise ArgumentError,
-            "column keys must be Strings (Symbols are reserved); got #{stray.inspect}"
+    attrs     = opts.delete(:attrs)
+    types     = opts.delete(:types)
+    on_error  = opts.key?(:on_error) ? opts.delete(:on_error) : :mask
+    opts.each_key do |k|
+      CAFrame.__send__(:column_key, k, "CAFrame.new",
+                       hint: "axis_name:, index:, attrs:, types: and on_error: are the options")
+    end
+    @attrs = nil
+    unless attrs.nil?
+      raise TypeError, "CAFrame.new: attrs: takes a Hash (got #{attrs.class})" unless attrs.is_a?(Hash)
+      set_attrs(attrs)
     end
     columns = columns.merge(opts) unless opts.empty?
 
     @columns   = {}
-    @axis_name = axis_name || DEFAULT_AXIS_NAME
+    @axis_name = axis_name.nil? ? DEFAULT_AXIS_NAME :
+                   CAFrame.__send__(:column_key, axis_name, "CAFrame.new", "axis_name:")
     @index     = nil
     # The row axis name this frame had before set_index promoted a column over
     # it, so reset_index can put it back.  A frame built with an index never
@@ -54,7 +91,8 @@ class CAFrame
     n = nil
     n_from = nil
     columns.each do |name, col|
-      key = name.to_s
+      key = column_key(name, "CAFrame.new")
+      raise ArgumentError, "CAFrame.new: a column name can not be empty" if key.empty?
       ca  = coerce_column(col)
       len = ca.shape[0]
       if n.nil?
@@ -92,6 +130,8 @@ class CAFrame
       raise ArgumentError,
             "axis_name #{@axis_name.inspect} collides with a column of the same name"
     end
+
+    cast(types, on_error: on_error, option_name: :types) unless types.nil?
   end
 
   # --- df[...] : key type decides the axis (memo §13.2) ------------------
@@ -112,7 +152,7 @@ class CAFrame
     if keys.size > 1
       unless keys.all? { |k| k.is_a?(String) }
         raise ArgumentError,
-              "multi-key df[...] escapes columns; every key must be a String " \
+              "df[...] with several keys returns columns; every key must be a String " \
               "(use df.select(...) for a subset frame)"
       end
       return keys.map { |k| @columns.fetch(k) { raise KeyError, "no column #{k.inspect}" } }
@@ -142,7 +182,7 @@ class CAFrame
               "CArray df[] key must be boolean or integer (got #{key.data_type})"
       end
     when Symbol
-      raise NotImplementedError, "df[symbol] is reserved for predicate keys"
+      raise ArgumentError, "df[symbol] is reserved for predicate keys"
     else
       raise ArgumentError, "unsupported df[] key: #{key.class}"
     end
@@ -197,6 +237,7 @@ class CAFrame
   # write path always propagates to derived views (unchanged from
   # previous behaviour).
   def []=(*keys, value)
+    refuse_if_frozen
     if keys.size != 1
       raise ArgumentError,
             "df[...] = takes one key (a column name or a row selector); " \
@@ -222,6 +263,56 @@ class CAFrame
     value
   end
 
+  # Freezing a frame fixes its columns, rows and index; the columns' cells are
+  # their own arrays' to guard, as an Array's elements are.  The check comes
+  # first so a refused edit leaves the frame as it was: the edits change the
+  # column table before any instance variable.
+  private def refuse_if_frozen
+    return unless frozen?
+    # The size, not the table: inspect prints every row.
+    size = "#{@nrow} row#{@nrow == 1 ? "" : "s"}, #{ncol} column#{ncol == 1 ? "" : "s"}"
+    raise FrozenError.new("can't modify frozen CAFrame (#{size})",
+                          receiver: self)
+  end
+
+  # Make this frame read-only and return it.  It is +freeze+ extended to the
+  # cells: the column set, the rows and the index are fixed as by +freeze+,
+  # and the cells and masks of every column and of the index refuse writes
+  # made through this frame.
+  #
+  # Each column (and the index) is replaced by a read-only view of itself, so
+  # the arrays the frame was built from are left as they were: whoever holds
+  # them can still write, and the writes show through this frame.  Frames
+  # derived from a protected frame by views (+select+, +filter+, a row slice)
+  # read through those views and refuse cell writes too, but are not frozen.
+  # +copy+ gives a frame that can be written again.
+  #
+  # Calling it on a protected frame returns the frame unchanged.  A frame
+  # frozen with +freeze+ cannot be protected afterwards, because its columns
+  # can no longer be replaced: raises +FrozenError+.
+  def protect
+    return self if protected?
+    refuse_if_frozen
+    @columns = @columns.transform_values { |col| read_only_view(col) }
+    @index   = read_only_view(@index) if @index
+    @protected = true
+    freeze
+  end
+
+  # True if this frame was made read-only by +protect+.  A +dup+ is not frozen
+  # and so not protected, though its columns stay the read-only views it
+  # shares; a +clone+ keeps both.
+  def protected?
+    frozen? && @protected == true
+  end
+
+  private def read_only_view(col)
+    return col if col.read_only?
+    view = col.refer
+    view.set_read_only_flag
+    view
+  end
+
   # df["name"] = ... : the column forms of []=.  Unlike the verbs, +[]=+ can
   # only ever mutate the receiver -- Ruby hands the right-hand side back as
   # the value of an assignment, so there is no way to return a new frame.
@@ -238,7 +329,7 @@ class CAFrame
       mask_column(key)
     elsif value.is_a?(CAFrame)
       raise ArgumentError,
-            "df[name] = takes a column, not a CAFrame; escape one with " \
+            "df[name] = takes a column, not a CAFrame; take one with " \
             "other[\"name\"], or splice rows with df[rows] = other"
     else
       rebind_column(key, value)
@@ -255,6 +346,7 @@ class CAFrame
   # leaves the old one alone (the same rule +cast+ follows, for the physical
   # reason that a type change cannot reuse the buffer).
   private def rebind_column(key, column)
+    raise ArgumentError, "df[name] =: a column name can not be empty" if key.empty?
     if @index && key == @axis_name
       raise ArgumentError,
             "#{key.inspect} names the index, not a column; " \
@@ -299,8 +391,7 @@ class CAFrame
   def select(*names)
     raise ArgumentError, "select requires at least one column name" if names.empty?
     cols = {}
-    names.each do |name|
-      key = name.to_s
+    column_keys(names, "select").each do |key|
       raise KeyError, "no column #{key.inspect}" unless @columns.key?(key)
       cols[key] = @columns[key]
     end
@@ -329,20 +420,78 @@ class CAFrame
     mask = yield(self)
     unless mask.is_a?(CArray) && mask.data_type == :boolean
       raise ArgumentError,
-            "filter block must return a boolean CArray (got #{mask.class})"
+            "filter block must return a boolean CArray (got #{mask.is_a?(CArray) ? "a #{CArray::Inspector.type_label(mask)} CArray" : mask.class})"
     end
-    unless mask.shape[0] == @nrow
+    unless mask.shape == [@nrow]
       raise ArgumentError,
-            "filter mask has axis-0 length #{mask.shape[0]}, expected nrow #{@nrow}"
+            "filter mask has shape #{mask.shape.inspect}, expected [#{@nrow}] (one value per row)"
     end
     select_rows(mask, keep_masked: keep_masked)
   end
 
+  # Judge every row against named rules, and return the verdicts as a frame:
+  #
+  #   report = df.verify(
+  #     "age is not negative" => ->(f) { f["age"] >= 0 },
+  #     "end after start"     => ->(f) { f["end"] > f["start"] },
+  #   )
+  #   df.filter { |f| report["end after start"].not }   # the rows that break it
+  #
+  # A rule is called with the frame, as a +filter+ block is, and returns a
+  # boolean CArray with one entry per row on its first axis; true means the
+  # rule holds.  A rule over an N-D column may answer per cell, in the
+  # column's own shape, so the cells that break it can be masked directly.
+  # A cell the rule could not judge -- it read a masked value -- stays
+  # UNDEF rather than becoming false.
+  #
+  # The result has one column per rule, named after it, and this frame's
+  # index and row axis name.
+  #
+  # @param rules [Hash{String => #call}] the rules by name.
+  # @return [CAFrame]
+  # @raise [ArgumentError] when there are no rules, a name is empty, or a
+  #   rule does not return a boolean CArray of this frame's length.
+  # @raise [TypeError] when a name is not a String.
+  def verify(rules)
+    unless rules.is_a?(Hash)
+      raise ArgumentError, "verify: the rules are a Hash of name => rule (got #{rules.class})"
+    end
+    raise ArgumentError, "verify: there are no rules" if rules.empty?
+    verdicts = {}
+    rules.each do |name, rule|
+      key = column_name_arg(name, "verify")
+      if @index && key == @axis_name
+        raise ArgumentError,
+              "verify: rule #{key.inspect} has the name of the row axis, " \
+              "which the index has in the result; name the rule otherwise"
+      end
+      unless rule.respond_to?(:call)
+        raise ArgumentError, "verify: rule #{key.inspect} is not callable (got #{rule.class})"
+      end
+      verdict = rule.call(self)
+      unless verdict.is_a?(CArray) && verdict.data_type == :boolean
+        raise ArgumentError,
+              "verify: rule #{key.inspect} must return a boolean CArray (got " \
+              "#{verdict.is_a?(CArray) ? "a #{verdict.data_type} CArray" : verdict.class})"
+      end
+      unless verdict.shape[0] == @nrow
+        raise ArgumentError,
+              "verify: rule #{key.inspect} returned shape #{verdict.shape.inspect}, " \
+              "expected #{@nrow} rows on the first axis"
+      end
+      verdicts[key] = verdict
+    end
+    # The verdicts are a table about the rows, not a part of this one, so the
+    # frame's attributes are not carried.
+    CAFrame.new(verdicts, axis_name: @axis_name, index: @index)
+  end
+
   # Move a column to the index and name the row axis after it (memo §3).
   # An index-role change: the data is unchanged, so this mutates self and
   # returns it (memo §3.8). Any existing index is replaced.
   def set_index(name)
-    key = name.to_s
+    refuse_if_frozen
+    key = column_key(name, "set_index")
     raise KeyError, "no column #{key.inspect}" unless @columns.key?(key)
     idx = @columns[key]
     unless idx.ndim == 1
@@ -370,6 +519,7 @@ class CAFrame
   # Also an index-role change, so it mutates self (memo §3.8). The former
   # index becomes the first column, named after the row axis.
   def reset_index
+    refuse_if_frozen
     return self unless @index
     @columns   = { @axis_name => @index }.merge(@columns)
     @index     = nil
@@ -394,7 +544,11 @@ class CAFrame
 
   # The single row whose index label equals +label+, as a Ruby Hash (memo
   # §13.2b). +label+ is matched exactly against the index (+index.eq+), so any
-  # orderable / object / datetime / categorical index works. The return type is
+  # orderable / object / datetime / categorical index works, and +label+ is
+  # whatever +index.eq+ takes -- for a time index, a Time, Date or a String
+  # such as "2024-01-02".  A NaN label finds the NaN label, as join and
+  # group_by match NaN keys.  A numeric index takes a number; a String or
+  # true / false raises. The return type is
   # a row Hash and stays that way: zero matches raise KeyError, and duplicate
   # labels raise (go through +filter { |f| f.index.eq(label) }+ for the
   # multi-row, frame-returning path). Positional access is +df[i]+.
@@ -411,16 +565,29 @@ class CAFrame
             "at(UNDEF): an undefined label identifies no row; " \
             "use filter { |f| f.index.is_masked } for the rows with no label"
     end
-    pos = @index.eq(label).where
+    # A NaN label is the NaN value, as join and group_by take it: eq answers
+    # false for NaN against anything, itself included.
+    # A numeric index is looked up with a number: a String or true/false would
+    # be read differently by each numeric type, or not at all.
+    if !@index.face? && (@index.integer? || @index.float? || @index.complex?) &&
+       !label.is_a?(Numeric)
+      raise ArgumentError,
+            "at: the index is #{@index.data_type}, so the label must be a number " \
+            "(got #{label.inspect}); convert it first, e.g. at(Float(s)) or at(Integer(s))"
+    end
+    nan = label.is_a?(Float) && label.nan?
+    hit = nan ? @index.is_in([label]) : @index.eq(label)
+    pos = hit.where
     case pos.elements
     when 0
       raise KeyError, "no row with index label #{label.inspect}"
     when 1
       row(pos[0])
     else
+      test = nan ? "f.index.is_nan" : "f.index.eq(label)"
       raise ArgumentError,
             "index label #{label.inspect} matches #{pos.elements} rows; " \
-            "use filter { |f| f.index.eq(label) } for duplicate labels"
+            "use filter { |f| #{test} } for duplicate labels"
     end
   end
 
@@ -428,7 +595,8 @@ class CAFrame
   def copy
     cols = {}
     @columns.each { |k, v| cols[k] = v.copy }
-    CAFrame.new(cols, axis_name: @axis_name, index: @index && @index.copy)
+    CAFrame.new(cols, axis_name: @axis_name, index: @index && @index.copy,
+                attrs: @attrs)
   end
 
   # +dup+ / +clone+ share the column data -- that is the CArray dup contract
@@ -439,25 +607,103 @@ class CAFrame
   private def initialize_copy(other)
     super
     @columns = @columns.dup
+    @attrs   = @attrs.dup if @attrs
+  end
+
+  # Marshal writes the instance variables as they are.  Loading stores the
+  # attribute values again as set_attr does, as frozen copies: Marshal
+  # brings back a value thawed.
+  private def marshal_dump
+    instance_variables.to_h { |name| [name, instance_variable_get(name)] }
+  end
+
+  private def marshal_load(ivars)
+    ivars.each { |name, value| instance_variable_set(name, value) }
+    if @attrs
+      @attrs = @attrs.transform_values { |v| CArray.__send__(:attr_coerce_value, v) }
+    end
+  end
+
+  # --- attributes of the frame ------------------------------------------
+  #
+  # Key/value metadata about the table as a whole (a title, a source), apart
+  # from each column's own attributes.  Keys and values follow the rules of
+  # CArray#set_attr: a Symbol or String key, stored as a String, and a
+  # JSON-compatible value, stored as a frozen copy.
+  #
+  # A frame made from this one takes its attributes when it holds the same
+  # table: a selection of rows (df[rows], filter, head, tail, sort_by,
+  # join(how: :semi / :anti)), a change of columns (select, append, drop,
+  # rename, ...), copy and dup.  A frame computed from it -- a summary, a
+  # join, a reshape -- does not; ask the frame it came from.  Each frame has
+  # its own Hash: setting an attribute on a frame made from this one leaves
+  # this one unchanged.
+
+  # The value of the attribute +key+, or nil when the frame has none.
+  def attr(key)
+    @attrs ? @attrs[CArray.__send__(:attr_normalize_key, key)] : nil
+  end
+
+  # Set the attribute +key+ to +value+ and return the stored value.
+  def set_attr(key, value)
+    refuse_if_frozen
+    CArray.__send__(:attr_validate_value, value)
+    (@attrs ||= {})[CArray.__send__(:attr_normalize_key, key)] =
+      CArray.__send__(:attr_coerce_value, value)
+  end
+
+  # Set every key of +hash+, as set_attr sets one, and return self.  Every
+  # value is checked before any is written.
+  def set_attrs(hash)
+    refuse_if_frozen
+    raise TypeError, "set_attrs takes a Hash (got #{hash.class})" unless hash.is_a?(Hash)
+    entries = hash.map do |key, value|
+      CArray.__send__(:attr_validate_value, value)
+      [CArray.__send__(:attr_normalize_key, key), CArray.__send__(:attr_coerce_value, value)]
+    end
+    unless entries.empty?
+      h = (@attrs ||= {})
+      entries.each { |k, v| h[k] = v }
+    end
+    self
+  end
+
+  # Remove the attribute +key+ and return its value, or nil.
+  def delete_attr(key)
+    k = CArray.__send__(:attr_normalize_key, key)
+    return nil unless @attrs&.key?(k)
+    refuse_if_frozen
+    @attrs.delete(k)
+  end
+
+  # A frozen Hash of the frame's attributes.
+  def attrs
+    (@attrs ? @attrs.dup : {}).freeze
+  end
+
+  # Whether the frame has any attribute, or the attribute +key+.
+  def has_attr?(key = nil)
+    return !(@attrs.nil? || @attrs.empty?) if key.nil?
+    !!@attrs&.key?(CArray.__send__(:attr_normalize_key, key))
   end
 
   # --- metadata readers (memo §13.2) ------------------------------------
   # Each returns a fresh object; the live columns Hash is never exposed.
 
-  # Variable (column) names in column order.  Returns +Array<String>+.
-  def variable_names
+  # Column names in column order.  Returns +Array<String>+.
+  def column_names
     @columns.keys
   end
 
-  # Variables (raw column CArrays) in column order.  Returns
-  # +Array<CArray>+.  Equivalent to +df[*variable_names]+ but built
-  # directly from the columns Hash.
-  def variables
+  # The columns (raw CArrays) in column order.  Returns +Array<CArray>+.
+  # Equivalent to +df[*column_names]+ but built directly from the columns
+  # Hash.
+  def columns
     @columns.values
   end
 
-  # Number of variables (columns).
-  def nvar
+  # Number of columns.
+  def ncol
     @columns.size
   end
 
@@ -470,22 +716,32 @@ class CAFrame
   # Index column (CArray) or nil.
   attr_reader :index
 
-  # name => data_type, freshly derived.
+  # name => data_type, freshly derived; a Face column gives its class
+  # (CATime, CAString, ...), since a Face's data_type is the surface its
+  # kernels dispatch on, not what the column holds.
   def data_types
     h = {}
-    @columns.each { |k, v| h[k] = v.data_type }
+    @columns.each { |k, v| h[k] = v.face? ? v.class : v.data_type }   # type-label: data_types returns the class itself, a value
     h
   end
 
+  # A frame of the same table with a different set of columns: it takes this
+  # frame's attributes.
   private def rebuild(cols)
-    CAFrame.new(cols, axis_name: @axis_name, index: @index)
+    CAFrame.new(cols, axis_name: @axis_name, index: @index, attrs: @attrs)
   end
 
+  # A column given to the frame: a CArray as it is; a Ruby Array typed by its
+  # values as from_records types a record's (build_record_column); anything
+  # else through its to_ca.
   private def coerce_column(col)
+    if col.is_a?(Array)
+      return CAFrame.__send__(:build_record_column, col, col.size)
+    end
     if col.is_a?(CAFrame)
       raise ArgumentError,
             "a CAFrame cannot be a column (it answers to_ca as a 2-D matrix); " \
-            "escape a column with df[\"name\"] or df.to_ca first"
+            "take a column with df[\"name\"] or df.to_ca first"
     end
     unless col.respond_to?(:to_ca)
       raise ArgumentError, "column must be a CArray or Array (got #{col.class})"
@@ -498,10 +754,11 @@ class CAFrame
   end
 
   private def row(i)
-    i += @nrow if i < 0
-    unless i >= 0 && i < @nrow
+    pos = i < 0 ? i + @nrow : i
+    unless pos >= 0 && pos < @nrow
       raise IndexError, "row index #{i} out of range (nrow=#{@nrow})"
     end
+    i = pos
     h = {}
     h[@axis_name] = elem_at(@index, i) if @index
     @columns.each { |name, col| h[name] = elem_at(col, i) }
@@ -562,10 +819,10 @@ class CAFrame
   # promote and the row count shifts by other.nrow - span.
   private def splice_rows(selector, other)
     lo, hi = contiguous_span(selector)
-    unless other.variable_names.sort == variable_names.sort
+    unless other.column_names.sort == column_names.sort
       raise ArgumentError,
-            "splice frame has columns #{other.variable_names.inspect}, " \
-            "expected the same set as #{variable_names.inspect}"
+            "splice frame has columns #{other.column_names.inspect}, " \
+            "expected the same set as #{column_names.inspect}"
     end
     new_cols = {}
     @columns.each do |name, col|
@@ -590,8 +847,10 @@ class CAFrame
                                                    # column beforehand — silent
                                                    # promotion in a splice would
                                                    # hide schema drift.
+      splice_keep_attrs(new_cols[name], col)
     end
     new_index = splice_index(other, lo, hi)
+    splice_keep_attrs(new_index, @index) if new_index
     @columns  = new_cols
     @index    = new_index
     # Read the new count off something the frame now holds, rather than
@@ -607,6 +866,13 @@ class CAFrame
     self
   end
 
+  # A splice edits this frame's table, so a spliced column keeps the
+  # attributes this frame's column had, whatever the rows put in carry.
+  private def splice_keep_attrs(result, own)
+    (result.attrs.keys - own.attrs.keys).each { |k| result.delete_attr(k) }
+    result.set_attrs(own.attrs)
+  end
+
   # The index for a splice: head + other's index + tail. When this frame has
   # an index, the spliced-in frame must have one too (its rows need labels).
   private def splice_index(other, lo, hi)
@@ -684,18 +950,27 @@ class CAFrame
       cols[name] = col[selector, *([nil] * (col.ndim - 1))]
     end
     new_index = @index ? @index[selector] : nil
-    CAFrame.new(cols, axis_name: @axis_name, index: new_index)
+    CAFrame.new(cols, axis_name: @axis_name, index: new_index, attrs: @attrs)
   end
 
   private def select_rows_keep_masked(selector)
     keep       = selector.strip_mask(1)   # true where selected OR undetermined
     undet_kept = selector.is_masked[keep] # among kept rows, which were undetermined
     cols = {}
+    any_undet = undet_kept.any
     @columns.each do |name, col|
       tail = [nil] * (col.ndim - 1)
-      g = col[keep, *tail].copy
-      g[undet_kept, *tail] = UNDEF
-      cols[name] = g
+      g = col[keep, *tail]
+      if any_undet
+        # mask_where copies and masks in one step, so a read-only Face
+        # (categorical, CAConstString) takes the mask as any column does.
+        cells = CArray.boolean(*g.shape)
+        cells[] = false
+        cells[undet_kept, *tail] = true
+        cols[name] = g.mask_where(cells)
+      else
+        cols[name] = g.copy
+      end
     end
     # The index is copied along with the columns. Its values are carried over
     # unmasked (an undetermined row keeps its label, as mask_rows leaves the
@@ -703,8 +978,57 @@ class CAFrame
     # aliased index would write through to the parent from a frame whose columns
     # do not.
     new_index = @index ? @index[keep].copy : nil
-    CAFrame.new(cols, axis_name: @axis_name, index: new_index)
+    CAFrame.new(cols, axis_name: @axis_name, index: new_index, attrs: @attrs)
+  end
+
+  # A column name given as an argument: a String, as the frame's column
+  # keys are. Symbols are the frame's options and types, never names.
+  private def column_key(name, verb)
+    CAFrame.__send__(:column_key, name, verb)
+  end
+
+  # A name a verb is given for a column -- or, with +what+, for the row
+  # axis -- is a String: a Symbol is a frame's option or type, never a
+  # name.  Anything else is refused with TypeError "<verb>: <what> is a
+  # String (got :x)", +hint+ appended.  A +verb+ that is an option, as
+  # "types:", already ends in its colon.
+  def self.column_key(name, verb, what = "a column name", hint: nil)
+    return name if name.is_a?(String)
+    message = "#{verb.end_with?(":") ? verb : "#{verb}:"} #{what} is a String (got #{name.inspect})"
+    message += "; #{hint}" if hint
+    raise TypeError, message
+  end
+  private_class_method :column_key
+
+  # A list of column names as a verb takes them: each a String, and none
+  # twice.
+  private def column_keys(names, verb)
+    CAFrame.__send__(:refuse_repeated_names, names.map { |n| column_key(n, verb) }, verb)
+  end
+
+  # Column names a verb makes or takes, none of them twice.  A frame holds
+  # one column per name, so a repeated name among new columns would keep
+  # only the last of them, and among the columns a verb takes would be
+  # taken once or twice depending on the verb.  Refused with ArgumentError
+  # "<verb>: <what> <name> more than once", +hint+ appended.  df[...] alone
+  # takes a name twice, as Hash#values_at does.
+  def self.refuse_repeated_names(names, verb, what = "names", hint: nil)
+    dup = names.tally.find { |_, count| count > 1 }
+    return names unless dup
+    message = "#{verb}: #{what} #{dup.first.inspect} more than once"
+    message += "; #{hint}" if hint
+    raise ArgumentError, message
+  end
+  private_class_method :refuse_repeated_names
+
+  # The labels an index is made of from a key -- a group's first values,
+  # the resample bins, the sorted pivot keys -- as the key column shows
+  # them: +labels+, already of the key's data type, Face and unit, given
+  # the key's attributes.  Returns +labels+.
+  def self.key_labels(key, labels)
+    key.__send__(:carry_attrs, labels)
   end
+  private_class_method :key_labels
 
   private def positional_range?(range)
     (range.begin.nil? || range.begin.is_a?(Integer)) &&