carray 3.0.5 → 3.0.6

data/lib/carray/frame/join.rb

@@ -29,9 +29,27 @@ class CAFrame
   #                 right row.
   #
   # Rows come in left-row order (right-row order for :right), the pairs of
-  # one row in the other side's order.  The left columns are views of this
-  # frame's, picked by row, wherever every row comes from the left (:left,
-  # :inner); the right columns are gathered into new arrays.
+  # one row in the other side's order.  A side whose row every result row
+  # has gives views of its columns, picked by row: this frame's for :left
+  # and :inner, +other+'s for :inner and :right (for :right, the key column
+  # too).  A
+  # write to the result then reaches that frame, and reading the result
+  # gathers through the views each time; call +copy+ on the result for
+  # columns of its own, when it will be written or read many times.  The
+  # side that gets UNDEF for an unmatched row is gathered into new arrays.
+  #
+  # The views are for cleaning data through the join, on frames read in as
+  # working copies just before an analysis: a condition built from both
+  # frames' columns masks or corrects the cells it marks, and the write
+  # lands in the frame they came from.  +view: :full+ (experimental)
+  # makes the other side views too, so a write reaches either frame, with a
+  # hole where a row has no match: the hole reads UNDEF and a write to it is
+  # dropped.  Every result column then reaches its frame, at a cost on each
+  # read (a column with holes is gathered whole: a reduction is about
+  # three times slower than on a column of its own, a +copy+ five to ten).  The key of an outer join welds the two key
+  # columns (+CArray.meld+), so it needs keys of one kind on both sides, the
+  # same type and, for a Face, the same state (time unit, labels); a key of
+  # +CAConstString+ cannot be welded.
   #
   # A non-key column present on both sides collides. The key column (+on+) is
   # kept once, never suffixed. By default the collision is resolved by suffixing
@@ -41,8 +59,12 @@ class CAFrame
   #
   # +on:+ may name several columns, as an Array: rows then match when every
   # key column matches, and a row with any key cell masked matches nothing.
+  # When the key has different names on the two sides, give a Hash of this
+  # frame's name to +other+'s; the key column keeps this frame's name, and
+  # +other+'s key column is not added.
   #
   #   obs.join(fcst, on: ["station", "date"])
+  #   obs.join(stations, on: { "station" => "code" })
   #
   # Two modes filter this frame's rows by +other+ instead of pairing them:
   #
@@ -55,21 +77,25 @@ class CAFrame
   # The result shares this frame's columns and index, as +filter+'s does.
   #
   #   obs.join(stations, on: "station", how: :anti)   # stations not listed
-  def join(other, on:, how: :left, suffixes: DEFAULT_JOIN_SUFFIXES)
+  def join(other, on:, how: :left, suffixes: DEFAULT_JOIN_SUFFIXES, view: nil)
     unless %i[left inner outer right semi anti].include?(how)
       raise ArgumentError, "unknown join mode #{how.inspect}"
     end
+    refuse_unknown_view(view, "join")
+    if (how == :semi || how == :anti) && view
+      raise ArgumentError, "join: how: #{how.inspect} adds no column of the other frame, so view: does not apply"
+    end
     if (how == :semi || how == :anti) && !suffixes.equal?(DEFAULT_JOIN_SUFFIXES)
       raise ArgumentError, "join: how: #{how.inspect} adds no column of the other frame, so suffixes: does not apply"
     end
-    names = join_key_names(on, "join", "on:")
+    names, rnames = join_key_pairs(on, "join", "on:")
     lkeys = names.map { |name| key_column(name, "join") }
-    rkeys = names.map { |name| other.__send__(:key_column, name, "join") }
+    rkeys = rnames.map { |name| other.__send__(:key_column, name, "join") }
     join_check_key_widths(names, lkeys, rkeys, "join")
     return join_filter(lkeys, rkeys, how) if how == :semi || how == :anti
 
