taxonifi 0.1.0

data/lib/lumper/lumps/parent_child_name_collection.rb

@@ -0,0 +1,84 @@
+# Handles DwC-esque files (e.g. as dumped by EoL), i.e. a file with columns like: 
+#   [identifier parent child rank synonyms] 
+# Instantiates individual names for all names (including synonym lists) into a NameCollection.
+# See 'test/test_lumper_parent_child_name_collection' for example use.
+module Taxonifi::Lumper::Lumps::ParentChildNameCollection
+
+  def self.name_collection(csv)
+    raise Taxonifi::Lumper::LumperError, "CSV does not have the required headers (#{Taxonifi::Lumper::LUMPS[:eol_basic].join(", ")})." if  !Taxonifi::Lumper.available_lumps(csv.headers).include?(:eol_basic)
+
+    nc = Taxonifi::Model::NameCollection.new(:initial_id => 1)
+    external_index = {} # identifier => Taxonifi::Name
+
+    csv.each_with_index do |row,i|
+      name = row['child']
+      rank = row['rank'].downcase if !row['rank'].nil?
+      parent_id = row['parent'].to_i
+      external_id = row['identifier'].to_i
+      valid_species_id = nil
+
+      case rank
+      when 'species', nil
+       valid_species_id = add_species_names_from_string(nc, name, external_index[parent_id])
+       external_index.merge!(external_id => nc.object_by_id(valid_species_id))
+      else  # Just a single string, we don't have to break anything down.
+        n = nil
+
+        if nc.by_name_index[rank][name]
+          exists = false
+          # TODO: this hasn't been hit yet
+          nc.by_name_index[rank][name].each do |id|
+            if nc.parent_id_vector(id).pop == nc.parent_id_vector(parent_id)
+              exists = true
+              break
+            end
+          end
+          if !exists
+            n = Taxonifi::Model::Name.new()
+          end 
+        else 
+          n = Taxonifi::Model::Name.new()
+        end
+
+        # Build the name
+        if !n.nil?
+          # TODO: No author, year have yet been observed for genus and higher names
+          n.rank = rank
+          n.name = name
+          n.external_id = external_id
+          n.row_number = i
+    
+          if parent = external_index[parent_id] 
+            n.parent = parent
+          end
+
+          nc.add_object(n)
+          external_index.merge!(external_id => n) 
+        end
+      end
+
+      if !row['synonyms'].nil? && row['synonyms'].size > 0 
+        other_names = row['synonyms'].split("|")
+        other_names.each do |n|
+          add_species_names_from_string(nc, n, external_index[parent_id], valid_species_id) 
+        end
+      end
+
+    end # end row
+    nc 
+  end
+
+  # Add the individual names in a species epithet string.  Assumes parents all previously created.
+  def self.add_species_names_from_string(nc, string, parent = nil, synonym_id = nil)
+    names = Taxonifi::Splitter::Builder.build_species_name(string) # A Taxonifi::Model::SpeciesName instance
+    if !parent.nil?                                                # nc.object_by_id(parent_id)
+      names.names.last.parent = parent                             # swap out the genus to the Model referenced by parent_id 
+    else
+      raise Taxonifi::Lumper::LumperError, "Parent of [#{names.names.last.name}] within [#{names.display_name}] not yet instantiated. \n !! To resolve: \n\t 1) If this is not a species name your file may be missing a value in the 'Rank' column (nil values are assumed to be species, all other ranks must be populated). \n\t 2) Parent names must be read before children, check that this is the case."
+    end
+    last_id = nc.add_object(names.names.last).id
+    nc.object_by_id(last_id).related_name = nc.object_by_id(synonym_id) if !synonym_id.nil?
+    last_id
+  end
+
+end 

data/lib/models/author_year.rb

