nesstar-api 0.0.1 → 0.0.2

data/lib/nesstar-api.rb

@@ -14,13 +14,17 @@ require 'nesstar-api/study_date'
 require 'nesstar-api/variable'
 require 'nesstar-api/summary_stat'
 
+#Methods for retrieving Nesstar catalog hierarchy and 
+#metadata information
 module Nesstar
   module Api
     
     class CatalogApi
       
-      #given tree of datasets and catalogs figure out which are the
-      #survey types, which are surveys and link them to child datasets
+      #Given tree of datasets and catalogs, contained in a RubyTree Node object
+      #figure out which are the survey types, which are surveys and link them to child datasets
+      #This is to match the MethodBox (http://www.methodbox.org) data model, basically
+      #a dataset belongs to a survey which has a survey type.
       def parse_surveys_from_nodes node, surveys_hash, survey_types_hash
         node.children.each do |node|
           if node.name.index('fStudy')
@@ -59,6 +63,14 @@ module Nesstar
         end
       end
 
+      #Get a hash of catalogs to child catalogs and datasets from a
+      #Nesstar instance.  The children will be contained in an Array object
+      #Inputs are a url to the nesstar server eg
+      #http://nesstar.somewhere.com and a catalog id eg myCatalog
+      #If there appears to be no parent catalog for something then
+      #the key will be listed as 'none'
+      #
+      #Returns a Hash of catalogs to children
       def get_catalog url, catalog
         
         #Hash of catalogs to their child datasets
@@ -75,6 +87,11 @@ module Nesstar
         return catalog_hash
       end
       
+      #Given a Nesstar url and catalog eg
+      #http://nesstar.somewhere.com and a catalog id eg myCatalog
+      #the return a RubyTree node object containing the hierarchy.
+      #
+      #Returns a RubyTree Node
       def get_nodes url, catalog
         #tree of catalogs to their child datasets
         root_tree_node = Tree::TreeNode.new(catalog, "Catalog Content")
@@ -90,7 +107,10 @@ module Nesstar
         return root_tree_node
       end
       
-      #get the ddi xml for a nesstar dataset
+      #Get the ddi xml for a nesstar dataset given a Nesstar url and catalog eg
+      #http://nesstar.somewhere.com and a catalog id eg myCatalog
+      #
+      #returns the ddi xml raw string
       def get_ddi uri, dataset
         ddi_uri = URI.parse(uri)
         ddi_uri.merge!("/obj/fStudy/" + dataset)
@@ -102,11 +122,13 @@ module Nesstar
       end
       
       #return a catalog object with information inside it
-      #uri is something like http://nesstar.here.com
-      #catalog is the name of the catalog eg Catalog20
-      def get_catalog_information uri, catalog
+      #given a Nesstar url and catalog eg
+      #http://nesstar.somewhere.com and a catalog id eg myCatalog
+      #
+      #Returns a Nesstar::Catalog object
+      def get_catalog_information uri, catalog_id
         catalog_uri = URI.parse(uri)
-        catalog_uri.merge!("/obj/fCatalog/" + catalog)
+        catalog_uri.merge!("/obj/fCatalog/" + catalog_id)
         catalog_res = Net::HTTP.get(catalog_uri)
         gz = Zlib::GzipReader.new(StringIO.new(catalog_res))
         catalog_info = gz.read
@@ -114,15 +136,21 @@ module Nesstar
         label = doc.xpath('//s:label')
         description = doc.xpath('//s:comment')
         catalog = Nesstar::Catalog.new
+        catalog.nesstar_id = catalog_id
+        catalog.nesstar_uri = uri
         catalog.label = label[0].content.strip unless label[0] == nil
         catalog.description = description[0].content.strip unless description[0] == nil
         return catalog
       end
       
-      #information about the dataset only
-      def get_simple_study_information uri, dataset
+      #Get basic information about the dataset only given a Nesstar url and catalog eg
+      #http://nesstar.somewhere.com and a catalog id eg myCatalog
+      #No information about the variables a study (ie dataset) contains are returned
+      #
+      #Returns a Nesstar::Study object
+      def get_simple_study_information uri, dataset_id
         dataset_uri = URI.parse(uri)
-        dataset_uri.merge!("/obj/fStudy/" + dataset)
+        dataset_uri.merge!("/obj/fStudy/" + dataset_id)
         dataset_res = Net::HTTP.get(dataset_uri)
         gz = Zlib::GzipReader.new(StringIO.new(dataset_res))
         dataset_info = gz.read
@@ -130,23 +158,31 @@ module Nesstar
         label = doc.xpath('//s:label')
         description = doc.xpath('//s:comment')
         study = Nesstar::Study.new
+        study.nesstar_id = dataset_id
+        study.nesstar_uri = uri
         study.title = label[0].content.strip unless label[0] == nil
         study.abstract = description[0].content.strip unless description[0] == nil
         return study
       end
       
       #information about the dataset and its variables