-    plan = join_name_plan(other, names, suffixes)
-    join_pairs(other, names, lkeys, rkeys, how, plan)
+    plan = join_name_plan(other, names, rnames, suffixes)
+    join_pairs(other, names, rnames, lkeys, rkeys, how, plan, view)
   end
 
   # As-of (nearest-key) left join for irregular series (memo §11.7). Each
@@ -80,22 +106,31 @@ class CAFrame
   # in that direction or beyond +tolerance:+ come back UNDEF. +tolerance:+
   # is a number for a numeric key and a duration for a time key
   # ("10 minutes", or a CATimedelta value). Same wiring as the left join,
-  # only the address primitive differs.
+  # only the address primitive differs; +view: :full+ makes +other+'s
+  # columns views with holes, as +join+'s does.
   #
   # +by:+ names columns that must match exactly, one name or an Array: each
   # left row is matched to the nearest row among the rows of +other+ with
   # the same +by+ values.  A row with a masked +by+ cell matches nothing.
+  # +on:+ and +by:+ take a Hash of this frame's name to +other+'s for a key
+  # named differently on the two sides, as +join+'s +on:+ does.
   #
   #   obs.join_asof(radar, on: "time", by: "station", tolerance: "10 minutes")
-  def join_asof(other, on:, by: nil, direction: :floor, tolerance: nil, suffixes: DEFAULT_JOIN_SUFFIXES)
-    on    = column_key(on, "join_asof")
-    exact = by.nil? ? [] : join_key_names(by, "join_asof", "by:")
-    if exact.include?(on)
-      raise ArgumentError, "join_asof: #{on.inspect} is the on: key; by: names the others"
+  def join_asof(other, on:, by: nil, direction: :floor, tolerance: nil, suffixes: DEFAULT_JOIN_SUFFIXES, view: nil)
+    refuse_unknown_view(view, "join_asof")
+    ons, ron = join_key_pairs(on, "join_asof", "on:")
+    if ons.size != 1
+      raise ArgumentError, "join_asof: on: names one key column (got #{ons.size}); by: names the others"
+    end
+    on, ron = ons.first, ron.first
+    exact, rexact_names = by.nil? ? [[], []] : join_key_pairs(by, "join_asof", "by:")
+    if exact.include?(on) || rexact_names.include?(ron)
+      name = exact.include?(on) ? on : ron
+      raise ArgumentError, "join_asof: #{name.inspect} is the on: key; by: names the others"
     end
-    plan = join_name_plan(other, [on, *exact], suffixes)
+    plan = join_name_plan(other, [on, *exact], [ron, *rexact_names], suffixes)
     lkey = key_column(on, "join_asof")
-    rkey = other.__send__(:key_column, on, "join_asof")
+    rkey = other.__send__(:key_column, ron, "join_asof")
     [lkey, rkey].each do |key|
       key.__send__(:nearest_refuse_bytes, key, "join_asof: the on: key #{on.inspect}",
                    "join on it exactly with join")
@@ -104,12 +139,12 @@ class CAFrame
              lkey.locate_nearest_addr(rkey, direction: direction, tolerance: tolerance)
            else
              lexact = exact.map { |name| key_column(name, "join_asof") }
-             rexact = exact.map { |name| other.__send__(:key_column, name, "join_asof") }
+             rexact = rexact_names.map { |name| other.__send__(:key_column, name, "join_asof") }
              join_check_key_widths(exact, lexact, rexact, "join_asof")
              _, lcode, rcode, k = join_codes(lexact, rexact)
              join_asof_by(lkey, rkey, lcode, rcode, k, direction, tolerance)
            end
-    join_by_addr(other, [on, *exact], addr, plan)
+    join_by_addr(other, [on, *exact], [ron, *rexact_names], addr, plan, view)
   end
 
   # Conform every column to an externally supplied reference key set (the
@@ -259,12 +294,21 @@ class CAFrame
     end
   end
 
