nexosis_api 1.0.3 → 1.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 52b0b16b9e0a7690ade72a0498b125aa2672f89d
-  data.tar.gz: da93e102814f4b830e5b5411e873c2cd2c6017c0
+  metadata.gz: 0f9a520d658fe88b6f7d4e73e9d04482dec0183a
+  data.tar.gz: b7e5ccaa92a1970ce6562e497791cab3a3f7b418
 SHA512:
-  metadata.gz: 8742572d3e9860871553bf5056d71e3ff30a5fae276e39479b73591ee443e5327b305bd4f35dafb16d451b9273facead20148b4524b7d57bc5b5924d9a9f8b94
-  data.tar.gz: 9298f52be1a0a8d6fe131d3c63bcd28a6236a85d372fabf3380d86f121041af14f5164fe15eee3e025cb1271a5f6aef386575be727107bf62bbd94b0141ef319
+  metadata.gz: 61280b997acca1559619d03797003621f0e5c2a12f5ac5b78d4a86af2a5bd707783f2b9524358457b750a1b6db79df2725e6e2c4627fc4d815bc462fa239b180
+  data.tar.gz: 5f6b90b6bbac7c35072ca6da4991cd1d69d66edeed02fa627e2e8c435a5f91dc6896ab800c39f80368f5e0c3807f98660a73028080e766b9e49ce4c9da5f75ad

data/lib/nexosis_api/client.rb

@@ -9,13 +9,16 @@ require 'nexosis_api/dataset_model'
 require 'nexosis_api/dataset_summary'
 require 'nexosis_api/http_exception'
 require 'nexosis_api/impact_metric'
+require 'nexosis_api/imports_response'
 require 'nexosis_api/link'
 require 'nexosis_api/metric'
 require 'nexosis_api/session_response'
 require 'nexosis_api/session_result'
 require 'nexosis_api/session'
+require 'nexosis_api/time_interval'
 require 'nexosis_api/client/sessions'
 require 'nexosis_api/client/datasets'
+require 'nexosis_api/client/imports'
 
 module NexosisApi
     # Primary entry point to working with Nexosis API
@@ -24,6 +27,7 @@ module NexosisApi
         base_uri 'https://ml.nexosis.com/v1'
         include Client::Sessions
         include Client::Datasets
+        include Client::Imports
 
         def initialize(options = {})
             raise ArgumentError, 'api_key was not defined' unless options[:api_key].nil? == false

data/lib/nexosis_api/client/imports.rb

@@ -0,0 +1,75 @@
+require 'json'
+module NexosisApi
+	class Client
+		# Imports-based API operations
+		#
+		# @see http://docs.nexosis.com/
+		module Imports
+
+            # List all existing import requests
+            #
+            # @return [Array of NexosisApi::ImportsResponse]
+            def list_imports
+                imports_url = "/imports"
+                response = self.class.get(imports_url, :headers => @headers)
+                if(response.success?)
+                    items = []
+                    response.parsed_response["items"].each do |i|
+                        items << NexosisApi::ImportsResponse.new(i)
+                    end
+                    items
+                else
+                   raise HttpException.new("There was a problem getting the imports: #{response.code}.", "uploading dataset from s3 #{dataset_name}" ,response)
+			    end
+            end
+
+            # Import a file from AWS s3 as your dataset
+            #
+            # @param dataset_name [String] the name to give to the new dataset or existing dataset to which this data will be upserted
+            # @param bucket_name [String] the AWS S3 bucket name in which the path will be found
+            # @param path [String] the path within the bucket (usually file name)
+            # @param region [String] the region in which your bucket exists. Defaults to us-east-1
+            # @param column_metadata [Array of NexosisApi::DatasetColumn] description of each column in target dataset. Optional.
+            # @return [NexosisApi::ImportsResponse]
+            # @see http://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region for information on region names
+            def import_from_s3(dataset_name, bucket_name, path, region = "us-east-1", column_metadata = [])
+                raise ArgumentError "dataset_name was not provided and is not optional " unless dataset_name.to_s.empty? == false
+                raise ArgumentError "bucket_name was not provided and is not optional " unless bucket_name.to_s.empty? == false
+                raise ArgumentError "path was not provided and is not optional " unless path.to_s.empty? == false
+                
+                s3_import_url = "/imports/s3"
+                column_json = DatasetColumn.to_json(column_metadata)
+                body = {
+                    "dataSetName" => dataset_name,
+                    "bucket" => bucket_name,
+                    "path" => path,
+                    "region" => region,
+                    "columns" => column_json
+                }
+                response = self.class.post(s3_import_url, :headers => @headers, :body => body.to_json)
+                if(response.success?)
+                    NexosisApi::ImportsResponse.new(response.parsed_response)
+                else
+                   raise HttpException.new("There was a problem importing from s3: #{response.code}.", "uploading dataset from s3 #{dataset_name}" ,response)
+			    end
+            end
+
+            # Get s3 response back from import created previously. Presumably to check status.
+            #
+            # @param import_id [String] The id returned from a previous request to import
+            # @return [NexosisApi::ImportsResponse]
+            # @example get S3 import
+            #    NexosisApi.client.retrieve_import('740dca2a-b488-4322-887e-fa473b1caa54')
+            def retrieve_import(import_id)
+                raise ArgumentError "import_id was not provided and is not optional " unless import_id.to_s.empty? == false
+                imports_url = "/imports/#{import_id}"
+                response = self.class.get(imports_url, :headers => @headers)
+                if(response.success?)
+                    NexosisApi::ImportsResponse.new(response.parsed_response)
+                else
+                   raise HttpException.new("There was a problem getting the import #{response.code}.", "requesting an import #{import_id}" ,response)
+			    end
+            end
+        end
+    end
+end

data/lib/nexosis_api/client/sessions.rb

@@ -11,7 +11,7 @@ module NexosisApi
 			# List sessions previously submitted
 			#
 			# @param query_options [Hash] optionally provide query parameters to limit the search of sessions. 
-			# @return[Array of NexosisApi::SessionResponse] with all sessions matching the query or all if no query
+			# @return [Array of NexosisApi::SessionResponse] with all sessions matching the query or all if no query
 			# @note query parameters hash members are dataset_name, event_name, requested_before_date, and requested_after_date. 
 			#    After and before dates refer to the session requested date.
 			# @example query for just one dataset
@@ -58,6 +58,8 @@ module NexosisApi
 			# @note query parameters hash members are type, dataset_name, event_name, start_date, and end_date. 
 			#    Start and end dates refer to the session requested date.
 			#    Results are not removed but then can only be accessed by dataset name
+			# @example Remove all sessions based on a dataset by name
+			#    NexosisApi.client.remove_sessions :dataset_name => 'existing_dataset'
 			def remove_sessions(query_options = {})
 				sessions_url = '/sessions'
 				response = self.class.delete(sessions_url, :headers => @headers, :query => get_query_from_options(query_options))
@@ -74,9 +76,13 @@ module NexosisApi
 			# @param start_date [DateTime] The starting date of the forecast period. Can be ISO 8601 string. 
 			# @param end_date [DateTime] The ending date of the forecast period. Can be ISO 8601 string.
 			# @param target_column [String] The name of the column for which you want predictions. Nil if defined in dataset.
+			# @param result_interval [NexosisApi::TimeInterval] (optional) - The date/time interval (e.g. Day, Hour) at which predictions should be generated. So, if Hour is specified for this parameter you will get a Result record for each hour between startDate and endDate. If unspecified, we’ll generate predictions at a Day interval.
 			# @return [NexosisApi::SessionResponse] providing information about the sesssion
-			def create_forecast_session(dataset_name, start_date, end_date, target_column = nil)
-				create_session(dataset_name, start_date, end_date, target_column)
+			# @note The time interval selected must be greater than or equal to the finest granularity of the data provided.
+			#    For instance if your data includes many recoreds per hour, then you could request hour, day, or any other result interval.
+			#    However, if your data includes only a few records per day or fewer, then a request for an hourly result interval will produce poor results. 
+			def create_forecast_session(dataset_name, start_date, end_date, target_column = nil, result_interval = NexosisApi::TimeInterval::DAY)
+				create_session(dataset_name, start_date, end_date, target_column, false, nil, "forecast", nil,nil,result_interval)
 			end
 
 			# Forecast from CSV formatted data.
@@ -85,13 +91,14 @@ module NexosisApi
 			# @param start_date [DateTime] The starting date of the forecast period. Can be ISO 8601 parseable string. 
 			# @param end_date [DateTime] The ending date of the forecast period. Can be ISO 8601 parseable string.
 			# @param target_column [String] The name of the column for which you want predictions.
