carray 3.0.2 → 3.0.4

data/lib/carray/histogram.rb

@@ -321,6 +321,7 @@ class CArray
 
       if weights
         raise ArgumentError, "weights given but accumulator is unweighted" unless @weighted
+        # coerce: the accumulator's type, declared by weights_data_type:
         weights = CArray.wrap_readonly(weights, @counts_data_type)
         expected_w_shape = chunk.shape.dup
         expected_w_shape.delete_at(channel_ax)
@@ -447,7 +448,7 @@ class CArray
   #   @param weights [CArray, nil] optional per-sample weights.
   #   @return [Histogram] 1-D accumulator (`m == 1`).
   def histogram1d (edges:, axis: -1, include_max: false, weights: nil)
-    ax = normalize_axis(axis, "histogram1d")
+    ax = normalize_axis(axis.nil? ? -1 : axis, "histogram1d")
 
     new_shape = shape + [1]
     arr_with_channel = reshape(*new_shape)
@@ -491,6 +492,10 @@ class CArray
   def histogram (edges:, axis: [-2, -1], include_max: false, weights: nil)
     raise ArgumentError, "edges must be an Array of edges arrays" unless edges.is_a?(Array)
     arr = self
+    axis = [-2, -1] if axis.nil?
+    unless axis.is_a?(Array) && axis.size == 2
+      raise ArgumentError, "histogram: axis: is a [sample, channel] pair (got #{axis.inspect})"
+    end
     sample_ax  = normalize_axis(axis[0], "histogram sample axis")
     channel_ax = normalize_axis(axis[1], "histogram channel axis")
     fiber_shape = arr.shape.dup

data/lib/carray/inspect.rb

@@ -17,13 +17,12 @@ class CArray::Inspector  # :nodoc:
       raise "can't inspect CArray of ndim == 0"
     end
     formatter  = get_formatter()
-    class_name = get_class_name()
-    type_name  = get_type_name()
+    label      = get_label()
     shape      = get_shape()
     data_spec  = get_data_spec(0, Array.new(@carray.ndim){0}, formatter, abbrev)
     info_list  = get_info_list()
     output = ["<",
-              format("%s.%s(%s)", class_name, type_name, shape.join(",")),
+              format("%s(%s)", label, shape.join(",")),
               ": ",
               info_list.join(" "),
               "\n",
@@ -35,6 +34,39 @@ class CArray::Inspector  # :nodoc:
   
   private
 
+  # The name before the shape: the class and the storage type, or for a
+  # Face its own name (see .face_label).
+  def get_label
+    return CArray::Inspector.face_label(@carray) if @carray.face?
+    return format("%s.%s", get_class_name, get_type_name)
+  end
+
+  public
+
+  # The name a Face goes by where a person reads it -- the head of inspect,
+  # a frame's column list.  A Face's data_type is the surface the kernels
+  # dispatch on (fixlen for a time, so arithmetic on it raises), which says
+  # nothing to a reader, so it is named by its class: what a private
+  # inspect_label gives (CATime adds its tick), or the class, with the
+  # surface type only for a Face whose surface is numeric.
+  # The type of an array as a person reads it in a message or a table: a
+  # Face by its name (face_label), any other array by its data type name.
+  # Every message and listing that names a type goes through here, so a
+  # Face is never named by its storage (:fixlen for a time).
+  def self.type_label (ca)
+    ca.face? ? face_label(ca) : CArray.data_type_name(ca.data_type).to_s
+  end
+
+  def self.face_label (ca)
+    return ca.send(:inspect_label) if ca.respond_to?(:inspect_label, true)
+    klass = ca.class
+    klass = klass.superclass while klass.name.nil?
+    return klass.name if [CA_FIXLEN, CA_OBJECT].include?(ca.data_type)
+    "#{klass.name}.#{CArray.data_type_name(ca.data_type)}"
+  end
+
+  private
+
   def get_class_name
     return @carray.class.to_s
   end
@@ -110,15 +142,27 @@ class CArray::Inspector  # :nodoc:
   end
 
   def get_formatter
-    # A Face that defines storage_to_scalar decodes each cell into a surface
+    # A Face can write its cells itself through a private
+    # inspect_cell_formatter, a lambda taking the decoded cell.
+    if @carray.respond_to?(:inspect_cell_formatter, true)
+      return @carray.send(:inspect_cell_formatter)
+    end
+    # A Face that defines storage_to_element decodes each cell into a surface
     # value (CATime::Element, a String, a category label, ...) that has nothing
     # to do with the storage data_type, so the formatter must follow the decoded
     # value, not the storage.  Faces without the hook (CAString) hand back the
     # stored value itself and fall through to the storage formatters below.
-    if @carray.face? and @carray.respond_to?(:storage_to_scalar)
+    if @carray.face? and @carray.respond_to?(:storage_to_element)
       return lambda { |x| x.inspect }
     end
-    case @carray.data_type
+    data_type = @carray.data_type
+    # The same Faces behind a gated (fixlen) surface hand back the value of
+    # their storage, so they take the storage's formatter.
+    if @carray.face? and data_type == CA_FIXLEN and not @carray.data_class
+      storage = @carray.parent.data_type
+      data_type = storage unless storage == CA_FIXLEN
+    end
+    case data_type
     when CA_BOOLEAN
       # Boolean cells fetch as true/false; show compact 1/0 (masked = _).
       # The type name in the inspect header distinguishes this from an int array.
@@ -134,11 +178,8 @@ class CArray::Inspector  # :nodoc:
                         x.real.inspect, (x.imag >= 0) ? "+" : "-", x.imag.abs.inspect) }
     when CA_FIXLEN
       if @carray.data_class
