nexosis_api 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 05cf5a6d76290c17f23d0db1e00a5d9215dfc56c
-  data.tar.gz: e28cbae30ef33132f250eb200efe6545eb46091b
+  metadata.gz: 7c526af7e9fcefc72090c15c425122bdcb1d84ad
+  data.tar.gz: d8b6c9a510f6c709f1d30cf4a7e63bd9864730cb
 SHA512:
-  metadata.gz: b17a834985acaa28a81bf3ecb2e7874b03adfd40907b9df3698b324b334bd8e0c1d51fb103cf8c521d7523d23b32c2c014392a3e0ae27689f55b48ec9a4b90ef
-  data.tar.gz: 06de1a773837de420b6a41cb24c32b41a50e007cdfd1eaccd2916fd18d7102448c7ea4b041545d29e1dbbefc98e759d68f9499f072fe15894b3709ad43e40e55
+  metadata.gz: bbfdbdc1f4da07c9ce8c88c7410ac483929ab07cd298906a31fb60395d5ed39a71c7609d3d69a705c2fba12c39de2102d8420d47ea3077efb6d20e4191e9232d
+  data.tar.gz: c17bdd00ea6712696f731b46193bcb6cd16f9a0f32bbe2c4cbb9e8fb8542e98ae8b13d21fbca517ddbb80c4892380b838215429a407eacbdaa076a51bcc0d0b2

data/lib/nexosis_api/calendar_jointarget.rb

@@ -23,6 +23,7 @@ module NexosisApi
     # @see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
     attr_accessor :timezone
 
+    # custom hash to match with api requests
     def to_hash
       hash = { 'calendar' => {} }
       hash['calendar'].store 'url', url unless url.nil?

data/lib/nexosis_api/client/datasets.rb

@@ -29,14 +29,22 @@ module NexosisApi
       # Gets the list of data sets that have been saved to the system, optionally filtering by partial name match.
       #
       # @param partial_name [String] if provided, all datasets returned will contain this string
-      # @return [Array of NexosisApi::DatasetSummary] array of datasets found
-      def list_datasets(partial_name = '')
-        list_dataset_url = "/data?partialName=#{partial_name}"
-        response = self.class.get(list_dataset_url, headers: @headers)
+      # @param page [int] page number for items in list
+      # @param page_size [int] number of items in each page
+      # @return [NexosisApi::PagedArray of NexosisApi::DatasetSummary] array of datasets found
+      # @since 1.4 - added paging parameters
+      def list_datasets(partial_name = '', page = 0, page_size = 50)
+        list_dataset_url = '/data'
+        query = {
+          page: page,
+          pageSize: page_size
+        }
+        query['partialName'] = partial_name unless partial_name.empty?
+        response = self.class.get(list_dataset_url, headers: @headers, query: query)
         if response.success?
-          response.parsed_response['items'].map do |dr|
-            NexosisApi::DatasetSummary.new(dr)
-          end
+          NexosisApi::PagedArray.new(response.parsed_response,
+                                     response.parsed_response['items']
+                                     .map { |dr| NexosisApi::DatasetSummary.new(dr) })
         else
           raise HttpException.new("There was a problem listing datasets: #{response.code}.", "listing datasets with partial name #{partial_name}", response)
         end

data/lib/nexosis_api/client/imports.rb

@@ -8,12 +8,23 @@ module NexosisApi
 
       # List all existing import requests
       #
-      # @return [Array of NexosisApi::ImportsResponse]
-      def list_imports
+      # @param dataset_name [String] optional name filter of dataset which was imported
+      # @param page [int] page number for items in list
+      # @param page_size [int] number of items in each page
+      # @return [NexosisApi::PagedArray of NexosisApi::ImportsResponse]
+      # @since 1.4 added paging parameters
+      def list_imports(dataset_name = '', page = 0, page_size = 50)
         imports_url = '/imports'
-        response = self.class.get(imports_url, headers: @headers)
+        query = {
+          dataSetName: dataset_name,
+          page: page,
+          pageSize: page_size
+        }
+        response = self.class.get(imports_url, headers: @headers, query: query)
         if (response.success?)
-          response.parsed_response['items'].map { |i| NexosisApi::ImportsResponse.new(i) }
+          NexosisApi::PagedArray.new(response.parsed_response,
+                                     response.parsed_response['items']
+                                     .map { |i| NexosisApi::ImportsResponse.new(i) })
         else
           raise HttpException.new("There was a problem getting the imports: #{response.code}.", "uploading dataset from s3 #{dataset_name}", response)
         end

data/lib/nexosis_api/client/models.rb

