nesstar_rest_api_client 0.1.0

data/README.md

@@ -0,0 +1,28 @@
+# Nesstar API for Ruby
+
+This is Nesstar REST API client written in Ruby. It represents the REST endpoints as plain old Ruby objects.
+
+## Installation
+
+```
+$ rake install
+```
+
+## Getting started
+
+Connect to a server like this:
+
+```
+server = NesstarAPI.get_server "http://my-instance-of-nesstar-rest-api.com"
+```
+
+From a server object you can list studies or load individual studies by ID:
+
+```
+studies = server.get_studies
+my_study = server.get_study "my-study-id"
+```
+
+## Documentation
+
+Run `rake docs` to build the documentation. The documentation will appear in the `docs` folder.

data/lib/nesstar-api.rb

@@ -0,0 +1,14 @@
+require 'nesstar-api/rest-client.rb'
+require 'nesstar-api/server.rb'
+
+##
+# This module is the starting point. Use this to get an instance of a server.
+module NesstarAPI
+
+  ##
+  # Gets a server identified by a URL
+  def self.get_server(url)
+    RestClient.instance.init url
+    Server.new
+  end
+end

data/lib/nesstar-api/category.rb

@@ -0,0 +1,22 @@
+require 'nesstar-api/nesstar-object.rb'
+
+##
+# A category in a variable.
+#
+# Categories have a name, a label, and a frequency
+class Category < NesstarObject
+  attr_reader :name, :label, :frequency
+
+  def initialize(data)
+    @label = data['label']
+    @value = data['value']
+    @frequency = data['frequency']
+    @missing = data['missing'] == 'true'
+  end
+
+  ##
+  # Returns true if this category is missing
+  def missing?
+    @missing
+  end
+end

data/lib/nesstar-api/nesstar-object.rb

@@ -0,0 +1,36 @@
+require 'nesstar-api/rest-client.rb'
+
+##
+# A parent class for all Nesstar objects.
+class NesstarObject
+
+  private
+
+  def load_metadata
+    path = "#{self.class.name.downcase}/#{@id}"
+    @@data ||= get_values path
+  end
+
+  def metadata
+    load_metadata
+  end
+
+  def get_values(path)
+    RestClient.instance.get_values path
+  end
+
+  def get_binary(path, &block)
+    RestClient.instance.get_binary(path, &block)
+  end
+
+  def dig(hash, *path)
+    if hash.nil?
+      nil
+    elsif path.length == 1
+      hash[path.pop.to_s]
+    elsif hash.respond_to?(:keys)
+      key = path.shift.to_s
+      dig(hash[key], *path)
+    end
+  end
+end

data/lib/nesstar-api/rest-client.rb

@@ -0,0 +1,57 @@
+require 'json'
+require 'net/http'
+require 'uri'
+require 'singleton'
+
+class RestClient
+  include Singleton
+
+  def init(url)
+    unless url =~ /\//
+      url = url + '/'
+    end
+    @@url = url
+  end
+
+  def get_values(path)
+    uri = get_uri(path)
+    response = Net::HTTP.get_response uri
+    if response.is_a? Net::HTTPServerError
+      raise ServerError, parse_server_error(response.body)
+    end
+    json = JSON.parse response.body
+
+    json['payload']
+  end
+
+  def get_binary(path)
+    uri = get_uri(path)
+    Net::HTTP.start(uri.host, uri.port) do | http |
+      response = http.get(uri.request_uri)
+      if response.is_a? Net::HTTPServerError
+        raise ServerError, parse_server_error(response.body)
+      end
+      yield(response.body)
+    end
+  end
+
+  private
+
+  def get_uri(path)
+    url = @@url + path
+    URI.parse url
+  end
+
+  def parse_server_error(error)
+    begin
+      json = JSON.parse(error)
+      error = json['error']
+      "#{error['type']}: #{error['message']}"
+    rescue JSON::ParserError
+      "Fatal: Unknown server error occurred"
+    end
+  end
+
+  class ServerError < StandardError
+  end
+end

data/lib/nesstar-api/server.rb

@@ -0,0 +1,30 @@
+require 'nesstar-api/nesstar-object.rb'
+require 'nesstar-api/study.rb'
+
+##
+# Represents the server.
+class Server < NesstarObject
+
+  ##
+  # Get a list of studies on the server.
+  def get_studies
+    json_studies = get_values "studies"
+    json_studies.collect do | study |
+      Study.new study
+    end
+  end
+
+  ##
+  # Get a particular study identified by its ID.
+  def get_study(id)
+    json = get_values "study/#{id}"
+    if json
+      study_id = dig(json, :ID)
+      name = dig(json, :stdyDscr, :citation, :titlStmt, :titl)
+      abstract = dig(json, :stdyDscr, :stdyInfo, :abstract)
+
+      Study.new({'id' => study_id, 'name' => name, 'abstract' => abstract})
+    end
+  end
+
+end

data/lib/nesstar-api/study.rb

@@ -0,0 +1,118 @@
+require 'tempfile'
+require 'nesstar-api/nesstar-object'
+require 'nesstar-api/variable'
+require 'nesstar-api/variable-group'
+require 'nesstar-api/variable-container'
+require 'nesstar-api/tabulation'
+
+## Represents a study
+class Study < NesstarObject
+  attr_reader :id, :name, :abstract
+
+  include VariableContainer
+
+  NSDSTAT = "NSDSTAT"
+  SAS = "SAS"
+  SPSS = "SPSS"
+  SPSSPORT = "SPSSPORT"
+  STATA = "STATA"
+  STATA6 = "STATA6"
+  STATA7 = "STATA7"
+
+  def initialize(data)
+    @id = data['id']
+    @name = data['name']
+    @abstract = data['abstract']
+    @last_update = data['updatedTimeStamp']
+  end
+
+  ##
+  # Returns a cross tabulation on this study
+  #
+  # The options parameter holds the following data:
+  #
+  # * +breakVars+ - A list of variable objects
+  # * +msrVar+ - The measure variable, if any
+  # * +msrType+ - A list of measure types to use. Valid types are MEAN, MEDIAN, STDDEV, MIN, MAX, SUM, COUNT, CI95MIN, CI95MAX, CI99MIN, CI99MAX, Q1, Q3, WHISKER_LO, WHISKER_HI, SUM_SQUARES, SE_MEAN
+  # * +casesubset+ - A subset expression to limit the categories to include. Documentation on expressions is found here: http://nesstar-dev.nsd.uib.no/javadoc/com.nesstar/nesstar-api/0.6.5/com/nesstar/api/subset/CaseSubset.html#compile
+  def tabulate(options)
+    path = "study/#{@id}/tabulate/"
+    query_string = prepare_query_string_for_tabulation options
+
+    if query_string.length > 0
+      path += "?" + query_string.join('&')
+    end
+
+    tabulation = get_values path
+    Tabulation.new tabulation, options
+  end
+
+  def correlate
+  end
+
+  def regress
+  end
+
+  ##
+  # Downloads the study (or parts of it) in different file formats.
+  #
+  # The file will be a zip file containing one or more files depending on the requested format.
+  #
+  # The +format+ parameter should be one of the constants in this class.
+  #
+  # To only download some variables, supply a list of the variables you wish.
+  #
+  # The download can be further refined using a case subset. See http://nesstar-dev.nsd.uib.no/javadoc/com.nesstar/nesstar-api/0.6.5/com/nesstar/api/subset/CaseSubset.html#compile for more information.
+  def download(format, variables = [], case_subset = nil)
+    path = "study/#{@id}/download"
+
+    query_string = ["format=" + format]
+    query_string += collect_list(variables, "var", :id)
+    query_string.push("caseSubset=" + case_subset) unless case_subset.nil?
+
+    path += "?" + query_string.join('&')
+
+    get_binary(path) do | data |
+      if block_given?
+        yield(data)
+      else
+        file = Tempfile.new("#{@name}.#{format}")
+        file.write(data)
+        file.close
+        return file
+      end
+    end
+  end
+
+  private
+
+  def get_variable_group_type
+    'variable-groups'
+  end
+
+  def get_rest_type
+    'study'
+  end
+
+  def prepare_query_string_for_tabulation(options)
+    query_string = []
+
+    query_string += collect_list(options['breakVars'], 'breakVar', :id)
+    query_string += collect_list(options['msrType'], 'msrType')
+    query_string.push "msrVar=#{options['msrVar'].id}" unless options['mrsVar'].nil?
+    query_string.push(options['casesubset']) unless options['casesubset'].nil?
+
+    query_string
+  end
+
+  def collect_list(list, name, attribute = nil)
+    if list.nil?
+      []
+    else
+      list.collect { | obj |
+        value = attribute.nil? ? obj : obj.send(attribute)
+        "#{name}=#{value}"
+      }
+    end
+  end
+end

data/lib/nesstar-api/tabulation.rb

@@ -0,0 +1,14 @@
+##
+# Represents a tabulation run on a +Study+.
+class Tabulation
+  attr_reader :data, :variables, :measure, :measure_types, :case_subset
+
+  def initialize(data, input)
+    @data = data['data']
+    @variables = input['breakVars']
+    @measure = input['msrVar']
+    @measure_types = input['msrType']
+    @case_subset = input['casesubset']
+  end
+
+end

data/lib/nesstar-api/variable-container.rb

@@ -0,0 +1,20 @@
+module VariableContainer
+
+  ##
+  # Gets a list of variables.
+  def get_variables
+    json_variables = get_values "#{get_rest_type}/#{@id}/variables"
+    json_variables.collect do | variable_json |
+      Variable.new variable_json
+    end
+  end
+
+  ##
+  # Gets a list of variable groups.
+  def get_variable_groups
+    json_variable_groups = get_values "#{get_rest_type}/#{@id}/#{get_variable_group_type}"
+    json_variable_groups.collect do | variable_group_json |
+      VariableGroup.new variable_group_json
+    end
+  end
+end

data/lib/nesstar-api/variable-group.rb

@@ -0,0 +1,25 @@
+require 'nesstar-api/nesstar-object.rb'
+require 'nesstar-api/variable-container.rb'
+
+##
+# Represents a group of variables in a +Study+.
+class VariableGroup < NesstarObject
+  include VariableContainer
+
+  attr_reader :id, :name
+
+  def initialize(data)
+    @id = data['id']
+    @name = data['name']
+  end
+
+  private
+
+  def get_variable_group_type
+    'child-groups'
+  end
+
+  def get_rest_type
+    'variable-group'
+  end
+end

data/lib/nesstar-api/variable.rb

@@ -0,0 +1,43 @@
+require 'nesstar-api/nesstar-object.rb'
+require 'nesstar-api/category.rb'
+
+##
+# Represents a variable in a +Study+.
+class Variable < NesstarObject
+  attr_reader :id, :name, :label
+
+  def initialize(data, eager = false)
+    @id = data['id']
+    @name = data['name']
+    @label = data['label']
+    if eager
+      load_metadata
+    end
+  end
+
+  ##
+  # Indicates whether the variable is discrete.
+  def discrete?
+    metadata['intrvl'] == 'discrete'
+  end
+
+  ##
+  # Indicates whether the variable is continuous.
+  def continuous?
+    metadata['intrvl'] == 'continuous'
+  end
+
+  ##
+  # Indicates whether this is a weight variable
+  def weighted?
+    metadata['wgt']
+  end
+
+  ##
+  # Returns a list of categories in this variable
+  def get_categories
+    metadata['catgry'].collect do | category |
+      Category.new category
+    end
+  end
+end

metadata

@@ -0,0 +1,56 @@
+--- !ruby/object:Gem::Specification
+name: nesstar_rest_api_client
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Ricco Førgaard
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-11-18 00:00:00.000000000 Z
+dependencies: []
+description: 
+email: ricco@fiskeben.dk
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/nesstar-api.rb
+- lib/nesstar-api/variable.rb
+- lib/nesstar-api/category.rb
+- lib/nesstar-api/variable-group.rb
+- lib/nesstar-api/server.rb
+- lib/nesstar-api/variable-container.rb
+- lib/nesstar-api/study.rb
+- lib/nesstar-api/tabulation.rb
+- lib/nesstar-api/rest-client.rb
+- lib/nesstar-api/nesstar-object.rb
+- LICENSE
+- README.md
+homepage: http://www.nesstar.com
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: Client for Nesstar REST API
+test_files: []