-        if @carray.bytes <= 6
-          lambda{|x| "%s" % x.encode.dump }
-        else
-          lambda{|x| "%s" % (x.encode.chomp[0, 5]+"...").dump }
-        end
+        # A record shows its members, as the element's own inspect does.
+        lambda{|x| x.inspect }
       else
         if @carray.bytes <= 6
           lambda{|x| "%s" % x.dump }
@@ -259,10 +300,10 @@ class CArray
     case data_type 
     when CA_FIXLEN
       output << sprintf("CArray.%s(%s, :bytes=>%i)", 
-                        data_type_name, dim.inspect[1..-2], bytes)
+                        data_type_name, shape.inspect[1..-2], bytes)
     else
       output << sprintf("CArray.%s(%s)", 
-                        data_type_name, dim.inspect[1..-2])
+                        data_type_name, shape.inspect[1..-2])
     end
     return output
   end

data/lib/carray/iterator.rb

@@ -29,6 +29,55 @@ class CAIterator
   attr_reader :ndim, :shape
   alias dim shape
 
+  # The keywords a member passes on to a core reduction over its own axes.
+  # The member sets `axis:`, so one from the caller is refused; the rest go
+  # to the core, which checks them.
+  # Whether a fill method carries values backward: :forward / :ffill carry
+  # them forward, :backward / :bfill back. A member fills within its own
+  # pieces by holding the nearest present value; :linear, which needs a
+  # coordinate, is the core's alone.
+  def self.hold_backward? (method) # :nodoc:
+    case method
+    when :forward, :ffill   then false
+    when :backward, :bfill  then true
+    else
+      raise ArgumentError,
+            "strip_mask: method must be :forward, :ffill, :backward or :bfill " \
+            "within a piece (got #{method.inspect})"
+    end
+  end
+
+  # A one-cell (1, 1) array of the kind `value` holds, for asking the core
+  # what a reduction or scan of it answers in: its data type, cell width and,
+  # for a Face, its Face.  A member that answers by a route of its own
+  # (a fused kernel, a fold by offset) takes its output type from here, so
+  # the route and the core cannot disagree.  A Face is a view of the values
+  # themselves rather than a blank -- a Face cannot be allocated from its
+  # surface data type alone, and a zeroed record is not a valid cell for every
+  # one (a const string's record indexes a shared pool).  A Face with no cell
+  # is asked with the blank cell its resize gives, so a reduction over no
+  # groups answers in the same kind as over some; this is nil only when the
+  # Face has no blank cell.
+  def self.core_probe (value) # :nodoc:
+    unless value.face?
+      return CArray.new(value.data_type, [1, 1], bytes: value.bytes)
+    end
+    flat = value.reshape(value.elements)
+    return flat[[0]].reshape(1, 1) if value.elements > 0
+    begin
+      flat.resize(1).reshape(1, 1)
+    rescue StandardError
+      nil
+    end
+  end
+
+  def self.reduce_keywords (op, kw) # :nodoc:
+    if kw.key?(:axis)
+      raise ArgumentError, "#{op}: unknown keyword: :axis (the iterator sets the axes)"
+    end
+    kw
+  end
+
   # The required reduction surface, modelled on the two reference members
   # CASlabIterator and CACategoricalIterator (the surface they both provide).
   # Declared abstract so a later member
@@ -117,6 +166,18 @@ class CAIterator
   #   Returns the five-number summary of each piece,
   #   `[min, Q1, median, Q3, max]`.
   #   @return [Array<CArray>] five arrays, one per position.
+  # @!method first
+  #   Returns the first present value of each piece, in the piece's own
+  #   order; a piece with no present value is UNDEF.
+  #   @return [CArray] one value per piece, in the source's data type.
+  # @!method last
+  #   Returns the last present value of each piece; a piece with no present
+  #   value is UNDEF.
+  #   @return [CArray] one value per piece, in the source's data type.
+  # @!method nunique
+  #   Returns the number of distinct present values in each piece, as
+  #   `CArray#nunique` counts them; a piece with none counts 0.
+  #   @return [CArray] `:int64`, one count per piece.
   # @!method count(value = nil)
   #   Returns a count per piece: with no argument the cells that are not
   #   masked, with `UNDEF` the masked cells, and with any other value the
@@ -144,19 +205,23 @@ class CAIterator
   #   @yieldparam piece [CArray] next piece.
   #   @yieldreturn [Object] updated accumulator.
   #   @return [Object] the final accumulator.
-  [
+  REQUIRED_SURFACE = [
     :sum, :accumulate, :prod, :mean, :min, :max,                      # tier 1
     :variance, :stddev, :all, :any,
     :variancep, :stddevp, :minmax,                                    # tier 2
     :min_index, :max_index, :min_addr, :max_addr,                     # position
     :wsum, :wmean,                                                    # weighted
     :median, :percentile, :quantile,                                 # tier 3
+    :first, :last, :nunique,                                          # position / distinct
     :count, :count_not_masked, :count_masked, :elements,             # count family
     :each, :reduce,                                                   # generic iterate
-  ].each do |name|
-    define_method(name) do |*, **, &_blk|
+  ].freeze
+
+  REQUIRED_SURFACE.each do |name|
+    # define_method: a stub that names itself in its own message
+    define_method(name, &Ractor.make_shareable(proc do |*, **, &_blk|
       raise NotImplementedError, "#{self.class} must implement ##{name}"
-    end
+    end))
   end
 
   # Recommended (should) surface -- template methods.  These are well-defined
@@ -164,7 +229,8 @@ class CAIterator
   # required: `map` is a per-piece element-wise transform scattered back to the
   # source, `sort_addr` is a per-piece sort returning source flat addresses, and
   # the segment scans (cumsum / cumprod / cummax / cummin / cumcount) write a
-  # per-cell running statistic of each piece.  A member implements each when it
+  # per-cell running statistic of each piece, and `lag` the value some steps
+  # earlier in the same piece.  A member implements each when it
   # is well-defined and overrides it to raise with a reason when it is not.  The
   # scans belong here for the same reason as map: a running per-cell value is
   # single-valued only when each cell belongs to exactly one piece, so the
@@ -209,11 +275,35 @@ class CAIterator
   #   masked within each piece.
   #   @return [CArray] shaped like the source.
   #   @raise [NotImplementedError] for a member whose pieces overlap.
-  [:map, :sort_addr,
-   :cumsum, :cumprod, :cummax, :cummin, :cumcount].each do |name|
-    define_method(name) do |*, **, &_blk|
+  # @!method lag(n = 1)
+  #   Returns a source-shaped array whose cell holds the value `n` steps
+  #   earlier within the same piece, as `CArray#lag` does along an axis; a
+  #   cell with no such value in its piece is UNDEF, so a lag never reaches
+  #   across into another piece.
+  #   @param n [Integer] steps back; a negative `n` looks ahead.
+  #   @return [CArray] shaped like the source.
+  #   @raise [NotImplementedError] for a member whose pieces overlap, where a
+  #     cell has no single position within a piece.
+  # @!method strip_mask(method:)
+  #   Returns a source-shaped array with each masked cell filled from its own
+  #   piece, as `CArray#strip_mask(method:)` fills: `:forward` (`:ffill`)
+  #   carries the last present value forward, `:backward` (`:bfill`) the next
+  #   one back, never across into another piece.
+  #   @param method [Symbol] `:forward`, `:ffill`, `:backward` or `:bfill`.
+  #   @return [CArray] shaped like the source.
+  #   @raise [NotImplementedError] for a member whose pieces overlap.
+  # @!method order(descending: false, method: :ordinal, kind: :quick)
+  #   Returns a source-shaped int64 array of each cell's rank among the cells
+  #   of its piece, as `CArray#order` ranks them (`0` the smallest).
+  #   @return [CArray] shaped like the source.
+  #   @raise [NotImplementedError] for a member whose pieces overlap, where a
+  #     cell has no single rank.
+  [:map, :sort_addr, :order, :strip_mask,
+   :cumsum, :cumprod, :cummax, :cummin, :cumcount, :lag].each do |name|
+    # define_method: a stub that names itself in its own message
+    define_method(name, &Ractor.make_shareable(proc do |*, **, &_blk|
       raise NotImplementedError, "#{self.class} does not provide ##{name} (optional)"
-    end
+    end))
   end
 
 end