@@ -9,7 +9,7 @@ module NexosisApi
       # models created for this data source name.
       # @param query_options [Hash] limit by dates: begin_date and/or end_date
       # @note - query options dates can either be ISO 8601 compliant strings or Date objects
-      # @return [Array of NexosisApi::ModelSummary] - all models available within the query parameters
+      # @return [NexosisApi::PagedArray of NexosisApi::ModelSummary] - all models available within the query parameters
       def list_models(datasource_name = nil, page = 0, page_size = 50, query_options = {})
         model_url = '/models'
         query = {
@@ -22,11 +22,12 @@ module NexosisApi
         end
         query.store(dataSourceName: datasource_name) unless datasource_name.nil?
         response = self.class.get(model_url, headers: @headers, query: query)
-        if (response.success?)
-          response.parsed_response['items'].map { |item| NexosisApi::ModelSummary.new(item) }
-        else
-          raise HttpException.new("There was a problem listing models: #{response.code}.", "listing models with data source name #{datasource_name}", response)
-        end
+        raise HttpException.new("There was a problem listing models: #{response.code}.",
+                                "listing models with data source name #{datasource_name}",
+                                response) unless response.success?
+        NexosisApi::PagedArray.new(response.parsed_response,
+                                   response.parsed_response['items']
+                                   .map { |item| NexosisApi::ModelSummary.new(item) })
       end
 
       # Get the details of the particular model requested by id

data/lib/nexosis_api/client/sessions.rb

@@ -13,14 +13,14 @@ module NexosisApi
       # @param query_options [Hash] optionally provide query parameters to limit the search of sessions. 
       # @param page [Integer] optionally provide a page number for paging. Defaults to 0 (first page).
       # @param pageSize [Integer] optionally provide a page size to limit the total number of results. Defaults to 50, max 1000
-      # @return [Array of NexosisApi::SessionResponse] with all sessions matching the query or all if no query
+      # @return [NexosisApi::PagedArray 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
       #   sessions = NexosisApi.client.list_sessions :dataset_name => 'MyDataset'
       def list_sessions(query_options = {}, page = 0, pageSize = 50)
         sessions_url = '/sessions'
-        query = { 
+        query = {
           'dataSetName' => query_options[:dataset_name],
           'eventName' => query_options[:event_name],
           'requestedAfterDate' => query_options[:requested_after_date],
@@ -29,17 +29,14 @@ module NexosisApi
           'page' => page,
           'pageSize' => pageSize
         }
-        response = self.class.get(sessions_url, :headers => @headers, :query => query)
-        if(response.success?)
-          all_responses = []
-          response.parsed_response['items'].each do |session_hash|
-            response_hash = { 'session' => session_hash }.merge(response.headers)
-            all_responses << NexosisApi::SessionResponse.new(response_hash)
-          end
-          all_responses
-        else
-          raise HttpException.new('Could not retrieve sessions',"Get all sessions with query #{query_options.to_s}",response)
-        end
+        response = self.class.get(sessions_url, headers: @headers, query: query)
+        raise HttpException.new('Could not retrieve sessions',
+                                "Get all sessions with query #{query_options}",
+                                response) unless response.success?
+        NexosisApi::PagedArray.new(response.parsed_response, response.parsed_response['items'].map do |session_hash|
+          response_hash = { 'session' => session_hash }.merge(response.headers)
+          NexosisApi::SessionResponse.new(response_hash)
+        end)
       end
 
       # Remove a session
@@ -127,11 +124,13 @@ module NexosisApi
       #
       # @param session_id [String] the Guid string returned in a previous session request
       # @param as_csv [Boolean] indicate whether results should be returned in csv format
+      # @param prediction_interval [Float] one of the available prediction intervals for the session.
       # @return [NexosisApi::SessionResult] SessionResult if parsed, String of csv data otherwise
-      def get_session_results(session_id, as_csv = false)
+      def get_session_results(session_id, as_csv = false, prediction_interval = nil)
         session_result_url = "/sessions/#{session_id}/results"
         @headers['Accept'] = 'text/csv' if as_csv
-        response = self.class.get(session_result_url, @options)
+        query = { predictionInterval: prediction_interval } unless prediction_interval.nil?
+        response = self.class.get(session_result_url, headers: @headers, query: query)
         @headers.delete('Accept')
 
         if (response.success?)
@@ -153,6 +152,12 @@ module NexosisApi
         raise HttpException.new("There was a problem getting the session: #{response.code}.", "getting session #{session_id}" ,response)
       end
 
+      # Create a new model based on a data source
+      #
+      # @param datasource_name [String] The datasource from which to build the model
+      # @param target_column [String] The column which will be predicted when using the model
+      # @param columns [Hash] column metadata to modify roles, imputation, or target.
+      # @since 1.3.0
       def create_model(datasource_name, target_column, columns = {})
         model_url = '/sessions/model'
         body = {

data/lib/nexosis_api/client/views.rb

@@ -11,7 +11,7 @@ module NexosisApi
       # @param dataset_name [String] optionally limit results by dataset used in definition
       # @param page [Integer] optionally get results by non-zero page - defaults to 0
       # @param page_size [Integer] optionally limit page size - defaults to 50 (max: 1000)
-      # @return [Array of NexosisApi::ViewDefinition]
+      # @return [NexosisApi::PagedArray of NexosisApi::ViewDefinition]
       # @raise [NexosisApi::HttpException]
       def list_views(partial_name = '', dataset_name = '', page = 0, page_size = 50)
         url = '/views'
@@ -22,11 +22,9 @@ module NexosisApi
         query.store 'partialName', partial_name if partial_name.empty? == false
         query.store 'dataSetName', dataset_name if dataset_name.empty? == false
         response = self.class.get(url, headers: @headers, query: query)
-        if response.success?
-          response.parsed_response['items'].map do |definition|
-            NexosisApi::ViewDefinition.new(definition)
-          end
-        end
+        raise NexosisApi::HttpException('Could not retrieve list of views.', 'attempting list of views', response) unless response.success?
+        NexosisApi::PagedArray.new(response.parsed_response, response.parsed_response['items']
+                               .map { |definition| NexosisApi::ViewDefinition.new(definition) })
       end
 
       # Create a new view or update an existing one by name

data/lib/nexosis_api/client.rb

@@ -17,6 +17,7 @@ require 'nexosis_api/join'
 require 'nexosis_api/link'
 require 'nexosis_api/metric'
 require 'nexosis_api/model_summary'
+require 'nexosis_api/paged_array'
 require 'nexosis_api/predict_response'
 require 'nexosis_api/session_response'
 require 'nexosis_api/session_result'

data/lib/nexosis_api/column.rb

@@ -40,6 +40,7 @@ module NexosisApi
                   'aggregation' => aggregation.to_s } }
     end
 
+    # allows json to be built for api requests
     def self.to_json(column_array)
       result = {}
       column_array.each { |col| result[col.to_hash.keys[0]] = col.to_hash.values[0] } 

data/lib/nexosis_api/column_options.rb

@@ -27,6 +27,7 @@ module NexosisApi
     # @return [String]
     attr_accessor :alias
 
+    # builds a custom hash which will match api requests
     def to_hash
       hash = { column_name => {} }
       hash[column_name]['join_interval'] = join_interval.to_s unless join_interval.nil?

data/lib/nexosis_api/dataset_jointarget.rb

@@ -11,6 +11,7 @@ module NexosisApi
     # @return [String] name of the dataset provided for this join
     attr_accessor :dataset_name
     
+    # provides a custom hash to match api requests
     def to_hash
       { 'dataSet' => { 'name' => dataset_name } }
     end

data/lib/nexosis_api/join.rb

@@ -37,6 +37,7 @@ module NexosisApi
     # @return [Array of NexosisApi::Join] zero or more additional joins
     attr_accessor :joins
 
+    # provides a custom hash which can be converted to json matching api request
     def to_hash
       hash = join_target.to_hash
       if column_options.nil? == false
@@ -54,6 +55,7 @@ module NexosisApi
       hash
     end
 
+    # gets a json represenation which can be used in api request
     def to_json
       to_hash.to_json
     end

data/lib/nexosis_api/paged_array.rb

@@ -0,0 +1,35 @@
+module NexosisApi
+  # Generic list base class for list responses
+  # @since 1.4.0
+  class PagedArray < Array
+    def initialize(paged_response, item_array = [])
+      self[0..item_array.length] = item_array
+      var_map = { 'pageNumber' => :@page_number,
+                  'totalPages' => :@total_pages,
+                  'pageSize' => :@page_size,
+                  'totalCount' => :@item_total }
+      paged_response.each { |k, v| instance_variable_set(var_map[k.to_s], v) unless var_map[k.to_s].nil? }
+      @links = paged_response['links'].map { |l| NexosisApi::Link.new(l) } unless paged_response['links'].nil?
+    end
+
+    # The current page number represented by this collection
+    # @return [int]
+    attr_accessor :page_number
+
+    # The total number of pages given the current page size and item total
+    # @return [int]
+    attr_accessor :total_pages
+
+    # The total number of items per page
+    # @return [int]
+    attr_accessor :page_size
+
+    # The total number of items available on the server for this collection
+    # @return [int]
+    attr_accessor :item_total
+
+    # paging links to first, last pages
+    # @return [Array of NexosisApi::Link]
+    attr_accessor :links
+  end
+end

data/lib/nexosis_api/session.rb

@@ -1,37 +1,41 @@
 module NexosisApi
   # Class for parsing the results of a session based request
   class Session
-    def initialize(sessionHash)
-      sessionHash.each do |k,v|
+    def initialize(session_hash)
+      val_map = { 'resultInterval' => :@result_interval,
+                  'dataSourceName' => :@datasource_name,
+                  'modelId' => :@model_id,
+                  'sessionId' => :@session_id,
+                  'availablePredictionIntervals' => :@prediction_intervals,
+                  'startDate' => :@start_date,
+                  'endDate' => :@end_date }
+      session_hash.each do |k, v|
         if (k == 'links')
-          links = Array.new
-          v.each { |l| links << NexosisApi::Link.new(l) }
-          instance_variable_set("@#{k}", links) unless v.nil?
-        elsif (k == 'isEstimate')
-          instance_variable_set('@is_estimate', v) unless v.nil?
+          @links = v.map { |l| NexosisApi::Link.new(l) }
         elsif (k == 'columns')
           @column_metadata = v.reject { |_key, value| value.nil? }
                               .map do |col_key, col_val|
                                 NexosisApi::Column.new(col_key, v[col_key])
                               end
-        elsif (k == 'resultInterval')
-          @result_interval = v
-        elsif (k == 'dataSourceName')
-          @datasource_name = v
-        elsif (k == 'modelId')
-          @model_id = v
         elsif (k == 'requestedDate')
           @requested_date = DateTime.parse(v)
         else
           instance_variable_set("@#{k}", v) unless v.nil?
         end
+        instance_variable_set(val_map[k], v) unless val_map[k].nil?
       end
     end
 
     # identifier for this sesssion
     # @return [String]
+    # @deprecated use session_id instead
     attr_accessor :sessionId
 
+    # identifier for this sesssion
+    # @return [String]
+    # @since 1.4.0
+    attr_accessor :session_id
+
     # What type of analysis was run during this session
     # @return [String]
     attr_accessor :type
@@ -59,12 +63,24 @@ module NexosisApi
 
     # The start date of analysis in this session
     # @return [DateTime]
+    # @deprecated use start_date instead
     attr_accessor :startDate
 
     # The end date of analysis in this session
     # @return [DateTime]
+    # @deprecated use end_date instead
     attr_accessor :endDate
 
+    # The start date of analysis in this session
+    # @return [DateTime]
+    # @since 1.4.0
+    attr_accessor :start_date
+    
+    # The end date of analysis in this session
+    # @return [DateTime]
+    # @since 1.4.0
+    attr_accessor :end_date
+    
     # associated hypermedia
     # @return [Array of NexosisApi::Link]
     attr_accessor :links
@@ -96,7 +112,14 @@ module NexosisApi
     # @since 1.3.0
     # @note This is always empty in time-series sessions (forecast/impact)
     # The model id returned here should be used in all future calls
-    # to model endpoints - primarily the /models/{modelId}/predict endpoint.
+    # to model endpoints - primarily the /models/{model_id}/predict endpoint.
     attr_accessor :model_id
+
+    # An array of the prediction intervals available for this session's results
+    # @return [Array]
+    # @note - by default the .5 interval will be returned in results. Consult
+    #    this list for other intervals which can be requested.
+    # @since 1.4.0
+    attr_accessor :prediction_intervals
   end
 end

data/lib/nexosis_api/view_definition.rb

@@ -44,6 +44,7 @@ module NexosisApi
     # @since 1.3.0
     alias_method :timeseries?, :is_timeseries
 
+    # Provides a custom hash which matches json of api request
     def to_json
       hash = {}
       hash['dataSetName'] = dataset_name

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.3.0'
+  spec.version = '1.4.0'
   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.3.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Nexosis,Inc
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-10-06 00:00:00.000000000 Z
+date: 2017-11-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -71,6 +71,7 @@ files:
 - lib/nexosis_api/link.rb
 - lib/nexosis_api/metric.rb
 - lib/nexosis_api/model_summary.rb
+- lib/nexosis_api/paged_array.rb
 - lib/nexosis_api/predict_response.rb
 - lib/nexosis_api/session.rb
 - lib/nexosis_api/session_response.rb