taxonifi 0.1.0

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/Gemfile

@@ -0,0 +1,18 @@
+source "http://rubygems.org"
+# Add dependencies required to use your gem here.
+# Example:
+#   gem "activesupport", ">= 2.3.5"
+
+#  gem 'geokit'
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+#  gem "shoulda", ">= 0"
+  gem "rdoc", "~> 3.12"
+  gem "bundler", "> 1.0.0"
+  gem "jeweler", "~> 1.8.3"
+  gem "debugger"
+#  gem "ruby-debug19"
+#  gem "simplecov", ">= 0"
+end

data/Gemfile.lock

@@ -0,0 +1,30 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    columnize (0.3.6)
+    debugger (1.1.1)
+      columnize (>= 0.3.1)
+      debugger-linecache (~> 1.1)
+      debugger-ruby_core_source (~> 1.1)
+    debugger-linecache (1.1.1)
+      debugger-ruby_core_source (>= 1.1.1)
+    debugger-ruby_core_source (1.1.1)
+    git (1.2.5)
+    jeweler (1.8.3)
+      bundler (~> 1.0)
+      git (>= 1.2.5)
+      rake
+      rdoc
+    json (1.6.6)
+    rake (0.9.2.2)
+    rdoc (3.12)
+      json (~> 1.4)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (> 1.0.0)
+  debugger
+  jeweler (~> 1.8.3)
+  rdoc (~> 3.12)

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2012 Illinois Natural History Survey 
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,155 @@
+= taxonifi
+There will always be "legacy" taxonomic data that needs shuffling around. The taxonifi gem is a suite of general purpose tools that act as a middle layer for data-conversion purposes (e.g. migrating legacy taxonomic databases).  It's first application was to convert DwC-style data downloaded from EoL into a Species File.  The code is well documented in unit tests, poke around to see if it might be useful.  In particular, if you've considered building a collection of regular expressions particular to biodiversity data look at the Tokens code and related tests. 
+
+Overall, the goal is to provide well documented (and unit-tested) coded that is broadly useful, and vanilla enough to encourage other to fork and hack on their own.
+
+== Source
+Source is available at https://github.com/SpeciesFile/taxonifi.  The rdoc API is also viewable at http://taxonifi.speciesfile.org, (though those docs may lag behind commits to github).
+
+== What's next?
+
+Before you jump on board you should also check out similar code from the Global Names team at https://github.com/GlobalNamesArchitecture. Future integration and merging of shared functionality is planned.  Code will be released in an "early-and-often" approach 
+
+= Getting started
+taxonifi is coded for Ruby 1.9.3, it has not been tested on earlier versions (though it will certainly not work with 1.8.7). 
+Using Ruby Version Manager (RVM, https://rvm.io/ ) is highly recommend. You can test your version of Ruby by doinging "ruby -v" in your terminal.
+
+Taxonifi is presently coded for convience, not speed (though it's not necessarily slow). It assumes that conversion processes are typically one-offs that can afford to run over a longer period of time (read minutes rather than seconds). Reading, and fully parsing into objects, around 25k rows of nomenclature (class to species, inc. author year, = ~45k names) in to memory as Taxonifi objects benchmarks at around 2 minutes. Faster indexing is planned as needed, likely using Redis (see GNA link above).
+
+
+To install:
+
+   gem install taxonifi
+
+In your script
+
+  require 'taxonifi'
+
+
+= Use
+== Quick start
+
+Write some code:
+
+  require 'taxonifi'
+
+  headers = ["a", "B", "c"]
+  csv_string = CSV.generate() do |csv|
+    csv <<  @headers
+    csv << %w{a b c}
+  end
+
+  csv = CSV.parse(csv_string, {headers: true, :header_converters :downcase})
+
+  # Taxonifi can create generic hierachical collections based on column headers
+  c = Taxonifi::Lumper.create_hierarchical_collection(csv, %w{a b c})    # => a Taxonifi::Model::Collection 
+  c.collection.first               # => Taxonifi::Model::GenericObject
+  c.collection.first.name          # => "a" 
+  c.collection.last.name           # => "c" 
+  c.collection.last.parent.name    # => "b" 
+  c.collection.first.row_number    # => 0
+  c.collection.first.rank          # => "a"
+
+  # Header order is important:
+  c = Taxonifi::Lumper.create_hierarchical_collection(csv, %w{c a b})    # => a Taxonifi::Model::Collection 
+  c.collection.first.name          # => "c" 
+  c.collection.last.rank           # => "c" 
+  c.collection.last.name           # => "b" 
+  c.collection.last.parent.name    # => "a" 
+  
+  # Collections of GenericObjects (and some other Taxonifi::Collection based objects like TaxonifiNameCollection) only include
+  # unique names, i.e. if a name has a shared parent lineage only the name itself is created, not its parents. 
+  # For example, for:
+  #  a b   c 
+  #  a d   nil
+  #  b nil d
+  # The collection consists of objects with names a,b,c,d,b,d respectively.
+  # This makes it very useful for handling not only nomenclatural but other nested data as well.
+
+There are collections of specific types (e.g. taxonomic names, geographic names):
+
+    string = CSV.generate() do |csv|
+      csv << %w{family genus species author_year}
+      csv << ["Fooidae", "Foo", "bar", "Smith, 1854"]
+      csv << ["Fooidae", "Foo", "foo", "(Smith, 1854)"]
+    end
+   
+    csv = CSV.parse(string, {headers: true})
+
+    nc = Taxonifi::Lumper.create_name_collection(csv)  # => Taxonifi::Model::NameCollection
+
+    nc.collection.first                                # => Taxonifi::Model::Name 
+    nc.collection.first.name                           # => "Fooidae"
+    nc.collection.first.rank                           # => "family" 
+    nc.collection.first.year                           # =>  nil
+    nc.collection.first.author                         # => []
+    nc.collection.last.rank                            # => "species" 
+    nc.collection.last.name                            # => "foo" 
+    nc.collection.last.author.first.last_name          # =>  "Smith"
+    nc.collection.last.year                            # =>  "1854"
+
+Parent/child style nomenclature is also parseable.
+
+There are *lots* more examples of code use in the test suite.
+
+== Export/conversion
+
+The following is an example that translates a DwC style input format as exported by EOL into tables importable to SpeciesFile.  The input file is has id, parent, child, vernacular, synonym columns.  Data are exported by default to a the users home folder in a taxonifi directory.  The export creates 6 tables that can be imported into Species File directly.
+
+    require 'taxonifi'
+    file = File.expand_path(File.join(File.dirname(__FILE__), 'file_fixtures/Lygaeoidea-csv.tsv'))
+
+    csv = CSV.read(file, { 
+      headers: true,
+      col_sep: "\t",
+      header_converters: :downcase
+    } ) 
+
+    nc = Taxonifi::Lumper::Lumps::ParentChildNameCollection.name_collection(csv)
+    e = Taxonifi::Export::SpeciesFile.new(:nc => nc, :authorized_user_id => 1)
+    e.export
+
+You should be able to relativley quickly use the export framework to code new output formats.
+
+== Reading files 
+
+taxonifi feeds on Ruby's CSV. read your files with header true, and downcased, e.g.:
+
+  csv = CSV.read('input/my_data.tab',  { 
+                headers: true,
+                header_converters: :downcase,
+                col_sep: "\t"  } ) 
+
+== Code organization
+
+  test                # unit tests, quite a few of them
+  lib                 # the main libraries
+  lib/assessor        # libraries to assess the properties of incoming data
+  lib/export          # export wrappers 
+  lib/export/format   # one module for each export type
+  lumper              # code that builds Taxonifi objects 
+  models              # Taxonifi objects
+  splitter            # a parser/lexer/token suite for breaking down data 
+
+= Contributing to taxonifi
+
+(this is generic)
+ 
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
+* Fork the project.
+* Start a feature/bugfix branch.
+* Commit and push until you are happy with your contribution.
+* Write unit test for your code.  Changes are good, just as long as tests run clean.  
+* All pull requests should test clean.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+= About
+
+taxonifi is coded by Matt Yoder in consultation with the Species File Group at University of Illinois.
+
+= Copyright
+
+Copyright (c) 2012 Illinois Natural History Survey. See LICENSE.txt for
+further details.
+

data/Rakefile

@@ -0,0 +1,53 @@
+# encodang: utf-8
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "taxonifi"
+  gem.homepage = "http://github.com/mjy/taxonifi"
+  gem.license = "MIT"
+  gem.summary = %Q{A general purpose framework for scripted handling of taxonomic names}
+  gem.description = %Q{Taxonifi contains simple models and utilties of use in for parsing lists of taxonomic name (life) related metadata}
+  gem.email = "diapriid@gmail.com"
+  gem.authors = ["mjy"]
+  # dependencies defined in Gemfile
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+# require 'rcov/rcovtask'
+# Rcov::RcovTask.new do |test|
+#  test.libs << 'test'
+#  test.pattern = 'test/**/test_*.rb'
+#  test.verbose = true
+#  test.rcov_opts << '--exclude "gems/*"'
+# end
+
+task :default => :test
+
+require 'rdoc/task'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+ rdoc.rdoc_dir = 'rdoc'
+ rdoc.title = "taxonifi #{version}"
+ rdoc.rdoc_files.include('README*')
+ rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/assessor/assessor.rb

@@ -0,0 +1,31 @@
+module Taxonifi
+
+  require File.expand_path(File.join(File.dirname(__FILE__), 'base'))
+  require File.expand_path(File.join(File.dirname(__FILE__), 'row_assessor'))
+
+  class AssessorError < StandardError; end
+
+  # The assessor assesses!
+  # 
+  # A work in progress. The idea is to provide
+  # a mechanism to assess incoming data to determine
+  # what possible outputs (or other operations)
+  # are possible.
+  module Assessor 
+
+    INPUTS = { 
+      name_and_heirarchy: {
+      complete_match:   true,
+      require_columns:  [ ],
+      optional_columns: [ ],
+    } 
+    }
+
+    # INPUT.key => /lumper/class
+    OUTPUTS = { 
+      name_and_heirarchy: [ ]
+    } 
+
+  end # end Assessor module
+end # Taxonifi module
+

data/lib/assessor/base.rb

@@ -0,0 +1,17 @@
+module Taxonifi
+  module Assessor 
+
+    # Stub for a base model. Not used
+    class Base 
+      attr_reader :outputs, :inputs
+
+      #  def _assess_inputs
+      #  end
+
+      #  def _assess_outputs
+      #  end
+    end
+
+  end # end Assessor module
+end # Taxonifi module
+

data/lib/assessor/row_assessor.rb

@@ -0,0 +1,131 @@
+module Taxonifi
+  module Assessor 
+
+    # Code to assess the metadata properties of a csv row.
+    #
+    # !! Note that there are various
+    # !! CSV methods for returning row columns
+    # !! that have particular attributes
+    module RowAssessor
+
+      class RowAssessorError < StandardError; end
+
+      # Pass a CSV (require "csv") row as read with the following 
+      # parameters: 
+      #   headers: true
+      #   header_converters: :symbol
+      class RowAssessor < Taxonifi::Assessor::Base
+        attr_reader :lumps # the lumps present in this row
+        def initialze(csv_row)
+          cols = []
+          cols = csv_row.entries.select{|c,v| !v.nil?}.collect{|c| c[0]}
+          @lumps = Taxonifi::Lumper.available_lumps(cols)
+        end
+      end
+
+      # Return the first column with data, scoped by lump if provided. 
+      def self.first_available(csv_row, lump = nil)
+        if lump.nil?
+          csv_row.entries.each do |c,v| 
+            return [c,v] if !csv_row[c].nil?
+          end
+        else
+          lump.each do |l|
+            return [l, csv_row[l.to_s]] if !csv_row[l.to_s].nil?
+          end
+        end
+      end
+      
+      # Return the last column with data, scoped by lump if provided. 
+      def self.last_available(csv_row, lump = nil)
+        if lump.nil?
+          csv_row.entries.reverse.each do |c,v| 
+            return [c,v] if !csv_row[c].nil?
+          end
+        else
+          lump.reverse.each do |l|
+            return [l, csv_row[l.to_s]] if !csv_row[l.to_s].nil?
+          end
+        end
+      end
+
+      # Return the rank (symbol) of the taxon name rank.  Raises
+      # if no name detected.
+      def self.lump_name_rank(csv_row)
+        lumps = Taxonifi::Lumper.available_lumps(csv_row.headers)        
+        if lumps.include?(:species) # has to be a species name
+          if csv_row[:subspecies].nil?
+            return :species
+          else
+            return :subspecies
+          end
+        elsif lumps.include?(:genera)
+          if csv_row[:subgenus].nil?
+            return :genus
+          else
+            return :subgenus
+          end
+        else
+          return Taxonifi::Assessor::RowAssessor.last_available(csv_row, Taxonifi::Lumper::LUMPS[:higher]).first.to_sym
+        end
+
+        # this far? bad
+        raise RowAssessor::RowAssessorError
+      end
+
+      # Return the column representing the parent of the name
+      # represented in this row.
+      def self.parent_taxon_column(csv_row)
+        lumps = Taxonifi::Lumper.available_lumps(csv_row.headers)
+        last = last_available(csv_row, Taxonifi::RANKS)
+        last_available(csv_row, Taxonifi::RANKS[0..Taxonifi::RANKS.index(last[0])-1])
+      end
+
+      # Return an Array of headers that represent taxonomic ranks.
+      def self.rank_headers(headers)
+        Taxonifi::RANKS & headers
+      end
+
+      # Return an Array of headers that represent geographic columns.
+      def self.geog_headers(headers)
+        Taxonifi::Lumper::LUMPS[:basic_geog] & headers
+      end
+
+      # Return lumps for which at least one column has data.
+      def self.intersecting_lumps_with_data(row, lumps_to_try = nil)
+        lumps_to_try ||= Taxonifi::Lumper::LUMPS.keys 
+        lumps = [] 
+        lumps_to_try.each do |l|  
+          has_data = false 
+          Taxonifi::Lumper::LUMPS[l].each do |c|
+            if !row[c].nil? && !row[c].empty?
+              has_data = true 
+              break
+            end
+          end
+          has_data && lumps.push(l) 
+        end
+        lumps
+      end
+
+      # Return lumps that have data for all columns.
+      def self.lumps_with_data(row, lumps_to_try = nil)
+        lumps_to_try ||= Taxonifi::Lumper::LUMPS.keys 
+        lumps = [] 
+        lumps_to_try.each do |l|  
+          has_data = true 
+          Taxonifi::Lumper::LUMPS[l].each do |c|
+            if row[c].nil? || row[c].empty?
+              has_data = false 
+              break
+            end
+          end
+          has_data && lumps.push(l) 
+        end
+        lumps
+      end
+
+    end
+  end 
+end 
+

data/lib/export/export.rb

@@ -0,0 +1,9 @@
+module Taxonifi
+  # Export related functionality.
+  module Export
+    class ExportError < StandardError; end 
+    Dir.glob( File.expand_path(File.join(File.dirname(__FILE__), "format/*.rb") )) do |file|
+      require file
+    end
+  end
+end

data/lib/export/format/base.rb

@@ -0,0 +1,43 @@
+module Taxonifi::Export
+
+  # All export classes inherit from Taxonifi::Export::Base
+  class Base
+    EXPORT_BASE =  File.expand_path(File.join(Dir.home(), 'taxonifi', 'export')) 
+    attr_accessor :base_export_path, :export_folder
+
+    def initialize(options = {})
+      opts = {
+        :base_export_path => EXPORT_BASE,
+        :export_folder => '.'
+      }.merge!(options)
+
+      @base_export_path = opts[:base_export_path]  
+      @export_folder = opts[:export_folder] 
+    end
+
+    # Return the path to which exported files will be written.
+    def export_path
+      File.expand_path(File.join(@base_export_path, @export_folder))
+    end 
+      
+    # Subclassed models expand on this method, typically writing files
+    # to the folders created here.
+    def export
+      configure_folders
+    end
+
+    # Recursively (over)write the the export path.
+    def configure_folders
+      FileUtils.mkdir_p export_path
+    end
+
+    # Write the string to a file in the export path.
+    def write_file(filename = 'foo', string = nil)
+      raise ExportError, 'Nothing to export for #{filename}.' if string.nil? || string == ""
+      f = File.new( File.expand_path(File.join(export_path, filename)), 'w+')
+      f.puts string
+      f.close
+    end
+
+  end
+end