+			# @param result_interval [NexosisApi::TimeInterval] (optional) - The date/time interval (e.g. Day, Hour) at which predictions should be generated. So, if Hour is specified for this parameter you will get a Result record for each hour between startDate and endDate. If unspecified, we’ll generate predictions at a Day interval.
 			# @return [NexosisApi::SessionResponse] providing information about the sesssion
 			# @example load and send local file
 			#    mycsv = CSV.read('.\mylocal.csv')
 			#    NexosisApi.client(:api_key=>mykey).create_forecast_session_csv(mycsv,'sales','01-01-2017','02-01-2017')
-            def create_forecast_session_csv(csv, start_date, end_date, target_column)
+            def create_forecast_session_csv(csv, start_date, end_date, target_column, result_interval = NexosisApi::TimeInterval::DAY)
 				content = process_csv_to_s csv
-                create_session(nil, start_date, end_date, target_column, false, nil, "forecast", content)
+                create_session(nil, start_date, end_date, target_column, false, nil, "forecast", content, "text/csv", result_interval)
             end
 
 			# Forecast from data posted in the request.
@@ -100,11 +107,12 @@ module NexosisApi
 			# @param start_date [DateTime] The starting date of the forecast period. Can be ISO 8601 string. 
 			# @param end_date [DateTime] The ending date of the forecast period. Can be ISO 8601 string.
 			# @param target_column [String] The name of the column for which you want predictions. Nil if defined in dataset
+			# @param result_interval [NexosisApi::TimeInterval] (optional) - The date/time interval (e.g. Day, Hour) at which predictions should be generated. So, if Hour is specified for this parameter you will get a Result record for each hour between startDate and endDate. If unspecified, we’ll generate predictions at a Day interval.
 			# @return [NexosisApi::SessionResponse] providing information about the sesssion
 			# @see https://developers.nexosis.com/docs/services/98847a3fbbe64f73aa959d3cededb3af/operations/5919ef80a730020dd851f233
-			def create_forecast_session_data(json_data, start_date, end_date, target_column = nil)
+			def create_forecast_session_data(json_data, start_date, end_date, target_column = nil, result_interval = NexosisApi::TimeInterval::DAY)
 				json_data = json_data.to_json unless json_data.is_a? String
-				create_session nil, start_date, end_date, target_column, false, nil, "forecast", json_data, "application/json"
+				create_session nil, start_date, end_date, target_column, false, nil, "forecast", json_data, "application/json", result_interval
 			end
 
 			# Estimate the cost of a forecast from data already saved to the API.
@@ -125,9 +133,10 @@ module NexosisApi
 			# @param end_date [DateTime] The ending date of the impactful event. Can be ISO 8601 string.
 			# @param event_name [String] The name of the event.
 			# @param target_column [String] The name of the column for which you want predictions. Nil if defined in datatset.
+			# @param result_interval [NexosisApi::TimeInterval] (optional) - The date/time interval (e.g. Day, Hour) at which predictions should be generated. So, if Hour is specified for this parameter you will get a Result record for each hour between startDate and endDate. If unspecified, we’ll generate predictions at a Day interval.
 			# @return [NexosisApi::SessionResponse] providing information about the sesssion
-            def create_impact_session(dataset_name, start_date, end_date, event_name, target_column = nil)
-                create_session dataset_name, start_date, end_date, target_column, false, event_name, "impact"
+            def create_impact_session(dataset_name, start_date, end_date, event_name, target_column = nil, result_interval = NexosisApi::TimeInterval::DAY)
+                create_session dataset_name, start_date, end_date, target_column, false, event_name, "impact", nil, result_interval
             end
 
 			# Analyze impact for an event with data in json format.
@@ -137,11 +146,12 @@ module NexosisApi
 			# @param end_date [DateTime] The ending date of the impactful event. Can be ISO 8601 string.
 			# @param event_name [String] The name of the event.
 			# @param target_column [String] The name of the column for which you want predictions. Nil if defined in dataset.
+			# @param result_interval [NexosisApi::TimeInterval] (optional) - The date/time interval (e.g. Day, Hour) at which predictions should be generated. So, if Hour is specified for this parameter you will get a Result record for each hour between startDate and endDate. If unspecified, we’ll generate predictions at a Day interval.
 			# @return [NexosisApi::SessionResponse] providing information about the sesssion
 			# @see https://developers.nexosis.com/docs/services/98847a3fbbe64f73aa959d3cededb3af/operations/5919ef80a730020dd851f233
-			def create_impact_session_data(json_data, start_date, end_date, event_name, target_column = nil)
+			def create_impact_session_data(json_data, start_date, end_date, event_name, target_column = nil, result_interval = NexosisApi::TimeInterval::DAY)
 				json_data = json_data.to_json unless json_data.is_a? String