-      #inputs are the uri to a dataset file
-      def get_study_information uri, dataset
+      #given a Nesstar url and catalog eg
+      #http://nesstar.somewhere.com and a catalog id eg myCatalog
+      #The study will contain variable level information if available
+      #
+      #Returns a Nesstar::Study object
+      def get_study_information uri, dataset_id
         #TODO use the get_ddi method above
         ddi_uri = URI.parse(uri)
-        ddi_uri.merge!("/obj/fStudy/" + dataset)
+        ddi_uri.merge!("/obj/fStudy/" + dataset_id)
         ddi_uri.merge!('?http://www.nesstar.org/rdf/method=http://www.nesstar.org/rdf/Dataset/GetDDI')
         res = Net::HTTP.get(ddi_uri)
         gz = Zlib::GzipReader.new(StringIO.new(res))
         xml = gz.read
         catalog = Nesstar::Catalog.new
         study = Nesstar::Study.new
+        study.nesstar_id = dataset_id
+        study.nesstar_uri = uri
         study_info_hash = Hash.new
         parser = LibXML::XML::Parser.string(xml)
         doc = parser.parse
@@ -308,10 +344,17 @@ module Nesstar
           #categories in ddi are value domains in mb
           catgry.each do |cat|
             category = Nesstar::Category.new
-            category.value = cat.find('./catValu').first.content
+            valxml = cat.find('./catValu')
+            if valxml != nil && valxml[0] != nil
+              category.value = valxml[0].first.content.strip unless valxml[0].first == nil
+            else
+              category.value = 'N/A'
+            end
             labxml = cat.find('./labl')
             if labxml != nil && labxml[0] != nil
               category.label = labxml[0].first.content.strip unless labxml[0].first == nil
+            else
+              category.label = 'N/A'
             end
             catstat = cat.find('./catStat')
             category_statistics = []
@@ -321,12 +364,11 @@ module Nesstar
               if a != nil
                 category_statistic.type = a.get_attribute('type').strip unless a.get_attribute('type') == nil
                 category_statistic.value = catstat.first.content.strip unless catstat.first == nil
-                category_statistic.type = a.get_attribute('type').strip unless a.get_attribute('type') == nil
                 category_statistics.push(category_statistic)
               end
             end
             category.category_statistics = category_statistics
-            categories.push(category_statistics)
+            categories.push(category)
           end
           #what group is the variable in
           variable_info_hash.each_key do |key|

data/lib/nesstar-api/catalog.rb

@@ -1,9 +1,9 @@
 module Nesstar
-  
+  #A Nesstar catalog object, can contain 1 or more studies (ie datasets)
   class Catalog
   
-    attr_reader :studies, :label, :description
-    attr_writer :studies, :label, :description
+    attr_reader :studies, :label, :description, :nesstar_id, :nesstar_uri
+    attr_writer :studies, :label, :description, :nesstar_id, :nesstar_uri
   
   end
   

data/lib/nesstar-api/category_statistic.rb

@@ -1,6 +1,6 @@
 module Nesstar
   
-  #Stats about a category belonging to a a variable
+  #Stats about a category (ie value domain) belonging to a a variable
   class CategoryStatistic
   
     attr_reader :type, :value

data/lib/nesstar-api/study.rb

@@ -3,8 +3,8 @@ module Nesstar
   #Contains a set of variables and belongs to a catalog
   class Study
   
-    attr_reader :variables, :abstract, :title, :id, :dates, :sampling_procedure, :weight
-    attr_writer :variables, :abstract, :title, :id, :dates, :sampling_procedure, :weight
+    attr_reader :variables, :abstract, :title, :id, :dates, :sampling_procedure, :weight, :nesstar_id, :nesstar_uri
+    attr_writer :variables, :abstract, :title, :id, :dates, :sampling_procedure, :weight, :nesstar_id, :nesstar_uri
   
   end
   

data/lib/nesstar-api/summary_stat.rb

@@ -1,5 +1,6 @@
 module Nesstar
   
+  #Stats at the variable level, eg how many valid or invalid rows
   class SummaryStat
   
     attr_reader :type, :value

data/lib/nesstar-api/version.rb

@@ -1,5 +1,5 @@
 module Nesstar
   module Api
-    VERSION = "0.0.1"
+    VERSION = "0.0.2"
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: nesstar-api
 version: !ruby/object:Gem::Version 
-  hash: 29
+  hash: 27
   prerelease: false
   segments: 
   - 0
   - 0
-  - 1
-  version: 0.0.1
+  - 2
+  version: 0.0.2
 platform: ruby
 authors: 
 - Ian Dunlop
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-02-24 00:00:00 +00:00
+date: 2011-03-09 00:00:00 +00:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency