veritable 0.1.0.79 → 0.1.0.80

data/lib/veritable/connection.rb

@@ -2,14 +2,21 @@ require 'veritable/object'
 require 'multi_json'
 
 module Veritable
+
+  # Encapsulates the HTTP logic for connecting to the Veritable API
+  #
+  # Users should not include this module.
   module Connection
     include VeritableObject
+
+    # Initalizes a new connection
     def initialize(opts=nil, doc=nil)
       super(opts, doc)
       require_opts :api_key, :api_base_url
       default_opts(:ssl_verify => true, :enable_gzip => true)
     end
 
+    # Wraps the HTTP GET logic
     def get(url, params=nil, headers={})
       if params and params.count > 0
         query_string = Util.query_params(params)
@@ -18,18 +25,23 @@ module Veritable
       request(:get, url, nil, headers)
     end
 
+    # Wraps the HTTP POST logic
     def post(url, payload, headers={})
       payload = MultiJson.encode(payload)
       headers = headers.merge({:content_type => 'application/json'})
       request(:post, url, payload, headers)
     end
 
+    # Wraps the HTTP PUT logic
     def put(url, payload, headers={})
       payload = MultiJson.encode(payload)
       headers = headers.merge({:content_type => 'application/json'})
       request(:put, url, payload, headers)
     end
 
+    # Wraps the HTTP DELETE logic
+    #
+    # Silently allows DELETE of nonexistent resources
     def delete(url, headers={})
       begin
         request(:delete, url, nil, headers)
@@ -40,6 +52,7 @@ module Veritable
       end
     end
 
+    # Wraps the core HTTP request logic
     def request(verb, url, payload=nil, headers={})
       url = api_base_url + "/" + url
 
@@ -75,9 +88,16 @@ module Veritable
 
     private
 
+    # Private accessor for API key
     def api_key; @opts[:api_key]; end
+
+    # Private accessor for API base URL
     def api_base_url; @opts[:api_base_url]; end
+
+    # Private accessor for API :ssl_verify option
     def ssl_verify; @opts[:ssl_verify]; end
+
+    # Private accessor for API :enable_gzip option
     def enable_gzip; @opts[:enable_gzip]; end
 
   end

data/lib/veritable/cursor.rb

@@ -2,9 +2,19 @@ require 'veritable/object'
 require 'veritable/resource'
 
 module Veritable
+
+  # Generic Cursor class for collections of API resources
+  #
+  # Cursors may be initialized with 'limit', 'start', and 'per_page' options.
+  #
+  # Users should call the #each and #next methods for access to the underlying resources.
   class Cursor
     include VeritableResource
     include Enumerable
+
+    # Initializes a new Veritable::Cursor from an API collection
+    #
+    # Optionally pass a block in for postprocessing of resources.
     def initialize(opts=nil, doc=nil, &lazymap)
       super(opts, doc)
 
@@ -17,6 +27,7 @@ module Veritable
       @opts['lazymap'] = lazymap if lazymap
     end
 
+    # Implements the Enumerable interface
     def each
       i = limit if limit
       loop do
@@ -35,11 +46,16 @@ module Veritable
         end
       end
     end
+
+    # String representation of the Cursor
     def inspect; to_s; end
+
+    # String representation of the Cursor
     def to_s; "#<Veritable::Cursor collection='" + collection + "'>"; end
 
     private
 
+    # Private method to refresh the cursor from the server
     def refresh
       return data.length if data.length > 0
       if next_page
@@ -52,15 +68,34 @@ module Veritable
       return data.length
     end
 
+    # Private accessor for the limit option
     def limit; @opts['limit']; end
+
+    # Private setter for the limit option
     def limit=(x); @opts['limit'] = x; end
+
+    # Private accessor for the start option
     def start; @opts['start']; end
+
+    # Private accessor for the per_page option
     def per_page; @opts['per_page']; end
+
+    # Privatre accessor for the collection
     def collection; @opts['collection'] end
+
+    # Postprocessing block, if any
     def lazymap; @opts['lazymap']; end
+
+    # Key for the underlying data
     def key; @opts['key'] end
+
+    # Link to the next page of the collection
     def next_page; link 'next' end
+
+    # True if the Cursor is on the last page of the collection
     def last_page?; ! @doc.has_key? 'next' end
+
+    # Fetches the underlying data
     def data; @doc[key] end
   end
 end

data/lib/veritable/datatypes.rb

@@ -1,3 +1,4 @@
 module Veritable
+  # Acceptable datatypes
   DATATYPES = ['boolean', 'categorical', 'real', 'count']
 end

data/lib/veritable/errors.rb

@@ -1,17 +1,41 @@
-class VeritableError < StandardError
-  attr_reader :message
-  def initialize(message, opts=nil)
-    @message = message
-    if opts.is_a? Hash
-      @opts = opts
-      eigenclass = class << self; self; end
-      @opts.keys.each {|k|
-        eigenclass.send(:define_method, k.to_sym) {
-          @opts[k]
+module Veritable
+
+  # Class for all errors returned by veritable-ruby
+  #
+  # ==== Attributes
+  # * +message+ -- the String message describing the error
+  # * dynamically defined -- errors may have other attributes, such as +http_code+ or +row+, dynamically defined at initialization.
+  class VeritableError < StandardError
+    # Accessor for the error message
+    attr_reader :message
+
+    # Initializes a Veritable::VeritableError
+    #
+    # Users should not invoke directly.
+    #
+    # ==== Arguments
+    # +message+ -- a String message describing the error
+    # +opts+ -- a Hash optionally specifying other instance attributes to be dynamically defined
+    #
+    # 
+    # See also: https://dev.priorknowledge.com/docs/client/ruby  
+    def initialize(message, opts=nil)
+      @message = message
+      if opts.is_a? Hash
+        @opts = opts
+        eigenclass = class << self; self; end
+        @opts.keys.each {|k|
+          eigenclass.send(:define_method, k.to_sym) {
+            @opts[k]
+          }
         }
-      }
+      end
     end
+
+    # Prints the error message
+    def to_s; message; end
+
+    # Prints the error message
+    def inspect; message; end
   end
-  def to_s; message; end
-  def inspect; message; end
-end
+end

data/lib/veritable/object.rb

@@ -1,7 +1,13 @@
 require 'veritable/errors'
 
 module Veritable
+  # Abstracts the structure of veritable-ruby objects
+  #
+  # Users should not include this module.
   module VeritableObject
+    # Initializes a new object from a hash of options and an API doc
+    #
+    # Users should not invoke directly.
     def initialize(opts=nil, doc=nil)
       @opts = opts
       @doc = doc
@@ -9,10 +15,12 @@ module Veritable
 
     private
 
+    # Private method -- requires that certain options be present at initialization
     def require_opts(*keys)
       keys.each {|k| raise VeritableError.new("Error initializing object -- must provide #{k}") unless @opts.has_key?(k)}
     end
 
+    # Private method -- specifies default options
     def default_opts(hash={})
       hash.each {|k, v| @opts[k] = v unless @opts.has_key?(k)}
     end

data/lib/veritable/resource.rb

@@ -2,11 +2,15 @@ require 'veritable/connection'
 require 'veritable/errors'
 
 module Veritable
+  # Abstracts the structure of Veritable API resources
+  #
+  # Users should not include this module.
   module VeritableResource
   	include Connection
 
     private
 
+    # Private method: retrieves the appropriate link field from the resource doc
     def link(name)
       @doc['links'][name]
     end

data/lib/veritable/util.rb

@@ -6,17 +6,51 @@ require 'csv'
 require 'set'
 
 module Veritable
+
+  # Encapsulates utilities for working with data
+  #
+  # ==== Methods
+  # * +read_csv+ -- reads a .csv from disk into an Array of row Hashes
+  # * +write_csv+ -- writes an Array of row Hashes to disk as .csv
+  # * +split_rows+ -- splits an Array of row Hashes into two sets
+  # * +make_schema+ -- makes a new analysis schema from a schema rule
+  # * +validate_data+ -- validates an Array of row Hashes against a schema
+  # * +clean_data+ -- cleans an Array of row Hashes to conform to a schema
+  # * +validate_predictions+ -- validates a single predictions request Hash against a schema
+  # * +clean_predictions+ -- cleans a predictions request Hash to conform to a schema
+  # * +validate_schema+ -- validates a schema
+  # * +check_id+ -- checks that a unique ID is valid
+  # * +check_row+ -- checks that a row Hash is well-formed
+  # * +check_datatype+ -- checks that a datatype is valid
+  # * +query_params+ -- helper function for HTTP form encoding
+  # * +make_table_id+ -- autogenerates a new valid ID for a table
+  # * +make_analysis_id+ -- autogenerates a new valid ID for an analysis
+  # 
+  # See also: https://dev.priorknowledge.com/docs/client/ruby  
   module Util
     class << self
+      # Autogenerate a new table ID
+      #
+      # Users should not call directly
       def make_table_id; UUID.new.generate :compact ; end
+
+      # Autogenerate a new analysis ID
+      #
+      # Users should not call directly
       def make_analysis_id; UUID.new.generate :compact ; end
 
+      # Helper function for HTTP form encoding
+      #
+      # Users should not call directly
       def query_params(params, parent=nil)
         flatten_params(params).collect {|x|
           "#{x[0]}=#{x[1]}"
         }.join("&")
       end
 
+      # Checks that a unique ID is valid
+      #
+      # Raises a VeritableError if the ID is invalid.
       def check_id(id)
         if not id.is_a? String
           begin
@@ -33,6 +67,9 @@ module Veritable
         end
       end
 
+      # Checks that a given row is well-formed
+      #
+      # Raises a VeritableError if the row Hash is not well-formed
       def check_row(row)
         if not row.is_a? Hash
           begin
@@ -53,6 +90,9 @@ module Veritable
         end
       end
 
+      # Checks tht a given datatype is valid
+      #
+      # Raises a VeritableError if the datatype is invalid.
       def check_datatype(datatype, msg=nil)
         if not DATATYPES.include? datatype
           begin
@@ -65,6 +105,16 @@ module Veritable
         end
       end
 
+      # Splits an array of row Hashes into two sets
+      #
+      # ==== Arguments
+      # * +rows+ -- an Array of valid row Hashes
+      # * +frac+ -- the fraction of the rows to include in the first set
+      #
+      # ==== Returns
+      # An array <tt>[train_dataset, test_dataset]</tt>, each of whose members is an Array of row Hashes.
+      # 
+      # See also: https://dev.priorknowledge.com/docs/client/ruby  
       def split_rows(rows, frac)
         rows = rows.to_a
         n = rows.size
@@ -75,32 +125,56 @@ module Veritable
         return [train_dataset, test_dataset]
       end
 
-      def validate_schema(schema)
-        schema.is_a? Veritable::Schema ? schema.validate : Veritable::Schema.new(schema).validate
-      end
+      # Validates a schema
+      #
+      # Checks that a Veritable::Schema or Hash of the appropriate form is well-formed.
+      def validate_schema(schema); schema.is_a? Veritable::Schema ? schema.validate : Veritable::Schema.new(schema).validate; end
 
+      # Makes a new analysis schema from a schema rule
+      #
+      # ==== Arguments
+      # * +schema_rule+ -- a Hash or Array of two-valued Arrays, whose keys or first values should be regexes to match against column names, and whose values should be the appropriate datatype to assign to matching columns, for instance:
+      #    [['a_regex_to_match', {'type' => 'continuous'}], ['another_regex', {'type' => 'count'}], ...]
+      # * +opts+ -- a Hash which must contain either:
+      #   - the key <tt>'headers'</tt>, whose value should be an Array of column names from which to construct the schema
+      #   - or the key <tt>'rows'</tt>, whose value should be an Array of row Hashes from whose columns the schema is to be constructed
+      #
+      # ==== Returns
+      # A new Veritable::Schema
+      #
+      # See also: https://dev.priorknowledge.com/docs/client/ruby  
       def make_schema(schema_rule, opts={})
-		if ((not opts.has_key?('headers')) and (not opts.has_key?('rows')))
-			raise VeritableError.new("Either :headers or :rows must be provided!")
-		end
-		headers = opts.has_key?('headers') ? opts['headers'] : nil
-		if headers.nil?
-			headers = Set.new
-			opts['rows'].each {|row| headers.merge(row.keys)}
-			headers = headers.to_a.sort
-		end
-		schema = {}
-		headers.each do |c|
-			schema_rule.each do |r, t|
-				if r === c
-					schema[c] = t
-					break
-				end
-			end
-		end
-		return Veritable::Schema.new(schema)
+        if ((not opts.has_key?('headers')) and (not opts.has_key?('rows')))
+          raise VeritableError.new("Either 'headers' or 'rows' must be provided!")
+        end
+        headers = opts.has_key?('headers') ? opts['headers'] : nil
+        if headers.nil?
+          headers = Set.new
+          opts['rows'].each {|row| headers.merge(row.keys)}
+          headers = headers.to_a.sort
+        end
+        schema = {}
+        headers.each do |c|
+          schema_rule.each do |r, t|
+            if r === c
+              schema[c] = t
+              break
+            end
+          end
+        end
+        return Veritable::Schema.new(schema)
       end
 
+      # Writes an Array of row Hashes out to .csv
+      #
+      # ==== Arguments
+      # * +rows+ -- an Array of valid row Hashes
+      # * +filename+ -- a path to the .csv file to write out
+      #
+      # ==== Returns
+      # +nil+ on success.
+      #
+      # See also: https://dev.priorknowledge.com/docs/client/ruby  
       def write_csv(rows, filename)
         headers = Set.new
         rows.each {|row| headers.merge(row.keys)}
@@ -112,8 +186,22 @@ module Veritable
             csv << out_row
           end
         end
+        nil
       end
 
+      # Reads a .csv with headers in as an Array of row Hashes
+      #
+      # All values are kept as strings, except empty strings, which are omitted. To clean data and convert types in accordance with a given schema, use the clean_data and validate_data functions.
+      #
+      # ==== Arguments
+      # * +filename+ -- a path to the .csv file to read in from
+      # * +id_col+ -- optionally specify the column to rename to +'_id'+. If +nil+ (default) and a column named +'_id'+ is present, that column is used. If +nil+ and no +'_id'+ column is present, then +'_id'+ will be automatically generated.
+      # * +na_cols+ -- a list of string values to omit; defaults to +['']+.
+      #
+      # ==== Returns
+      # An Array of row Hashes
+      #
+      # See also: https://dev.priorknowledge.com/docs/client/ruby  
       def read_csv(filename, id_col=nil, na_vals=[''])
         rows = CSV.read(filename)
         header = rows.shift
@@ -135,7 +223,29 @@ module Veritable
         end
         return rows
       end
-      
+        
+      # Cleans up an Array of row Hashes in accordance with an analysis schema
+      #
+      # This method mutates its +rows+ argument. If clean_data raises an exception, values in some rows may be converted while others are left in their original state.
+      #
+      # ==== Arguments
+      # * +rows+ -- the Array of Hashes to clean up
+      # * +schema+ -- a Schema specifying the types of the columns appearing in the rows being cleaned
+      # * +opts+ -- a Hash optionally containing the keys:
+      #   - +convert_types+ -- controls whether clean_data will attempt to convert cells in a column to be of the correct type (default: +true+)
+      #   - +remove_nones+ -- controls whether clean_data will automatically remove cells containing the value +nil+ (default: +true+)
+      #   - +remove_invalids+ -- controls whether clean_data will automatically remove cells that are invalid for a given column (default: +true+)
+      #   - +reduce_categories+ -- controls whether clean_data will automatically reduce the number of categories in categorical columns with too many categories (default: +true+) If +true+, the largest categories in a column will be preserved, up to the allowable limit, and the other categories will be binned as <tt>"Other"</tt>.
+      #   - +assign_ids+ -- controls whether clean_data will automatically assign new ids to the rows (default: +false=) If +true+, rows will be numbered sequentially. If the rows have an existing <tt>'_id'</tt> column, +remove_extra_fields+ must also be set to +true+ to avoid raising a Veritable::VeritableError.
+      #   - +remove_extra_fields+ -- controls whether clean_data will automatically remove columns that are not contained in the schema (default: +false+) If +assign_ids+ is +true+ (default), will also remove the <tt>'_id'</tt> column.
+      #
+      # ==== Raises
+      # A Veritable::VeritableError containing further details if the data does not validate against the schema.
+      #
+      # ==== Returns
+      # +nil+ on success (mutates +rows+ argument)
+      # 
+      # See also: https://dev.priorknowledge.com/docs/client/ruby
       def clean_data(rows, schema, opts={})
         validate(rows, schema, {
           'convert_types' => opts.has_key?('convert_types') ? opts['convert_types'] : true,
@@ -150,6 +260,19 @@ module Veritable
           'allow_empty_columns' => false})
       end
 
+      # Validates an Array of row Hashes against an analysis schema
+      #
+      # ==== Arguments
+      # * +rows+ -- the Array of Hashes to clean up
+      # * +schema+ -- a Schema specifying the types of the columns appearing in the rows being cleaned
+      #
+      # ==== Raises
+      # A Veritable::VeritableError containing further details if the data does not validate against the schema.
+      #
+      # ==== Returns
+      # +nil+ on success
+      # 
+      # See also: https://dev.priorknowledge.com/docs/client/ruby
       def validate_data(rows, schema)
         validate(rows, schema, {
           'convert_types' => false,
@@ -164,6 +287,25 @@ module Veritable
           'allow_empty_columns' => false})
       end
 
+      # Cleans up a predictions request in accordance with an analysis schema
+      #
+      # This method mutates its +predictions+ argument. If clean_predictions raises an exception, values in some columns may be converted while others are left in their original state.
+      #
+      # ==== Arguments
+      # * +predictions+ -- the predictions request to clean up
+      # * +schema+ -- a Schema specifying the types of the columns appearing in the predictions request
+      # * +opts+ -- a Hash optionally containing the keys:
+      #   - +convert_types+ -- controls whether clean_data will attempt to convert cells in a column to be of the correct type (default: +true+)
+      #   - +remove_invalids+ -- controls whether clean_data will automatically remove cells that are invalid for a given column (default: +true+)
+      #   - +remove_extra_fields+ -- controls whether clean_data will automatically remove columns that are not contained in the schema (default: +true+)
+      #
+      # ==== Raises
+      # A Veritable::VeritableError containing further details if the predictions request does not validate against the schema
+      #
+      # ==== Returns
+      # +nil+ on success (mutates +predictions+ argument)
+      # 
+      # See also: https://dev.priorknowledge.com/docs/client/ruby
       def clean_predictions(predictions, schema, opts={})
         validate(predictions, schema, {
           'convert_types' => opts.has_key?('convert_types') ? opts['convert_types'] : true,
@@ -178,6 +320,19 @@ module Veritable
           'allow_empty_columns' => true})
       end
 
+      # Validates a predictions request against an analysis schema
+      #
+      # ==== Arguments
+      # * +predictions+ -- the predictions request to clean up
+      # * +schema+ -- a Schema specifying the types of the columns appearing in the predictions request
+      #
+      # ==== Raises
+      # A Veritable::VeritableError containing further details if the predictions request does not validate against the schema.
+      #
+      # ==== Returns
+      # +nil+ on success
+      # 
+      # See also: https://dev.priorknowledge.com/docs/client/ruby
       def validate_predictions(predictions, schema)
         validate(predictions, schema, {
           'convert_types' => false,
@@ -194,6 +349,7 @@ module Veritable
 
       private
 
+      # Private helper function for form encoding
       def flatten_params(params, parent=nil)
         result = []
         if params.is_a? Hash
@@ -217,16 +373,19 @@ module Veritable
         result
       end
 
-      def urlencode(k)
-        URI.escape(k.to_s, Regexp.new("[^#{URI::PATTERN::UNRESERVED}]"))
-      end
+      # Wraps URL encoding
+      def urlencode(k); URI.escape(k.to_s, Regexp.new("[^#{URI::PATTERN::UNRESERVED}]")); end
 
+      # Private helper function to convert to Integer
       def to_integer(v)
         return v if v.is_a? Fixnum
         v.gsub!(/\A([+-]?\d+?)\.0*?\Z/, '\1')
         Integer(v)
       end
-	  	  
+        
+      # Row validation logic
+      #
+      # Users should call clean_data, validate_data, clean_predictions, or validate_predictions
       def validate(rows, schema, opts)
         schema = Veritable::Schema.new(schema) unless schema.is_a? Veritable::Schema
 

data/lib/veritable/version.rb

@@ -1,3 +1,5 @@
 module Veritable
-  VERSION = "0.1.0.79"
+
+  # The current version of veritable-ruby
+  VERSION = "0.1.0.80"
 end

data/lib/veritable.rb

@@ -10,10 +10,54 @@ require 'rest_client'
 require 'uuid'
 require 'multi_json'
 
+# The main module for the Veritable client
+#
+# ==== Module methods
+# Veritable.connect is the main entry point.
+#
+# ==== Classes
+# Veritable::API represents a single user's tables and settings.
+#
+# Veritable::Table, Veritable::Analysis, and Veritable::Prediction represent API resources.
+#
+# Veritable::Schema represents schemas for Veritable analyses.
+#
+# Collections of API resources are returned as instances of Veritable::Cursor, an Enumerable.
+#
+# All errors are instances of Veritable::VeritableError.
+#
+# ==== Modules
+# The Veritable::Connection module encapsulates the HTTP logic.
+#
+# The Veritable::Util module includes some helper methods for working with datasets.
+#
+# The Veritable::VeritableResource and Veritable::VeritableObject modules are internal abstractions.
+# 
+# See also: https://dev.priorknowledge.com/docs/client/ruby
 module Veritable
+
+  # The HTTP User-Agent header used by the client library.
   USER_AGENT = 'veritable-ruby ' + VERSION
+
+  # The default base URL for the Veritable API server.
   BASE_URL = "https://api.priorknowledge.com"
   
+  # The main entry point to the Veritable API
+  #
+  # ==== Arguments
+  # * +opts+ -- a Hash containing options for the connection. Possible keys include:
+  #   - +:api_key+ -- the Veritable API key to use. If not set, defaults to <tt>ENV['VERITABLE_KEY']</tt>
+  #   - +:api_base_url+ -- the base URL of the Veritable API. If not set, defaults to <tt>ENV['VERITABLE_URL']</tt> or BASE_URL
+  #   - +:ssl_verify+ -- if +true+, the SSL certificate of the API server will be verified.
+  #   - +:enable_gzip+ -- if +true+, requests to the API server will be gzipped.
+  #
+  # ==== Raises
+  # A Veritable::VeritableError if no Veritable API server is found at the indicated URL.
+  # 
+  # ==== Returns
+  # An instance of Veritable::API.
+  #
+  # See also: https://dev.priorknowledge.com/docs/client/ruby
   def self.connect(opts={})
     opts[:api_key] = opts[:api_key] || ENV['VERITABLE_KEY']
     opts[:api_base_url] = opts[:api_base_url] || ENV['VERITABLE_URL'] || BASE_URL