@@ -0,0 +1,39 @@
+require File.expand_path(File.join(File.dirname(__FILE__), "../models/base.rb"))
+
+module Taxonifi
+  module Model
+    # A class to aggregate People and Year combinations.
+   class AuthorYear < Taxonifi::Model::Base
+      # Array of Taxonifi::Model::People
+      attr_accessor :people
+      # String 
+      attr_accessor :year
+      # The parens attribute reflects that this combinations was
+      # cited in parentheses.
+      attr_accessor :parens
+
+      def initialize(options = {})
+        opts = {
+          :people => [],
+          :parens => false,
+          :year => nil
+        }.merge!(options)
+
+        @parens = opts[:parens] 
+        @people = opts[:people] 
+        @year = opts[:year] 
+      end
+
+      # Return a string representing all data, used in indexing.
+      def compact_index
+        index = [@year]
+        @people.each do |a|
+          index.push a.compact_string
+        end
+        index.join("-")
+      end
+
+    end
+  end
+end
+

data/lib/models/base.rb

@@ -0,0 +1,73 @@
+module Taxonifi
+  class ModelError < StandardError; end
+  module Model
+  
+    # A base class for all Taxonifi::Models that represent
+    # "individuals" (as opposed to collections of indviduals).  
+    class Base 
+      # The id of this object.
+      attr_accessor :id
+      # Optionly store the row this came from
+      attr_accessor :row_number
+      # Optionally store an id representing the original id usef for this record. 
+      attr_accessor :external_id
+
+        # Assign on new() all attributes for the ATTRIBUTES 
+        # constant in a given subclass. 
+        # !! Check validity prior to building.
+        def build(attributes, opts)
+          attributes.each do |c|
+            self.send("#{c}=",opts[c]) if !opts[c].nil?
+          end
+        end
+
+        def id=(id)
+          raise Taxonifi::ModelError, "Base model objects must have Fixnum ids." if !id.nil? && id.class != Fixnum
+          @id = id
+        end
+
+        # The ids only of ancestors.
+        # Immediate ancestor id is in [].last
+        def ancestor_ids
+          i = 0 # check for recursion
+          ids = []
+          p = parent 
+          while !p.nil?
+            ids.unshift p.id
+            p = p.parent
+            i += 1
+            raise Taxonifi::ModelError, "Infite recursion in parent string detected for Base model object #{id}." if i > 100
+          end
+          ids
+        end
+
+        # Ancestor objects for subclasses
+        # that have a parent property.
+        # TODO: check for parent attributes
+        def ancestors
+          i = 0 # check for recursion
+          ancestors = []
+          p = parent 
+          while !p.nil?
+            ancestors.unshift p
+            p = p.parent
+            i += 1
+            raise Taxonifi::ModelError, "Infite recursion in parent string detected for Base model object #{id.display_name}." if i > 100
+          end
+          ancestors 
+        end
+
+        # Determines identity base ONLY
+        # on attributes in ATTRIBUTES.
+        def identical?(obj)
+          raise Taxonifi::ModelError, "Objects are not comparible." if obj.class != self.class
+          self.class::ATTRIBUTES.each do |a|
+            next if a == :id # don't compare
+            return false if obj.send(a) != self.send(a)
+          end
+          return true
+        end
+
+    end
+  end
+end

data/lib/models/collection.rb

