plos 0.0.2 → 0.0.3

data/README.md

@@ -18,6 +18,10 @@ Or install it yourself as:
 
 ## Usage
 
+### Searching
+
+You can perform a basic search using the ```PLOS::Client.search(query, rows, start)``` method. The second two parameters are optional. That method returns a ```PLOS::ArtcleSet``` object. ```ArticleSet``` inherits from Array and includes some meta-information about the search. The following example show the information that's available:
+
 ```ruby
 require 'plos'
 
@@ -27,8 +31,86 @@ hits.each do |hit|
   puts "#{hit.score} - #{hit.title} - #{hit.article_url}"
 end
 
-xml = hit[2].article_xml
-puts hit[2].citation
+hits.status # Return status of the query (0 is success)
+hits.time # The amount of time the query took (in ms)
+hits.num_found # Total number of results
+hits.max_score # Score of the closest matching document
+hits.start # Index of the first result
+
+xml = hits[2].article_xml
+puts hits[2].citation
+```
+
+Change the number of results starting position. The following retrieves 50 results starting at result 100:
+
+```ruby
+require 'plos'
+client = PLOS::Client.new(ENV["API_KEY"])
+hits = client.search("xenograft", 50, 100)
+```
+
+Retrieve all results (paged). The following retrieves all results 200 - 300:
+
+```ruby
+require 'plos'
+client = PLOS::Client.new(ENV["API_KEY"])
+hits = client.all(100, 200)
+```
+
+### Getting the Article Details
+
+You can get the full article from the ```ArticleRef``` in a number of ways.
+
+You can get the raw xml content using ```ArticleRef.article_content```. For example, the following returns a string:
+
+```ruby
+require 'plos'
+client = PLOS::Client.new(ENV["API_KEY"])
+hits = client.search("xenograft")
+str = hits.first.article_content
+```
+
+You may also get the parsed xml content using ```ArticleRef.article_xml```. For example, the following returns a ```Nokogiri::XML::Document```:
+
+```ruby
+require 'plos'
+client = PLOS::Client.new(ENV["API_KEY"])
+hits = client.search("xenograft")
+xml_doc = hits.first.article_xml
+```
+
+Finally you may get an ```Article``` object using ```ArticleRef.article```. For example, the following returns a ```PLOS::Article```:
+
+```ruby
+require 'plos'
+client = PLOS::Client.new(ENV["API_KEY"])
+hits = client.search("xenograft")
+article = hits.first.article
+```
+
+### Working with Articles
+
+Once you have an article, you can get a number of pieces of information from that article. The following will give you an idea of the type of information that's available:
+
+```ruby
+require 'plos'
+client = PLOS::Client.new(ENV["API_KEY"])
+hits = client.search("xenograft")
+article = hits.first.article
+
+article.article_title # The title of the article
+article.article_ids   # Returns a Hash of ids. For instance {"doi"=>"##.###/journal.pxxx.###", "publisher-id"=>"###-ABC-###"} 
+article.journal_title # The title of the journal that published the article
+article.journal_ids   # Returns a Hash of ids. Keys could include publisher-id, publisher, allenpress-id, nlm-ta, pmc, etc.
+article.issns         # Returns a Hash of ISSN numbers, keys could include ppub or epub among others.
+article.affiliations  # Returns an Array of PLOS::Affiliation objects representing the organizations involved in this research.
+article.contributors  # Returns an Array of PLOS::Contributor objects representing all the people involved in this research, including authors and editors.
+article.authors       # Returns an Array of PLOS::Name objects, one for each author of this research
+article.editors       # Returns an Array of PLOS::Name objects, one for each editor of this research
+article.figures       # Returns an Array of PLOS::Figure objects representing the figures in this article.
+article.references    # Returns an Array of PLOS::Reference objects representing all the articles this article references.
+article.sections      # Returns an Array of PLOS::Section objects containing the actual content of the article.
+article.named_content # Returns an Array of Hash objects. Each representing a piece of "named-content". Named content is often used to separate genes from other text.
 ```
 
 ## Contributing

data/lib/plos.rb

@@ -1,3 +1,12 @@
+require "plos/xml_helpers"
+require "plos/affiliation"
 require "plos/article_ref"
+require "plos/article_set"
+require "plos/article"
+require "plos/contributor"
 require "plos/client"
+require "plos/figure"
+require "plos/reference"
+require "plos/name"
+require "plos/section"
 require "plos/version"

data/lib/plos/affiliation.rb

@@ -0,0 +1,15 @@
+module PLOS
+  class Affiliation
+    include XmlHelpers
+
+    attr_accessor :id
+    attr_accessor :label
+    attr_accessor :address
+
+    def initialize(node)
+      self.id = node.attr("id")
+      self.label = tag_value(node, "label")
+      self.address = tag_value(node, "addr-line")
+    end
+  end
+end

