nexosis_api 2.3.0 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 68de69240c73f21137b109d7b15c8e7cf1da75b2
-  data.tar.gz: 4a293eef3fb48705ab8de41588429eebcf94448c
+SHA256:
+  metadata.gz: b203efa8f3451eb665f2f55c6e608305d4f4b0f8173289eca997fbea0ce6b569
+  data.tar.gz: 5c154fb6ec0124f977959279fc520855c4427adeadc24acc7e7eb82b27cbfc67
 SHA512:
-  metadata.gz: 0df0c54a56b46490157727a763a76142863f93c53cb46e2ab7c873c76a2b5a2933d8a1e04f7532a9cfb25c2958c02d7c8c25ce6a7e621102ec9685a11d2ab798
-  data.tar.gz: 68eecf2f181e40fb7cb6683ac1e2af3d736e270a5da4bc1c59c90f590700368da17d691d6a67cd382d7e0c0295aa91cbb3da85c0b5d3b20e853dcf30b58a5def
+  metadata.gz: 53eaabf7b732f7122e064203fed2f3d80fa6ebad81da13d2dc36ca05531558ba909a8de5ac3a0664f7065841899358609950a34fcb30bb9b3ef67392548c11f2
+  data.tar.gz: bf05c4eaebb1ead6cf124c3546636af8e08f9163fcb92de05c8fde5db87e52209e66325fd68f9790492dcdaea5112baea5ad7bc8c2bcda00b3fc541dbda4d948

data/lib/nexosis_api/anomaly_distances.rb

@@ -0,0 +1,16 @@
+require 'nexosis_api/session_response'
+module NexosisApi
+  # class to hold parsed results of distance metric request
+  # @since 2.4.0
+  class AnomalyDistances < SessionResponse
+    def initialize(distance_data)
+      data = distance_data.fetch(:data) { |k| distance_data.fetch(k.to_s) }
+      @data = NexosisApi::PagedArray.new(distance_data, data.map { |v| NexosisApi::DistanceMetric.new(v) })
+      super(distance_data.reject { |k, _v| k.to_s.casecmp('data').zero? })
+    end
+
+    # array of metrics providing the distance along with standard anomaly result
+    # @return [NexosisApi::PagedArray NexosisApi::DistanceMetric] - each anomaly score, distance, and the row values
+    attr_reader :data
+  end
+end

data/lib/nexosis_api/client.rb

@@ -1,5 +1,6 @@
 require 'nexosis_api/algorithm_contestant'
 require 'nexosis_api/algorithm'
+require 'nexosis_api/anomaly_distances'
 require 'nexosis_api/anomaly_scores'
 require 'nexosis_api/calendar_jointarget'
 require 'nexosis_api/classifier_result'
@@ -12,6 +13,8 @@ require 'nexosis_api/dataset_data'
 require 'nexosis_api/dataset_jointarget'
 require 'nexosis_api/dataset_model'
 require 'nexosis_api/dataset_summary'
+require 'nexosis_api/distance_metric'
+require 'nexosis_api/feature_importance'
 require 'nexosis_api/http_exception'
 require 'nexosis_api/impact_metric'
 require 'nexosis_api/imports_response'
@@ -20,6 +23,7 @@ require 'nexosis_api/link'
 require 'nexosis_api/message'
 require 'nexosis_api/metric'
 require 'nexosis_api/model_summary'
+require 'nexosis_api/outlier'
 require 'nexosis_api/paged_array'
 require 'nexosis_api/predict_response'
 require 'nexosis_api/session_contest'
@@ -28,6 +32,7 @@ require 'nexosis_api/session_result'
 require 'nexosis_api/session_selection_metrics'
 require 'nexosis_api/session'
 require 'nexosis_api/time_interval'
+require 'nexosis_api/timeseries_outliers'
 require 'nexosis_api/view_definition'
 require 'nexosis_api/view_data'
 require 'nexosis_api/vocabulary_summary'

data/lib/nexosis_api/client/sessions.rb

@@ -115,7 +115,7 @@ module NexosisApi
       #
       # @param session_id [String] the Guid string returned in a previous session request
       # @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
+      # @param page_size [Integer] optionally provide a page size to limit the total number of results. Defaults to 50, max 1000
       # @param options [Hash] as_csv [Boolean] to indicate whether results should be returned in csv format; prediction_interval [Float] one of the available prediction intervals for the session.
       # @return [NexosisApi::SessionResult] SessionResult if parsed, String of csv data otherwise
       # @raise [NexosisApi::HttpException]
@@ -246,14 +246,16 @@ module NexosisApi
 
       # Get the observation class score for a completed classification session
       # @param session_id [String] The unique id of the completed classification session
+      # @param page_number [Integer] zero-based page number of results to retrieve
+      # @param page_size [Integer] Count of results to retrieve in each page (max 1000).
       # @return [NexosisApi::ScoreResult] A session result with a list of each observation and score per column.
       # @raise [NexosisApi::HttpException]
       # @since 2.1.0
       # @note - This endpoint returns a 404 for requests of non-classification sessions
-      def get_class_scores(session_id, page = 0, page_size = 50)
+      def get_class_scores(session_id, page_number = 0, page_size = 50)
         score_url = "/sessions/#{session_id}/results/classScores"
         query = {
-          page: page,
+          page: page_number,
           pageSize: page_size
         }
         response = self.class.get(score_url, headers: @headers, query: query)
@@ -261,6 +263,56 @@ module NexosisApi
         NexosisApi::ClassifierScores.new(response.parsed_response.merge(response.headers))
       end
 
+      # Get a feature importance score for each column in the data source used in a session
+      # @param session_id [String] The unique id of the completed session
+      # @param page_number [Integer] zero-based page number of results to retrieve
+      # @param page_size [Integer] Count of results to retrieve in each page (max 1000).
+      # @return [NexosisApi::FeatureImportance]
+      # @since 2.4.0
+      # @note The score returned here is calculated before algorithm selection and so is not algorithm specific. For algorithms 
+      # that can return internal scores you need to use the champion endpoints.
+      # @note Those sessions which will provide scores have the supports_feature_importance attribute set True. Others will 404 at this endpoint.
+      def get_feature_importance(session_id, page_number = 0, page_size = 50)
+        importance_url = "/sessions/#{session_id}/results/featureimportance"
+        query = {
+          page: page_number,
+          pageSize: page_size
+        }
+        response = self.class.get(importance_url, headers: @headers, query: query)
+        raise HttpException.new("There was a problem getting the feature importance scores for session #{session_id}", 'getting feature importance', response) unless response.success?
+        NexosisApi::FeatureImportance.new(response.parsed_response.merge(response.headers))
+      end
+
+      # Get per result distance metric for anomaly detection sessions.
+      # @param session_id [String] The unique id of the completed session
+      # @param page_number [Integer] zero-based page number of results to retrieve
+      # @param page_size [Integer] Count of results to retrieve in each page (max 1000).
+      # @return [NexosisApi::AnomalyDistances]
+      # @since 2.4.0
+      # @note This method will return 404 when the session for the given session id does not have a prediction domain of 'anomalies'
+      # @see https://en.wikipedia.org/wiki/Mahalanobis_distance
+      def get_distance_metrics(session_id, page_number = 0, page_size = 50)
+        distance_url = "/sessions/#{session_id}/results/mahalanobisdistances"
+        query = {
+          page: page_number,
+          pageSize: page_size
+        }
+        response = self.class.get(distance_url, headers: @headers, query: query)
+        raise HttpException.new("There was a problem getting the distance metrics for session #{session_id}", 'getting distance metrics', response) unless response.success?
+        NexosisApi::AnomalyDistances.new(response.parsed_response.merge(response.headers))
+      end
+
+      def get_timeseries_outliers(session_id, page_number = 0, page_size = 50)
+        outlier_url = "/sessions/#{session_id}/results/outliers"
+        query = {
+          page: page_number,
+          pageSize: page_size
+        }
+        response = self.class.get(outlier_url, headers: @headers, query: query)
+        raise HttpException.new("There was a problem getting the outliers for session #{session_id}", 'getting outliers', response) unless response.success?
+        NexosisApi::TimeseriesOutliers.new(response.parsed_response.merge(response.headers))
+      end
+
       private
 
       # @private

data/lib/nexosis_api/distance_metric.rb

@@ -0,0 +1,24 @@
+module NexosisApi
+  # Class to hold the parse results of each 'row' in distance metric response
+  # @since 2.4.0
+  class DistanceMetric
+    def initialize(metric_hash)
+      failover = ->(k) { metric_hash.fetch(k.to_s) }
+      @anomaly_score = metric_hash.fetch(:anomaly, &failover).to_f
+      @distance = metric_hash.fetch(:mahalanobis_distance, &failover).to_f
+      @data = metric_hash.reject { |k, _v| (k.to_s.casecmp('mahalanobis_distance').zero?) || (k.to_s.casecmp('anomaly').zero?) }
+    end
+
+    # The anomaly score determining if this entry is an anomaly
+    # @return [Float]
+    attr_reader :anomaly_score
+
+    # The calculated distance for this row of values
+    # @return [Float]
+    attr_reader :distance
+
+    # The set of values in this row
+    # @return [Hash]
+    attr_reader :data
+  end
+end

data/lib/nexosis_api/feature_importance.rb

@@ -0,0 +1,12 @@
+module NexosisApi
+  # Class to hold the parse results of a request for Feature Importance scores
+  # @since 2.4.0
+  class FeatureImportance < SessionResponse
+    def initialize(session_hash)
+      @scores = session_hash.fetch(:featureImportance) { |k| session_hash.fetch(k.to_s) }
+      super(session_hash.reject { |k, _v| k.to_s.casecmp('featureimportance').zero? })
+    end
+
+    attr_reader :scores
+  end
+end

data/lib/nexosis_api/outlier.rb

@@ -0,0 +1,28 @@
+module NexosisApi
+  # Class to hold the parse results of an individual outlier for time-series
+  # @note When Nexosis runs a time-series forecast, a smoothed dataset is created in addition
+  # to the original. These outlier values represent those which were modified in that smoothed
+  # dataset.
+  # @since 2.4.0
+  class Outlier
+    def initialize(outlier_hash)
+      match_smooth = ->(k, _v) { !k.match(/:smooth/).nil? }
+      match_actual = ->(k, _v) { !k.match(/:actual/).nil? }
+      @timestamp = DateTime.parse(outlier_hash.fetch(:timeStamp) { |k| outlier_hash.fetch(k.to_s) })
+      @smoothed = outlier_hash.select(&match_smooth).first[1].to_f if outlier_hash.any? &match_smooth
+      @actual = outlier_hash.select(&match_actual).first[1].to_f if outlier_hash.any? &match_actual
+    end
+
+    # Record timestamp for the given target values
+    # @return [DateTime]
+    attr_reader :timestamp
+
+    # The original value for this target
+    # @return [Float]
+    attr_reader :actual
+
+    # The smoothed target used in the smoothed data set
+    # @return [Float]
+    attr_reader :smoothed
+  end
+end

data/lib/nexosis_api/session.rb

@@ -12,7 +12,8 @@ module NexosisApi
                   'predictionDomain' => :@prediction_domain,
                   'extraParameters' => :@extra_parameters,
                   'targetColumn' => :@target_column,
-                  'statusHistory' => :@status_history }
+                  'statusHistory' => :@status_history,
+                  'supportsFeatureImportance' => :@supports_feature_importance}
       session_hash.each do |k, v|
         if (k == 'links')
           @links = v.map { |l| NexosisApi::Link.new(l) }
@@ -118,5 +119,10 @@ module NexosisApi
     # A list of warning or error messages optionally returned from session
     # @return [Array of Message]
     attr_accessor :messages
+
+    # Identifies if this session will provide feature importance scores when completed
+    # @return [Boolean]
+    # @since 2.4.0
+    attr_reader :supports_feature_importance
   end
 end

data/lib/nexosis_api/timeseries_outliers.rb

@@ -0,0 +1,18 @@
+module NexosisApi
+  # Class to hold the parse results of an outlier response
+  # @note When Nexosis runs a time-series forecast, a smoothed dataset is created in addition
+  # to the original. These outlier values represent those which were modified in that smoothed
+  # dataset.
+  # @since 2.4.0
+  class TimeseriesOutliers < SessionResponse
+    def initialize(outlier_hash)
+      data = outlier_hash.fetch(:data) { |k| outlier_hash.fetch(k.to_s) }
+      @data = NexosisApi::PagedArray.new(outlier_hash, data.map { |v| NexosisApi::Outlier.new(v) })
+      super(outlier_hash.reject { |k, _v| k.to_s.casecmp('data').zero? })
+    end
+
+    # The set of outlier values found in the given sessions dataset
+    # @return [NexosisApi::PagedArray NexosisApi::Outlier]
+    attr_reader :data
+  end
+end

data/lib/nexosis_api/vocabulary_summary.rb

@@ -34,7 +34,7 @@ module NexosisApi
     attr_reader :created_on
 
     # The unique id of the session for which this vocabulary was built.
-    # @reutn [String]
+    # @return [String]
     attr_reader :created_by_session
 
     # hypermedia related to this vocabulary

data/nexosisapi.gemspec

@@ -14,8 +14,8 @@ Gem::Specification.new do |spec|
   spec.licenses = ['Apache-2.0']
   spec.name = 'nexosis_api'
   spec.require_paths = ['lib']
-  spec.required_ruby_version = '>= 2.0.0'
+  spec.required_ruby_version = '>= 2.3.0'
   spec.summary = "Ruby client for working with the Nexosis API"
-  spec.version = '2.3.0'
+  spec.version = '2.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: 2.3.0
+  version: 2.4.0
 platform: ruby
 authors:
 - Nexosis,Inc
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-04-04 00:00:00.000000000 Z
+date: 2018-04-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -48,6 +48,7 @@ files:
 - lib/nexosis_api.rb
 - lib/nexosis_api/algorithm.rb
 - lib/nexosis_api/algorithm_contestant.rb
+- lib/nexosis_api/anomaly_distances.rb
 - lib/nexosis_api/anomaly_scores.rb
 - lib/nexosis_api/calendar_jointarget.rb
 - lib/nexosis_api/classifier_result.rb
@@ -68,6 +69,8 @@ files:
 - lib/nexosis_api/dataset_jointarget.rb
 - lib/nexosis_api/dataset_model.rb
 - lib/nexosis_api/dataset_summary.rb
+- lib/nexosis_api/distance_metric.rb
+- lib/nexosis_api/feature_importance.rb
 - lib/nexosis_api/http_exception.rb
 - lib/nexosis_api/impact_metric.rb
 - lib/nexosis_api/imports_response.rb
@@ -76,6 +79,7 @@ files:
 - lib/nexosis_api/message.rb
 - lib/nexosis_api/metric.rb
 - lib/nexosis_api/model_summary.rb
+- lib/nexosis_api/outlier.rb
 - lib/nexosis_api/paged_array.rb
 - lib/nexosis_api/predict_response.rb
 - lib/nexosis_api/session.rb
@@ -84,6 +88,7 @@ files:
 - lib/nexosis_api/session_result.rb
 - lib/nexosis_api/session_selection_metrics.rb
 - lib/nexosis_api/time_interval.rb
+- lib/nexosis_api/timeseries_outliers.rb
 - lib/nexosis_api/view_data.rb
 - lib/nexosis_api/view_definition.rb
 - lib/nexosis_api/vocabulary_summary.rb
@@ -102,7 +107,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.0.0
+      version: 2.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -110,7 +115,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.11
+rubygems_version: 2.7.6
 signing_key: 
 specification_version: 4
 summary: Ruby client for working with the Nexosis API