red_amber 0.3.0 → 0.4.0

data/lib/red_amber/group.rb

@@ -1,16 +1,72 @@
 # frozen_string_literal: true
 
 module RedAmber
-  # group class
+  # Group class
   class Group
     include Enumerable # This feature is experimental
 
     using RefineArrowTable
 
+    # Source DataFrame.
+    #
+    # @return [DataFrame]
+    #   source DataFrame.
+    #
+    attr_reader :dataframe
+
+    # Keys for grouping by value.
+    #
+    # @return [Array]
+    #   group keys.
+    #
+    attr_reader :group_keys
+
+    class << self
+      private
+
+      # @!macro [attach] define_group_aggregation
+      #   @!method $1(*summary_keys)
+      #     Group aggregation function `$1`.
+      #     @param summary_keys [Array<Symbol, String>]
+      #       summary keys.
+      #     @return [DataFrame]
+      #       aggregated DataFrame
+      #
+      def define_group_aggregation(function)
+        define_method(function) do |*summary_keys|
+          summary_keys = Array(summary_keys).flatten
+          d = summary_keys - @dataframe.keys
+          unless summary_keys.empty? || d.empty?
+            raise GroupArgumentError, "#{d} is not a key of\n #{@dataframe}."
+          end
+
+          table = @group.aggregate(*build_aggregation_keys("hash_#{function}",
+                                                           summary_keys))
+          g = @group_keys.map(&:to_s)
+          DataFrame.new(table[g + (table.keys - g)])
+        end
+      end
+    end
+
     # Creates a new Group object.
     #
-    # @param dataframe [DataFrame] dataframe to be grouped.
-    # @param group_keys [Array<>] keys for grouping.
+    # @param dataframe [DataFrame]
+    #   dataframe to be grouped.
+    # @param group_keys [Array<Symbol, String>]
+    #   keys for grouping.
+    # @return [Group]
+    #   Group object.
+    # @example
+    #   Group.new(penguins, :species)
+    #
+    #   # =>
+    #   #<RedAmber::Group : 0x000000000000f410>
+    #     species   group_count
+    #     <string>      <uint8>
+    #   0 Adelie            152
+    #   1 Chinstrap          68
+    #   2 Gentoo            124
+    #
     def initialize(dataframe, *group_keys)
       @dataframe = dataframe
       @group_keys = group_keys.flatten
@@ -23,24 +79,7 @@ module RedAmber
       @group = @dataframe.table.group(*@group_keys)
     end
 
-    attr_reader :dataframe, :group_keys
-
-    functions = %i[count sum product mean min max stddev variance]
-    functions.each do |function|
-      define_method(function) do |*summary_keys|
-        summary_keys = Array(summary_keys).flatten
-        d = summary_keys - @dataframe.keys
-        unless summary_keys.empty? || d.empty?
-          raise GroupArgumentError, "#{d} is not a key of\n #{@dataframe}."
-        end
-
-        table = @group.aggregate(*build_aggregation_keys("hash_#{function}",
-                                                         summary_keys))
-        g = @group_keys.map(&:to_s)
-        DataFrame.new(table[g + (table.keys - g)])
-      end
-    end
-
+    define_group_aggregation(:count)
     alias_method :__count, :count
     private :__count
 
@@ -54,6 +93,26 @@ module RedAmber
       end
     end
 
+    define_group_aggregation(:sum)
+
+    define_group_aggregation(:product)
+
+    define_group_aggregation(:mean)
+
+    define_group_aggregation(:min)
+
+    define_group_aggregation(:max)
+
+    define_group_aggregation(:stddev)
+
+    define_group_aggregation(:variance)
+
+    # Returns Array of boolean filters to select each records in the Group.
+    #
+    # @api private
+    # @return [Array]
+    #   an Array of boolean filter Vectors.
+    #
     def filters
       @filters ||= begin
         first, *others = @group_keys.map do |key|
@@ -69,6 +128,25 @@ module RedAmber
       end
     end
 
+    # Iterates over each record group as a DataFrame or returns a Enumerator.
+    #
+    # @api private
+    # @overload each
+    #   Returns a new Enumerator if no block given.
+    #
+    #   @return [Enumerator]
+    #     Enumerator of each group as a DataFrame.
+    #
+    # @overload each
+    #   When a block given, passes each record group as a DataFrame to the block.
+    #
+    #   @yieldparam df [DataFrame]
+    #     passes each record group as a DataFrame by a block parameter.
+    #   @yieldreturn [Object]
+    #     evaluated result value from the block.
+    #   @return [Integer]
+    #     group size.
+    #
     def each
       filters
       return enum_for(:each) unless block_given?