-  # The key column names of a join: one name, or an Array of names.
-  private def join_key_names(on, verb, option)
-    names = on.is_a?(Array) ? on : [on]
-    raise ArgumentError, "#{verb}: #{option} names no key column" if names.empty?
-    CAFrame.__send__(:refuse_repeated_names, names.map { |name| column_key(name, verb) },
-                     verb, "#{option} names")
+  # The key column names of a join, this frame's and the other's: one name
+  # or an Array of names (the same on both sides), or a Hash of this frame's
+  # name to the other's.
+  private def join_key_pairs(on, verb, option)
+    pairs = case on
+            when Hash  then on.to_a
+            when Array then on.map { |name| [name, name] }
+            else            [[on, on]]
+            end
+    raise ArgumentError, "#{verb}: #{option} names no key column" if pairs.empty?
+    lnames = pairs.map { |name, _| column_key(name, verb) }
+    rnames = pairs.map { |_, name| column_key(name, verb) }
+    CAFrame.__send__(:refuse_repeated_names, lnames, verb, "#{option} names")
+    CAFrame.__send__(:refuse_repeated_names, rnames, verb, "#{option} names")
+    return [lnames, rnames]
   end
 
   # Codes for the rows of both sides of a join on +lkeys+ / +rkeys+ (one
@@ -396,9 +440,11 @@ class CAFrame
   # The left index keeps its name as the result's row axis, so a right
   # column of that name collides with it as with a left column: it takes
   # the right suffix, and there is no left column to take the left one.
-  private def join_name_plan(other, names, suffixes)
+  # The names of +other+'s columns that the join adds (its key columns
+  # +rnames+ are not added) and that this frame already has collide.
+  private def join_name_plan(other, names, rnames, suffixes)
     taken = @index ? column_names | [@axis_name] : column_names
-    collisions = (taken & other.column_names) - names
+    collisions = taken & (other.column_names - rnames)
     return { collisions: [], lsuf: nil, rsuf: nil } if collisions.empty?
 
     if suffixes == false
@@ -427,19 +473,24 @@ class CAFrame
     cols[name] = col
   end
 
-  private def join_by_addr(other, names, addr, plan)
+  # The left key columns keep their names, as in join_pairs; a right column
+  # of the same name takes the right suffix.
+  private def join_by_addr(other, names, rnames, addr, plan, view)
     cols = {}
-    column_names.each { |name| put_join_column(cols, join_name(name, plan[:lsuf], plan), self[name]) }
+    column_names.each do |name|
+      name_out = names.include?(name) ? name : join_name(name, plan[:lsuf], plan)
+      put_join_column(cols, name_out, self[name])
+    end
     other.column_names.each do |name|
-      next if names.include?(name)
-      put_join_column(cols, join_name(name, plan[:rsuf], plan), project_rows(other[name], addr))
+      next if rnames.include?(name)
+      put_join_column(cols, join_name(name, plan[:rsuf], plan), join_rows(other[name], addr, view))
     end
     CAFrame.new(cols, axis_name: @axis_name, index: @index)
   end
 
   # The rows of a key join: li / ri are the left / right row of each result
   # row, UNDEF on the side a row has no match on.
-  private def join_pairs(other, names, lkeys, rkeys, how, plan)
+  private def join_pairs(other, names, rnames, lkeys, rkeys, how, plan, view)
     parts, lcode, rcode, k = join_codes(lkeys, rkeys)
     extra = nil
     if how == :right
@@ -463,21 +514,33 @@ class CAFrame
     every_left = how == :left || how == :inner
     identity   = every_left && li.elements == nrow &&
                  (nrow == 0 || li.eq(CArray.int64(nrow).seq).all)
-    rows = { li: li, ri: ri, extra: extra, how: how, every_left: every_left, identity: identity }
+    # Every result row of an inner or right join has a row of the other
+    # frame, so its columns are views of those rows, as the left's are in
+    # an inner or left join.
+    every_right    = how == :right || how == :inner
+    right_identity = every_right && ri.elements == other.nrow &&
+                     (other.nrow == 0 || ri.eq(CArray.int64(other.nrow).seq).all)
+    rows = { li: li, ri: ri, extra: extra, how: how, every_left: every_left, identity: identity,
+             view: view }
     cols = {}
     column_names.each do |name|
       j = names.index(name)
       col = if j                 then joined_key(j, parts, lkeys, rkeys, rows)
             elsif identity       then self[name]
             elsif every_left     then self[name][li, *([nil] * (self[name].ndim - 1))]
-            else                      project_rows(self[name], li)
+            else                      join_rows(self[name], li, view)
             end
       name = join_name(name, plan[:lsuf], plan) unless j
       put_join_column(cols, name, col)
     end
     other.column_names.each do |name|
-      next if names.include?(name)
-      put_join_column(cols, join_name(name, plan[:rsuf], plan), project_rows(other[name], ri))
+      next if rnames.include?(name)
+      col = other[name]
+      col = if right_identity then col
+            elsif every_right then col[ri, *([nil] * (col.ndim - 1))]
+            else                   join_rows(col, ri, view)
+            end
+      put_join_column(cols, join_name(name, plan[:rsuf], plan), col)
     end
     # A key that is the left index is the result's index, as a key column
     # is a column of it.
@@ -486,7 +549,7 @@ class CAFrame
                 elsif ij        then joined_key(ij, parts, lkeys, rkeys, rows)
                 elsif identity  then @index
                 elsif every_left then @index[li]
-                else                  project_rows(@index, li)
+                else                  join_rows(@index, li, view)
                 end
     CAFrame.new(cols, axis_name: @axis_name, index: new_index)
   end
@@ -498,7 +561,8 @@ class CAFrame
     li, ri = rows[:li], rows[:ri]
     return lkeys[j] if rows[:identity]
     return lkeys[j][li] if rows[:every_left]
-    return project_rows(rkeys[j], ri) if rows[:how] == :right
+    return rkeys[j][ri] if rows[:how] == :right
+    return joined_key_view(lkeys[j], rkeys[j], li, rows[:extra]) if rows[:view]
     common, lc, rc = parts[j]
     extra = rows[:extra]
     code = if extra
@@ -586,6 +650,51 @@ class CAFrame
     end
   end
 
+  # The key of an outer join as a view: the two key columns welded
+  # (+CArray.meld+), picked at the left rows and then at the right rows no
+  # left row matched. Welding the whole columns, whatever rows the join
+  # gives, makes the call raise or pass the same way with any data, and
+  # makes the key show the attributes both keys have alike, as the default
+  # key does.
+  private def joined_key_view(lkey, rkey, li, extra)
+    # A Face's class, not the view class a filtered key has.
+    lface = lkey.class if lkey.face?
+    rface = rkey.class if rkey.face?
+    reason = if lface != rface || lkey.data_type != rkey.data_type
+               "#{CArray::Inspector.type_label(lkey)} and #{CArray::Inspector.type_label(rkey)}"
+             end
+    unless reason
+      begin
+        both = CArray.meld([lkey, rkey], axis: 0)
+      rescue ArgumentError => e   # a Face's state, such as a time unit
+        reason = e.message
+      end
+    end
+    if reason
+      raise ArgumentError,
+            "join: view: :full welds the two key columns of an outer join, which needs " \
+            "one kind of key (#{reason}); cast one side first, or leave view: out"
+    end
+    return both[li] unless extra
+    nleft = li.elements - extra.elements
+    both[CArray.concatenate([li[0...nleft], extra + lkey.elements])]
+  end
+
+  # view: is nil (views where every row has a row of the side, new columns
+  # where some do not) or :full (views throughout, UNDEF for a row with no
+  # row of the side).
+  private def refuse_unknown_view(view, verb)
+    return if view.nil? || view == :full
+    raise ArgumentError, "#{verb}: view: takes :full (got #{view.inspect})"
+  end
+
+  # The rows +addr+ picks from +col+, UNDEF where +addr+ is masked: a view
+  # with view: :full, else a new column.
+  private def join_rows(col, addr, view)
+    return project_rows(col, addr) unless view == :full
+    col[addr, *([nil] * (col.ndim - 1))]
+  end
+
   private def project_rows(col, addr)
     return col.project(addr) if col.ndim == 1
     trailing = col.shape[1..]

