daru-io 0.1.0

data/Rakefile

@@ -0,0 +1,12 @@
+require 'bundler/setup'
+
+require 'rubygems/tasks'
+Gem::Tasks.new
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new
+
+require 'rubocop/rake_task'
+RuboCop::RakeTask.new
+
+task default: %w[spec rubocop]

data/daru-io.gemspec

@@ -0,0 +1,39 @@
+# coding: utf-8
+
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'daru/io/version'
+
+Daru::IO::DESCRIPTION = <<MSG.freeze
+  Daru-IO is a plugin-gem to Daru gem, which stands for Data Analysis in RUby. Daru-IO extends support for many Import and Export methods of Daru::DataFrame. This gem is intended to help Rubyists who are into Data Analysis or Web Development, by serving as a general purpose conversion library,  while also making it incredibly easy to getting started on analyzing data with daru.
+MSG
+
+Gem::Specification.new do |spec|
+  spec.name          = 'daru-io'
+  spec.version       = Daru::IO::VERSION
+  spec.authors       = ['Athitya Kumar']
+  spec.email         = ['athityakumar@gmail.com']
+  spec.summary       = 'Daru-IO is a plugin-gem to Daru gem, which stands for Data Analysis in RUby.'
+  spec.description   = Daru::IO::DESCRIPTION
+  spec.homepage      = 'https://github.com/athityakumar/daru-io'
+  spec.license       = 'MIT'
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = 'bin'
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_runtime_dependency 'daru', '~> 0.1.5'
+
+  spec.add_development_dependency 'bundler', '~> 1.15'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'redcarpet'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'rspec-its'
+  spec.add_development_dependency 'rubocop', '>= 0.40.0'
+  spec.add_development_dependency 'rubocop-rspec'
+  spec.add_development_dependency 'rubygems-tasks'
+  spec.add_development_dependency 'simplecov'
+  spec.add_development_dependency 'webmock'
+  spec.add_development_dependency 'yard'
+  spec.add_development_dependency 'guard-rspec' if RUBY_VERSION >= '2.2.5'
+end

data/lib/daru/io.rb

@@ -0,0 +1,3 @@
+require 'daru/io/version'
+require 'daru/io/importers'
+require 'daru/io/exporters'

data/lib/daru/io/base.rb

@@ -0,0 +1,45 @@
+require 'daru'
+require 'daru/io/link'
+
+module Daru
+  module IO
+    # Base IO Class that contains generic helper methods, to be
+    # used by other {Importers::Base} and {Exporters::Base} via inheritence
+    class Base
+      # Specifies and requires a gem, if the gem is present in the application
+      # environment. Else, raises `LoadError` with meaningful message of which
+      # dependency to install for which Daru-IO module.
+      #
+      # @param dependency [String] A dependency to specify with `gem` command
+      # @param version [String] A version range to specify with `gem` command
+      # @param requires [String] The gem name to be required, in case it's
+      #   different from the dependency name. For example, activerecord
+      #   dependency has to be required as `require 'active_record'`
+      # @param callback [Class] The Daru-IO module which is being used currently.
+      #   Useful for throwing meaningful `LoadError` message.
+      #
+      # @example Requires with dependency
+      #   optional_gem 'avro'
+      #   #=> true
+      #
+      # @example Requires with version and requires
+      #   optional_gem 'activerecord', '~> 4.0', requires: 'active_record'
+      #   #=> true
+      #
+      # @example Raises error with meaningful message
+      #   df = Daru::DataFrame.from_json('path/to/file.json')
+      #   #=> LoadError: Please install the jsonpath gem, or add it to the
+      #   #   Gemfile to use the Daru::IO::Importers::JSON module.
+      def optional_gem(dependency, version=nil, requires: nil,
+        callback: self.class.name)
+        gem dependency, version
+        require requires || dependency
+      rescue LoadError
+        version = version.nil? ? '' : " #{version} version"
+        raise LoadError,
+          "Please install the #{dependency} gem#{version}, "\
+          "or add it to the Gemfile to use the #{callback} module."
+      end
+    end
+  end
+end

data/lib/daru/io/exporters.rb

@@ -0,0 +1 @@
+Dir["#{__dir__}/exporters/*.rb"].each { |file| require "daru/io#{file.gsub(__dir__, '')}" }

data/lib/daru/io/exporters/avro.rb