@@ -0,0 +1,92 @@
+module Taxonifi
+  class CollectionError < StandardError; end
+  module Model
+
+    # The base class that all collection classes are derived from.
+    class Collection
+      attr_accessor :by_id_index
+      attr_accessor :current_free_id
+      attr_accessor :collection 
+
+      def initialize(options = {})
+        opts = {
+          :initial_id => 0
+        }.merge!(options)
+        raise CollectionError, "Can not start with an initial_id of nil." if opts[:initial_id].nil?
+        @collection = []
+        @by_id_index = {} 
+        @current_free_id = opts[:initial_id]
+        true
+      end 
+
+      # Define the default class. Over-ridden in 
+      # specific collections. 
+      def object_class
+        Taxonifi::Model::GenericObject
+      end
+
+      # Return an object in this collection by id.
+      def object_by_id(id)
+        @by_id_index[id] 
+      end
+
+      # Add an object to the collection. 
+      def add_object(obj)
+        raise CollectionError, "Taxonifi::Model::#{object_class.class}#id may not be pre-initialized if used with #add_object, consider using #add_object_pre_indexed." if !obj.id.nil?
+        object_is_allowed?(obj)
+        obj.id = @current_free_id.to_i
+        @current_free_id += 1
+        @collection.push(obj)
+        @by_id_index.merge!(obj.id => obj) 
+        return obj
+      end
+
+      # Add an object without setting its ID. 
+      def add_object_pre_indexed(obj)
+        object_is_allowed?(obj)
+        raise CollectionError, "Taxonifi::Model::#{object_class.class} does not have a pre-indexed id." if obj.id.nil?
+        @collection.push(obj)
+        @by_id_index.merge!(obj.id => obj)
+        return obj
+      end
+
+
+      # Return an array of ancestor (parent) ids.
+      # TODO: deprecate?
+      # More or less identical to Taxonifi::Name.ancestor_ids except
+      # this checks against the indexed names in the collection
+      # rather than Name->Name relationships
+      # The two should be identical in all(?) conievable cases
+      def parent_id_vector(id = Fixnum)
+        vector = []
+        return vector if @by_id_index[id].nil? || @by_id_index[id].parent.nil?
+        id = @by_id_index[id].parent.id
+        while !id.nil?
+          vector.unshift id
+          if @by_id_index[id].parent
+            id = @by_id_index[id].parent.id 
+          else
+            id = nil
+          end
+        end
+        vector
+      end
+
+      # Returns an Array which respresents
+      # all the "root" objects.
+      def objects_without_parents
+        collection.select{|o| o.parent.nil?}
+      end
+
+      protected
+
+      # Check to see that the object can be added to this collection.
+      def object_is_allowed?(obj)
+        raise CollectionError, "Taxonifi::Model::#{object_class.class} not passed to Collection.add_object()." if !(obj.class == object_class)
+        true
+      end
+
+    end
+  end
+
+end

data/lib/models/generic_object.rb

@@ -0,0 +1,15 @@
+module Taxonifi
+  class ModelError < StandardError; end
+  module Model
+
+    # A generic object, has name, parent, rank properties. 
+    class GenericObject < Base 
+      # String
+      attr_accessor :name
+      # Parent object, same class as self
+      attr_accessor :parent
+      # String, arbitrarily assignable rank
+      attr_accessor  :rank
+    end
+  end
+end

data/lib/models/geog.rb

@@ -0,0 +1,59 @@
+module Taxonifi
+  class GeogError < StandardError; end
+  module Model
+
+    # An instance of some geopolitical unit.
+    # Not fully developed yet.
+    class Geog < Taxonifi::Model::Base
+
+      # require 'geokit'
+      # include Geokit::Geocoders
+
+      GEOG_RANKS = ['country', 'state', 'county']
+      ATTRIBUTES = [:name, :rank, :parent]
+      ATTRIBUTES.each do |a|
+        attr_accessor a
+      end
+
+      def initialize(options = {})
+        opts = {
+        }.merge!(options)
+        @parent = nil
+        build(ATTRIBUTES - [:parent], opts)
+        @parent = opts[:parent] if (!opts[:parent].nil? && opts[:parent].class == Taxonifi::Model::Geog)
+        true
+      end 
+
+      # Set the "rank" of this geographic unit.
+      def rank=(rank)
+        r = rank.to_s.downcase.strip
+        if !GEOG_RANKS.include?(r) 
+          raise GeogError, "#{r} is not a valid rank."
+        end
+        @rank = r
+      end
+
+      # Set parent of this rank (also a Taxonifi::Model::Geog instance).
+      def parent=(parent)
+       if parent.nil?
+         raise GeogError, "Parent can't be set to nil in Taxonifi::Model::Geog."
+       end
+
+        if @rank.nil?
+          raise Taxonifi::GeogError, "Parent of geog can not be set if rank of child is not set." 
+        end
+
+        if parent.class != Taxonifi::Model::Geog
+          raise GeogError, "Parent is not a Taxonifi::Model::Geog."
+        end
+
+        if GEOG_RANKS.index(parent.rank) >= GEOG_RANKS.index(self.rank)
+          raise GeogError, "Parent is same or lower rank than self (#{rank})."
+        end
+        
+        @parent = parent
+      end
+
+    end
+  end
+end

data/lib/models/geog_collection.rb

@@ -0,0 +1,28 @@
+module Taxonifi
+  class GeogCollectionError < StandardError; end
+  module Model
+
+    # Collection of geog objects.
+    # TODO: Consider moving the row index to the base collection (those this doesn't
+    # always make sense).
+    class GeogCollection < Taxonifi::Model::Collection
+      attr_accessor :row_index
+
+      def initialize(options = {})
+        super
+        @row_index = []
+        true
+      end 
+
+      # Return the object represented by a row.
+      def object_from_row(row_number)
+        @row_index[row_number]
+      end
+
+      def object_class
+        Taxonifi::Model::Geog
+      end
+    
+    end
+  end
+end

data/lib/models/name.rb

@@ -0,0 +1,206 @@
+module Taxonifi
+  class NameError < StandardError; end
+
+  # A taxonomic name.
+  class Model::Name < Taxonifi::Model::Base
+
+    # String
+    attr_accessor  :name      
+    # String 
+    attr_accessor  :rank   
+    # String, authors as originally read 
+    attr_accessor  :year         
+    # Boolean, true if parens present (i.e. _not_ in original combination) 
+    attr_accessor  :parens       
+    # A Taxonifi::Model::Name 
+    attr_accessor  :parent      
+    # String
+    attr_accessor  :author        
+    # General purpose relationship, typically used to indicate synonymy.  A Taxonifi::Model::Name 
+    attr_accessor  :related_name 
+
+    # Array, contains properties assignable in Taxonifi::Model::Name#new()
+    ATTRIBUTES = [:name, :rank, :year, :parens, :parent, :author, :related_name]
+
+    ATTRIBUTES.each do |a|
+      attr_accessor a
+    end
+
+    # optionally parsed/index
+    attr_accessor :authors                    
+
+    # optionally parsed/index
+    attr_accessor :author_year_index    
+
+    def initialize(options = {})
+      opts = {
+        id: nil
+      }.merge!(options)
+      @parent = nil
+      build(ATTRIBUTES, opts)
+      add_author_year(opts[:author_year]) if !opts[:author_year].nil? && opts[:author_year].size > 0
+      @parent = opts[:parent] if (!opts[:parent].nil? && opts[:parent].class == Taxonifi::Model::Name)
+      @id = opts[:id] # if !opts[:id].nil? && opts[:id].size != 0
+      @authors ||= []
+      true
+    end 
+
+    # Returns an Array of Taxonifi::Model::Person
+    def add_author_year(string) # :yields: Array of Taxonifi::Model::Person
+      auth_yr = Taxonifi::Splitter::Builder.build_author_year(string)
+      @year = auth_yr.year
+      @authors = auth_yr.people
+    end
+
+    # Translates the String representation of author year to an Array of People.
+    # Used in indexing, when comparing Name microtations to Ref microcitations.
+    def derive_authors_year
+      add_author_year(author_year_string) 
+    end
+
+    # Set the rank.
+    def rank=(rank)
+      r = rank.to_s.downcase.strip
+      if !RANKS.include?(r) 
+        raise NameError, "#{r} is not a valid rank."
+      end
+      @rank = r
+    end
+
+    # Set the parent (a Taxonifi::Model::Name) 
+    def parent=(parent)
+      if @rank.nil?
+        raise Taxonifi::NameError, "Parent of name can not be set if rank of child is not set." 
+      end
+
+      # TODO: ICZN class over-ride
+      if parent.class != Taxonifi::Model::Name
+        raise NameError, "Parent is not a Taxonifi::Model::Name."
+      end
+
+      if RANKS.index(parent.rank) >= RANKS.index(self.rank)
+        raise NameError, "Parent is same or lower rank than self (#{rank})."
+      end
+
+      @parent = parent
+    end
+
+    # Returns a formatted string, including parens for the name
+    # TODO: rename to reflect parens
+    def author_year
+      au = author_year_string
+      if self.parens == false
+        "(#{au})"        
+      else
+        au.size == 0 ? nil : au
+      end
+    end
+
+    # Return the author year string. 
+    def author_year_string
+      au = [self.author, self.year].compact.join(", ")
+    end
+
+    # Return the name of a parent at a given rank.
+    # TODO: move method to Base? 
+    def parent_name_at_rank(rank)
+      return self.name if self.rank == rank
+      p = @parent
+      i = 0
+      while !p.nil?
+        return p.name if p.rank == rank
+        p = p.parent
+        i+= 1
+        raise NameError, "Loop detected among parents for [#{self.display_name}]." if i > 75 
+      end
+      nil 
+    end
+
+    # Return the parent at a given rank.
+    # TODO: move method to Base? 
+    def parent_at_rank(rank)
+      return self if self.rank == rank
+      p = @parent
+      i = 0
+      while !p.nil?
+        return p if p.rank == rank
+        p = p.parent
+        raise NameError, "Loop detected among parents fo [#{self.display_name}]" if i > 75 
+      end
+      nil 
+    end
+
+    # Return the human readable version of this name with author year (String)
+    def display_name
+      [nomenclator_name, author_year].compact.join(" ")
+    end
+
+    # Return the human readable version of this name, without author year (String)
+    def nomenclator_name 
+      case @rank
+      when 'species', 'subspecies'
+        [parent_name_at_rank('genus'), (parent_name_at_rank('subgenus') ? "({parent_name_at_rank('subgenus')})" : nil), parent_name_at_rank('species'), @name].compact.join(" ")
+      when 'subgenus'
+        [parent_name_at_rank('genus'), "(#{@name})"].compact.join(" ")
+      else
+        [@name].compact.join(" ")
+      end
+    end
+
+    # Return a dashed "vector" of ids representing the ancestor parent closure, like:
+    #  0-1-14-29g-45s-99-100.
+    #  Postfixed g means "genus", postifed s means "subgenus.  As per SpecieFile usage.
+    def parent_ids_sf_style
+      ids = [] 
+      (ancestors.push self).each do |a|
+        case a.rank
+        when 'genus'
+          ids.push "#{a.id}g"
+        when 'subgenus'
+          ids.push "#{a.id}s"
+        else
+          ids.push a.id.to_s
+        end
+      end
+
+      ids.join("-")
+    end
+
+    # Return names indexed by author_year.
+    def author_year_index
+      @author_year_index ||= generate_author_year_index
+    end
+
+    # Generate/return the author year index.
+    def generate_author_year_index
+      @author_year_index = Taxonifi::Model::AuthorYear.new(people: @authors, year: @year).compact_index
+    end
+
+  end 
+
+  # ICZN specific sublassing of a taxonomic name.
+  # !! Minimally tested and not broadly implmented.
+  class Model::IcznName < Taxonifi::Model::Name
+    def initialize
+      super
+    end
+    
+    # Set the name, checks for family group restrictions. 
+    def name=(name)
+      case @rank
+      when 'superfamily'
+        raise NameError, "ICZN superfamily name does not end in 'oidae'." if name[-5,5] != 'oidae'
+      when 'family'
+        raise NameError, "ICZN family name does not end in 'idae'." if name[-4,4] != 'idae'
+      when 'subfamily'
+        raise NameError, "ICZN subfamily name does not end in 'inae'." if name[-4,4] != 'inae'
+      when 'tribe'
+        raise NameError, "ICZN tribe name does not end in 'ini'." if name[-3,3] != 'ini'
+      when 'subtribe'
+        raise NameError, "ICZN subtribe name does not end in 'ina'." if name[-3,3] != 'ina'
+      end
+      @name = name
+    end
+  end
+
+end