carray 3.0.1 → 3.0.3

data/lib/carray/basics.rb

@@ -80,31 +80,31 @@ class CArray
         Array.new(flat.length, repeat)
       end
 
-  # Validate each value.  A positive Integer only; nil is not a valid
-  # per-axis repeat.
-  reps.each do |r|
-    unless r.is_a?(Integer)
-      raise ArgumentError,
-        "insert_axis: repeat must be a positive Integer, got #{r.inspect}"
+    # Validate each value.  A positive Integer only; nil is not a valid
+    # per-axis repeat.
+    reps.each do |r|
+      unless r.is_a?(Integer)
+        raise ArgumentError,
+          "insert_axis: repeat must be a positive Integer, got #{r.inspect}"
+      end
+      raise ArgumentError, "insert_axis: repeat count must be >= 1" if r < 1
     end
-    raise ArgumentError, "insert_axis: repeat count must be >= 1" if r < 1
-  end
 
-  # Final output layout: stable order by (gap, argument index) keeps
-  # same-gap axes in argument order; the k-th inserted axis lands at output
-  # position gap + k.  This output position only drives broadcast_to; the
-  # insertion itself always goes through the source-frame primitive.
-  order = (0...flat.length).sort_by { |i| [gaps[i], i] }
-  final = {}
-  order.each_with_index { |i, k| final[i] = gaps[i] + k }
+    # Final output layout: stable order by (gap, argument index) keeps
+    # same-gap axes in argument order; the k-th inserted axis lands at output
+    # position gap + k.  This output position only drives broadcast_to; the
+    # insertion itself always goes through the source-frame primitive.
+    order = (0...flat.length).sort_by { |i| [gaps[i], i] }
+    final = {}
+    order.each_with_index { |i, k| final[i] = gaps[i] + k }
 
-  inter = __insert_axis_size1__(*order.map { |i| gaps[i] })
-  return inter unless order.any? { |i| reps[i] > 1 }
+    inter = __insert_axis_size1__(*order.map { |i| gaps[i] })
+    return inter unless order.any? { |i| reps[i] > 1 }
 
-  shp = inter.shape
-  order.each { |i| shp[final[i]] = reps[i] if reps[i] > 1 }
-  inter.broadcast_to(*shp)
-end
+    shp = inter.shape
+    order.each { |i| shp[final[i]] = reps[i] if reps[i] > 1 }
+    inter.broadcast_to(*shp)
+  end
 
   # @overload drop_axis
   #   Returns a view of `self` with every size-1 axis dropped.
@@ -142,6 +142,28 @@ end
     return template(:boolean) { 1 }
   end
 
+  # A Face is clipped in its own terms: its comparisons decide which cells are
+  # out of range (a time array reads its bounds as times, a record array
+  # orders by its declared members, a Face that cannot be ordered refuses),
+  # and its store writes the bound or the fill value into them.
+  private def __face_clip__ (min, max, fill_value, lfill, ufill)
+    lfill = fill_value if lfill.nil?
+    ufill = fill_value if ufill.nil?
+    out = copy
+    out[self < min] = lfill.nil? ? min : lfill unless min.nil?
+    out[self > max] = ufill.nil? ? max : ufill unless max.nil?
+    out
+  end
+
+  # An array of +shape+ of the same kind as self: its data type and cell
+  # width, or its Face over a zero storage.  Nothing is written into it, so
+  # it can be built for a read-only Face too.
+  private def __blank_like__ (shape)
+    storage = __face_storage__
+    out = CArray.new(storage.data_type, shape, bytes: storage.bytes)
+    face? ? out.face_lift(self) : out
+  end
+
   # Sub-region copy (paste / crop), the old C `ca_paste` / `ca_clip` pair.
   # `clip` is reserved for value clamping (clamp to a min/max range), so
   # the read-out side is `crop`.  Kept together as a pair (crop is rare, but paste is reached
@@ -159,6 +181,10 @@ end
   #   @raise [ArgumentError] when `offset.length != self.ndim`.
   def paste (offset, src)
     raise ArgumentError, "offset length must equal ndim" if offset.length != ndim
+    # A zero-length source covers no cell, so there is nothing to write --
+    # and the empty range it would ask for is not a window CAWindow can
+    # build.  This is what lets concatenate / mosaic take an empty piece.
+    return self if src.elements.zero?
     ranges = offset.each_with_index.map { |o, i| o...(o + src.shape[i]) }
     self.window(*ranges)[] = src
     self