@@ -0,0 +1,96 @@
+require 'daru/io/exporters/base'
+
+module Daru
+  module IO
+    module Exporters
+      # Avro Exporter Class, that extends `to_avro_string` and `write_avro` methods to
+      # `Daru::DataFrame` instance variables
+      class Avro < Base
+        Daru::DataFrame.register_io_module :to_avro_string, self
+        Daru::DataFrame.register_io_module :write_avro, self
+
+        # Initializes an Avro Exporter instance.
+        #
+        # @param dataframe [Daru::DataFrame] A dataframe to export
+        # @param schema [Avro::Schema or Hash] The schema should contain details such as `:type`,
+        #   `:name` and `:fields`
+        #
+        # @return A `Daru::IO::Exporter::Avro` instance
+        #
+        # @example Initializing an Avro Exporter
+        #   schema = {
+        #     "type" => "record",
+        #     "name" => "User",
+        #     "fields" => [
+        #       {"name" => "name", "type" => "string"},
+        #       {"name" => "points", "type" => "int"},
+        #       {"name"=> "winner", "type"=> "boolean", "default"=> "false"}
+        #     ]
+        #   }
+        #
+        #   df = Daru::DataFrame.new(
+        #     [
+        #       {"name"=> "Dany", "points"=> 100, "winner"=> true},
+        #       {"name"=> "Jon", "points"=> 100, "winner"=> true},
+        #       {"name"=> "Tyrion", "points"=> 100, "winner"=> true}
+        #     ]
+        #   )
+        #
+        #   #=> #<Daru::DataFrame(3x3)>
+        #   #        name points winner
+        #   #    0   Dany    100   true
+        #   #    1    Jon    100   true
+        #   #    2 Tyrion    100   true
+        #
+        #   instance = Daru::IO::Exporters::Avro.new(df, schema)
+        def initialize(dataframe, schema=nil)
+          optional_gem 'avro'
+          require 'json'
+
+          super(dataframe)
+          @schema = schema
+        end
+
+        # Exports an Avro Exporter instance to a file-writable String.
+        #
+        # @return [String] A file-writable string
+        #
+        # @example Getting a file-writable string from Avro Exporter instance
+        #   instance.to_s
+        #
+        #   #=> "Obj\u0001\u0004\u0014avro.codec\bnull\u0016avro.schema\xBC\u0002{\"type\":\"record\"..."
+        def to_s
+          super
+        end
+
+        # Exports an Avro Exporter instance to an avro file.
+        #
+        # @param path [String] Path of Avro file where the dataframe is to be saved
+        #
+        # @example Writing an Avro Exporter instance to an Avro file
+        #   instance.write('azor_ahai.avro')
+        def write(path)
+          @schema_obj = process_schema
+          @writer     = ::Avro::IO::DatumWriter.new(@schema_obj)
+          @buffer     = StringIO.new
+          @writer     = ::Avro::DataFile::Writer.new(@buffer, @writer, @schema_obj)
+          @dataframe.each_row { |row| @writer << row.to_h }
+          @writer.close
+
+          File.open(path, 'w') { |file| file.write(@buffer.string) }
+        end
+
+        private
+
+        def process_schema
+          case @schema
+          when ::Avro::Schema then @schema
+          when String         then ::Avro::Schema.parse(@schema)
+          when Hash           then ::Avro::Schema.parse(@schema.to_json)
+          else raise ArgumentError, 'Invalid Avro Schema provided.'
+          end
+        end
+      end
+    end
+  end
+end

data/lib/daru/io/exporters/base.rb

@@ -0,0 +1,54 @@
+require 'daru/io/base'
+
+module Daru
+  module IO
+    module Exporters
+      # Base Exporter Class that contains generic helper methods, to be
+      # used by other Exporters via inheritence
+      class Base < Daru::IO::Base
+        # Checks whether the first argument given to any `Daru::IO::<Exporter>` module
+        # is a `Daru::DataFrame`. Raises an error when it's not a `Daru::DataFrame`.
+        #
+        # @param dataframe [Daru::DataFrame] A DataFrame to initialize
+        #
+        # @example Stores the dataframe
+        #   df = Daru::DataFrame.new([[1,2],[3,4]], order: [:a, :b])
+        #   Daru::IO::Exporters::Base.new(df)
+        #
+        #   #=> #<Daru::IO::Exporters::Base:0x007f899081af08 @dataframe=#<Daru::DataFrame(2x2)>
+        #   #      a   b
+        #   #  0   1   3
+        #   #  1   2   4>
+        #
+        # @example Raises error when not a DataFrame
+        #   Daru::IO::Exporters::Base.new(nil)
+        #
+        #   #=> ArgumentError: Expected first argument to be a Daru::DataFrame, received NilClass instead
+        def initialize(dataframe)
+          unless dataframe.is_a?(Daru::DataFrame)
+            raise ArgumentError,
+              'Expected first argument to be a Daru::DataFrame, '\
+              "received #{dataframe.class} instead."
+          end
+          @dataframe = dataframe
+        end
+
+        # Exports an Exporter instance to a file-writable String.
+        #
+        # @return A file-writable `String`
+        #
+        # @example Getting a file-writable string from Avro Exporter instance
+        #
+        #   instance = Daru::IO::Exporters::Format.new(opts)
+        #   instance.to_s #! same as df.to_format_string(opts)
+        def to_s
+          tempfile = Tempfile.new('tempfile')
+          path     = tempfile.path
+          write(path)
+
+          File.read(path)
+        end
+      end
+    end
+  end
+end

data/lib/daru/io/exporters/csv.rb

@@ -0,0 +1,103 @@
+require 'daru/io/exporters/base'
+
+module Daru
+  module IO
+    module Exporters
+      # CSV Exporter Class, that extends `to_csv_string` and `write_csv` methods to
+      # `Daru::DataFrame` instance variables
+      class CSV < Base
+        Daru::DataFrame.register_io_module :to_csv_string, self
+        Daru::DataFrame.register_io_module :write_csv, self
+
+        # Initializes a CSV Exporter instance
+        #
+        # @param dataframe [Daru::DataFrame] A dataframe to export
+        # @param converters [Symbol] A type to convert the data in dataframe
+        # @param compression [Symbol] Defaults to `:infer`, which decides depending on file format
+        #   like `.csv.gz`. For explicitly writing into a `.csv.gz` file, set
+        #   `:compression` as `:gzip`.
+        # @param headers [Boolean] When set to `false`, the headers aren't written
+        #   to the CSV file
+        # @param convert_comma [Boolean] When set to `true`, the decimal delimiter
+        #   for float values is a comma (,) rather than a dot (.).
+        # @param options [Hash] CSV standard library options, to tweak other
+        #   default options of CSV gem.
+        #
+        # @example Initializing a CSV Exporter Instance
+        #   df = Daru::DataFrame.new([[1,2],[3,4]], order: [:a, :b])
+        #
+        #   #=> #<Daru::DataFrame(2x2)>
+        #   #      a   b
+        #   #  0   1   3
+        #   #  1   2   4
+        #
+        #   csv_instance = Daru::IO::Exporters::CSV.new(df, col_sep: ' ')
+        #   csv_gz_instance = Daru::IO::Exporters::CSV.new(df, col_sep: ' ', compression: :gzip)
+        def initialize(dataframe, converters: :numeric, compression: :infer,
+          headers: nil, convert_comma: nil, **options)
+          require 'csv'
+
+          super(dataframe)
+          @headers       = headers
+          @compression   = compression
+          @convert_comma = convert_comma
+          @options       = options.merge converters: converters
+        end
+
+        # Exports a CSV Exporter instance to a file-writable String.
+        #
+        # @return [String] A file-writable string
+        #
+        # @example Getting a file-writable string from CSV Exporter instance
+        #   csv_instance.to_s
+        #   #=> "a b\n1 3\n2 4\n"
+        #
+        #   csv_gz_instance.to_s
+        #   #=> "\u001F\x8B\b\u0000*D\xA4Y\u0000\u0003KTH\xE22T0\xE62R0\xE1\u0002\u0000\xF2\\\x96y\..."
+        def to_s
+          super
+        end
+
+        # Exports an Avro Exporter instance to a csv / csv.gz file.
+        #
+        # @param path [String] Path of the csv / csv.gz file where the dataframe is to be saved
+        #
+        # @example Writing an Avro Exporter instance to an Avro file
+        #   csv_instance.write('filename.csv')
+        #   csv_gz_instance.write('filename.csv.gz')
+        def write(path)
+          @path    = path
+          contents = process_dataframe
+
+          if compression?(:gzip, '.csv.gz')
+            require 'zlib'
+            ::Zlib::GzipWriter.open(@path) do |gz|
+              contents.each { |content| gz.write(content.to_csv(@options)) }
+              gz.close
+            end
+          else
+            csv = ::CSV.open(@path, 'w', @options)
+            contents.each { |content| csv << content }
+            csv.close
+          end
+        end
+
+        private
+
+        def compression?(algorithm, *formats)
+          @compression == algorithm || formats.any? { |f| @path.end_with?(f) }
+        end
+
+        def process_dataframe
+          [].tap do |result|
+            result << @dataframe.vectors.to_a unless @headers == false
+            @dataframe.map_rows do |row|
+              next result << row.to_a unless @convert_comma
+              result << row.map(&:to_s).map { |v| v =~ /^\d+./ ? v.tr('.',',') : v }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/daru/io/exporters/excel.rb

@@ -0,0 +1,148 @@
+require 'daru/io/exporters/base'
+
+module Daru
+  module IO
+    module Exporters
+      # Excel Exporter Class, that extends `to_excel_string` and `write_excel` methods to
+      # `Daru::DataFrame` instance variables
+      class Excel < Base
+        Daru::DataFrame.register_io_module :to_excel_string, self
+        Daru::DataFrame.register_io_module :write_excel, self
+
+        # Initializes an Excel Exporter instance.
+        #
+        # @note For giving formatting options as hashes to the `:data`, `:index` or `header`
+        #   keyword argument(s), please have a look at the
+        #   {http://www.rubydoc.info/gems/ruby-spreadsheet/Spreadsheet/Font Spreadsheet::Font}
+        #   and
+        #   {http://www.rubydoc.info/gems/ruby-spreadsheet/Spreadsheet/Format Spreadsheet::Format}
+        #   pages.
+        #
+        # @param dataframe [Daru::DataFrame] A dataframe to export. Supports even dataframes
+        #   with multi-index.
+        # @param header [Hash or Boolean] Defaults to true. When set to false or nil,
+        #   headers are not written. When given a hash of formatting options,
+        #   headers are written with the specific formatting. When set to true,
+        #   headers are written without any formatting.
+        # @param data [Hash or Boolean] Defaults to true. When set to false or nil,
+        #   data values are not written. When given a hash of formatting options,
+        #   data values are written with the specific formatting. When set to true,
+        #   data values are written without any formatting.
+        # @param index [Hash or Boolean] Defaults to true. When set to false or nil,
+        #   index values are not written. When given a hash of formatting options,
+        #   index values are written with the specific formatting. When set to true,
+        #   index values are written without any formatting.
+        #
+        # @example Initializing an Excel Exporter instance
+        #   df = Daru::DataFrame.new([[1,2],[3,4]], order: [:a, :b])
+        #
+        #   #=> #<Daru::DataFrame(2x2)>
+        #   #      a   b
+        #   #  0   1   3
+        #   #  1   2   4
+        #
+        #   simple_instance = Daru::IO::Exporters::Excel.new(df)
+        #   formatted_instance = Daru::IO::Exporters::Excel.new(
+        #     df,
+        #     header: { color: :red, weight: :bold },
+        #     index: false,
+        #     data: { color: :blue }
+        #   )
+        def initialize(dataframe, header: true, data: true, index: true)
+          optional_gem 'spreadsheet', '~> 1.1.1'
+
+          super(dataframe)
+          @data   = data
+          @index  = index
+          @header = header
+        end
+
+        # Exports an Excel Exporter instance to a file-writable String.
+        #
+        # @return [String] A file-writable string
+        #
+        # @example Getting a file-writable string from Excel Exporter instance
+        #   simple_instance.to_s #! same as df.to_avro_string(schema)
+        #
+        #   #=> "\xD0\xCF\u0011\u0871\u001A\xE1\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000..."
+        #
+        #   formatted_instance.to_s
+        #
+        #   #=> "\xD0\xCF\u0011\u0871\u001A\xE1\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000..."
+        def to_s
+          super
+        end
+
+        # Exports an Excel Exporter instance to an xls file.
+        #
+        # @param path [String] Path of excel file where the dataframe is to be saved
+        #
+        # @example Writing an Excel Exporter instance to an xls file
+        #   instance.write('filename.xls')
+        def write(path)
+          @book  = Spreadsheet::Workbook.new
+          @sheet = @book.create_worksheet
+
+          process_offsets
+          write_headers
+
+          @dataframe.each_row_with_index.with_index do |(row, idx), r|
+            write_index(idx, r+@row_offset)
+            write_data(row,  r+@row_offset)
+          end
+
+          @book.write(path)
+        end
+
+        private
+
+        def process_offsets
+          @row_offset   = @header ? 1 : 0
+          @col_offset   = 0 unless @index
+          @col_offset ||= @dataframe.index.is_a?(Daru::MultiIndex) ? @dataframe.index.width : 1
+        end
+
+        def write_headers
+          formatting(
+            0...@col_offset + @dataframe.ncols,
+            0,
+            [' '] * @col_offset + @dataframe.vectors.map(&:to_s),
+            @header
+          )
+        end
+
+        def write_index(idx, row)
+          formatting(
+            0...@col_offset,
+            row,
+            idx,
+            @index
+          )
+        end
+
+        def write_data(row, idx)
+          formatting(
+            @col_offset...@col_offset + @dataframe.ncols,
+            idx,
+            row,
+            @data
+          )
+        end
+
+        def formatting(col_range, row, idx, format)
+          return unless format
+          @sheet.row(row).concat(
+            case idx
+            when Daru::Vector then idx.to_a
+            when Array then idx.map(&:to_s)
+            else [idx.to_s]
+            end
+          )
+
+          return unless format.is_a?(Hash)
+          col_range.each { |col| @sheet.row(row).set_format(col, Spreadsheet::Format.new(format)) }
+        end
+      end
+    end
+  end
+end