data/lib/carray/frame/records.rb

@@ -1,7 +1,7 @@
 # CAFrame record (row-oriented) input (memo §11.2, §11.5).
 #
 # from_records takes an Array of row Hashes -- the shape JSON.parse yields for
-# a JSON array of objects -- and arranges it into columns. Unlike from_csv,
+# a JSON array of objects -- and arranges it into columns. Unlike read_csv,
 # the cell values are already typed Ruby objects (Float / Integer / DateTime /
 # String), so a homogeneous column is built at its native leaf type rather than
 # left as strings ("arrange by the value's own type", not string inference --
@@ -41,7 +41,7 @@ class CAFrame
     end
 
     frame = new(cols)
-    frame.cast(types, on_error: on_error, option_name: :types) unless types.nil?
+    frame.__send__(:cast_in_place, types, on_error: on_error, option_name: :types) unless types.nil?
     frame
   end
 
@@ -67,7 +67,7 @@ class CAFrame
   # them (CAFrame.new and df[name]= given an Array, from_records, the values
   # a group's block or Proc gives).  All-Array cells of equal length -> N-D
   # native column; numeric scalars -> native scalar column (missing ->
-  # UNDEF); Strings -> a text column (CAString), as from_csv reads text;
+  # UNDEF); Strings -> a text column (CAString), as read_csv reads text;
   # time and duration elements -> a CATime / CATimedelta column in the finest
   # resolution among them; anything else -> object column.
   def self.build_record_column(values, n)

data/lib/carray/frame/reshape.rb

@@ -165,8 +165,8 @@ class CAFrame
         # names-check: two rows for one cell of the grid
         first = cell.to_a.tally.find { |_, count| count > 1 }.first
         raise ArgumentError,
-              "pivot: more than one row for #{index}=#{rlab[first / nc].inspect}, " \
-              "#{columns}=#{clab[first % nc].inspect}; pass aggregate: to combine them"
+              "pivot: more than one row for #{index}=#{CAFrame.__send__(:key_text, rlab[first / nc])}, " \
+              "#{columns}=#{CAFrame.__send__(:key_text, clab[first % nc])}; pass aggregate: to combine them"
       end
       source[cell] = CArray.int64(nrow).seq[placed]
     end
@@ -199,6 +199,61 @@ class CAFrame
     groups.public_send(plan[:aggregate])
   end
 
