carray 2.0.0 → 3.0.0

data/lib/carray/frame/group.rb

@@ -0,0 +1,186 @@
+# CAFrame group_by (memo §5 spine, §11.6 surface).
+#
+# Grouping is always on the row axis (axis 0). The key is any length-N
+# thing: a column name, several column names (composite key), or an
+# external length-N CArray. Everything routes through categorize -> codes
+# -> group_by_category, so the frame layer only builds the key and hands
+# the group iterator back (exposure, §4.3).
+
+class CAFrame
+  # Group rows by one or more keys. Each key is a column name (String) or an
+  # external length-N CArray. Returns a GroupedFrame.
+  def group_by(*keys)
+    raise ArgumentError, "group_by needs at least one key" if keys.empty?
+    cat  = grouping_categorical(keys)
+    axis = keys.size == 1 && keys.first.is_a?(String) ? keys.first : "group"
+    GroupedFrame.new(self, cat, axis)
+  end
+
+  # Number of rows currently selected — used by group per-group view-frames
+  # and elsewhere; already provided by the core (attr_reader :nrow).
+
+  private def grouping_categorical(keys)
+    cols = keys.map { |k| key_column(k) }
+    if cols.size == 1
+      cols.first.categorize
+    else
+      # Composite key: one object cell per row holding the tuple of key
+      # values, categorized by content (the codes are composed from the
+      # per-column keys).
+      n = nrow
+      CArray.object(n) { |i| cols.map { |c| c[i] } }.categorize
+    end
+  end
+
+  private def key_column(key)
+    case key
+    when String
+      self[key]
+    when CArray
+      unless key.shape[0] == nrow
+        raise ArgumentError,
+              "external group key length #{key.shape[0]} != nrow #{nrow}"
+      end
+      key
+    else
+      raise ArgumentError, "group key must be a column name or CArray (got #{key.class})"
+    end
+  end
+end
+
+# GroupedFrame — the result of +CAFrame#group_by+ (memo §11.6, §16).
+#
+# Holds the grouping categorical once (grouping is per-key, computed once
+# and shared across every column). Three surfaces:
+#   grp["col"]   -> the CArray group iterator (raw exposure)
+#   aggregate    -> declarative per-column reductions into a new frame
+#   table { |g| }-> cross-column Ruby escape, g is a per-group view-frame
+class GroupedFrame
+  def initialize(frame, cat, axis_name)
+    @frame     = frame
+    @cat       = cat
+    @axis_name = axis_name
+    @labels    = cat.labels          # group values, in code order
+  end
+
+  # Number of groups.
+  def ngroup
+    @labels.size
+  end
+
+  # Group key values (one per group), as an Array.
+  def labels
+    @labels.dup
+  end
+
+  # Raw exposure: the CArray group iterator for one column (memo §11.6).
+  def [](name)
+    @frame[name].group_by_category(@cat)
+  end
+
+  # Declarative aggregation (memo §11.6). Spec maps an output column name to
+  # +[input_column, reduction]+, where reduction is a Symbol (vectorized,
+  # applied through the group iterator) or a Proc (per-group custom, called
+  # with the group's column slice).
+  def aggregate(spec)
+    cols = {}
+    spec.each do |out_name, (in_name, reduction)|
+      out = out_name.to_s
+      cols[out] =
+        case reduction
+        when Symbol
+          self[in_name].public_send(reduction)
+        when Proc
+          per_group_column(in_name, reduction)
+        else
+          raise ArgumentError,
+                "reduction must be a Symbol or Proc (got #{reduction.class})"
+        end
+    end
+    CAFrame.new(cols, axis_name: @axis_name, index: label_index)
+  end
+
+  # Cross-column Ruby escape (memo §11.6). The block receives a per-group
+  # view-frame and returns a Hash of output-name => value; the values are
+  # collected column-wise across groups into a new frame.
+  def table
+    collected = {}
+    order = nil
+    each_group_frame do |g|
+      out = yield(g)
+      unless out.is_a?(Hash)
+        raise ArgumentError, "table block must return a Hash (got #{out.class})"
+      end
+      order ||= out.keys.map(&:to_s)
+      out.each { |k, v| (collected[k.to_s] ||= []) << v }
+    end
+    cols = {}
+    (order || []).each do |name|
+      vals = collected[name]
+      cols[name] = CArray.object(vals.size) { |i| vals[i] }
+    end
+    CAFrame.new(cols, axis_name: @axis_name, index: label_index)
+  end
+
+  # Convenience reductions over every numeric scalar column (memo §6-4
+  # "grp.mean"). Non-numeric / N-D columns are skipped.
+  [:sum, :mean, :min, :max].each do |red|
+    define_method(red) { reduce_numeric(red) }
+  end
+
+  # @return [String]
+  def inspect
+    "#<GroupedFrame ngroup=#{ngroup} by=#{@axis_name.inspect}>"
+  end
+
+  private def label_index
+    CArray.object(@labels.size) { |i| @labels[i] }
+  end
+
+  NON_NUMERIC = [:object, :boolean, :fixlen].freeze
+  private_constant :NON_NUMERIC
+
+  private def reduce_numeric(reduction)
+    cols = {}
+    @frame.variable_names.each do |name|
+      col = @frame[name]
+      next unless col.ndim == 1 && !NON_NUMERIC.include?(col.data_type)
+      cols[name] = col.group_by_category(@cat).public_send(reduction)
+    end
+    CAFrame.new(cols, axis_name: @axis_name, index: label_index)
+  end
+
+  private def per_group_column(in_name, proc)
+    results = []
+    each_group_slice(in_name) { |slice| results << proc.call(slice) }
+    CArray.object(results.size) { |i| results[i] }
+  end
+
+  private def each_group_slice(in_name)
+    col = @frame[in_name]
+    ngroup.times do |k|
+      yield col[group_address(k), *([nil] * (col.ndim - 1))]
+    end
+  end
+
+  private def each_group_frame
+    ngroup.times { |k| yield @frame[group_address(k)] }
+  end
+
+  private def group_address(k)
+    start = group_offsets[k]
+    group_perm[start...(start + group_sizes[k])]
+  end
+
+  private def group_perm
+    @group_perm ||= @cat.sort_addr
+  end
+
+  private def group_offsets
+    @group_offsets ||= @cat.reduceat_index
+  end
+
+  private def group_sizes
+    @group_sizes ||= @cat.category_sizes
+  end
+end

