red_amber 0.3.0 → 0.4.1

data/lib/red_amber/data_frame_loadsave.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module RedAmber
-  # mix-ins for the class DataFrame
+  # Mix-in for the class DataFrame
   module DataFrameLoadSave
     # Enable `self.load` as class method of DataFrame
     def self.included(klass)
@@ -10,30 +10,98 @@ module RedAmber
 
     # Enable `self.load` as class method of DataFrame
     module ClassMethods
-      # Load DataFrame via Arrow::Table.load
-      def load(path, options = {})
-        DataFrame.new(Arrow::Table.load(path, options))
+      # Load DataFrame via Arrow::Table.load.
+      #
+      # Format is automatically detected by extension.
+      # @!method load(input, format: nil, compression: nil, schema: nil, skip_lines: nil)
+      # @param input [path]
+      #   source path.
+      # @param format [:arrow_file, :batch, :arrows, :arrow_stream, :stream, :csv, :tsv]
+      #   format specifier.
+      # @param compression [:gzip, nil]
+      #   compression type.
+      # @param schema [Arrow::Schema]
+      #   schema of table.
+      # @param skip_lines [Regexp]
+      #   pattern of rows to skip.
+      # @return [DataFrame]
+      #   loaded DataFrame.
+      # @example Load a tsv file
+      #   DataFrame.load("file.tsv")
+      #
+      # @example Load a csv.gz file
+      #   DataFrame.load("file.csv.gz")
+      #
+      # @example Load from URI
+      #   DataFrame.load(URI("https://some_uri/file.csv"))
+      #
+      # @example Load from a Buffer
+      #   DataFrame.load(Arrow::Buffer.new(<<~BUFFER), format: :csv)
+      #     name,age
+      #     Yasuko,68
+      #     Rui,49
+      #     Hinata,28
+      #   BUFFER
+      #
+      # @example Load from a Buffer skipping comment line
+      #   DataFrame.load(Arrow::Buffer.new(<<~BUFFER), format: :csv, skip_lines: /^#/)
+      #     # comment
+      #     name,age
+      #     Yasuko,68
+      #     Rui,49
+      #     Hinata,28
+      #   BUFFER
+      #
+      def load(input, **options)
+        DataFrame.new(Arrow::Table.load(input, options))
       end
     end
 
     # Save DataFrame
     #
-    # @return [DataFrame] self.
-    def save(output, options = {})
+    # Format is automatically detected by extension.
+    # @!method save(output, format: nil, compression: nil, schema: nil, skip_lines: nil)
+    # @param output [path]
+    #   output path.
+    # @param format [:arrow_file, :batch, :arrows, :arrow_stream, :stream, :csv, :tsv]
+    #   format specifier.
+    # @param compression [:gzip, nil]
+    #   compression type.
+    # @param schema [Arrow::Schema]
+    #   schema of table.
+    # @param skip_lines [Regexp]
+    #   pattern of rows to skip.
+    # @return [DataFrame]
+    #   self.
+    # @example Save a csv file
+    #   DataFrame.save("file.csv")
+    #
+    # @example Save a csv.gz file
+    #   DataFrame.save("file.csv.gz")
+    #
+    # @example Save an arrow file
+    #   DataFrame.save("file.arrow")
+    #
+    def save(output, **options)
       @table.save(output, options)
       self
     end
 
     # Save and reload to cast automatically
-    #   Via tsv format file temporally as default
+    # via tsv format file temporally as default.
+    #
+    # @param format [Symbol]
+    #   format specifier.
+    # @return [DataFrame]
+    #   reloaded DataFrame.
     #
     # @note experimental feature
     def auto_cast(format: :tsv)
       return self if empty?
 
-      tempfile = Arrow::ResizableBuffer.new(1024)
-      save(tempfile, format: format)
-      DataFrame.load(tempfile, format: format)
+      buffer = Arrow::ResizableBuffer.new(1024)
+      save(buffer, format: format)
+      DataFrame.load(buffer, format: format)
     end
   end
 end

data/lib/red_amber/data_frame_reshaping.rb

@@ -1,17 +1,94 @@
 # frozen_string_literal: true
 
 module RedAmber
-  # mix-ins for the class DataFrame
+  # Mix-in for the class DataFrame
   module DataFrameReshaping
-    # Transpose a wide DataFrame.
+    # Create a transposed DataFrame for the wide (may be messy) DataFrame.
     #
-    # @param key [Symbol] key of the index column
+    # @param key [Symbol]
+    #   key of the index column
     #   to transepose into keys.
     #   If it is not specified, keys[0] is used.
-    # @param name [Symbol] key name of transposed index column.
+    # @param name [Symbol]
+    #   key name of transposed index column.
     #   If it is not specified, :NAME is used.
     #   If it already exists, :NAME1 or :NAME1.succ is used.
-    # @return [DataFrame] trnsposed DataFrame
+    # @return [DataFrame]
+    #   trnsposed DataFrame
+    #
+    # @example Transpose a DataFrame without options
+    #
+    #   import_cars
+    #
+    #   # =>
+    #   #<RedAmber::DataFrame : 5 x 6 Vectors, 0x000000000000d520>
+    #        Year    Audi     BMW BMW_MINI Mercedes-Benz      VW
+    #     <int64> <int64> <int64>  <int64>       <int64> <int64>
+    #   0    2017   28336   52527    25427         68221   49040
+    #   1    2018   26473   50982    25984         67554   51961
+    #   2    2019   24222   46814    23813         66553   46794
+    #   3    2020   22304   35712    20196         57041   36576
+    #   4    2021   22535   35905    18211         51722   35215
+    #
+    #   import_cars.transpose
+    #
+    #   # =>
+    #   #<RedAmber::DataFrame : 5 x 6 Vectors, 0x0000000000010a2c>
+    #     NAME              2017     2018     2019     2020     2021
+    #     <string>      <uint32> <uint32> <uint32> <uint16> <uint16>
+    #   0 Audi             28336    26473    24222    22304    22535
+    #   1 BMW              52527    50982    46814    35712    35905
+    #   2 BMW_MINI         25427    25984    23813    20196    18211
+    #   3 Mercedes-Benz    68221    67554    66553    57041    51722
+    #   4 VW               49040    51961    46794    36576    35215
+    #
+    #   The leftmost column is created by original keys and
+    #   `:NAME` is automatically used for the column name.
+    #
+    # @example Transpose a DataFrame with `:name` option
+    #
+    #   import_cars.transpose(name: :Manufacturer)
+    #
+    #   # =>
+    #   #<RedAmber::DataFrame : 5 x 6 Vectors, 0x0000000000010a2c>
+    #     Manufacturer      2017     2018     2019     2020     2021
+    #     <string>      <uint32> <uint32> <uint32> <uint16> <uint16>
+    #   0 Audi             28336    26473    24222    22304    22535
+    #   1 BMW              52527    50982    46814    35712    35905
+    #   2 BMW_MINI         25427    25984    23813    20196    18211
+    #   3 Mercedes-Benz    68221    67554    66553    57041    51722
+    #   4 VW               49040    51961    46794    36576    35215
+    #
+    #   `:name` option can specify column name.
+    #
+    # @example Transpose a DataFrame by the :key in the middle of the DataFrame
+    #
+    #   import_cars_middle = import_cars.pick(1..2, 0, 3..)
+    #
+    #   # =>
+    #   #<RedAmber::DataFrame : 5 x 6 Vectors, 0x000000000000f244>
+    #        Audi     BMW    Year BMW_MINI Mercedes-Benz      VW
+    #     <int64> <int64> <int64>  <int64>       <int64> <int64>
+    #   0   28336   52527    2017    25427         68221   49040
+    #   1   26473   50982    2018    25984         67554   51961
+    #   2   24222   46814    2019    23813         66553   46794
+    #   3   22304   35712    2020    20196         57041   36576
+    #   4   22535   35905    2021    18211         51722   35215
+    #
+    #   import_cars_middle.transpose(key: :Year)
+    #
+    #   # =>
+    #   #<RedAmber::DataFrame : 5 x 6 Vectors, 0x0000000000010a2c>
+    #     NAME              2017     2018     2019     2020     2021
+    #     <string>      <uint32> <uint32> <uint32> <uint16> <uint16>
+    #   0 Audi             28336    26473    24222    22304    22535
+    #   1 BMW              52527    50982    46814    35712    35905
+    #   2 BMW_MINI         25427    25984    23813    20196    18211
+    #   3 Mercedes-Benz    68221    67554    66553    57041    51722
+    #   4 VW               49040    51961    46794    36576    35215
+    #
+    # @since 0.2.0
+    #
     def transpose(key: keys.first, name: :NAME)
       unless keys.include?(key)
         raise DataFrameArgumentError, "Self does not include: #{key}"
@@ -31,12 +108,67 @@ module RedAmber
       DataFrame.new(hash)
     end
 
-    # Reshape wide DataFrame to a longer DataFrame.
+    # Create a 'long' (may be tidy) DataFrame from a 'wide' DataFrame.
+    #
+    # @param keep_keys [<Symbol>]
+    #   keys to keep.
+    # @param name [Symbol, String]
+    #   a new key name of the column which is come from key names.
+    # @param value [Symbol, String]
+    #   a new key name of the column which is come from values.
+    # @return [DataFrame]
+    #   long DataFrame.
+    #
+    # @example `to_long` without options
+    #
+    #   import_cars
+    #
+    #   # =>
+    #   #<RedAmber::DataFrame : 5 x 6 Vectors, 0x000000000000d520>
+    #        Year    Audi     BMW BMW_MINI Mercedes-Benz      VW
+    #     <int64> <int64> <int64>  <int64>       <int64> <int64>
+    #   0    2017   28336   52527    25427         68221   49040
+    #   1    2018   26473   50982    25984         67554   51961
+    #   2    2019   24222   46814    23813         66553   46794
+    #   3    2020   22304   35712    20196         57041   36576
+    #   4    2021   22535   35905    18211         51722   35215
+    #
+    #   import_cars.to_long(:Year)
+    #
+    #   # =>
+    #   #<RedAmber::DataFrame : 25 x 3 Vectors, 0x0000000000011864>
+    #          Year NAME             VALUE
+    #      <uint16> <string>      <uint32>
+    #    0     2017 Audi             28336
+    #    1     2017 BMW              52527
+    #    2     2017 BMW_MINI         25427
+    #    3     2017 Mercedes-Benz    68221
+    #    4     2017 VW               49040
+    #    :        : :                    :
+    #   22     2021 BMW_MINI         18211
+    #   23     2021 Mercedes-Benz    51722
+    #   24     2021 VW               35215
+    #
+    # @example `to_long` with options `:name` and `:value`
+    #
+    #   import_cars.to_long(:Year, name: :Manufacturer, value: :Num_of_imported)
+    #
+    #   # =>
+    #   #<RedAmber::DataFrame : 25 x 3 Vectors, 0x000000000001359c>
+    #          Year Manufacturer  Num_of_imported
+    #      <uint16> <string>             <uint32>
+    #    0     2017 Audi                    28336
+    #    1     2017 BMW                     52527
+    #    2     2017 BMW_MINI                25427
+    #    3     2017 Mercedes-Benz           68221
+    #    4     2017 VW                      49040
+    #    :        : :                           :
+    #   22     2021 BMW_MINI                18211
+    #   23     2021 Mercedes-Benz           51722
+    #   24     2021 VW                      35215
+    #
+    # @since 0.2.0
     #
-    # @param keep_keys [Array] keys to keep.
-    # @param name [Symbol, String] key of the column which is come **from values**.
-    # @param value [Symbol, String] key of the column which is come **from values**.
-    # @return [DataFrame] long DataFrame.
     def to_long(*keep_keys, name: :NAME, value: :VALUE)
       warn('[Info] No key to keep is specified.') if keep_keys.empty?
 
@@ -73,13 +205,51 @@ module RedAmber
       DataFrame.new(hash)
     end
 
-    # Reshape long DataFrame to a wide DataFrame.
+    # Create a 'wide' (may be messy) DataFrame from a 'long' DataFrame.
     #
     # @param name [Symbol, String]
-    #   key of the column which will be expanded **to key names**.
+    #   a new key name of the columnwhich will be expanded to key names.
     # @param value [Symbol, String]
-    #   key of the column which will be expanded **to values**.
-    # @return [DataFrame] wide DataFrame.
+    #   a new key name of the column which will be expanded to values.
+    # @return [DataFrame]
+    #   wide DataFrame.
+    #
+    # @example `to_wide` without options
+    #
+    #   import_cars_long = import_cars.to_long(:Year)
+    #
+    #   # =>
+    #   #<RedAmber::DataFrame : 25 x 3 Vectors, 0x0000000000011864>
+    #          Year NAME             VALUE
+    #      <uint16> <string>      <uint32>
+    #    0     2017 Audi             28336
+    #    1     2017 BMW              52527
+    #    2     2017 BMW_MINI         25427
+    #    3     2017 Mercedes-Benz    68221
+    #    4     2017 VW               49040
+    #    :        : :                    :
+    #   22     2021 BMW_MINI         18211
+    #   23     2021 Mercedes-Benz    51722
+    #   24     2021 VW               35215
+    #
+    #   import_cars_long.to_wide
+    #   # or same as `import_cars_long.to_wide(name: :NAME, value: VALUE)`
+    #
+    #   # =>
+    #   #<RedAmber::DataFrame : 5 x 6 Vectors, 0x000000000000d520>
+    #        Year    Audi     BMW BMW_MINI Mercedes-Benz      VW
+    #     <int64> <int64> <int64>  <int64>       <int64> <int64>
+    #   0    2017   28336   52527    25427         68221   49040
+    #   1    2018   26473   50982    25984         67554   51961
+    #   2    2019   24222   46814    23813         66553   46794
+    #   3    2020   22304   35712    20196         57041   36576
+    #   4    2021   22535   35905    18211         51722   35215
+    #
+    #   Columns other than `NAME` and `VALUE` (it is `Year` for this case) will be
+    #   automatically processed and do not need to specify.
+    #
+    # @since 0.2.0
+    #
     def to_wide(name: :NAME, value: :VALUE)
       name = name.to_sym
       unless keys.include?(name)