+  # The bits of each integer type and whether it is signed; the significand
+  # bits of each floating type (a complex type by its parts).
+  INTEGER_BITS = {
+    "int8" => [8, true], "int16" => [16, true], "int32" => [32, true], "int64" => [64, true],
+    "uint8" => [8, false], "uint16" => [16, false], "uint32" => [32, false], "uint64" => [64, false],
+  }.freeze
+  SIGNIFICAND_BITS = { "float32" => 24, "float64" => 53, "cmplx64" => 24, "cmplx128" => 53 }.freeze
+  Ractor.make_shareable(INTEGER_BITS)
+  Ractor.make_shareable(SIGNIFICAND_BITS)
+  private_constant :INTEGER_BITS, :SIGNIFICAND_BITS
+
+  # Whether every value of data type +from+ is exactly a value of +to+, for
+  # numbers and booleans: a boolean in any number, an integer in a wide
+  # enough integer (a signed one never in an unsigned) or in a float whose
+  # significand holds it, a float in a wider float or complex.
+  def self.holds_every_value (from, to)
+    f = CArray.data_type_name(from)
+    t = CArray.data_type_name(to)
+    return true if f == t || f == "boolean"
+    if (fbits, fsigned = INTEGER_BITS[f])
+      if (tbits, tsigned = INTEGER_BITS[t])
+        return fsigned ? (tsigned && tbits >= fbits) : (tsigned ? tbits > fbits : tbits >= fbits)
+      end
+      significand = SIGNIFICAND_BITS[t]
+      return !significand.nil? && (fsigned ? fbits - 1 : fbits) <= significand
+    end
+    fs = SIGNIFICAND_BITS[f]
+    ts = SIGNIFICAND_BITS[t]
+    return false if fs.nil? || ts.nil? || ts < fs
+    return !(f.start_with?("cmplx") && t.start_with?("float"))
+  end
+  private_class_method :holds_every_value
+
+  # The types melt may bring number columns to, narrowest first within each
+  # kind, so the first that holds every column's type is the common one.
+  MELT_TYPES = %w[int8 uint8 int16 uint16 int32 uint32 int64 uint64
+                  float32 float64 cmplx64 cmplx128].freeze
+  Ractor.make_shareable(MELT_TYPES)
+  private_constant :MELT_TYPES
+
+  # The common type of number (and boolean) columns of different types: the
+  # one CArray.result_type picks when it holds every value of every column's
+  # type, else the narrowest that does; nil when no type does. Decided by
+  # the types alone, so a value written to a column later is one the common
+  # type holds too.
+  def self.melt_common_type (pieces)
+    types = pieces.map(&:data_type)
+    holds = ->(to) { types.all? { |t| holds_every_value(t, to) } }
+    first = CArray.result_type(*pieces)
+    return first if holds.(first)
+    name = MELT_TYPES.find { |t| holds.(t) }
+    name&.to_sym
+  end
+  private_class_method :melt_common_type
+
   # Gather a wide frame into a long one.  The +value_columns+ are stacked one
   # after another into a single +value_name+ column, a +var_name+ column says
   # which of them each row came from (a text column), and every +id+ column
@@ -212,8 +267,12 @@ class CAFrame
   #
   # The result is a view frame: the value column is +CArray.meld+ of the
   # melted columns and each id column is +CArray.meld+ of itself, so a write
-  # to the result lands in +self+.  The value columns must therefore share
-  # one data type and one trailing shape; cast first when they do not.
+  # to the result lands in +self+.  Number columns of different types meet
+  # at a type that holds every value of each column's type (int8 and uint8
+  # at int16, int32 and float64 at float64), so a value written later reads
+  # back unchanged; a mixture no type holds (int64 and float64) raises, and
+  # so do other mixtures of types. The value columns share one trailing
+  # shape; cast first when they do not.
   #
   # @param id [String, Array<String>] columns repeated alongside each value.
   # @param value_columns [Array<String>, nil] columns to stack; default all
@@ -222,7 +281,7 @@ class CAFrame
   # @param value_name [String] name of the stacked value column.
   # @return [CAFrame] a view frame of +nrow * value_columns.size+ rows.
   # @raise [ArgumentError] when there is nothing to melt, or the value
-  #   columns differ in data type.
+  #   columns differ in data type and no type holds every value of each.
   def melt(id: [], value_columns: nil, var_name: "variable", value_name: "value")
     ids = column_keys(Array(id), "melt")
     ids.each { |name| self[name] }
@@ -235,9 +294,20 @@ class CAFrame
     pieces = vars.map { |name| self[name] }
     types = pieces.map(&:data_type).uniq
     unless types.size == 1
-      raise ArgumentError,
-            "melt: value columns differ in data type (#{vars.zip(pieces.map(&:data_type)).to_h}); " \
-            "cast them to one type first"
+      # Numbers of different types meet at a type that holds every value of
+      # every column's type, each through a view of its own column (as_type),
+      # so the value column still reads and writes the columns it was made
+      # from, whatever is written to them later.
+      common = nil
+      if pieces.all? { |c| !c.face? && (c.numeric? || c.data_type == :boolean) }
+        common = CAFrame.__send__(:melt_common_type, pieces)
+      end
+      if common.nil?
+        raise ArgumentError,
+              "melt: value columns differ in data type (#{vars.zip(pieces.map(&:data_type)).to_h}) " \
+              "and no type holds every value of each; cast them to one type first"
+      end
+      pieces = pieces.map { |c| c.data_type == common ? c : c.as_type(common) }
     end
     shapes = pieces.map { |c| c.shape.drop(1) }.uniq
     unless shapes.size == 1
@@ -259,7 +329,15 @@ class CAFrame
     end
     n = nrow
     out[var_name]   = CArray.string(Array.new(n * k) { |i| vars[i / n] })
-    out[value_name] = CArray.meld(pieces)
+    begin
+      out[value_name] = CArray.meld(pieces)
+    rescue ArgumentError => e
+      raise unless e.message.start_with?("promote_list:")
+      labels = vars.zip(pieces.map { |c| CArray::Inspector.type_label(c) }).to_h
+      raise ArgumentError,
+            "melt: value columns #{labels} do not meet as one column " \
+            "(#{e.message.delete_prefix("promote_list: ")}); cast them to one type first"
+    end
     CAFrame.new(out)
   end
 
@@ -323,7 +401,7 @@ class CAFrame
     end
     if on
       on = column_name_arg(on, "stack_rows")
-      raise KeyError, "stack_rows: no column #{on.inspect}" unless frame.column_names.include?(on)
+      frame.__send__(:refuse_missing_column, on, "stack_rows") unless frame.column_names.include?(on)
       return stack_rows_on(frame, keys, on)
     end
     grouped = frame.group_by(*keys)
@@ -362,7 +440,7 @@ class CAFrame
   # given as a CArray has no name and is written "key").
   private def group_key_desc(keys, label)
     values = keys.size == 1 ? [label] : label
-    keys.zip(values).map { |k, v| "#{k.is_a?(String) ? k : "key"}=#{v.inspect}" }.join(", ")
+    keys.zip(values).map { |k, v| "#{k.is_a?(String) ? k : "key"}=#{CAFrame.__send__(:key_text, v)}" }.join(", ")
   end
 
   private def stack_rows_on(frame, keys, on)

data/lib/carray/frame/sort.rb

@@ -5,7 +5,7 @@
 # the single-key instance CArray#sort_index) -- and gathering every column and
 # the index by that address into a view-frame in key order:
 #
-#   sort_by_key(*keys, order:, masked_position:)  -- sort by named columns, with
+#   sort_by_key(*keys, descending:, masked_position:)  -- sort by named columns, with
 #                           per-key or blanket ascending/descending.
 #   sort_by { |f| ... }  -- sort by key CArrays the block builds (the escape,
 #                           §4.3): derived or composite keys are ordinary column
@@ -25,19 +25,20 @@ class CAFrame
   # row permutation and gathers every column and the index by it.
   #
   # Each key is a **column name** (or the index axis name), or a
-  # **`[name, :asc | :desc]`** pair for a per-key direction. The +order:+ keyword
-  # is the direction for bare-name keys (default +:asc+). +masked_position:+
+  # **`[name, :asc | :desc]`** pair for a per-key direction. +descending: true+
+  # sorts the bare-name keys from largest to smallest (default ascending), as
+  # +CArray#order+ takes it. +masked_position:+
   # sends masked key rows to the +:last+ (default) or +:first+ end.
   #
   #   df.sort_by_key("temp")                              # one column, ascending
   #   df.sort_by_key("station", "temp")                   # lexicographic
-  #   df.sort_by_key("temp", order: :desc)                # all keys descending
+  #   df.sort_by_key("temp", descending: true)            # all keys descending
   #   df.sort_by_key(["station", :asc], ["temp", :desc])  # per-key direction
   #   df.sort_by_key("temp", masked_position: :first)     # masked rows first
   #   df.sort_by_key("time")                              # by the index
-  def sort_by_key(*specs, order: :asc, masked_position: :last)
+  def sort_by_key(*specs, descending: false, masked_position: :last)
     raise ArgumentError, "sort_by_key requires at least one key" if specs.empty?
-    validate_sort_order(order)
+    order = descending ? :desc : :asc
     named = specs.map do |spec|
       name, dir = parse_sort_key_spec(spec, order)
       [column_key(name, "sort_by_key"), key_column(column_key(name, "sort_by_key"), "sort_by_key"), dir]
@@ -74,6 +75,50 @@ class CAFrame
     false
   end
 
+  # The +n+ rows with the largest values of the key columns, largest first,
+  # as a view-frame: +sort_by_key(*keys, descending: true).head(n)+. Several
+  # keys break ties in turn, as +sort_by_key+ takes them; rows that tie on
+  # every key keep their order. A NaN and a masked key lose to every value,
+  # as +CArray#nlargest+ has them, so they come only when fewer than +n+
+  # rows have a value.
+  #
+  #   df.nlargest(3, "revenue")
+  #   df.nsmallest(2, "rank", "time")
+  #
+  # @param n [Integer] how many rows, 0 or more.
+  # @param keys [Array<String>] the key columns (or the index axis name).
+  # @return [CAFrame]
+  # @raise [ArgumentError] when +n+ is negative or no key is given.
+  def nlargest (n, *keys)
+    return largest_or_smallest("nlargest", n, keys, true)
+  end
+
+  # The +n+ rows with the smallest values of the key columns, smallest first,
+  # as +nlargest+ gives the largest.
+  #
+  # @param n [Integer] how many rows, 0 or more.
+  # @param keys [Array<String>] the key columns (or the index axis name).
+  # @return [CAFrame]
+  # @raise [ArgumentError] when +n+ is negative or no key is given.
+  def nsmallest (n, *keys)
+    return largest_or_smallest("nsmallest", n, keys, false)
+  end
+
+  private def largest_or_smallest (verb, n, keys, descending)
+    unless n.is_a?(Integer)
+      raise TypeError, "#{verb}: the count is an Integer (got #{n.inspect})"
+    end
+    raise ArgumentError, "#{verb}: the count must be 0 or more (got #{n})" if n < 0
+    raise ArgumentError, "#{verb}: give at least one key column" if keys.empty?
+    keys.each { |k| column_key(k, verb) }
+    begin
+      return sort_by_key(*keys, descending: descending).head(n)
+    rescue ArgumentError, KeyError, TypeError, CArray::DataTypeError => e
+      # The sort is this verb's own, so its refusal names this verb.
+      raise e.class, e.message.sub(/\Asort_by_key:/, "#{verb}:"), e.backtrace
+    end
+  end
+
   # Sort rows by key columns the block builds (memo §4.3 escape). The block
   # receives the frame and returns a key CArray, or an Array of them for a
   # multi-key lexicographic sort; rows are sorted ascending by +CArray.sort_addr+
@@ -81,11 +126,13 @@ class CAFrame
   # +filter+: where +sort_by_key+ takes plain column names, the block form lets
   # you build any key with CArray ops -- a descending key is its dense
   # descending rank, derived or composite keys are ordinary column math.
-  # +masked_position:+ places masked key rows first or last (default last).
+  # +descending: true+ sorts every key from largest to smallest, as
+  # +sort_by_key+ takes it; +masked_position:+ places masked key rows first or
+  # last (default last).
   #
   #   df.sort_by { |f| (f["temp"] - target).abs }   # nearest-to-target first
-  #   df.sort_by { |f| f["temp"].order(descending: true, method: :dense) }
-  def sort_by(masked_position: :last)
+  #   df.sort_by(descending: true) { |f| f["name"].length }
+  def sort_by(descending: false, masked_position: :last)
     raise ArgumentError, "sort_by requires a block" unless block_given?
     keys = yield(self)
     keys = [keys] unless keys.is_a?(Array)
@@ -99,6 +146,7 @@ class CAFrame
               "sort_by key #{i} must be a 1-D column of length #{nrow} (got shape #{k.shape.inspect})"
       end
     end
+    keys = keys.map { |k| k.order(descending: true, method: :dense) } if descending
     select_rows(CArray.sort_addr(*keys, masked_position: masked_position))
   end