carray 2.0.0 → 3.0.0

data/lib/carray/methods/nunique.rb

@@ -0,0 +1,46 @@
+class CArray
+
+  # @overload nunique(axis: nil, keep_axis: false)
+  #   Counts the distinct values of `self`. This is the scalar-reduction
+  #   member of the value-hash discovery family ({#unique},
+  #   {#mask_duplicates}, {#value_counts}): where {#unique} compresses
+  #   and {#value_counts} tabulates, `nunique` just counts.
+  #
+  #   With `axis: nil` (default) it counts distinct values across the
+  #   whole array and returns an Integer. With `axis: k` it counts per
+  #   fiber along axis `k`, returning a reduced `CA_INT64` CArray
+  #   (shape = self.shape with axis `k` removed; `keep_axis: true` keeps
+  #   it as a length-1 axis). The shape rule matches other per-axis
+  #   reductions such as `sum(axis:)`.
+  #
+  #   The distinct count has identity 0: an empty array, an all-masked
+  #   fiber, or a zero-length axis counts 0 (not UNDEF) — an empty set
+  #   has zero distinct values. Masked cells do not participate.
+  #
+  #   Numeric distinctness follows `==` with the family's two float
+  #   special cases: all NaN collapse to a single value and
+  #   -0.0 / +0.0 are the same value. For `CA_OBJECT` / `CA_FIXLEN`
+  #   distinctness follows Ruby `eql?` / `hash` (which, unlike numeric,
+  #   does not collapse distinct NaN objects).
+  #
+  #   @param axis [Integer, nil] axis to count along; `nil` counts over
+  #     the whole array.
+  #   @param keep_axis [Boolean] when `axis` is given, keep the reduced
+  #     axis as a length-1 axis instead of dropping it.
+  #   @return [Integer, CArray] Integer for `axis: nil`, otherwise a
+  #     reduced `CA_INT64` CArray.
+  def nunique (axis: nil, keep_axis: false)
+    # Per-fiber single-pass seen-set hash (C __nunique__), one lane per dtype
+    # family (numeric widen / NaN collapse, object rb_hash + rb_eql, fixlen
+    # byte-hash + memcmp). Masked cells are skipped; the accumulator is a no-op
+    # (the distinct count is the interned-key count).
+    if axis.nil?
+      # Whole-array distinct count: flatten to 1-D and reduce its only axis,
+      # then read the single reduced cell as an Integer.
+      flatten.send(:__nunique__, 0, false)[0]
+    else
+      __nunique__(normalize_axis(axis, "nunique"), keep_axis)
+    end
+  end
+
+end

data/lib/carray/methods/resize.rb

@@ -0,0 +1,56 @@
+class CArray
+
+  # @overload resize(*newdim, fill_value: 0)
+  #   Returns `self` resized to `newdim`. The original data is
+  #   placed at offset 0 (positive size) or right-aligned (negative
+  #   size); the new area outside the original region is filled
+  #   with `fill_value`, or -- for fixlen storage -- left as zero
+  #   bytes. Pass `UNDEF` to mask the new area.
+  #
+  #   Each entry of `newdim` is: `nil` to keep the current
+  #   `shape[i]`, a positive Integer for a new size with the
+  #   original left-aligned at offset 0, or a negative Integer
+  #   `d` for a new size `|d|` with the original right-aligned.
+  #
+  #   Works on Face arrays (CARecord / CATime / ...) and
+  #   plain fixlen: the resize is done on the storage layout
+  #   (preserving bytes) and re-wrapped as the same Face.
+  #
+  #   @param newdim [Array<Integer, nil>] new shape spec, one entry
+  #     per axis.
+  #   @param fill_value [Object] value for the extended area.
+  #   @return [CArray] resized copy.
+  def resize (*newdim, fill_value: 0)
+    raise "ndim mismatch" if newdim.size != ndim
+    offset = Array.new(ndim, 0)
+    newdim = newdim.each_with_index.map do |d, i|
+      case d
+      when nil
+        shape[i]
+      when Integer
+        size = d.abs
+        offset[i] = size - shape[i] if d < 0
+        size
+      else
+        raise "invalid dimension size"
+      end
+    end
+    face_parent = self.face? ? self : nil
+    src = self
+    src = src.parent while src.face?
+    dt    = src.data_type
+    bytes = (dt == :fixlen) ? src.bytes : nil
+    out = CArray.new(dt, newdim, bytes: bytes)
+    # Fill the new area: numeric storage takes fill_value as-is; fixlen
+    # storage cannot hold a numeric 0, so leave zero bytes and honor only
+    # UNDEF (mask) or an explicit String fill.
+    if dt != :fixlen || fill_value.equal?(UNDEF) || fill_value.is_a?(String)
+      out[] = fill_value
+    end
+    out.mask.paste(offset, src.false) if out.has_mask?
+    out.paste(offset, src)
+    out = out.face_lift(face_parent) if face_parent
+    out
+  end
+
+end

data/lib/carray/methods/snap.rb

@@ -0,0 +1,156 @@
+class CArray
+
+  # @overload snap(step, offset: 0.0, direction: :round)
+  #   Returns each element snapped to a point on the uniform grid
+  #   `..., -step + offset, offset, step + offset, 2*step + offset, ...`.
+  #   The rounding rule follows `direction:` (default `:round`,
+  #   matching `CArray#round`; `:floor` snaps toward `-inf`, `:ceil`
+  #   toward `+inf`).
+  #
+  #   The output has the same dtype as `self` (integer input is coerced
+  #   to float internally when `step` / `offset` are floats, following
+  #   normal arithmetic promotion). NaN / Inf are preserved as a mask
+  #   on the output; the rounding kernels map NaN to 0.0, which would
+  #   silently land NaN cells on the grid, so NaN is detected
+  #   explicitly on the scaled chain.
+  #
+  #   Use `snap_to(list)` when the target grid is non-uniform; use
+  #   `bin(vmin, vmax, step)` when the desired output is a bin index.
+  #
+  #   @param step [Numeric] positive grid spacing.
+  #   @param offset [Numeric] phase / origin of the grid; the grid
+  #     always passes through `offset`.
+  #   @param direction [:round, :floor, :ceil] rounding rule; `:round`
+  #     picks the nearest grid point (ties half-away-from-zero),
+  #     `:floor` picks the grid point at or below the value, `:ceil`
+  #     picks the grid point at or above.
+  #   @return [CArray] snapped values, same shape as `self`.
+  #   @raise [ArgumentError] when `step <= 0` or `direction` is not one
+  #     of the accepted symbols.
+  #   @example
+  #     temp.snap(0.5)                        # nearest 0.5 K grid point
+  #     temp.snap(0.5, offset: 0.25)          # to 0.25, 0.75, 1.25, ... (bin centers)
+  #     temp.snap(0.5, direction: :floor)     # bin lower edge
+  #     temp.snap(0.5, direction: :ceil)      # bin upper edge
+  def snap(step, offset: 0.0, direction: :round)
+    raise ArgumentError, "snap: step must be > 0" unless step > 0
+    unless [:round, :floor, :ceil].include?(direction)
+      raise ArgumentError,
+            "snap: direction must be :round / :floor / :ceil " \
+            "(got #{direction.inspect})"
+    end
+
+    scaled = (self - offset) / step
+
+    # Detect NaN / Inf before rounding (which maps NaN -> 0.0 silently).
+    invalid_mask = scaled.float? ? scaled.is_invalid : nil
+
+    out = scaled.send(direction) * step + offset
+
+    if invalid_mask && invalid_mask.count(true) > 0
+      out.mask = out.has_mask? ? (out.mask | invalid_mask) : invalid_mask
+    end
+
+    out
+  end
+
+  # @overload snap_to(list, lfill: :clamp, ufill: :clamp, direction: :round)
+  #   Returns each element snapped to a value in `list` (non-uniform
+  #   grid). The rounding rule follows `direction:` (default `:round`
+  #   for nearest neighbour; `:floor` picks the list value at or below
+  #   the sample, `:ceil` at or above), and delegates to
+  #   `locate_nearest_addr(direction:)`.
+  #
+  #   `list` must be a 1-D ascending numeric CArray (or convertible via
+  #   `CArray.wrap_readonly`). Out-of-range and NaN handling follows the
+  #   same pattern as `bin_to`, but with an additional `:clamp`
+  #   sentinel that snaps out-of-range cells to the nearest list end.
+  #
+  #   - `:clamp` (default) — below-range cells become `list[0]`,
+  #     above-range cells become `list[-1]`.
+  #   - `nil` — the side is masked in the output.
+  #   - any other value — the side is filled with that value.
+  #
+  #   NaN / masked input cells are always masked in the output,
+  #   regardless of `lfill` / `ufill`.
+  #
+  #   Use `snap(step, offset:)` when the target grid is uniform; use
+  #   `bin_to(edges)` when the output is a bin index against half-open
+  #   intervals rather than a nearest-value snap.
+  #
+  #   @param list [CArray, Array<Numeric>] 1-D ascending grid, at least
+  #     one value.
+  #   @param lfill [:clamp, nil, Numeric] handling for below-`list[0]`
+  #     cells.
+  #   @param ufill [:clamp, nil, Numeric] handling for above-`list[-1]`
+  #     cells.
+  #   @param direction [:round, :floor, :ceil] rounding rule; forwarded
+  #     to `locate_nearest_addr`.
+  #   @return [CArray] snapped values with `list`'s data_type, same
+  #     shape as `self`.
+  #   @raise [ArgumentError] when `list` is not 1-D or is empty, or
+  #     `direction` is not one of the accepted symbols.
+  #   @example
+  #     temp.snap_to([270.0, 280.0, 290.0, 300.0])                   # clamp OOB
+  #     temp.snap_to(grid, lfill: nil, ufill: nil)                   # mask OOB
+  #     rain.snap_to([0.0, 1.0, 5.0, 20.0], direction: :floor)       # list value at or below
+  def snap_to(list, lfill: :clamp, ufill: :clamp, direction: :round)
+    ref = list.is_a?(CArray) ? list : CArray.wrap_readonly(list, self.data_type)
+    raise ArgumentError, "snap_to: list must be 1-D" unless ref.ndim == 1
+    n = ref.elements
+    raise ArgumentError, "snap_to: list must have at least one value" if n < 1
+
+    if n == 1
+      # Degenerate: every finite cell snaps to the only value.
+      out = CArray.new(ref.data_type, shape).fill(ref[0])
+      out.mask = self.mask.to_ca if self.has_mask?
+      if self.float?
+        inv = self.is_invalid
+        if inv.count(true) > 0
+          out.mask = out.has_mask? ? (out.mask | inv) : inv
+        end
+      end
+      return out
+    end
+
+    # `locate_nearest_addr` (via `linear_section`) accepts a 1-D `val` only;
+    # flatten multi-D input and reshape the result back to preserve the
+    # element-wise semantic on any shape.
+    if ndim > 1
+      return reshape(-1).snap_to(ref, lfill: lfill, ufill: ufill,
+                                 direction: direction).reshape(*shape)
+    end
+
+    # locate_nearest_addr returns int64 indices; OOB (below / above / NaN)
+    # cells come back masked. We split OOB into below / above with
+    # explicit comparisons so the two sides can be filled independently.
+    idx = self.locate_nearest_addr(ref, direction: direction)
+    out = ref.project(idx)
+
+    below = self.lt(ref[0])
+    above = self.gt(ref[-1])
+
+    case lfill
+    when :clamp then out[below] = ref[0]
+    when nil    then # leave masked (locate_nearest_addr already masked OOB)
+    else             out[below] = lfill
+    end
+
+    case ufill
+    when :clamp then out[above] = ref[-1]
+    when nil    then # leave masked
+    else             out[above] = ufill
+    end
+
+    # Propagate input mask (locate_nearest_addr / project do not forward
+    # `self`'s mask on their own; a masked input cell must produce a
+    # masked output cell regardless of the fill options above).
+    if self.has_mask?
+      m = self.mask.to_ca
+      out.mask = out.has_mask? ? (out.mask | m) : m
+    end
+
+    out
+  end
+
+end

data/lib/carray/methods/string_format.rb

@@ -0,0 +1,57 @@
+#  CArray.format (class) and CArray#format (instance) — element-wise
+#  Kernel.format producing a CAString.  The instance form is the explicit
+#  numeric->string escape (a numeric array carries no implicit to_string).
+#  Single-feature method file (autoloaded on first format call).
+
+class CArray
+
+  # @overload format(fmt, *argv)
+  #   Returns a {CAString} of formatted strings.  Each output cell at index
+  #   `idx` is `Kernel.format(fmt, *args)` where a CArray argument contributes
+  #   its `[*idx]` cell and any non-CArray argument is broadcast as-is.  The
+  #   output shape is taken from the first CArray argument; every CArray
+  #   argument must share that shape.
+  #   @param fmt [String] `Kernel.format` template.
+  #   @param argv [Array<CArray, Object>] per-cell CArrays and/or broadcast scalars.
+  #   @return [CAString]
+  #   @raise [ArgumentError] when no CArray argument is given, or CArray shapes differ.
+  def self.format (fmt, *argv)
+    cas = argv.select { |a| a.is_a?(CArray) }
+    raise ArgumentError, "CArray.format: at least one CArray argument is required" if cas.empty?
+    shape = cas.first.shape
+    cas.each do |a|
+      next if a.shape == shape
+      raise ArgumentError,
+            "CArray.format: shape mismatch (#{a.shape.inspect} vs #{shape.inspect})"
+    end
+    out = CArray.object(*shape)
+    out.map_with_index! do |_, *idx|
+      args = argv.map { |a| a.is_a?(CArray) ? a[*idx] : a }
+      # a masked cell in any source array masks the output (UNDEF), rather
+      # than feeding UNDEF into Kernel.format.
+      args.any? { |v| v.equal?(UNDEF) } ? UNDEF : Kernel.format(fmt, *args)
+    end
+    CAString.wrap(out)
+  end
+
+  # @overload format(fmt, *argv)
+  #   Returns a {CAString} formatting each cell of `self` with `fmt`; `self`
+  #   is the first `Kernel.format` argument, so `arr.format("%03d")` renders
+  #   the cells and `arr.format("%s=%d", other)` interleaves a second array.
+  #   This is the explicit stringify path for numeric (and any) arrays — the
+  #   `to_*` string conversions are String-Face only.  Equivalent to
+  #   `CArray.format(fmt, self, *argv)`.
+  #
+  #   Defining a public `CArray#format` shadows the private `Kernel#format`
+  #   for CArray instances; internal CArray methods therefore use `sprintf` /
+  #   `Kernel.format` explicitly (verified: no bare `format(...)` call runs on
+  #   a CArray receiver anywhere in the library).
+  #   @param fmt [String] `Kernel.format` template.
+  #   @param argv [Array<CArray, Object>] additional per-cell CArrays / broadcast scalars.
+  #   @return [CAString]
+  #   @raise [ArgumentError] when a CArray argument's shape differs from self.
+  def format (fmt, *argv)
+    CArray.format(fmt, self, *argv)
+  end
+
+end