data/lib/plos/article.rb

@@ -0,0 +1,86 @@
+module PLOS
+  class Article
+    include XmlHelpers
+
+    attr_accessor :article_title
+    attr_accessor :article_ids
+    attr_accessor :journal_title
+    attr_accessor :journal_ids
+    attr_accessor :issns
+    attr_writer :affiliations
+    attr_writer :contributors
+    attr_writer :figures
+    attr_writer :references
+    attr_writer :sections
+    attr_writer :named_content
+
+    def initialize(node)
+      self.article_title = tag_value(node.search("title-group"), "article-title")
+      self.journal_title = tag_value(node.search("journal-title-group"), "journal-title")
+
+      self.issns = nodes_to_hash(node.search("journal-meta/issn"), "pub-type")
+      self.journal_ids = nodes_to_hash(node.search("journal-meta/journal-id"), "journal-id-type")
+      self.article_ids = nodes_to_hash(node.search("article-meta/article-id"), "pub-id-type")
+
+      node.search("aff").each do |aff_node|
+        self.affiliations << PLOS::Affiliation.new(aff_node)
+      end
+
+      node.search("contrib").each do |contrib_node|
+        self.contributors << PLOS::Contributor.new(contrib_node)
+      end
+
+      node.search("fig").each do |fig_node|
+        self.figures << PLOS::Figure.new(fig_node)
+      end
+
+      node.search("sec").each do |section_node|
+        self.sections << PLOS::Section.new(section_node)
+      end
+
+      node.search("ref").each do |ref_node|
+        self.references << PLOS::Reference.new(ref_node)
+      end
+
+      node.search("named-content").each do |content_node|
+        type = content_node.attr("content-type")
+        value = content_node.text
+        named_content << {:type => type, :value => value}
+      end
+    end
+
+    def authors
+      contributors.collect { |contrib| contrib.name if contrib.type == "author" }.compact
+    end
+
+    def editors
+      contributors.collect { |contrib| contrib.name if contrib.type == "editor" }.compact
+    end
+
+    def affiliations
+      @affiliations ||= []
+    end
+
+    def contributors
+      @contributors ||= []
+    end
+
+    def figures
+      @figures ||= []
+    end
+
+    def references
+      @references ||= []
+    end
+
+    def sections
+      @sections ||= []
+    end
+
+    def named_content
+      @named_content ||= []
+    end
+  end
+end
+
+# <named-content content-type="gene" xlink:type="simple">5′- AGGACGCAAGGAGGGTTTG -3′</named-content>

data/lib/plos/article_ref.rb

@@ -1,7 +1,7 @@
-require "rest_client"
-
 module PLOS
   class ArticleRef
+    include PLOS::XmlHelpers
+
     attr_accessor :client
     attr_accessor :score
     attr_accessor :type
@@ -17,32 +17,23 @@ module PLOS
     alias :title_display= :title=
     alias :publication_date= :published_at=
 
-    def self.parse_node(node, obj=nil)
-      value = case(node.name)
-      when "arr"
-        node.children.collect { |child| parse_node(child) }
-      when "date"
-        DateTime.parse(node.content)
-      when "float"
-        node.content.to_f
-      else
-        node.content
-      end
-      if node.attr("name") && obj
-        obj.send("#{node.attr("name")}=",value)
-      end
-      value
-    end
-
     def initialize(client, node)
       self.client = client
       node.children.each do |child|
-        ArticleRef.parse_node(child, self)
+        parse_node(child, self)
       end
     end
 
+    def article
+      @article ||= PLOS::Article.new(article_xml)
+    end
+
     def article_xml
-      Nokogiri::XML(RestClient.get(article_url))
+      Nokogiri::XML(article_content)
+    end
+
+    def article_content
+      RestClient.get(article_url)
     end
 
     def citation(format="RIS")

data/lib/plos/article_set.rb

@@ -0,0 +1,9 @@
+module PLOS
+  class ArticleSet < Array
+    attr_accessor :status
+    attr_accessor :time
+    attr_accessor :num_found
+    attr_accessor :start
+    attr_accessor :max_score
+  end
+end

data/lib/plos/client.rb

@@ -16,13 +16,26 @@ module PLOS
     end
 
     def search(query, rows=50, start=0)
-      result = []
+      result = PLOS::ArticleSet.new
       doc = execute( search_url, { :q => query, :rows => rows, :start => start } )
       if doc && doc.root
         doc.root.children.each do |child|
-          next unless child.name == "result"
-          child.children.each do |doc|
-            result << PLOS::ArticleRef.new(self, doc)
+          if child.name == "lst"
+            child.children.each do |int|
+              case int.attr("name")
+              when "status"
+                result.status = int.text
+              when "QTime"
+                result.time = int.text.to_i
+              end
+            end
+          elsif child.name == "result"
+            result.num_found = child.attr("numFound").to_i if child.attr("numFound")
+            result.start = child.attr("start").to_i if child.attr("start")
+            result.max_score = child.attr("maxScore").to_f if child.attr("maxScore")
+            child.children.each do |doc|
+              result << PLOS::ArticleRef.new(self, doc)
+            end
           end
         end
       end

data/lib/plos/contributor.rb

@@ -0,0 +1,25 @@
+module PLOS
+  class Contributor
+    include XmlHelpers
+
+    attr_accessor :name
+    attr_accessor :type
+    attr_accessor :role
+    attr_writer :xrefs
+
+    def initialize(node)
+      self.type = node.attr("contrib-type")
+      self.name = PLOS::Name.new(node.search("name").first)
+      self.role = tag_value(node, "role")
+      node.search("xref").each do |xref|
+        type = xref.attr("ref-type")
+        id = xref.attr("rid")
+        self.xrefs << { :type => type, :id => id }
+      end
+    end
+
+    def xrefs
+      @xrefs ||= []
+    end
+  end
+end

data/lib/plos/figure.rb

@@ -0,0 +1,55 @@
+require "rest_client"
+
+module PLOS
+  class Figure
+    include XmlHelpers
+
+    attr_accessor :id
+    attr_accessor :position
+    attr_accessor :label
+    attr_writer   :caption
+    attr_writer   :graphic
+    attr_writer   :object
+
+    def initialize(node)
+      self.id = node.attr("id")
+      self.position = node.attr("position")
+      self.label = tag_value(node, "label")
+      caption_node = node.search("caption").first
+      if caption_node
+        self.caption[:title] = tag_value(caption_node, "title")
+        self.caption[:body] = tag_value(caption_node, "p")
+      end
+
+      graphic_node = node.search("graphic").first
+      if graphic_node
+        mimetype = graphic_node.attr("mimetype")
+        position = graphic_node.attr("position")
+        link = graphic_node.attr("xlink:href")
+        self.graphic[:mimetype] = mimetype if mimetype
+        self.graphic[:position] = position if position
+        self.graphic[:link] = link if link
+      end
+
+      object_node = node.search("object-id").first
+      if object_node
+        type = object_node.attr("pub-id-type")
+        value = object_node.text
+        self.object[:type] = type if type
+        self.object[:value] = value if value
+      end
+    end
+
+    def caption
+      @caption ||= {}
+    end
+
+    def graphic
+      @graphic ||= {}
+    end
+
+    def object
+      @object ||= {}
+    end
+  end
+end

data/lib/plos/name.rb

@@ -0,0 +1,19 @@
+module PLOS
+  class Name
+    include XmlHelpers
+
+    attr_accessor :style
+    attr_accessor :given_name
+    attr_accessor :surname
+
+    def initialize(node)
+      self.style = node.attr("name-style") if node.attr("name-style")
+      self.given_name = tag_value(node, "given-names")
+      self.surname = tag_value(node, "surname")
+    end
+
+    def to_s
+      "#{given_name} #{surname}"
+    end
+  end
+end

data/lib/plos/reference.rb

@@ -0,0 +1,38 @@
+module PLOS
+  class Reference
+    include PLOS::XmlHelpers
+
+    attr_accessor :id
+    attr_accessor :label
+    attr_accessor :year
+    attr_accessor :type
+    attr_accessor :title
+    attr_accessor :source
+    attr_accessor :volume
+    attr_accessor :first_page
+    attr_accessor :last_page
+    attr_writer :authors
+
+    def initialize(node)
+      self.id = node.attr("id") if node.attr("id")
+      self.label = tag_value(node, "label")
+      citation_node = node.search("element-citation")
+      if citation_node
+        self.type = citation_node.attr("publication-type").value if citation_node.attr("publication-type")
+        self.year = tag_value(citation_node, "year")
+        self.title = tag_value(citation_node, "article-title")
+        self.source = tag_value(citation_node, "source")
+        self.volume = tag_value(citation_node, "volume")
+        self.first_page = tag_value(citation_node, "fpage")
+        self.last_page = tag_value(citation_node, "lpage")
+        citation_node.search("name").each do |name_node|
+          self.authors << PLOS::Name.new(name_node)
+        end
+      end
+    end
+
+    def authors
+      @authors ||= []
+    end
+  end
+end