data/lib/carray/frame/io.rb

@@ -0,0 +1,164 @@
+# CAFrame CSV input/output (memo §11.2, §6-2).
+
+require "carray/frame/csv_parser"
+
+class CAFrame
+  # Read a CSV into a frame. The header row supplies column names (Strings,
+  # §3.7); every column is built raw as an object CArray of the cell strings
+  # (§4.2 -- read and arrange only, no type-inference engine). Casting is a
+  # separate step: pass +types:+ ({ "temp" => :float64 }, or the array-key /
+  # reverse forms of +cast+) to cast named columns on load, or call +cast+
+  # later. Broken cells fail to_type and become UNDEF automatically
+  # (parse-mask, §6-2).
+  #
+  # Parsing uses the built-in fast tokenizer (CSVParser). Options:
+  #   sep:      field separator (default ",")
+  #   quote:    quote character (default '"')
+  #   strip:    trim spaces from unquoted fields (default false, RFC spacing)
+  #   +encoding+: IO open-mode encoding (default "bom|utf-8", strips a BOM)
+  #   parser:   a callable path -> [headers, rows] to inject another parser
+  #             (e.g. the stdlib +csv+, or a typed-table source); when given,
+  #             sep/quote/strip/encoding and any block are that parser's concern.
+  #
+  # A block gives reading control for files with preamble lines, a units row,
+  # or no header (memo §11.2), using +skip+ / +header+ / +column_names+ /
+  # +body+ (see CSVReader). Without a block the default is +header+ then +body+.
+  #
+  #   CAFrame.from_csv("obs.csv") do
+  #     skip 2; header; skip 1; body
+  #   end
+  #
+  # Columns are handed to the frame as CABlock views over one backing object
+  # array (§3.6 view-by-default); casting a column materializes it, and +copy+
+  # gives an independent frame.
+  def self.from_csv(path, types: nil,
+                    sep: ",", quote: '"', strip: false,
+                    encoding: "bom|utf-8", parser: nil, &block)
+    names, rows =
+      if parser
+        parser.call(path)
+      else
+        File.open(path, "r:#{encoding}") do |io|
+          reader = CSVReader.new(io, sep: sep, quote: quote, strip: strip)
+          if block
+            block.arity == 1 ? block.call(reader) : reader.instance_exec(&block)
+          else
+            reader.header
+            reader.body
+          end
+          reader.result
+        end
+      end
+
+    frame = build_frame(names, rows)
+    frame.cast(types) if types
+    frame
+  end
+
+  # Build a frame from parsed [names, rows]. When names is nil (headerless and
+  # no column_names) positional names "c0".."cN" are generated from the widest
+  # row. Rows are squared off to the column count (short rows padded with nil,
+  # over-long rows raise), one 2-D object array is bulk-filled, and each column
+  # is a view into it (§3.6).
+  # Write the frame as CSV. CSV is a flat table of scalar cells, so this is the
+  # text form of the same all-scalar subset +to_ca+ requires (§11.9): every
+  # column must be 1-D. Unlike +to_ca+ it does not promote to a common dtype --
+  # each column is formatted to text independently, so mixed dtypes (numbers,
+  # strings, datetime / categorical Faces) sit side by side. An N-D column has
+  # no flat CSV cell and raises; export it per column, or use +to_records+ +
+  # JSON for the structured shape (memo §11.9, the N-D escape).
+  #
+  # With +path+, writes the file and returns self; without it, returns the CSV
+  # String. The index (if any) is written as the first column under +axis_name+
+  # unless +index: false+. A masked cell (UNDEF) becomes an empty field, which
+  # +from_csv+ reads back as UNDEF (parse-mask, §6-2) -- so mask round-trips. A
+  # genuine empty string is written quoted (+""+) to stay distinct from missing,
+  # matching the tokenizer's own unquoted-empty vs quoted-empty distinction.
+  #
+  #   df.to_csv("out.csv")          # write file
+  #   csv = df.to_csv               # get a String
+  #
+  # Options: +sep+ / +quote+ mirror +from_csv+; +header+ writes the name row
+  # (default true); +index+ writes the index column (default true).
+  def to_csv(path = nil, sep: ",", quote: '"', header: true, index: true)
+    nd = @columns.find { |_, c| c.ndim != 1 }
+    if nd
+      raise ArgumentError,
+            "to_csv needs all-scalar (1-D) columns; #{nd.first.inspect} is " \
+            "#{nd.last.ndim}-D — export it per column or via to_records + JSON"
+    end
+
+    names     = []
+    formatted = []
+    if index && @index
+      names     << @axis_name
+      formatted << format_csv_column(@index)
+    end
+    @columns.each do |name, col|
+      names     << name
+      formatted << format_csv_column(col)
+    end
+
+    out = +""
+    if header
+      out << names.map { |t| quote_csv_field(t, sep, quote) }.join(sep) << "\n"
+    end
+    @nrow.times do |i|
+      out << formatted.map { |fcol| quote_csv_field(fcol[i], sep, quote) }.join(sep) << "\n"
+    end
+
+    if path
+      File.write(path, out)
+      self
+    else
+      out
+    end
+  end
+
+  private def format_csv_column(col)
+    col.to_a.map do |e|
+      if UNDEF.equal?(e) || e.nil?
+        nil
+      elsif e.is_a?(String)
+        e
+      elsif e.respond_to?(:iso8601)
+        e.iso8601
+      else
+        e.to_s
+      end
+    end
+  end
+
+  private def quote_csv_field(text, sep, quote)
+    return "" if text.nil?
+    if text.empty? || text.include?(sep) || text.include?(quote) ||
+       text.include?("\n") || text.include?("\r")
+      quote + text.gsub(quote, quote * 2) + quote
+    else
+      text
+    end
+  end
+
+  def self.build_frame(names, rows)
+    ncol  = names ? names.size : (rows.map(&:size).max || 0)
+    names ||= Array.new(ncol) { |j| "c#{j}" }
+
+    cols = {}
+    if rows.empty?
+      names.each { |name| cols[name] = CArray.object(0) }
+      return new(cols)
+    end
+    rows.each_with_index do |r, i|
+      if r.size < ncol
+        r.concat(Array.new(ncol - r.size))
+      elsif r.size > ncol
+        raise ArgumentError,
+              "row #{i + 1} has #{r.size} fields, expected #{ncol}"
+      end
+    end
+    table = CArray.object(rows.size, ncol) { rows }
+    names.each_with_index { |name, j| cols[name] = table[nil, j] }
+    new(cols)
+  end
+  private_class_method :build_frame
+end

data/lib/carray/frame/join.rb

@@ -0,0 +1,248 @@
+# CAFrame join (memo §5, §11.7, §13.3).
+#
+# Join is a thin delegation to landed addressing primitives: the join key
+# yields an address array (locate_addr for a row-preserving left lookup,
+# align_addr for symmetric set alignment), and each column is gathered by
+# +project+ (length-preserving, miss -> UNDEF, Face-lift, read-only safe).
+# The frame layer just distributes that address to every column.
+
+class CAFrame
+  # Default disambiguation for non-key columns present on both sides (§12-C):
+  # left gets "_left", right gets "_right". +_left+/+_right+ read clearer than
+  # pandas' +_x+/+_y+ for the target audience.
+  DEFAULT_JOIN_SUFFIXES = ["_left", "_right"].freeze
+  private_constant :DEFAULT_JOIN_SUFFIXES
+
+  # Join +other+ on a shared key column.
+  #
+  #   how: :left  (default) — keep all left rows; right columns gathered per
+  #                           left row (locate_addr), misses become UNDEF.
+  #   how: :inner/:outer/:right — set-align both key sets (align_addr) and
+  #                           gather both sides; the aligned key values form
+  #                           the +on+ column.
+  #
+  # 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
+  # both sides (+suffixes: ["_left", "_right"]+); pass a 2-element array to pick
+  # meaningful names up front (+["_obs", "_fcst"]+), or +suffixes: false+ to
+  # raise instead. Rename afterward with +rename+ if needed (§12-C).
+  def join(other, on:, how: :left, suffixes: DEFAULT_JOIN_SUFFIXES)
+    on   = on.to_s
+    lkey = self[on]
+    rkey = other[on]
+    plan = join_name_plan(other, on, suffixes)
+
+    case how
+    when :left
+      join_left(other, on, lkey, rkey, plan)
+    when :inner, :outer, :right
+      join_align(other, on, lkey, rkey, how, plan)
+    else
+      raise ArgumentError, "unknown join mode #{how.inspect}"
+    end
+  end
+
+  # As-of (nearest-key) left join for irregular series (memo §11.7). Each
+  # left row is matched to the nearest +other+ row by +on+ via
+  # locate_nearest_addr (the per-row, row-preserving counterpart of
+  # align_nearest_addr); +direction:+ follows CArray (:floor = most recent
+  # at-or-before, :ceil = next, :round = nearest), and rows with no match
+  # in range or beyond +tolerance:+ come back UNDEF. Same wiring as the left
+  # join, only the address primitive differs.
+  def join_asof(other, on:, direction: :floor, tolerance: nil, suffixes: DEFAULT_JOIN_SUFFIXES)
+    on   = on.to_s
+    plan = join_name_plan(other, on, suffixes)
+    addr = self[on].locate_nearest_addr(other[on], direction: direction, tolerance: tolerance)
+    join_by_addr(other, on, addr, plan)
+  end
+
+  # Conform every variable to an externally supplied reference key set (the
+  # asymmetric sibling of +join+; pandas +reindex+). Given a +reference+ array
+  # of key values, each column is gathered onto it by exact key match
+  # (+locate_addr+): the aligned key column (or index) becomes the reference
+  # itself, and a reference key absent from the source comes back UNDEF in
+  # every other column.
+  #
+  # CAFrame measures no interval and generates nothing -- the caller owns the
+  # reference. This is the primitive for reindexing to a caller-built axis
+  # (e.g. a complete 10-minute time grid): supply that axis as +reference+ and
+  # the gaps fill with UNDEF rows carrying only the reference key.
+  #
+  #   df.align("time", reftime)   # reftime = a CArray of reference key values
+  #
+  # +key+ may be a column name or the index axis name. +reference+ is a CArray
+  # (or Array); its keys are matched against the source key by value, so their
+  # data types must be comparable (a DateTime object key matches by eql?/hash).
+  def align(key, reference)
+    key = key.to_s
+    ref = reference.is_a?(CArray) ? reference : reference.to_ca
+    on_index = !@columns.key?(key) && @axis_name == key && @index
+    addr = ref.locate_addr(on_index ? @index : self[key])
+
+    cols = {}
+    variable_names.each { |name| cols[name] = project_rows(self[name], addr) }
+    if on_index
+      CAFrame.new(cols, axis_name: key, index: ref)
+    else
+      cols[key] = ref
+      CAFrame.new(cols, axis_name: @axis_name,
+                        index: @index && project_rows(@index, addr))
+    end
+  end
+
+  # Paste +other+'s variables beside this frame's, matched by **row position**
+  # (memo §12-C) — a keyless column merge (the column-direction counterpart of
+  # the row-stacking +concat+, and the positional counterpart of the key-aligned
+  # +join+; named after the UNIX +paste+). Both frames must have the same
+  # +nrow+; rows are assumed to already correspond (no key alignment, consistent
+  # with the no-implicit-align stance). Colliding column names are disambiguated
+  # by the same policy as +join+ (default suffix +_left+/+_right+, +suffixes:+ to
+  # override, +suffixes: false+ to raise). This frame's index is kept; +other+'s
+  # index, if any, is not carried (only its columns are pasted). Returns a new
+  # frame.
+  #
+  #   obs.paste(fcst)                          # side by side, same rows
+  #   obs.paste(fcst, suffixes: ["_obs", "_fcst"])
+  def paste(other, suffixes: DEFAULT_JOIN_SUFFIXES)
+    CAFrame.paste(self, other, suffixes: suffixes)
+  end
+
+  # Paste N frames side by side by row position (symmetric N-ary sibling of
+  # the instance +#paste+; see the instance verb's docstring for the pair
+  # semantics).  All frames must have the same +nrow+.  The result's
+  # +axis_name+ and +index+ come from the first frame (peers, but a base is
+  # needed for the index).  Column names that appear in more than one frame
+  # are colliding — pass +suffixes:+ as an Array of exactly K strings (one
+  # per input frame) to disambiguate them; otherwise the collision raises.
+  #
+  #   CAFrame.paste(obs, fcst)
+  #   CAFrame.paste(obs, ecmwf, gfs, suffixes: ["_obs", "_ecmwf", "_gfs"])
+  #   CAFrame.paste([obs, fcst])                              # Array is accepted too
+  def self.paste(*frames, suffixes: DEFAULT_JOIN_SUFFIXES)
+    frames = frames.flatten
+    raise ArgumentError, "paste requires at least one frame" if frames.empty?
+    unless frames.all? { |f| f.is_a?(CAFrame) }
+      raise ArgumentError, "paste expects CAFrame arguments"
+    end
+    first = frames.first
+    nrow  = first.nrow
+    frames.each_with_index do |f, i|
+      next if i.zero?
+      unless f.nrow == nrow
+        raise ArgumentError,
+              "paste: row-count mismatch (frame #{i}: #{f.nrow} vs #{nrow}); " \
+              "use join for key alignment"
+      end
+    end
+
+    # Detect columns that appear in 2+ frames (collisions across the K inputs).
+    name_count = Hash.new(0)
+    frames.each { |f| f.variable_names.each { |name| name_count[name] += 1 } }
+    collisions = name_count.select { |_, n| n > 1 }.keys
+
+    if collisions.any?
+      if suffixes == false
+        raise ArgumentError,
+              "paste column name collision: #{collisions.inspect} " \
+              "(pass suffixes: [\"_a\", \"_b\", ...] with one entry per frame, " \
+              "or rename first)"
+      end
+      # For the 2-frame case DEFAULT_JOIN_SUFFIXES ("_left", "_right") works
+      # as-is; for K > 2 the caller must pass a K-length Array (or use the
+      # pair-only default indirectly via the instance method).
+      unless suffixes.is_a?(Array) && suffixes.size == frames.size &&
+             suffixes.all? { |s| s.is_a?(String) }
+        raise ArgumentError,
+              "paste: suffixes must be an Array of #{frames.size} Strings " \
+              "(one per frame), got #{suffixes.inspect}"
+      end
+    end
+
+    cols = {}
+    frames.each_with_index do |f, i|
+      f.variable_names.each do |name|
+        key = collisions.include?(name) ? "#{name}#{suffixes[i]}" : name
+        if cols.key?(key)
+          raise ArgumentError,
+                "paste: column name #{key.inspect} produced twice " \
+                "(collision after suffix from frame #{i})"
+        end
+        cols[key] = f[name]
+      end
+    end
+    new(cols, axis_name: first.axis_name, index: first.index)
+  end
+
+  private def join_name_plan(other, on, suffixes)
+    collisions = (variable_names & other.variable_names) - [on]
+    return { collisions: [], lsuf: nil, rsuf: nil } if collisions.empty?
+
+    if suffixes == false
+      raise ArgumentError,
+            "join column name collision: #{collisions.inspect} " \
+            "(pass suffixes: [\"_l\", \"_r\"] to disambiguate, or rename first)"
+    end
+    unless suffixes.is_a?(Array) && suffixes.size == 2 && suffixes.all? { |s| s.is_a?(String) }
+      raise ArgumentError,
+            "suffixes must be false or a 2-element array of Strings, got #{suffixes.inspect}"
+    end
+    { collisions: collisions, lsuf: suffixes[0], rsuf: suffixes[1] }
+  end
+
+  private def join_name(name, suffix, plan)
+    plan[:collisions].include?(name) ? "#{name}#{suffix}" : name
+  end
+
+  private def put_join_column(cols, name, col)
+    if cols.key?(name)
+      raise ArgumentError,
+            "join produces a duplicate column #{name.inspect} after suffixing; " \
+            "rename a column first or pass different suffixes"
+    end
+    cols[name] = col
+  end
+
+  private def join_left(other, on, lkey, rkey, plan)
+    join_by_addr(other, on, lkey.locate_addr(rkey), plan)
+  end
+
+  private def join_by_addr(other, on, addr, plan)
+    cols = {}
+    variable_names.each { |name| put_join_column(cols, join_name(name, plan[:lsuf], plan), self[name]) }
+    other.variable_names.each do |name|
+      next if name == on
+      put_join_column(cols, join_name(name, plan[:rsuf], plan), project_rows(other[name], addr))
+    end
+    CAFrame.new(cols, axis_name: @axis_name, index: @index)
+  end
+
+  private def join_align(other, on, lkey, rkey, how, plan)
+    common, a_idx, b_idx = CArray.align_addr(lkey, rkey, join: how)
+    cols = {}
+    variable_names.each do |name|
+      if name == on
+        put_join_column(cols, on, common)
+      else
+        put_join_column(cols, join_name(name, plan[:lsuf], plan), project_rows(self[name], a_idx))
+      end
+    end
+    other.variable_names.each do |name|
+      next if name == on
+      put_join_column(cols, join_name(name, plan[:rsuf], plan), project_rows(other[name], b_idx))
+    end
+    # Carry the left index the same way its columns are gathered (by a_idx),
+    # so it stays consistent with the left join; rows with no left match
+    # (outer/right) become UNDEF.
+    new_index = @index && project_rows(@index, a_idx)
+    CAFrame.new(cols, axis_name: @axis_name, index: new_index)
+  end
+
+  private def project_rows(col, addr)
+    return col.project(addr) if col.ndim == 1
+    trailing = col.shape[1..]
+    t = trailing.inject(1, :*)
+    n = addr.shape[0]
+    flat = addr.reshape(n, 1) * t + CArray.int64(t).seq.reshape(1, t)
+    col.project(flat).reshape(n, *trailing)
+  end
+end

data/lib/carray/frame/records.rb

@@ -0,0 +1,99 @@
+# 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,
+# 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 --
+# §4.2 stays intact: no date-like string is parsed, mixed columns stay object).
+#
+# An Array-valued cell that is the same length across every record becomes an
+# N-D column (§11.5): { "temp" => [min, mean, max] } over N records is one
+# (N, 3) column. Ragged or non-numeric arrays fall back to an object column.
+#
+# Missing keys and explicit nils become UNDEF for numeric columns (mask, not a
+# float promotion): an int column with a hole stays int + UNDEF.
+
+class CAFrame
+  # Build a frame from an Array of row Hashes. Column set is the union of keys
+  # in first-appearance order; keys are stringified. +types:+ casts named
+  # columns afterward (same map / array-key forms as +cast+).
+  def self.from_records(records, types: nil)
+    unless records.is_a?(Array) && records.all? { |r| r.is_a?(Hash) }
+      raise ArgumentError, "from_records expects an Array of Hashes"
+    end
+    return new if records.empty?
+
+    keys = record_key_union(records)
+    n = records.size
+    cols = {}
+    keys.each do |key|
+      values = records.map { |r| r[key] }
+      cols[key.to_s] = build_record_column(values, n)
+    end
+
+    frame = new(cols)
+    frame.cast(types) if types
+    frame
+  end
+
+  # Union of record keys in first-appearance order (original key objects, so a
+  # String- or Symbol-keyed set both work; the column name stringifies later).
+  def self.record_key_union(records)
+    seen = {}
+    keys = []
+    records.each do |r|
+      r.each_key do |k|
+        unless seen.key?(k)
+          seen[k] = true
+          keys << k
+        end
+      end
+    end
+    keys
+  end
+  private_class_method :record_key_union
+
+  # Arrange one column's values (Ruby objects, nil for missing) into a CArray.
+  # All-Array cells of equal length -> N-D native column; numeric scalars ->
+  # native scalar column (nil -> UNDEF); anything else -> object column.
+  def self.build_record_column(values, n)
+    present = values.reject(&:nil?)
+    return CArray.object(n) { values } if present.empty?
+
+    if present.all? { |v| v.is_a?(Array) || v.is_a?(CArray) }
+      build_nd_column(values, present, n)
+    else
+      type = numeric_leaf_type(present)
+      col = CArray.object(n) { values }
+      type ? col.to_type(type) : col
+    end
+  end
+  private_class_method :build_record_column
+
+  # Stack equal-length array cells into an (N, L) column via an object 2-D fill
+  # + to_type (nil rows -> UNDEF, int/float by leaf). Ragged lengths or
+  # non-numeric leaves fall back to a 1-D object column of the raw cells.
+  def self.build_nd_column(values, present, n)
+    lengths = present.map { |v| v.is_a?(CArray) ? v.shape[0] : v.size }
+    len = lengths.first
+    return CArray.object(n) { values } unless lengths.all? { |x| x == len }
+
+    nested = values.map { |v| v.nil? ? Array.new(len) : (v.is_a?(CArray) ? v.to_a : v) }
+    type = numeric_leaf_type(nested.flatten.compact)
+    table = CArray.object(n, len) { nested }
+    type ? table.to_type(type) : table
+  end
+  private_class_method :build_nd_column
+
+  # :int64 if every value is an Integer, :float64 if all are Numeric (int/float
+  # mix), otherwise nil (strings / DateTime / booleans / mixed -> keep object).
+  def self.numeric_leaf_type(values)
+    if values.all? { |v| v.is_a?(Integer) }
+      :int64
+    elsif values.all? { |v| v.is_a?(Numeric) }
+      :float64
+    end
+  end
+  private_class_method :numeric_leaf_type
+end