bioruby-phyloxml 1.0.0

data/README.md

@@ -0,0 +1,214 @@
+# bio-phyloxml
+
+[![Build Status](https://secure.travis-ci.org/bioruby/bioruby-phyloxml.png)](http://travis-ci.org/bioruby/bioruby-phyloxml)
+
+bio-phyloxml (the package name on RubyGems.org is bioruby-phyloxml)
+is a [phyloXML](http://www.phyloxml.org/) plugin for
+[BioRuby](http://bioruby.org/), an open source bioinformatics
+library for Ruby.
+
+phyloXML is an XML language for saving, analyzing and exchanging data
+of annotated phylogenetic trees. The phyloXML parser in BioRuby is
+implemented in Bio::PhyloXML::Parser, and its writer in
+Bio::PhyloXML::Writer.  More information can be found at
+[phyloxml.org](http://www.phyloxml.org).
+
+This phyloXML code has historically been part of the core BioRuby
+[gem](https://github.com/bioruby/bioruby), but has been split into its
+own gem as part of an effort to
+[modularize](http://bioruby.open-bio.org/wiki/Plugins)
+BioRuby. bio-phyloxml and many more plugins are available at
+[biogems.info](http://www.biogems.info/).
+
+This code was originally written by Diana Jaunzeikare during the
+Google Summer of Code 2009 for the
+[Implementing phyloXML support in BioRuby](http://informatics.nescent.org/wiki/Phyloinformatics_Summer_of_Code_2009#Implementing_phyloXML_support_in_BioRuby)
+project with NESCent, mentored by Christian Zmasek et al. For details
+of development, see
+[github.com/latvianlinuxgirl/bioruby](https://github.com/latvianlinuxgirl/bioruby)
+and the BioRuby mailing list archives.
+
+## Requirements
+
+bio-phyloxml uses [libxml-ruby](http://xml4r.github.com/libxml-ruby/),
+which requires several C libraries and their headers to be installed:
+ * `zlib`
+ * `libiconv`
+ * `libxml`
+ 
+With these installed, `libxml-ruby` gem should be installed.
+
+```sh
+gem install libxml-ruby
+```
+
+If you see "ERROR: Failed to build gem native extension", the above
+C libraries and their headers may be missing. See doc/Tutorial.rd
+about installation of them in some system.
+
+bio-phyloxml also uses the `bio` gem. It will automatically be installed
+during the installation of `bio-phyloxml` in normal cases.
+
+For more information see the
+[libxml page](https://rubygems.org/gems/libxml-ruby) and
+the [BioRuby installation page](http://bioruby.open-bio.org/wiki/Installation).
+
+
+## Installation
+
+```sh
+gem install bioruby-phyloxml
+```
+
+Note: Please uninstall old bio-phyloxml gem that have not been maintained
+since 2012. The old bio-phyloxml gem was created in 2012 as a preliminary
+trial of splitting bioruby components to separate gems.
+We tried to contact the author of the old bio-phyloxml gem, but no response.
+
+```sh
+gem uninstall bio-phyloxml
+```
+
+## Migration
+
+Users who were previously using the phyloXML support in the core
+BioRuby gem should be able to migrate to using this gem very
+easily. Simply install the `bio-phyloxml` gem as described below, and
+add `require 'bio-phyloxml'` to the relevant application code.
+
+## Usage
+
+```ruby
+require 'bio-phyloxml'
+```
+
+### Parsing a file
+
+```ruby
+require 'bio-phyloxml'
+
+# Create new phyloxml parser
+phyloxml = Bio::PhyloXML::Parser.open('example.xml')
+
+# Print the names of all trees in the file
+phyloxml.each do |tree|
+  puts tree.name
+end
+```
+
+If there are several trees in the file, you can access the one you wish by specifying its index:
+
+```ruby
+tree = phyloxml[3]
+```
+You can use all Bio::Tree methods on the tree, since PhyloXML::Tree inherits from Bio::Tree. For example, 
+
+```ruby
+tree.leaves.each do |node|
+ puts node.name
+end
+```
+
+PhyloXML files can hold additional information besides phylogenies at the end of the file. This info can be accessed through the 'other' array of the parser object.
+
+```ruby
+phyloxml = Bio::PhyloXML::Parser.open('example.xml')
+while tree = phyloxml.next_tree
+  # do stuff with trees
+end 
+
+puts phyloxml.other
+```
+
+### Writing a file
+
+```ruby
+# Create new phyloxml writer
+writer = Bio::PhyloXML::Writer.new('tree.xml')
+
+# Write tree to the file tree.xml
+writer.write(tree1) 
+
+# Add another tree to the file
+writer.write(tree2)
+```
+
+### Retrieving data
+
+Here is an example of how to retrieve the scientific name of the clades included in each tree.
+
+```ruby
+require 'bio-phyloxml'
+
+phyloxml = Bio::PhyloXML::Parser.open('ncbi_taxonomy_mollusca.xml')
+phyloxml.each do |tree|
+  tree.each_node do |node|
+    print "Scientific name: ", node.taxonomies[0].scientific_name, "\n"
+  end
+end
+```
+
+### Retrieving 'other' data
+
+```ruby
+require 'bio'
+
+phyloxml = Bio::PhyloXML::Parser.open('phyloxml_examples.xml')
+while tree = phyloxml.next_tree
+ #do something with the trees
+end
+
+p phyloxml.other
+puts "\n"
+#=> output is an object representation
+
+#Print in a readable way
+puts phyloxml.other[0].to_xml, "\n"
+#=>:
+#
+#<align:alignment xmlns:align="http://example.org/align">
+#  <seq name="A">acgtcgcggcccgtggaagtcctctcct</seq>
+#  <seq name="B">aggtcgcggcctgtggaagtcctctcct</seq>
+#  <seq name="C">taaatcgc--cccgtgg-agtccc-cct</seq>
+#</align:alignment>
+
+#Once we know whats there, lets output just sequences
+phyloxml.other[0].children.each do |node|
+ puts node.value
+end
+#=>
+#
+#acgtcgcggcccgtggaagtcctctcct
+#aggtcgcggcctgtggaagtcctctcct
+#taaatcgc--cccgtgg-agtccc-cct
+```
+
+The API doc is online. (TODO: generate and link) For more code
+examples see the test files in the source tree.
+
+## Project home page
+
+Information on the source tree, documentation, examples, issues and
+how to contribute, see
+
+  http://github.com/bioruby/bioruby-phyloxml
+
+The BioRuby community is on IRC server: irc.freenode.org, channel: #bioruby.
+
+## Cite
+
+If you use this software, please cite one of
+  
+* [BioRuby: bioinformatics software for the Ruby programming language](http://dx.doi.org/10.1093/bioinformatics/btq475)
+* [Biogem: an effective tool-based approach for scaling up open source software development in bioinformatics](http://dx.doi.org/10.1093/bioinformatics/bts080)
+
+## Biogems.info
+
+This Biogem is published at [#bio-phyloxml](http://biogems.info/index.html)
+
+## Copyright
+
+Copyright (c) 2009 Diana Jaunzeikare and BioRuby project.
+See COPYING or COPYING.ja for further details.
+
+This README.md was first written by Clayton Wheeler.

data/Rakefile

@@ -0,0 +1,20 @@
+require "bundler/gem_tasks"
+require 'rdoc/task'
+require 'rake/testtask'
+
+task :default => "test"
+
+Rake::TestTask.new do |t|
+  t.test_files = FileList["test/unit/**/test_*.rb"]
+end
+
+Rake::RDocTask.new do |r|
+  r.rdoc_dir = "rdoc"
+  r.rdoc_files.include("README.md",
+                       "COPYING", "COPYING.ja", "BSDL", "LGPL", "GPL",
+                       "doc/Tutorial.rd",
+                       "lib/**/*.rb")
+  r.main = "README.md"
+  r.options << '--title' << 'Bio::PhyloXML API documentation'
+  r.options << '--line-numbers'
+end

data/bioruby-phyloxml.gemspec

@@ -0,0 +1,36 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'bio-phyloxml/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "bioruby-phyloxml"
+  spec.version       = Bio::PhyloXML::VERSION
+  spec.authors       = [ "Diana Jaunzeikare", "Clayton Wheeler",
+                         "BioRuby project" ]
+  spec.email         = [ "staff@bioruby.org" ]
+
+  spec.summary       = %q{PhyloXML plugin for BioRuby}
+  spec.description   = %q{Provides PhyloXML support for BioRuby. This bioruby-phyloxml gem replaces old unmaintained bio-phyloxml gem.}
+  spec.homepage      = "http://github.com/bioruby/bioruby-phyloxml"
+  spec.license       = "Ruby"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.extra_rdoc_files = [ "README.md",
+                            "COPYING", "COPYING.ja", "BSDL", "LGPL", "GPL",
+                            "doc/Tutorial.rd" ]
+  spec.rdoc_options << '--main' << 'README.md'
+  spec.rdoc_options << '--title' << 'Bio::PhyloXML API documentation'
+  spec.rdoc_options << '--line-numbers'
+
+  spec.add_runtime_dependency "bio", ">= 1.5.0"
+  spec.add_runtime_dependency "libxml-ruby", "~> 2.8"
+
+  spec.add_development_dependency "bundler", "~> 1.10"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rdoc", "~> 4"
+end

data/doc/Tutorial.rd

@@ -0,0 +1,152 @@
+# This document is generated with a version of rd2html (part of Hiki)
+#
+# A possible test run could be from rdtool (on Debian package rdtool)
+#
+#   rd2 $BIORUBYPATH/doc/Tutorial.rd
+#
+# or with style sheet:
+#
+#   rd2 -r rd/rd2html-lib.rb --with-css=bioruby.css $BIORUBYPATH/doc/Tutorial.rd > ~/bioruby.html
+#
+# in Debian:
+#
+#   rd2 -r rd/rd2html-lib  --with-css="../lib/bio/shell/rails/vendor/plugins/bioruby/generators/bioruby/templates/bioruby.css" Tutorial.rd > Tutorial.rd.html
+#
+# A common problem is tabs in the text file! TABs are not allowed.
+#
+# To add tests run Toshiaki's bioruby shell and paste in the query plus
+# results.
+#
+# To run the embedded Ruby doctests you can use the rubydoctest tool, part
+# of the bioruby-support repository at http://github.com/pjotrp/bioruby-support/
+#
+
+=begin
+#doctest Testing bioruby
+
+= Bio::PhyloXML Tutorial
+
+* Copyright (C) 2001-2003 KATAYAMA Toshiaki <k .at. bioruby.org>
+* Copyright (C) 2005-2009 Pjotr Prins, Naohisa Goto and others
+
+= PhyloXML
+
+PhyloXML is an XML language for saving, analyzing and exchanging data of 
+annotated phylogenetic trees. PhyloXML parser in BioRuby is implemented in 
+Bio::PhyloXML::Parser and writer in Bio::PhyloXML::Writer. 
+More information at www.phyloxml.org
+
+== Install
+
+  % gem install bio-phyloxml
+
+In addition to bio-phyloxml, dependent gems such as bio and libxml-ruby
+will automatically be installed.
+
+== Parsing a file
+
+    require 'bio-phyloxml'
+    
+    # Create new phyloxml parser
+    phyloxml = Bio::PhyloXML::Parser.new('example.xml')
+    
+    # Print the names of all trees in the file
+    phyloxml.each do |tree|
+      puts tree.name
+    end
+
+If there are several trees in the file, you can access the one you wish by an index
+
+    tree = phyloxml[3]
+
+You can use all Bio::Tree methods on the tree, since PhyloXML::Tree inherits from Bio::Tree. For example,
+
+   tree.leaves.each do |node|
+     puts node.name
+   end
+
+PhyloXML files can hold additional information besides phylogenies at the end of the file. This info can be accessed through the 'other' array of the parser object.
+
+    phyloxml = Bio::PhyloXML::Parser.new('example.xml')
+    while tree = phyloxml.next_tree
+      # do stuff with trees
+    end 
+      
+    puts phyloxml.other
+
+== Writing a file
+
+    # Create new phyloxml writer
+    writer = Bio::PhyloXML::Writer.new('tree.xml')
+   
+    # Write tree to the file tree.xml
+    writer.write(tree1) 
+    
+    # Add another tree to the file
+    writer.write(tree2)
+
+== Retrieving data
+
+Here is an example of how to retrieve the scientific name of the clades.
+
+    require 'bio-phyloxml'
+    
+    phyloxml = Bio::PhyloXML::Parser.new('ncbi_taxonomy_mollusca.xml')
+    phyloxml.each do |tree|
+      tree.each_node do |node|
+        print "Scientific name: ", node.taxonomies[0].scientific_name, "\n"
+      end
+    end
+
+== Retrieving 'other' data
+
+    require 'bio-phyloxml'
+    
+    phyloxml = Bio::PhyloXML::Parser.new('phyloxml_examples.xml')
+    while tree = phyloxml.next_tree
+     #do something with the trees
+    end
+
+    p phyloxml.other
+    puts "\n"
+    #=> output is an object representation
+    
+    #Print in a readable way
+    puts phyloxml.other[0].to_xml, "\n"
+    #=>:
+    #
+    #<align:alignment xmlns:align="http://example.org/align">
+    #  <seq name="A">acgtcgcggcccgtggaagtcctctcct</seq>
+    #  <seq name="B">aggtcgcggcctgtggaagtcctctcct</seq>
+    #  <seq name="C">taaatcgc--cccgtgg-agtccc-cct</seq>
+    #</align:alignment>
+    
+    #Once we know whats there, lets output just sequences
+    phyloxml.other[0].children.each do |node|
+     puts node.value
+    end
+    #=>
+    #
+    #acgtcgcggcccgtggaagtcctctcct
+    #aggtcgcggcctgtggaagtcctctcct
+    #taaatcgc--cccgtgg-agtccc-cct
+
+
+= APPENDIX
+
+=== Troubleshooting libxml-ruby installation problem
+
+If you get "Failed to build gem native extension" error, you may need to
+install the GNOME Libxml2 XML toolkit library and development files.
+
+On Debian or Ubuntu,
+
+  sudo aptitude install libxml2-dev
+
+On RedHat or CentOS,
+
+  sudo yum install libxml2-devel
+
+On other platforms, see ((<URL:http://www.xmlsoft.org/>)).
+
+=end

data/lib/bio-phyloxml.rb

@@ -0,0 +1,27 @@
+# Please require your code below, respecting the naming conventions in the
+# bioruby directory tree.
+#
+# For example, say you have a plugin named bio-plugin, the only uncommented
+# line in this file would be
+#
+#   require 'bio/bio-plugin/plugin'
+#
+# In this file only require other files. Avoid other source code.
+
+require 'bio-phyloxml/compat/cleanup.rb'
+require 'bio-phyloxml/version.rb'
+require 'bio-phyloxml/phyloxml_elements.rb'
+require 'bio-phyloxml/phyloxml_parser.rb'
+require 'bio-phyloxml/phyloxml_writer.rb'
+
+if require 'bio-phyloxml/compat/stub_phyloxml_elements.rb'
+  require_relative 'bio/db/phyloxml/phyloxml_elements.rb'
+end
+
+if require 'bio-phyloxml/compat/stub_phyloxml_parser.rb'
+  require_relative 'bio/db/phyloxml/phyloxml_parser.rb'
+end
+
+if require 'bio-phyloxml/compat/stub_phyloxml_writer.rb'
+  require_relative 'bio/db/phyloxml/phyloxml_writer.rb'
+end