@@ -246,6 +272,31 @@ end
 
   # @!endgroup
 
+  # An Integer shift count on an integer array means what it means to
+  # Integer#<< and #>>: negative shifts the other way, and a count past the
+  # width shifts every bit out.  The kernels do that for a count of the
+  # array's own type; this brings a count the type cannot hold -- -1 for a
+  # uint8 array, 300 for an int8 one -- to one it can.
+  module IntegerShiftCount
+    UNSIGNED = [CA_UINT8, CA_UINT16, CA_UINT32, CA_UINT64].freeze
+
+    def << (other)
+      return super unless other.is_a?(Integer) && integer? && ! face?
+      w = bytes * 8
+      return self >> -other if other < 0 && UNSIGNED.include?(data_type)
+      super(other.clamp(-w, w))
+    end
+
+    def >> (other)
+      return super unless other.is_a?(Integer) && integer? && ! face?
+      w = bytes * 8
+      return self << -other if other < 0 && UNSIGNED.include?(data_type)
+      super(other.clamp(-w, w))
+    end
+  end
+  # Prepended by carray/lazy, after it has wrapped << and >>: prepended
+  # here, the method lazy aliases as the eager form would be this one.
+
   # @overload clip(min, max = nil, fill_value = nil, lfill: nil, ufill: nil)
   #   Returns `self` with every element clamped to `[min, max]`.
   #
@@ -254,7 +305,12 @@ end
   #   `fill_value` (or `lfill` / `ufill`) is given, out-of-range
   #   cells are replaced by the fill instead of clamped -- pass
   #   `UNDEF` to mask that end. `fill_value` is sugar for symmetric
-  #   dual-fill; `lfill` / `ufill` override per side.
+  #   dual-fill; `lfill` / `ufill` override per side, and a side
+  #   given no fill is still clamped.
+  #
+  #   `min` may not exceed `max` (in any cell, when a bound is an
+  #   array); equal bounds give every unmasked cell that value.
+  #   A NaN bound bounds nothing.
   #
   #   Boundary is strict `[min, max]`: values equal to a bound
   #   remain unchanged in both the clamped and filled variants.
@@ -268,7 +324,8 @@ end
   #   @param lfill [Object, nil] override below-range fill.
   #   @param ufill [Object, nil] override above-range fill.
   #   @return [CArray] new CArray with clamped or filled values.
-  #   @raise [ArgumentError] when both `min` and `max` are `nil`.
+  #   @raise [ArgumentError] when both `min` and `max` are `nil`,
+  #     or when `min` exceeds `max`.
   #   @example
   #     a.clip(0, 10)                          # strict clamp
   #     a.clip(0, 10, -1)                      # both ends -> -1
@@ -277,6 +334,16 @@ end
     if min.nil? && max.nil?
       raise ArgumentError, "clip: at least one of (min, max) must be given"
     end
+    return __face_clip__(min, max, fill_value, lfill, ufill) if face?
+    if !min.nil? && !max.nil?
+      reversed = if min.is_a?(CArray) then min.gt(max).any
+                 elsif max.is_a?(CArray) then max.lt(min).any
+                 else min > max
+                 end
+      if reversed
+        raise ArgumentError, "clip: min must be less than or equal to max"
+      end
+    end
 
     # `fill_value` as a single argument is sugar applied to both ends; kwargs override.
     lfill = fill_value if lfill.nil?
@@ -288,9 +355,12 @@ end
       return pmin(max)
     end
 
+    # A side without a fill still clamps.
     out = self.copy
-    out[:lt, min] = lfill unless min.nil? || lfill.nil?
-    out[:gt, max] = ufill unless max.nil? || ufill.nil?
+    out = out.pmax(min) if !min.nil? && lfill.nil?
+    out = out.pmin(max) if !max.nil? && ufill.nil?
+    out[self.lt(min)] = lfill unless min.nil? || lfill.nil?
+    out[self.gt(max)] = ufill unless max.nil? || ufill.nil?
     out
   end
 

data/lib/carray/bincount_nd.rb

@@ -269,6 +269,12 @@ class CArray
           term = strides_ext[k] == 1 ? b : b * strides_ext[k]
           ravel = ravel.nil? ? term : ravel + term
         end
+        # A NaN weight drops its sample, as the fiber kernel and histogram
+        # do; bincount itself would add the NaN in.
+        if tweights && tweights.float?
+          nan = tweights.is_nan
+          tweights = tweights.mask_where(nan) if nan.any
+        end
         chunk_counts = ravel.bincount(weights: tweights, length: total_ext)
         @full_counts[] = @full_counts + chunk_counts.reshape(*@full_counts.shape)
       else

data/lib/carray/block_iterator.rb

@@ -167,19 +167,44 @@ class CABlockIterator < CAIterator
   # below a full tile, so `min_count:` marks them UNDEF with no masking.  The
   # output data type is seeded from the first region (all regions share it).
   def assemble
-    outs = nil
+    grids = nil
+    faces = nil
+    single = true
     each_region do |strip_ranges, tiles, out_ranges|
       view = @source[*strip_ranges].block_view(*tiles)
       res  = yield(view, tiles)
-      if res.is_a?(Array)
-        outs ||= res.map { |r| CArray.new(r.data_type, @shape) }
-        res.each_index { |k| outs[k][*out_ranges] = res[k] }
-      else
-        outs ||= CArray.new(res.data_type, @shape)
-        outs[*out_ranges] = res
-      end
+      single = false if res.is_a?(Array)
+      res  = [res] unless res.is_a?(Array)
+      faces ||= res.map { |r| r.face? ? r : nil }
+      parts = res.map { |r| r.face? ? face_grid_part(r) : r }
+      grids ||= parts.map { |r| CArray.new(r.data_type, @shape, bytes: r.bytes) }
+      parts.each_index { |k| grids[k][*out_ranges] = parts[k] }
     end
-    outs
+    unless grids
+      # An empty source has no region.  A view with unit tiles has no cells
+      # either; reducing it gives each output's type for the empty grid.
+      res = yield(@source.block_view(*[1] * @sndim), [1] * @sndim)
+      single = !res.is_a?(Array)
+      res = [res] unless res.is_a?(Array)
+      faces = res.map { |r| r.face? ? r : nil }
+      grids = res.map { |r| r = face_grid_part(r) if r.face?; CArray.new(r.data_type, @shape, bytes: r.bytes) }
+    end
+    outs = grids.each_index.map { |k| faces[k] ? face_grid(grids[k], faces[k]) : grids[k] }
+    single ? outs[0] : outs
+  end
+
+  # A region result that is a Face (a CATime mean, a CATimedelta stddev) is
+  # assembled on its storage and the Face is put back on the whole grid;
+  # assembling the Face itself would copy its surface bytes into an array that
+  # no longer knows it is one.  A CAConstString's storage points into its own
+  # buffer, which the regions do not share, so it is assembled as strings.
+  def face_grid_part (r)
+    r.is_a?(CAConstString) ? r.to_string.parent : r.parent
+  end
+
+  def face_grid (grid, face)
+    return CArray.const_string(grid, encoding: face.encoding) if face.is_a?(CAConstString)
+    grid.face_lift(face)
   end
 
   # Fold every region with a single core reduction `op` (the tier-1 shape).
@@ -197,19 +222,92 @@ class CABlockIterator < CAIterator
   # data type, mask, empty / all-masked (identity vs UNDEF) and epsilon-close
   # contracts unchanged.  `min_count:` / `fill_value:` pass straight to the core.
 
-  # @overload sum(min_count: nil, fill_value: nil)
-  #   Per-tile sum.  @return [CArray] tile-grid shaped
-  # @overload accumulate(min_count: nil, fill_value: nil)
-  #   Per-tile sum kept in the source's own data type, wrapping at its width,
-  #   as the core `accumulate` does -- `sum` answers in the type the core
-  #   promotes to (float64 for integers), so a tile count over `uint8` cells
-  #   stays one byte wide instead of eight.
+  # @!method sum(min_count: nil, fill_value: nil)
+  #   Per-tile sum.
+  #   @param min_count [Integer, nil] fewest cells that must be present
+  #     for a result; a piece with fewer comes back masked.
+  #   @param fill_value [Object, nil] value to put in place of a masked
+  #     result instead of leaving it masked.
+  #   @return [CArray] tile-grid shaped
+  # @!method accumulate(min_count: nil, fill_value: nil)
+  #   Per-tile sum kept in the source's own data type, wrapping at its
+  #   width, as the core `accumulate` does -- `sum` answers in the type
+  #   the core promotes to (float64 for integers).
+  #   @param min_count [Integer, nil] fewest cells that must be present
+  #     for a result; a piece with fewer comes back masked.
+  #   @param fill_value [Object, nil] value to put in place of a masked
+  #     result instead of leaving it masked.
+  #   @return [CArray] tile-grid shaped
+  # @!method prod(min_count: nil, fill_value: nil)
+  #   Per-tile product.
+  #   @param min_count [Integer, nil] fewest cells that must be present
+  #     for a result; a piece with fewer comes back masked.
+  #   @param fill_value [Object, nil] value to put in place of a masked
+  #     result instead of leaving it masked.
+  #   @return [CArray] tile-grid shaped
+  # @!method mean(min_count: nil, fill_value: nil)
+  #   Per-tile arithmetic mean.
+  #   @param min_count [Integer, nil] fewest cells that must be present
+  #     for a result; a piece with fewer comes back masked.
+  #   @param fill_value [Object, nil] value to put in place of a masked
+  #     result instead of leaving it masked.
+  #   @return [CArray] tile-grid shaped
+  # @!method min(min_count: nil, fill_value: nil)
+  #   Per-tile minimum.
+  #   @param min_count [Integer, nil] fewest cells that must be present
+  #     for a result; a piece with fewer comes back masked.
+  #   @param fill_value [Object, nil] value to put in place of a masked
+  #     result instead of leaving it masked.
+  #   @return [CArray] tile-grid shaped
+  # @!method max(min_count: nil, fill_value: nil)
+  #   Per-tile maximum.
+  #   @param min_count [Integer, nil] fewest cells that must be present
+  #     for a result; a piece with fewer comes back masked.
+  #   @param fill_value [Object, nil] value to put in place of a masked
+  #     result instead of leaving it masked.
+  #   @return [CArray] tile-grid shaped
+  # @!method variance(min_count: nil, fill_value: nil)
+  #   Per-tile sample variance (divisor `n - 1`).
+  #   @param min_count [Integer, nil] fewest cells that must be present
+  #     for a result; a piece with fewer comes back masked.
+  #   @param fill_value [Object, nil] value to put in place of a masked
+  #     result instead of leaving it masked.
+  #   @return [CArray] tile-grid shaped
+  # @!method stddev(min_count: nil, fill_value: nil)
+  #   Per-tile sample standard deviation (divisor `n - 1`).
+  #   @param min_count [Integer, nil] fewest cells that must be present
+  #     for a result; a piece with fewer comes back masked.
+  #   @param fill_value [Object, nil] value to put in place of a masked
+  #     result instead of leaving it masked.
   #   @return [CArray] tile-grid shaped
-  # The rest are analogous: prod / mean / min / max, sample and population
-  # variance / stddev, all / any.
-  [:sum, :accumulate, :prod, :mean, :min, :max, :variance, :stddev, :all, :any,
+  # @!method all
+  #   Whether every cell of each tile is true.
+  #   Takes no `min_count:` or `fill_value:`, as the core `all` does not.
+  #   @return [CArray] tile-grid shaped
+  # @!method any
+  #   Whether any cell of each tile is true.
+  #   Takes no `min_count:` or `fill_value:`, as the core `any` does not.
+  #   @return [CArray] tile-grid shaped
+  # @!method variancep(min_count: nil, fill_value: nil)
+  #   Per-tile population variance (divisor `n`).
+  #   @param min_count [Integer, nil] fewest cells that must be present
+  #     for a result; a piece with fewer comes back masked.
+  #   @param fill_value [Object, nil] value to put in place of a masked
+  #     result instead of leaving it masked.
+  #   @return [CArray] tile-grid shaped
+  # @!method stddevp(min_count: nil, fill_value: nil)
+  #   Per-tile population standard deviation (divisor `n`).
+  #   @param min_count [Integer, nil] fewest cells that must be present
+  #     for a result; a piece with fewer comes back masked.
+  #   @param fill_value [Object, nil] value to put in place of a masked
+  #     result instead of leaving it masked.
+  #   @return [CArray] tile-grid shaped
+  [:sum, :accumulate, :prod, :mean, :min, :max, :variance, :stddev,
    :variancep, :stddevp].each do |op|
     define_method(op) do |min_count: nil, fill_value: nil|
+      if FACE_WINNER_INDEX.key?(op) && @source.face?
+        return face_winner(FACE_WINNER_INDEX[op], min_count, fill_value)
+      end
       kw = {}
       kw[:min_count]  = min_count  unless min_count.nil?
       kw[:fill_value] = fill_value unless fill_value.nil?
@@ -217,6 +315,17 @@ class CABlockIterator < CAIterator
     end
   end
 
+  [:all, :any].each do |op|
+    define_method(op) { |**kw| fold(op, **CAIterator.reduce_keywords(op, kw)) }
+  end
+
+  # A Face's minimum and maximum are cells of the Face, so they are gathered
+  # from the source by the winner's address.  Assembling the per-region results
+  # instead copies the Face's storage into an array that no longer knows it is
+  # one: a CATime came back as 8-byte strings.
+  FACE_WINNER_INDEX = { min: :min_index, max: :max_index }.freeze
+  private_constant :FACE_WINNER_INDEX
+
   # ---- count family and elements ----------------------------------------
 
   # @overload count(v = <none>)
@@ -224,15 +333,16 @@ class CABlockIterator < CAIterator
   #   partial edge tile); `count(UNDEF)` counts masked cells; `count(v)` counts
   #   cells equal to `v`.
   #   @return [CArray] tile-grid shaped
-  def count (*args)
-    return count_not_masked if args.empty?
+  def count (*args, **kw)
+    return count_not_masked(**kw) if args.empty?
+    kw = CAIterator.reduce_keywords(:count, kw)
     out = nil
     each_region do |strip_ranges, tiles, out_ranges|
       view = @source[*strip_ranges].block_view(*tiles)
       # block_view is a CAStride, so #count is not shadowed; dispatch
       # CArray#count explicitly anyway, matching the family regularity.
-      red = CArray.instance_method(:count).bind_call(view, *args, axis: @tile_axes)
-      out ||= CArray.new(red.data_type, @shape)
+      red = CArray.instance_method(:count).bind_call(view, *args, axis: @tile_axes, **kw)
+      out ||= CArray.new(red.data_type, @shape, bytes: red.bytes)
       out[*out_ranges] = red
     end
     out
@@ -242,16 +352,21 @@ class CABlockIterator < CAIterator
   #   Per-tile count of present (non-masked) cells.  For a partial edge tile
   #   this is the real cell count (the OOB cells are not present).
   #   @return [CArray]
-  def count_not_masked
-    fold(:count_not_masked)
+  def count_not_masked (**kw)
+    fold(:count_not_masked, **CAIterator.reduce_keywords(:count_not_masked, kw))
   end
 
   # @overload count_masked
   #   Per-tile count of masked cells.  Equals `elements - count_not_masked`;
   #   the OOB cells of a partial edge tile count here.
   #   @return [CArray]
-  def count_masked
-    elements - count_not_masked
+  def count_masked (**kw)
+    kw   = CAIterator.reduce_keywords(:count_masked, kw)
+    need = CArray.__min_count_need__(:count_masked, kw[:min_count], 0)
+    out  = elements - count_not_masked
+    # A count of the mask reads every cell of the tile.
+    out[elements.lt(need)] = UNDEF if need > 0
+    CArray.__reduce_fill__(out, kw[:fill_value])
   end
 
   # @overload elements
@@ -273,23 +388,28 @@ class CABlockIterator < CAIterator
   #   Per-tile `[min, max]` (two tile-grid-shaped CArrays, a single fused pass).
   #   @return [Array<CArray>]
   def minmax (min_count: nil, fill_value: nil)
+    if @source.face?
+      return [min(min_count: min_count, fill_value: fill_value),
+              max(min_count: min_count, fill_value: fill_value)]
+    end
     kw = {}
     kw[:min_count]  = min_count  unless min_count.nil?
     kw[:fill_value] = fill_value unless fill_value.nil?
     assemble { |view, _| view.minmax(axis: @tile_axes, **kw) }
   end
 
-  # @overload min_index
+  # @!method min_index
   #   Per-tile position of the minimum, as a flat index within the tile (a
   #   partial edge tile indexes within its own present cells).
   #   @return [CArray] tile-grid shaped
-  # @overload max_index
+  # @!method max_index
   #   Per-tile position of the maximum (tile-local flat index).
   #   @return [CArray]
   [:min_index, :max_index].each do |op|
     class_eval <<~RUBY, __FILE__, __LINE__ + 1
-      def #{op}
-        assemble { |view, _| view.#{op}(axis: @tile_axes) }
+      def #{op} (**kw)
+        kw = CAIterator.reduce_keywords(:#{op}, kw)
+        assemble { |view, _| view.#{op}(axis: @tile_axes, **kw) }
       end
     RUBY
   end
@@ -300,26 +420,49 @@ class CABlockIterator < CAIterator
   #   minima. Unlike `min_index` (the tile-local position) this indexes back
   #   into the original array. An all-masked tile is a masked cell.
   #   @return [CArray] tile-grid shaped int64
-  def min_addr; winner_addr(:min_index); end
+  def min_addr (**kw); winner_addr(:min_index, kw); end
 
   # @overload max_addr
   #   Per-tile flat source address of the maximum. See {#min_addr}.
   #   @return [CArray] tile-grid shaped int64
-  def max_addr; winner_addr(:max_index); end
+  def max_addr (**kw); winner_addr(:max_index, kw); end
 
   private
 
+  # Per-tile minimum or maximum of a Face source, gathered from the source by
+  # the winner's address so the result is the Face itself.  An all-masked tile,
+  # and with `min_count` a tile with too few present cells, is a masked cell.
+  def face_winner (idx_op, min_count, fill_value)
+    addr = winner_addr(idx_op)
+    need = CArray.__min_count_need__(idx_op == :min_index ? :min : :max, min_count, 0)
+    addr[count_not_masked.lt(need)] = UNDEF if need > 0
+    src   = @source.reshape(@source.elements)
+    empty = addr.is_masked
+    return src[addr].copy unless empty.any
+    # A masked index drops the cell rather than masking it, so an empty tile
+    # needs a placeholder address.  Pointing it at a masked cell of the source
+    # carries the mask through the gather, which a read-only Face (whose copy
+    # cannot be written) needs.  Otherwise mask the placeholder afterwards.
+    if fill_value.nil? && src.has_mask? && (hole = src.is_masked.where).elements > 0
+      return src[addr.strip_mask(hole[0])].copy
+    end
+    out = src[addr.strip_mask(0)].copy
+    out[empty] = fill_value.nil? ? UNDEF : fill_value
+    out
+  end
+
   # Per-tile source address of the winner. The tile-local flat index (min_index /
   # max_index) is looked up in a source-address companion tiled the same way, so
   # the tile geometry is reused rather than recomputed. An all-masked tile yields
   # a masked index; it is gathered at 0 and re-masked in the result.
-  def winner_addr (idx_op)
+  def winner_addr (idx_op, kw = {})
+    kw    = CAIterator.reduce_keywords(idx_op, kw)
     saddr = CArray.int64(*@source.shape).seq!
     out = nil
     each_region do |strip_ranges, tiles, out_ranges|
       vview = @source[*strip_ranges].block_view(*tiles)
       sview = saddr[*strip_ranges].block_view(*tiles)
-      mi    = vview.public_send(idx_op, axis: @tile_axes)  # tile-local flat index
+      mi    = vview.public_send(idx_op, axis: @tile_axes, **kw.slice(:min_count))  # tile-local flat index
       grid  = (0...@sndim).map { |i| vview.shape[i] }
       cells = tiles.inject(1) { |p, t| p * t }
       safe  = mi.copy
@@ -331,7 +474,7 @@ class CABlockIterator < CAIterator
       out ||= CArray.int64(*@shape)
       out[*out_ranges] = picked
     end
-    out
+    CArray.__reduce_fill__(out || CArray.int64(*@shape), kw[:fill_value])
   end
 
   public
@@ -365,15 +508,17 @@ class CABlockIterator < CAIterator
   #   Per-tile weighted sum; `weights` is shaped like one full tile (`Π b_i`).
   #   At a partial edge tile the weight kernel is sliced to the present cells.
   #   @return [CArray]
-  def wsum (weights)
-    weighted(weights) { |view, w| view.wsum(w, axis: @tile_axes) }
+  def wsum (weights, **kw)
+    kw = CAIterator.reduce_keywords(:wsum, kw)
+    weighted(weights) { |view, w| view.wsum(w, axis: @tile_axes, **kw) }
   end
 
   # @overload wmean(weights)
   #   Per-tile weighted mean; `weights` shaped like one full tile.
   #   @return [CArray]
-  def wmean (weights)
-    weighted(weights) { |view, w| view.wmean(w, axis: @tile_axes) }
+  def wmean (weights, **kw)
+    kw = CAIterator.reduce_keywords(:wmean, kw)
+    weighted(weights) { |view, w| view.wmean(w, axis: @tile_axes, **kw) }
   end
 
   private
@@ -403,21 +548,22 @@ class CABlockIterator < CAIterator
   # Core per-axis order statistics take a single integer axis, so a 1-D tile
   # delegates straight to the C path; a multi-axis tile is materialized per
   # region and its tile axes flattened into one before the single-axis core
-  # order-stat.  A masked source raises (the known per-axis masked limitation);
-  # strip the mask with `ca.value` first if needed.
+  # order-stat.  Masked cells are left out, as in `CArray#median(axis:)`.
 
   # @overload median
   #   Per-tile median.  @return [CArray]
-  def median
-    order_stat { |v, axis| v.median(axis: axis) }
+  def median (**kw)
+    kw = CAIterator.reduce_keywords(:median, kw)
+    order_stat { |v, axis| v.median(axis: axis, **kw) }
   end
 
   # @overload percentile(*pers)
   #   Per-tile percentile(s).  One argument returns one CArray, several an array
   #   of CArrays (as `CArray#percentile`).
   #   @return [CArray, Array<CArray>]
-  def percentile (*pers)
-    order_stat { |v, axis| v.percentile(*pers, axis: axis) }
+  def percentile (*pers, **kw)
+    kw = CAIterator.reduce_keywords(:percentile, kw)
+    order_stat { |v, axis| v.percentile(*pers, axis: axis, **kw) }
   end
 
   # @overload quantile
@@ -509,7 +655,7 @@ class CABlockIterator < CAIterator
   #   @return [CArray, Enumerator] source-shaped
   def map
     return to_enum(:map) unless block_given?
-    pout = CArray.new(padded_source.data_type, padded_source.shape)
+    pout = CArray.new(padded_source.data_type, padded_source.shape, bytes: padded_source.bytes)
     pgv  = pout.block_view(*@sizes)
     tgv  = tile_grid_view
     nils = Array.new(@sndim, nil)
@@ -530,19 +676,19 @@ class CABlockIterator < CAIterator
   # cumcount -> int64 running count of present cells; the output data type is seeded
   # from the first tile's scan.
 
-  # @overload cumsum
+  # @!method cumsum
   #   Per-tile inclusive running sum (float64), source-shaped.
   #   @return [CArray]
-  # @overload cumprod
+  # @!method cumprod
   #   Per-tile inclusive running product (float64), source-shaped.
   #   @return [CArray]
-  # @overload cummax
+  # @!method cummax
   #   Per-tile inclusive running maximum (value data type), source-shaped.
   #   @return [CArray]
-  # @overload cummin
+  # @!method cummin
   #   Per-tile inclusive running minimum (value data type), source-shaped.
   #   @return [CArray]
-  # @overload cumcount
+  # @!method cumcount
   #   Per-tile running count of present cells (int64), source-shaped.
   #   @return [CArray]
   [:cumsum, :cumprod, :cummax, :cummin, :cumcount].each do |op|
@@ -564,7 +710,7 @@ class CABlockIterator < CAIterator
       tile    = tgv[*g, *nils]
       scanned = tile.copy.reshape(tile.elements).public_send(op).reshape(*@sizes)
       unless pout
-        pout = CArray.new(scanned.data_type, padded_source.shape)
+        pout = CArray.new(scanned.data_type, padded_source.shape, bytes: scanned.bytes)
         pout[] = UNDEF
         pgv  = pout.block_view(*@sizes)
       end
@@ -583,7 +729,7 @@ class CABlockIterator < CAIterator
       if pshape == @source.shape.to_a
         @source
       else
-        pad = CArray.new(@source.data_type, pshape)
+        pad = CArray.new(@source.data_type, pshape, bytes: @source.bytes)
         pad[] = UNDEF
         pad[*@sndim.times.map { |i| 0...@source.shape[i] }] = @source
         pad