@@ -79,14 +157,98 @@ module RedAmber
       @filters.size
     end
 
+    # Returns each record group size as a DataFrame.
+    #
+    # @return [DataFrame]
+    #   DataFrame consists of:
+    #   - Group key columns.
+    #   - Result columns by group aggregation.
+    # @example
+    #   penguins.group(:species).group_count
+    #
+    #   # =>
+    #   #<RedAmber::DataFrame : 3 x 2 Vectors, 0x0000000000003a70>
+    #     species   group_count
+    #     <string>      <uint8>
+    #   0 Adelie            152
+    #   1 Chinstrap          68
+    #   2 Gentoo            124
+    #
     def group_count
       DataFrame.create(add_columns_to_table(base_table, [:group_count], [group_counts]))
     end
 
+    # String representation of self.
+    #
+    # @return [String]
+    #   show information of self as a String.
+    # @example
+    #   puts penguins.group(:species).inspect
+    #
+    #   # =>
+    #   #<RedAmber::Group : 0x0000000000003a98>
+    #     species   group_count
+    #     <string>      <uint8>
+    #   0 Adelie            152
+    #   1 Chinstrap          68
+    #   2 Gentoo            124
+    #
     def inspect
       "#<#{self.class} : #{format('0x%016x', object_id)}>\n#{group_count}"
     end
 
+    # Summarize Group by aggregation functions from the block.
+    #
+    # @yieldparam group [Group]
+    #   passes group object self.
+    # @yieldreturn [DataFrame, Array<DataFrame>]
+    #   an aggregated DataFrame or an array of aggregated DataFrames.
+    # @return [DataFrame]
+    #   summarized DataFrame.
+    # @example Single function and single variable
+    #   group = penguins.group(:species)
+    #   group
+    #
+    #   # =>
+    #   #<RedAmber::Group : 0x000000000000c314>
+    #     species   group_count
+    #     <string>      <uint8>
+    #   0 Adelie            152
+    #   1 Chinstrap          68
+    #   2 Gentoo            124
+    #
+    #   group.summarize { mean(:bill_length_mm) }
+    #
+    #   # =>
+    #   #<RedAmber::DataFrame : 3 x 2 Vectors, 0x000000000000c364>
+    #     species   mean(bill_length_mm)
+    #     <string>              <double>
+    #   0 Adelie                   38.79
+    #   1 Chinstrap                48.83
+    #   2 Gentoo                    47.5
+    #
+    # @example Single function only
+    #   group.summarize { mean }
+    #
+    #   # =>
+    #   #<RedAmber::DataFrame : 3 x 6 Vectors, 0x000000000000c350>
+    #     species   mean(bill_length_mm) mean(bill_depth_mm) ... mean(year)
+    #     <string>              <double>            <double> ...   <double>
+    #   0 Adelie                   38.79               18.35 ...    2008.01
+    #   1 Chinstrap                48.83               18.42 ...    2007.97
+    #   2 Gentoo                    47.5               14.98 ...    2008.08
+    #
+    # @example Multiple functions
+    #   group.summarize { [min(:bill_length_mm), max(:bill_length_mm)] }
+    #
+    #   # =>
+    #   #<RedAmber::DataFrame : 3 x 3 Vectors, 0x000000000000c378>
+    #     species   min(bill_length_mm) max(bill_length_mm)
+    #     <string>             <double>            <double>
+    #   0 Adelie                   32.1                46.0
+    #   1 Chinstrap                40.9                58.0
+    #   2 Gentoo                   40.9                59.6
+    #
     def summarize(&block)
       agg = instance_eval(&block)
       case agg
@@ -99,7 +261,10 @@ module RedAmber
       end
     end
 
-    # experimental
+    # Aggregating summary.
+    #
+    # @api private
+    #
     def agg_sum(*summary_keys)
       call_aggregating_function(:sum, summary_keys, _options = nil)
     end

data/lib/red_amber/helper.rb

@@ -1,28 +1,33 @@
 # frozen_string_literal: true
 
 module RedAmber
-  # mix-in for the class DataFrame
+  # Mix-in for the class DataFrame
   module Helper
     private
 
     # If num is larger than 1 return 's' to be plural.
     #
-    # @param num [Numeric] some number.
-    # @return ['s', ''] return 's' if num is larger than 1.
+    # @param num [Numeric]
+    #   some number.
+    # @return ['s', '']
+    #   return 's' if num is larger than 1.
     #   Otherwise return ''.
+    #
     def pl(num)
       num > 1 ? 's' : ''
     end
 
