nexosis_api 1.1.2 → 1.2.0

data/lib/nexosis_api/client/views.rb

@@ -0,0 +1,109 @@
+module NexosisApi
+  # class to operate on views endpoint in Nexosis API
+  class Client
+    # Views-based API operations
+    # @see http://docs.nexosis.com/
+    # @since v1.2
+    module Views
+      ## List all existing view defintions, optionally limited by
+      # partial name or participating data sources
+      # @param partial_name [String] optionally limit results by view name
+      # @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]
+      # @raise [NexosisApi::HttpException]
+      def list_views(partial_name = '', dataset_name = '', page = 0, page_size = 50)
+        url = '/views'
+        query = {
+          'page': page,
+          'pageSize': page_size
+        }
+        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?
+          items = []
+          response.parsed_response['items'].each do |definition|
+            items << NexosisApi::ViewDefinition.new(definition)
+          end
+          items
+        end
+      end
+
+      # Create a new view or update an existing one by name
+      # @param view_name [String] the name of the view to create or update.
+      # @param dataset_name [String] the unique name of a data that is one source of this view.
+      # @param right_datasource_name [String] the additional data source to join in this view.
+      # @return [NexosisApi::ViewDefinition] - definition as created by API
+      # @note @view_name Must be unique within your organization
+      # @raise [NexosisApi::HttpException]
+      def create_view(view_name, dataset_name, right_datasource_name)
+        raise ArgumentError 'view_name was not provided and is not optional' unless view_name.to_s.empty? == false
+        raise ArgumentError 'dataset_name was not provided and is not optional' unless dataset_name.to_s.empty? == false
+        raise ArgumentError 'right_datasource_name was not provided and is not optional' unless right_datasource_name.to_s.empty? == false
+        view_definition = NexosisApi::ViewDefinition.new('viewName' => view_name)
+        view_definition.dataset_name = dataset_name
+        join = NexosisApi::Join.new('dataSet' => { 'name' => right_datasource_name })
+        view_definition.joins = [join]
+        create_view_by_def(view_definition)
+      end
+
+      # Create or update a view based on a view definition object
+      # @param view_definition [NexosisApi::ViewDefinition] an object populated with the view configuration to create
+      # @return [NexosisApi::ViewDefinition] - definition as created by API
+      # @raise [NexosisApi::HttpException]
+      def create_view_by_def(view_definition)
+        view_name = view_definition.view_name
+        raise ArgumentError 'view_name was not provided and is not optional' unless view_name.to_s.empty? == false
+        url = "/views/#{view_name}"
+        response = self.class.put(url, headers: @headers, body: view_definition.to_json)
+        if response.success?
+          return NexosisApi::ViewDefinition.new(response.parsed_response)
+        else
+          raise NexosisApi::HttpException.new('Could not create the requested view',
+                                              "Attempting to create view named #{view_name}",
+                                              response)
+        end
+      end
+
+      # Deletes the named view and optionally all sessions created from it
+      # @param view_name [String] the view to remove
+      # @param cascade [String] indicate any non-nil to remove associated sessions
+      # @return [void]
+      # @raise [NexosisApi::HttpException]
+      def remove_view(view_name, cascade = nil)
+        raise ArgumentError 'view_name was not provided and is not optional' unless view_name.to_s.empty? == false
+        url = "/views/#{view_name}"
+        query = 'cascade=sessions' unless cascade.nil?
+        response = self.class.delete(url, headers: @headers, query: query)
+        unless response.success?
+          raise NexosisApi::HttpException.new('Could not delete view',
+                                              "Attempting to delete view #{view_name}",
+                                              response)
+        end
+      end
+
+      # Get the processed data from the view definition
+      #
+      # @param view_name [String] the unique name of the view for which to retrieve data
+      # @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).
+      # @param query_options [Hash] options hash for limiting and projecting returned results
+      # @note Query Options includes start_date as a DateTime or ISO 8601 compliant string,
+      #    end_date, also as a DateTime or string, and :include as an Array of strings indicating the columns to return.
+      #    The dates can be used independently and are inclusive. Lack of options returns all values within the given page.
+      # @note - the results include any transformations or imputations required to prepare the data for a session
+      # @raise [NexosisApi::HttpException]
+      def get_view(view_name, page_number = 0, page_size = 50, query_options = {})
+        raise ArgumentError 'view_name was not provided and is not optional' unless view_name.to_s.empty? == false
+        url = "/views/#{view_name}"
+        response = self.class.get(url, headers: @headers,
+                                       query: create_query(page_number, page_size, query_options),
+                                       query_string_normalizer: ->(query_map) { array_query_normalizer(query_map) } )
+        raise NexosisApi::HttpException.new('Could not retrieve data for the given view', "Requesting data for view #{view_name}", response) unless response.success?
+        NexosisApi::ViewData.new(response.parsed_response)
+      end
+    end
+  end
+end

data/lib/nexosis_api/column.rb

@@ -0,0 +1,49 @@
+module NexosisApi
+  # class to hold the parsed results of column metadata
+  class Column
+    def initialize(column_name, value_hash)
+      @name = column_name
+      @type = NexosisApi::ColumnType.const_get(value_hash['dataType'].upcase) unless value_hash['dataType'].nil?
+      @role = NexosisApi::ColumnRole.const_get(value_hash['role'].upcase) unless value_hash['role'].nil?
+      @imputation = value_hash['imputation'] unless value_hash['imputation'].nil?
+      @aggregation = value_hash['aggregation'] unless value_hash['aggregation'].nil?
+    end
+    # The column header, label, or name
+    # @return [String]
+    attr_accessor :name
+
+    # The data type of this column
+    # @note Either string, numeric, logical, or date
+    # @return [NexosisApi::ColumnType]
+    attr_accessor :type
+
+    # The role of this column
+    # @note Either none, timestamp, target, or feature
+    # @return [NexosisApi::ColumnRole]
+    attr_accessor :role
+
+    # The strategy used to imput missing values
+    # @note Either Zeroes, Mean, Median, or Mode
+    # @return [String]
+    attr_accessor :imputation
+
+    # The strategy used to aggregate data if requested prediction period is greater than observation period
+    # @note Either Sum, Mean, Median, or Mode
+    # @return [String]
+    attr_accessor :aggregation
+
+    # utility method to format a column description in the way it is expected on input
+    def to_hash
+      { name => { 'dataType' => type.to_s,
+                  'role' => role.to_s,
+                  'imputation' => imputation.to_s,
+                  'aggregation' => aggregation.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/column_options.rb

@@ -0,0 +1,33 @@
+module NexosisApi
+  # Class for holding the join options on a column in a view-based join
+  # @since v1.2
+  class ColumnOptions
+    # Create a new option for a join column.
+    # @param column_name [String] the name of the original column from the source dataset
+    # @param options_hash [Hash] additional information about how to process the column in a join
+    def initialize(column_name, options_hash)
+      @name = column_name
+      @join_interval = NexosisApi::TimeInterval.const_get(options_hash['joinInterval'].upcase) unless options_hash['joinInterval'].nil?
+      @alias = options_hash['alias']
+    end
+
+    attr_accessor :name
+
+    # Optional interval of a time series column being joined to another time series
+    # @note not valid outside of join defintion
+    # @return [NexosisApi::TimeInterval]
+    attr_accessor :join_interval
+
+    # Optional alias of the column when participating in a join
+    # @note An alias can be used to keep two same-named columns distinct
+    # or to merge two distinctly named columns. By default same-named columns
+    # on two sides of a join will be merged.
+    # @return [String]
+    attr_accessor :alias
+
+    def to_hash
+      { name => { 'join_interval' => @join_internal.to_s,
+                  'alias' => @alias.to_s } }
+    end
+  end
+end

data/lib/nexosis_api/column_role.rb

@@ -1,13 +1,16 @@
-module NexosisApi
-    # Constants for dataset column role
-    module ColumnRole
-        # No specific role, additional data which could be identified as target in a session
-        NONE = :none
-        # The timestamp column to use as the basis for a time-series session request
-        TIMESTAMP = :timestamp
-        # The target column for which to make predictions
-        TARGET = :target
-        # A feature to be included in analysis
-        FEATURE = :feature
-    end
+module NexosisApi
+  # Constants for dataset column role
+  module ColumnRole
+    # No specific role, additional data which could be identified as target in a session
+    NONE = :none
+
+    # The timestamp column to use as the basis for a time-series session request
+    TIMESTAMP = :timestamp
+
+    # The target column for which to make predictions
+    TARGET = :target
+
+    # A feature to be included in analysis
+    FEATURE = :feature
+  end
 end

data/lib/nexosis_api/column_type.rb

@@ -1,15 +1,19 @@
-module NexosisApi
-    # Constants for column data type
-    module ColumnType
-        # contains string data
-        STRING = :string
-        # contains numeric data
-        NUMERIC = :numeric
-        # contains boolean logical data (i.e. 1 and 0, true and false, etc.)
-        LOGICAL = :logical
-        # contains ISO-8601 compatible date 
-        DATE = :date
-        # Indicates a number which is not countable, or is not 'ordinal scaled' but 'ratio' or 'interval' scaled - i.e. a device measurement  
-        NUMERICMEASURE = :numericmeasure
-    end
-end
+module NexosisApi
+  # Constants for column data type
+  module ColumnType
+    # contains string data
+    STRING = :string
+
+    # contains numeric data
+    NUMERIC = :numeric
+
+    # contains boolean logical data (i.e. 1 and 0, true and false, etc.)
+    LOGICAL = :logical
+
+    # contains ISO-8601 compatible date 
+    DATE = :date
+
+    # Indicates a number which is not countable, or is not 'ordinal scaled' but 'ratio' or 'interval' scaled - i.e. a device measurement  
+    NUMERICMEASURE = :numericmeasure
+  end
+end

data/lib/nexosis_api/dataset_data.rb

@@ -1,24 +1,24 @@
-module NexosisApi
-    # class to hold the parsed results of a dataset
-    class DatasetData
-        def initialize(data_hash)
-            data_hash.each do |k,v|
-                if(k == "data")
-                    @data = v
-                elsif(k == "links")
-                    links = Array.new
-					v.each do |l| links << NexosisApi::Link.new(l) end
-					@links = links
-                end
-            end
-        end
-    
-        # Helpful links to more information about this dataset
-        # @return [Array of NexosisApi::Link]
-        attr_accessor :links
-
-        #The hash of data values from the dataset
-        # @return [Array of Hash] where each hash contains the dataset data
-        attr_accessor :data
-    end
-end
+module NexosisApi
+  # class to hold the parsed results of a dataset
+  class DatasetData
+    def initialize(data_hash)
+      data_hash.each do |k, v|
+        if (k == 'data')
+          @data = v
+        elsif (k == 'links')
+          links = Array.new
+          v.each do |l| links << NexosisApi::Link.new(l) end
+          @links = links
+        end
+      end
+    end
+
+    # Helpful links to more information about this dataset
+    # @return [Array of NexosisApi::Link]
+    attr_accessor :links
+
+    #The hash of data values from the dataset
+    # @return [Array of Hash] where each hash contains the dataset data
+    attr_accessor :data
+  end
+end

data/lib/nexosis_api/dataset_model.rb

@@ -1,26 +1,26 @@
-module NexosisApi
-    # Class to parse the model results calculated for a dataset
-    class DatasetModel
-        def initialize(dataHash)
-           dataHash.each do |k,v|
-               if k == "championContest"
-                    instance_variable_set("@#{k}", NexosisApi::AlgorithmSelection.new(v))
-               else
-                    instance_variable_set("@#{k}", v) unless v.nil?
-               end
-           end
-        end
-        
-        # The name of the dataset used in the evaluation
-        # @return [String]
-        attr_accessor :datasetName
-
-        # The column targeted for prediction
-        # @return [String] 
-        attr_accessor :targetColumn
-
-        # The details of the winning algorithm
-        # @return [NexosisApi::AlgorithmSelection]
-        attr_accessor :championContest
-    end
-end
+module NexosisApi
+  # Class to parse the model results calculated for a dataset
+  class DatasetModel
+    def initialize(data_hash)
+      data_hash.each do |k, v|
+        if k == 'championContest'
+          instance_variable_set("@#{k}", NexosisApi::AlgorithmSelection.new(v))
+        else
+          instance_variable_set("@#{k}", v) unless v.nil?
+        end
+      end
+    end
+
+    # The name of the dataset used in the evaluation
+    # @return [String]
+    attr_accessor :datasetName
+
+    # The column targeted for prediction
+    # @return [String] 
+    attr_accessor :targetColumn
+
+    # The details of the winning algorithm
+    # @return [NexosisApi::AlgorithmSelection]
+    attr_accessor :championContest
+  end
+end

data/lib/nexosis_api/dataset_summary.rb

@@ -1,27 +1,27 @@
-module NexosisApi
-    # class to hold the parsed results of a dataset
-    class DatasetSummary
-        def initialize(data_hash)
-            data_hash.each do |k,v|
-                if(k == "dataSetName")
-                    @dataset_name = 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
-                end
-            end
-        end
-    
-        # The name of the dataset uploaded and saved
-        # @return [String]
-        attr_accessor :dataset_name
-
-        # Descriptive information about the columns
-        # @return [Array of NexosisApi::DatasetColumn]
-        attr_accessor :column_metadata
-    end
-end
+module NexosisApi
+  # class to hold the parsed results of a dataset
+  class DatasetSummary
+    def initialize(data_hash)
+      data_hash.each do |k, v|
+        if(k == 'dataSetName')
+          @dataset_name = v unless v.nil?
+        elsif(k == 'columns')
+          columns = []
+          next if v.nil?
+          v.keys.each do |col_key|
+            columns << NexosisApi::Column.new(col_key, v[col_key])
+          end
+          @column_metadata = columns
+        end
+      end
+    end
+
+    # The name of the dataset uploaded and saved
+    # @return [String]
+    attr_accessor :dataset_name
+
+    # Descriptive information about the columns
+    # @return [Array of NexosisApi::Column]
+    attr_accessor :column_metadata
+  end
+end

data/lib/nexosis_api/http_exception.rb

@@ -1,25 +1,29 @@
-module NexosisApi
-  # encapsulate errors from the Nexosis API
-  class HttpException < StandardError
-      attr_reader :message,:action,:response,:request
-      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
-        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
-
-      attr_reader :code
-      attr_reader :response
-      attr_reader :request
-      attr_reader :message
-      attr_reader :type      
-  end
+module NexosisApi
+  # encapsulate errors from the Nexosis API
+  class HttpException < StandardError
+    attr_reader :message,:action,:response,:request
+    def initialize(message = "", action = nil, http_obj)
+      base_message = message
+      full_message = nil
+      if(http_obj.is_a?(Hash))
+        base_message.prepend(http_obj['message'].concat(': ')) unless http_obj['message'].nil?
+        @action = action
+      elsif(http_obj.instance_of?(HTTParty::Response))
+        full_message = http_obj.parsed_response['message']
+        full_message = full_message.concat(' || Details: ').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
+      full_message ||= base_message
+      @message = full_message
+    end
+
+    attr_reader :code
+    attr_reader :response
+    attr_reader :request
+    attr_reader :message
+    attr_reader :type
+  end
 end