data/lib/carray/methods/unique.rb

@@ -0,0 +1,47 @@
+class CArray
+
+  # @overload unique(sort: false)
+  #   Returns a 1-D CArray of the distinct values of `self`, in
+  #   first-appearance (row-major flatten) order. This is the
+  #   compressing counterpart of {#mask_duplicates} (which marks
+  #   without compressing): because different fibers may hold
+  #   different numbers of distinct values, compression is only
+  #   well-defined over the whole array, so `unique` is always flat.
+  #
+  #   Named `unique` (not `uniq`) because distinctness is value-based
+  #   like NumPy / pandas `unique`: unlike Ruby `Array#uniq` it
+  #   collapses all NaN to a single value (see below), so the name
+  #   avoids promising `Array#uniq` semantics.
+  #
+  #   Masked cells do not participate and never appear in the result;
+  #   an all-masked array yields an empty CArray.
+  #
+  #   Distinctness follows `==` for numeric dtypes, with two float
+  #   special cases so the result matches value-based expectations:
+  #   all NaN collapse to a single distinct value (rather than one per
+  #   cell) and -0.0 / +0.0 are the same value. The value kept for
+  #   each key is the first one seen, so a leading -0.0 keeps its sign.
+  #   For `CA_OBJECT` / `CA_FIXLEN` distinctness follows Ruby
+  #   `eql?` / `hash`; note that Ruby does not collapse distinct NaN
+  #   objects, so a `CA_OBJECT` array of Float NaN is not collapsed
+  #   (unlike the numeric path).
+  #
+  #   @param sort [Boolean] when true, return the distinct values
+  #     sorted ascending instead of in first-appearance order.
+  #   A time array (`CATime` / `CATimedelta`) answers with its own type on
+  #   its own unit: the distinct values are values, so the array comes back
+  #   as itself rather than as raw storage ticks.
+  #
+  #   @return [CArray] 1-D CArray of the distinct values, same dtype
+  #     as `self`.
+  def unique (sort: false)
+    # Single-pass seen-set hash (C __unique_flat__), one lane per dtype family:
+    # integer widens to a 64-bit key; float uses the bitwise key with all-NaN
+    # collapsed and -0.0 / +0.0 normalized; object keys on rb_hash + rb_eql and
+    # fixlen on a byte-hash + memcmp, both reproducing Ruby Hash distinctness.
+    # Masked cells are skipped in the kernel.
+    levels = __unique_flat__
+    sort ? levels.sort : levels
+  end
+
+end