-    # Parse the argments in an Array
-    #   and returns a parsed Array.
+    # Parse the argments in an Array and returns a parsed Array.
     #
     # @param args
     #   [<Integer, Symbol, true, false, nil, Array, Range, Enumerator, String, Float>]
     #   arguments.
-    # @param array_size [Integer] size of target Array to use in a endless Range.
-    # @return [<Integer, Symbol, true, false, nil>] parsed flat Array.
+    # @param array_size [Integer]
+    #   size of target Array to use in a endless Range.
+    # @return [<Integer, Symbol, true, false, nil>]
+    #   parsed flat Array.
     # @note This method is recursively called to parse.
+    #
     def parse_args(args, array_size)
       args.flat_map do |elem|
         case elem
@@ -46,9 +51,13 @@ module RedAmber
 
     # Parse a Range to an Array
     #
-    # @param range [Range] Range to parse.
-    # @param array_size [Integer] size of target Array to use in a endless Range.
-    # @return [Array<Integer, Symbol, String>] parsed Array.
+    # @param range [Range]
+    #   range to parse.
+    # @param array_size [Integer]
+    #   size of target Array to use in a endless Range.
+    # @return [Array<Integer, Symbol, String>]
+    #   parsed Array.
+    #
     def parse_range(range, array_size)
       bg = range.begin
       en = range.end
@@ -70,4 +79,55 @@ module RedAmber
       end
     end
   end
+
+  # rubocop:disable Layout/LineLength
+
+  # Helper for Arrow Functions
+  module ArrowFunction
+    module_function
+
+    # Find Arrow's compute function.
+    #
+    # {https://arrow.apache.org/docs/cpp/compute.html}
+    # @param function_name [Symbol]
+    #   function name.
+    # @return [Arrow::Function]
+    #   arrow compute function object.
+    # @example
+    #   RedAmber::ArrowFunction.find(:array_sort_indices)
+    #
+    #   # =>
+    #   #<Arrow::Function:0x7fa8838a0d80 ptr=0x7fa87e9b7320 array_sort_indices(array, {order=Ascending, null_placement=AtEnd}): Return the indices that would sort an array>
+    #
+    def find(function_name)
+      Arrow::Function.find(function_name)
+    end
+
+    # Show document of Arrow's compute function.
+    #
+    # @param function_name [Symbol]
+    #   function name.
+    # @return [String]
+    #   document of compute function object.
+    # @example
+    #   puts RedAmber::ArrowFunction.arrow_doc(:array_sort_indices)
+    #
+    #   # =>
+    #   array_sort_indices(array, {order=Ascending, null_placement=AtEnd}): Return the indices that would sort an array
+    #   ------------------
+    #   This function computes an array of indices that define a stable sort
+    #   of the input array.  By default, Null values are considered greater
+    #   than any other value and are therefore sorted at the end of the array.
+    #   For floating-point types, NaNs are considered greater than any
+    #   other non-null value, but smaller than null values.
+    #
+    #   The handling of nulls and NaNs can be changed in ArraySortOptions.
+    #
+    def arrow_doc(function_name)
+      f = find(function_name)
+      "#{f}\n#{'-' * function_name.size}\n#{f.doc.description}"
+    end
+  end
+
+  # rubocop:enable Layout/LineLength
 end

data/lib/red_amber/refinements.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+# Namespace of RedAmber
 module RedAmber
   # Add additional capabilities to Hash
   module RefineHash
@@ -154,23 +155,27 @@ module RedAmber
   # Add additional capabilities to Array
   module RefineArray
     refine Array do
-      def integers?
+      def integer?
         all? { |e| e.is_a?(Integer) } # rubocop:disable Performance/RedundantEqualityComparisonBlock
       end
 
-      def booleans?
+      def numeric?
+        all? { |e| e.is_a?(Numeric) } # rubocop:disable Performance/RedundantEqualityComparisonBlock
+      end
+
+      def boolean?
         all? { |e| e.is_a?(TrueClass) || e.is_a?(FalseClass) || e.is_a?(NilClass) }
       end
 
-      def symbols?
+      def symbol?
         all? { |e| e.is_a?(Symbol) } # rubocop:disable Performance/RedundantEqualityComparisonBlock
       end
 
-      def strings?
+      def string?
         all? { |e| e.is_a?(String) } # rubocop:disable Performance/RedundantEqualityComparisonBlock
       end
 
-      def symbols_or_strings?
+      def symbol_or_string?
         all? { |e| e.is_a?(Symbol) || e.is_a?(String) }
       end
 
@@ -196,4 +201,6 @@ module RedAmber
       end
     end
   end
+
+  private_constant :RefineArray, :RefineArrayLike, :RefineArrowTable, :RefineHash
 end