-				create_session nil, start_date, end_date, target_column, false, event_name, "impact", json_data, "application/json"
+				create_session nil, start_date, end_date, target_column, false, event_name, "impact", json_data, "application/json", result_interval
 			end
             
 			# Estimate the cost of impact analysis for an event with data already saved to the API.
@@ -195,13 +205,14 @@ module NexosisApi
 			    end
             end
         private
-			def create_session(dataset_name, start_date, end_date, target_column = nil, is_estimate=false, event_name = nil, type = "forecast", content = nil, content_type = "text/csv")
+			def create_session(dataset_name, start_date, end_date, target_column = nil, is_estimate=false, event_name = nil, type = "forecast", content = nil, content_type = "text/csv", result_interval = NexosisApi::TimeInterval::DAY)
 				session_url = "/sessions/#{type}"
 				query = { 
 					"targetColumn" => target_column.to_s,
 					"startDate" => start_date.to_s,
 					"endDate" => end_date.to_s,
-					"isestimate" => is_estimate.to_s
+					"isestimate" => is_estimate.to_s,
+					"resultInterval" => result_interval.to_s
 				}
 				query["dataSetName"] = dataset_name.to_s unless dataset_name.to_s.empty?
 				if(event_name.nil? == false)

data/lib/nexosis_api/dataset_column.rb

@@ -20,5 +20,16 @@ module NexosisApi
         # @note Either none, timestamp, target, or feature
         # @return [NexosisApi::ColumnRole]
         attr_accessor :role
+
+        # utility method to format a column description in the way it is expected on input
+        def to_hash
+            { self.name => { "dataType" => self.type.to_s, "role" => self.role.to_s }} 
+        end
+
+        def self.to_json(column_array)
+            result = {}
+            column_array.each {|col| result[col.to_hash.keys[0]] = col.to_hash.values[0] } 
+            result
+        end
     end
 end

data/lib/nexosis_api/http_exception.rb

@@ -5,16 +5,13 @@ module NexosisApi
       def initialize(message = "", action = nil, http_obj)
         @message = message
         if(http_obj.is_a?(Hash))
-        @message.prepend(http_obj["message"].concat(": ")) unless http_obj["message"].nil?
-        @action = action
-          if(http_obj.instance_of?(HTTParty::Response))
-            @message = message.concat("|| Explanation: ").concat(http_obj["errorDetails"]["message"]) unless http_obj["errorDetails"]["message"].nil?
-            @code = http_obj.parsed_response["statusCode"]
-            @type = http_obj.parsed_response["errorType"]
-            @response = http_obj.response
-            @request = http_obj.request
-          end
-        else
+          @message.prepend(http_obj["message"].concat(": ")) unless http_obj["message"].nil?
+          @action = action
+        elsif(http_obj.instance_of?(HTTParty::Response))
+          @message = message.concat("|| Explanation: ").concat(http_obj.parsed_response["errorDetails"].to_s) unless http_obj.parsed_response["errorDetails"].nil?
+          @type = http_obj.parsed_response["errorType"]
+          @response = http_obj.response
+          @request = http_obj.request
           @code = http_obj.code
         end
       end

data/lib/nexosis_api/imports_response.rb

@@ -0,0 +1,66 @@
+module NexosisApi
+    # class to parse results from an imports call
+    class ImportsResponse
+        def initialize(response_hash)
+            response_hash.each do |k,v|
+                if(k == "importId")
+                    @import_id = v
+                elsif(k == "requestedDate")
+                    @requested_date = v
+                elsif(k == "columns")
+                    columns = []
+                    next if v.nil?
+                    v.keys.each do |col_key|
+                        columns << NexosisApi::DatasetColumn.new(col_key, v[col_key])
+                    end
+                    @column_metadata = columns
+                elsif(k == "links")
+					links = Array.new
+					v.each do |l| links << NexosisApi::Link.new(l) end
+					instance_variable_set("@#{k}", links) unless v.nil?
+                else
+                   instance_variable_set("@#{k}", v) unless v.nil?
+                end
+            end
+        end
+
+        # The unique identifier for this import request
+        # @return [String]
+        attr_accessor :import_id
+
+        # Currently always s3
+        # @return [String]
+        attr_accessor :type, :s3 
+        
+        # The current status of the import request
+        # @return [String]
+        # @note The import will be performed in a FIFO queue. Check back on status before attempting to start a session using the dataset.
+        attr_accessor :status
+
+        # echo back the dataset name provided
+        # @return [String]
+        attr_accessor :dataSetName
+
+        # The S3 parameters used to import a dataset
+        # @return [Hash]
+        # For an S3 response the keys of this hash should be 'bucket', 'path', and 'region'
+        attr_accessor :parameters
+
+        # The date of the import request
+        # @return [DateTime]
+        attr_accessor :requested_date
+
+        # Additional details. Normally empty.
+        # @return [Array]
+        attr_accessor :messages
+
+		# The column descriptors for the data in this session
+		#    will reflect either the metadata sent in, defaults form dataset, or inferred values
+		# @return[Array of NexosisApi::DatasetColumn]
+        attr_accessor :column_metadata
+
+        # associated hypermedia
+		# @return [Array of NexosisApi::Link]
+		attr_accessor :links
+    end
+end