data/lib/carray/methods/value_counts.rb

@@ -0,0 +1,71 @@
+class CArray
+
+  # @overload value_counts(sort: false)
+  #   Returns `[values, counts]`, the distinct values of `self` paired
+  #   with the number of times each occurs. `values` is a 1-D CArray of
+  #   `self`'s dtype; `counts` is a 1-D `CA_INT64` where `counts[i]` is
+  #   the number of occurrences of `values[i]`. This is the frequency-
+  #   table member of the value-hash discovery family ({#unique},
+  #   {#mask_duplicates}, {#nunique}); like {#unique} it always
+  #   flattens, because per-fiber distinct counts would be ragged.
+  #
+  #   By default the pairs are in first-appearance (row-major flatten)
+  #   order, matching {#unique}. `sort:` reorders both arrays together:
+  #
+  #   - `false` (default) — first-appearance order.
+  #   - `:count` — descending frequency; ties keep first-appearance
+  #     order (deterministic).
+  #   - `:value` — ascending value (float NaN sorts last, as in
+  #     `unique(sort: true)`).
+  #
+  #   Masked cells do not participate and never appear; an all-masked
+  #   array yields two empty CArrays.
+  #
+  #   Numeric distinctness follows `==` with two float special cases so
+  #   the result matches value-based expectations: all NaN collapse to a
+  #   single value (their counts add up) and -0.0 / +0.0 are the same
+  #   value (the first-seen value is kept, so a leading -0.0 keeps its
+  #   sign). For `CA_OBJECT` / `CA_FIXLEN` distinctness follows Ruby
+  #   `eql?` / `hash`; Ruby does not collapse distinct NaN objects, so a
+  #   `CA_OBJECT` array of Float NaN is not collapsed (unlike numeric).
+  #
+  #   @param sort [false, :count, :value] pair ordering.
+  #   The values keep `self`'s type (a `CATime` comes back as a `CATime` on
+  #   its own unit); the counts are always a plain `:int64` CArray.
+  #
+  #   @return [Array(CArray, CArray)] `[values, counts]`.
+  def value_counts (sort: false)
+    unless [false, :count, :value].include?(sort)
+      raise ArgumentError, "value_counts: sort must be false, :count, or :value"
+    end
+    # Single-pass frequency-table hash (C __value_counts_flat__), one lane per
+    # dtype family: integer widens to a 64-bit key; float uses the bitwise key
+    # with all NaN collapsed and -0.0 / +0.0 normalized; object keys on rb_hash +
+    # rb_eql and fixlen on a byte-hash + memcmp, both reproducing Ruby Hash
+    # distinctness. Masked cells are skipped in the kernel.
+    values, counts = __value_counts_flat__
+    case sort
+    when :count
+      # Descending count, ties broken by first-appearance index (stable).
+      c = counts.to_a
+      order = (0...c.size).sort_by { |i| [-c[i], i] }
+      [ values[CArray.int64(order.size) { |i| order[i] }],
+        counts[CArray.int64(order.size) { |i| order[i] }] ]
+    when :value
+      # Ascending value; NaN (numeric) or non-comparable last. Build the
+      # permutation with an explicit NaN-last key so float NaN doesn't blow up
+      # the Ruby sort, then gather both arrays through it.
+      v = values.to_a
+      order = (0...v.size).sort_by do |i|
+        x = v[i]
+        nan = x.is_a?(Float) && x.nan?
+        [nan ? 1 : 0, nan ? 0 : x, i]
+      end
+      [ values[CArray.int64(order.size) { |i| order[i] }],
+        counts[CArray.int64(order.size) { |i| order[i] }] ]
+    else
+      [values, counts]
+    end
+  end
+
+end