data/lib/nexosis_api/session.rb

@@ -9,6 +9,15 @@ module NexosisApi
 					instance_variable_set("@#{k}", links) unless v.nil?
 				elsif(k == "isEstimate")
                     instance_variable_set("@is_estimate", v) unless v.nil?
+				elsif(k == "columns")
+                    columns = []
+                    next if v.nil?
+                    v.keys.each do |col_key|
+                        columns << NexosisApi::DatasetColumn.new(col_key, v[col_key])
+                    end
+                    @column_metadata = columns
+				elsif(k == "resultInterval")
+					@result_interval = v
 				else
 					instance_variable_set("@#{k}", v) unless v.nil?
 				end
@@ -58,6 +67,15 @@ module NexosisApi
 		# Is this session an estimate only session
 		# @return [Boolean]
 		attr_accessor :is_estimate
+
+		# The column descriptors for the data in this session
+		#    will reflect either the metadata sent in, defaults form dataset, or inferred values
+		# @return[Array of NexosisApi::DatasetColumn]
+		attr_accessor :column_metadata
+
+		# The requested result interval. Default is DAY if none was requested during session creation.
+		# @return [NexosisApi::TimeInterval]
+		attr_accessor :result_interval
 	end
 end
 

data/lib/nexosis_api/session_response.rb

@@ -11,7 +11,7 @@ module NexosisApi
 					instance_variable_set("@cost", v[0]) unless v.nil?
                 elsif(k == "nexosis-account-balance")
                     instance_variable_set("@account_balance", v[0]) unless v.nil?
-				end
+                end
 			end
         end
 

data/lib/nexosis_api/time_interval.rb

@@ -0,0 +1,15 @@
+module NexosisApi
+    #constants for the date/time interval (e.g. Day, Hour) at which predictions should be generated. 
+    module TimeInterval
+        # results summarized by hour
+        HOUR = :hour
+        # results summarized by day. Default option.
+        DAY = :day
+        # results summarized by week
+        WEEK = :week
+        # results summarized by month
+        MONTH = :month
+        # results summarized by year
+        YEAR = :year
+    end
+end

data/nexosisapi.gemspec

@@ -16,6 +16,6 @@ Gem::Specification.new do |spec|
   spec.require_paths = ['lib']
   spec.required_ruby_version = '>= 2.0.0'
   spec.summary = "Ruby client for working with the Nexosis API"
-  spec.version = '1.0.3'
+  spec.version = '1.0.5'
   spec.metadata["yard.run"] = "yri"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: nexosis_api
 version: !ruby/object:Gem::Version
-  version: 1.0.3
+  version: 1.0.5
 platform: ruby
 authors:
 - Nexosis,Inc
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-06-28 00:00:00.000000000 Z
+date: 2017-07-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -51,6 +51,7 @@ files:
 - lib/nexosis_api/algorithm_selection.rb
 - lib/nexosis_api/client.rb
 - lib/nexosis_api/client/datasets.rb
+- lib/nexosis_api/client/imports.rb
 - lib/nexosis_api/client/sessions.rb
 - lib/nexosis_api/column_role.rb
 - lib/nexosis_api/column_type.rb
@@ -60,11 +61,13 @@ files:
 - lib/nexosis_api/dataset_summary.rb
 - lib/nexosis_api/http_exception.rb
 - lib/nexosis_api/impact_metric.rb
+- lib/nexosis_api/imports_response.rb
 - lib/nexosis_api/link.rb
 - lib/nexosis_api/metric.rb
 - lib/nexosis_api/session.rb
 - lib/nexosis_api/session_response.rb
 - lib/nexosis_api/session_result.rb
+- lib/nexosis_api/time_interval.rb
 - nexosisapi.gemspec
 homepage: https://github.com/nexosis/nexosisclient-rb
 licenses: