bio 1.2.1 → 1.3.0

data/KNOWN_ISSUES.rdoc

@@ -0,0 +1,88 @@
+= KNOWN_ISSUES.rdoc - Known issues and bugs in BioRuby
+Copyright:: Copyright (C) 2009 Naohisa Goto <ng@bioruby.org>
+License::   The Ruby License
+
+= Known issues and bugs in BioRuby
+
+Below are known issues and bugs in BioRuby. They will be fixed in the future,
+except items with (WONT_FIX) tags.
+
+== 1. Ruby version specific issues
+
+=== Ruby 1.9.1 or later
+
+Some classes/modules/methods still may not work or may return incorrect
+results in Ruby 1.9.1, especially those not covered by the unit tests.
+
+==== String encodings
+
+Currently, BioRuby do not care string encodings. In some cases,
+Encoding::CompatibilityError may be raised.
+
+=== Ruby 1.9.0
+
+(WONT_FIX) Ruby 1.9.0 is NOT supported because it isn't a stable release.
+Use Ruby 1.9.1 or later.
+
+=== Ruby 1.8.2 or earlier
+
+(WONT_FIX) In some cases, temporary files and directories may not be
+removed because of the lack of FileUtils.remove_entry_secure.
+
+(WONT_FIX) We will soon end support for Ruby 1.8.2. Note that Ruby
+1.8.1 or earlier is no longer supported, as described in README.rdoc.
+
+=== Issues about SOAP/WSDL
+
+SOAP4R (SOAP and WSDL implementation) is no longer bundled with Ruby 1.9.
+In addition, because of the API changes in recent SOAP4R, some
+classes/modules using SOAP4R may not work.
+
+=== Problem with REXML DoS vulnerability patch before 09-Nov-2008
+
+(WONT_FIX) If you have applied a patch taken from
+http://www.ruby-lang.org/en/news/2008/08/23/dos-vulnerability-in-rexml/
+before 09 Nov 2008 12:40 +0900, because of the bug in the patch,
+parsing of Blast XML results with REXML parser may fail. The bug is already
+fixed and new patch is available on the above URL. Note that some Linux
+distributions would have incorporated the patch in their manners, and may
+have the same problem.
+
+== 2. OS and/or architecture-dependent issues
+
+=== Microsoft Windows
+
+==== Text mode issues
+
+Following 4 tests failed on mswin32 (and maybe on mingw32 and bccwin32)
+because of the conversion of line feed codes in the text mode.
+
+* test_ended_pos and test_start_pos in test/unit/bio/io/test_flatfile.rb
+* test_pos in test/unit/bio/io/flatfile/test_buffer.rb
+* test_entry_pos in test/unit/bio/appl/blast/test_rpsblast.rb
+
+This indicates that br_bioflat.rb and Bio::FlatFileIndex may create
+incorrect indexes on mswin32, mingw32, and bccwin32. In addition,
+Bio::FlatFile may return incorrect data.
+
+==== Windows 95/98/98SE/ME
+
+(WONT_FIX) Some methods that call external programs may not work in
+Windows 95/98/98SE/ME because of the limitation of COMMAND.COM.
+
+=== OpenVMS, BeOS, OS/2, djgpp, Windows CE
+
+(WONT_FIX) BioRuby may not work on these platforms.
+
+== 3. Known issues and bugs in BioRuby
+
+=== Bio::Ensembl
+
+Due to the renewal of Ensembl web site, Bio::Ensembl does not work for
+the latest Ensembl. For a workaround, use an archive server. For example,
+"jul2008.archive.ensembl.org" seems to be the last server before the renewal.
+  human = Bio::Ensembl.new("Homo_sapiens", "jul2008.archive.ensembl.org")
+
+Alternatively, consider using Ruby Ensembl API.
+* http://github.com/jandot/ruby-ensembl-api
+

data/README.rdoc

@@ -0,0 +1,252 @@
+--
+= README.rdoc - README for BioRuby
+Copyright:: Copyright (C) 2001-2007 Toshiaki Katayama <k@bioruby.org>,
+            Copyright (C) 2008      Jan Aerts <jandot@bioruby.org>
+License::   The Ruby License
+* The above statement is limited to this file. See below about BioRuby's
+  copyright and license.
+++
+
+= BioRuby
+
+Copyright (C) 2001-2009 Toshiaki Katayama <k@bioruby.org>
+
+BioRuby is an open source Ruby library for developing bioinformatics
+software.  Object oriented scripting language Ruby has many features
+suitable for bioinformatics research, for example, clear syntax to
+express complex objects, regular expressions for text handling as
+powerful as Perl's, a wide variety of libraries including web service
+etc.  As the syntax of the Ruby language is simple and very clean, we
+believe that it is easy to learn for beginners, easy to use for
+biologists, and also powerful enough for the software developers.
+
+In BioRuby, you can retrieve biological database entries from flat
+files, internet web servers and local relational databases.  These
+database entries can be parsed to extract information you need.
+Biological sequences can be treated with the fulfilling methods of the
+Ruby's String class and with regular expressions.  Daily tools like
+Blast, Fasta, Hmmer and many other software packages for biological
+analysis can be executed within the BioRuby script, and the results
+can be fully parsed to extract the portion you need.  BioRuby supports
+major biological database formats and provides many ways for accessing
+them through flatfile indexing, SQL, web services etc.  Various web
+services including KEGG API can be easily utilized by BioRuby.
+
+
+== FOR MORE INFORMATION
+
+=== Documents in this distribution
+
+==== General information
+
+README.rdoc:: This file. General information and installation procedure.
+KNOWN_ISSUES.rdoc:: Known issues and bugs in BioRuby.
+doc/Changes-1.3.rdoc:: News and incompatible changes from 1.2.1 to 1.3.0.
+doc/Changes-0.7.rd:: News and incompatible changes from 0.6.4 to 1.2.1.
+
+==== Tutorials and other useful information
+
+doc/Tutorial.rd:: BioRuby Tutorial.
+doc/Tutorial.rd.html:: HTML version of Tutorial.rd.
+doc/KEGG_API.rd:: Documents about KEGG API, including usage of Bio::KEGG::API.
+
+==== BioRuby development
+
+ChangeLog:: History of changes.
+README_DEV.rdoc:: Describes ways to contribute to the BioRuby project, including coding styles and documentation guidelines.
+
+==== Documents written in Japanese
+
+doc/Tutorial.rd.ja:: BioRuby Tutorial written in Japanese.
+doc/Tutorial.rd.ja.html:: HTML version of Tutorial.rd.ja.
+doc/KEGG_API.rd.ja:: Japanese translation of KEGG_API.rd.
+
+
+=== WWW
+
+BioRuby's official website is at http://bioruby.org/.
+You will find links to related resources including downloads,
+mailing lists, Wiki documentation etc. in the top page.
+
+* http://bioruby.org/
+
+
+== WHERE TO OBTAIN
+
+=== WWW
+
+The stable release is freely available from the BioRuby website.
+
+* http://bioruby.org/archive/
+
+=== RubyGems
+
+RubyGems[URL:http://rubyforge.org/projects/rubygems/] version of
+the BioRuby package is also available for easy installation.
+
+* http://rubyforge.org/projects/bioruby/
+
+=== git
+
+If you need the latest development version, this is provided at
+
+* http://github.com/bioruby/bioruby
+
+and can be obtained by the following procedure:
+
+  % git clone git://github.com/bioruby/bioruby.git
+
+==== CVS
+
+CVS is now deprecated as source control has moved to github. Please use git 
+instead of CVS. For historical purposes: the anonymous CVS was provided at 
+
+* http://cvs.bioruby.org/
+
+and could be obtained by the following procedure.
+
+  % cvs -d :pserver:cvs@code.open-bio.org:/home/repository/bioruby login
+  CVS password: cvs (login with a password 'cvs' for the first time)
+  % cvs -d :pserver:cvs@code.open-bio.org:/home/repository/bioruby co bioruby
+
+
+== REQUIREMENTS
+
+* Ruby 1.8.2 or later -- http://www.ruby-lang.org/
+  * Ruby 1.8.5 or later is recommended.
+  * Not yet fully ready with Ruby 1.9, although many components can now work
+    in Ruby 1.9.1.
+
+== OPTIONAL REQUIREMENTS
+
+Some optional libraries can be utilized to extend BioRuby's functionality.
+If your needs meets the following conditions, install them from the "Ruby
+Application Archive" at http://raa.ruby-lang.org/, RubyForge at
+http://rubyforge.org/, or the following web sites.
+
+For faster parsing of the BLAST XML output format:
+
+* {RAA:xmlparser}[http://raa.ruby-lang.org/project/xmlparser/]
+
+Creating faster flatfile index using Berkley DB:
+
+* {RAA:bdb}[http://raa.ruby-lang.org/project/bdb/]
+
+Accessing BioSQL database created by other Open Bio* libraries:
+
+* {RubyForge:ActiveRecord}[http://rubyforge.org/projects/activerecord/]
+  and at least one driver (or adapter) from
+  {RubyForge:MySQL/Ruby}[http://rubyforge.org/projects/mysql-ruby/],
+  {RubyForge:postgres-pr}[http://rubyforge.org/projects/postgres-pr], or
+  {RubyForge:ActiveRecord Oracle enhanced adapter}[http://rubyforge.org/projects/oracle-enhanced/].
+* For BioRuby 1.2.1 or older version,
+  {RubyForge:Ruby/DBI}[http://rubyforge.org/projects/ruby-dbi] and
+  at least one driver from MySQL/Ruby, postgres-pr, or
+  {RubyForge:ruby-oci8}[http://ruby-oci8.rubyforge.org/]
+  (note that ruby-oci8 can only work with ruby-dbi 0.2.2).
+
+
+== INSTALL
+
+In the bioruby source directory (such as bioruby-x.x.x/), run setup.rb
+as follows:
+
+  % su
+  # ruby setup.rb
+
+These simple step installs this program under the default location of
+Ruby libraries.  You can also install files into your favorite directory
+by supplying setup.rb some options. Try "ruby setup.rb --help".
+
+If your operating system supports 'sudo' command (such as Mac OS X),
+try the following procedure instead of the above.
+
+  % sudo ruby setup.rb
+
+For older version users: "install.rb" is now renamed to "setup.rb".
+The options "config", "setup", and "install" are still available.
+
+  % ruby setup.rb config
+  % ruby setup.rb setup
+  % su
+  # ruby setup.rb install
+
+You can run tests by
+
+  % ruby setup.rb test
+
+and run
+
+  % ruby setup.rb --help
+
+for more details.
+
+=== RubyGems
+
+If you are using RubyGems, just type
+
+  % gems install bio
+
+
+== SETUP
+
+If you want to use the OBDA (Open Bio Database Access) to obtain database
+entries, copy a sample configuration file in the BioRuby distribution
+
+  bioruby-x.x.x/etc/bioinformatics/seqdatabase.ini
+
+to
+
+  /etc/bioinformatics/seqdatabase.ini	(system wide configuration)
+
+or
+
+  ~/.bioinformatics/seqdatabase.ini	(personal configuration)
+
+and change the contents according to your preference.  For more
+information on the OBDA, see http://obda.open-bio.org/ .
+
+
+== USAGE
+
+You can load all BioRuby classes just by requiring 'bio.rb'.  All the
+BioRuby classes and modules are located under the module name 'Bio' to
+separate the name space.
+
+  #!/usr/bin/env ruby
+  require 'bio'
+
+You can also read other documentation in the 'doc' directory.
+
+  bioruby-x.x.x/doc/
+
+=== RubyGems
+
+With RubyGems, you need to load 'rubygems' library before using 'bio'.
+
+  #!/usr/bin/env ruby
+  require 'rubygems'
+  require 'bio'
+
+With old version of RubyGems, use 'require_gem' which was deprecated in
+RubyGems 0.9.0 and removed in RubyGems 1.0.1.
+
+  #!/usr/bin/env ruby
+  require 'rubygems'
+  require_gem 'bio'
+
+
+== LICENSE
+
+BioRuby can be freely distributed under the same terms as Ruby.
+
+Note that setup.rb included in the BioRuby package comes from
+{RAA:setup}[http://raa.ruby-lang.org/project/setup/] developed by Minero Aoki
+(http://i.loveruby.net/en/projects/setup/).
+
+
+== CONTACT
+
+Current staff of the BioRuby project can be reached by sending e-mail
+to <staff@bioruby.org>.
+

data/README_DEV.rdoc

@@ -0,0 +1,285 @@
+= README.DEV
+
+Copyright::  Copyright (C) 2005, 2006 Toshiaki Katayama <k@bioruby.org>
+Copyright::  Copyright (C) 2006, 2008 Jan Aerts <jandot@bioruby.org>
+
+= HOW TO CONTRIBUTE TO THE BIORUBY PROJECT?
+
+There are many possible ways to contribute to the BioRuby project,
+such as:
+
+* Join the discussion on the BioRuby mailing list
+* Send a bug report or write a bug fix patch
+* Add and correct documentation
+* Develop code for new features, etc.
+
+All of these are welcome!  However, this document describes the last option,
+how to contribute your code to the BioRuby distribution.
+
+We would like to include your contribution as long as the scope of
+your module meets the field of bioinformatics.
+
+== Git
+
+Bioruby is now under git source control at http://github.com/bioruby/bioruby. 
+There are two basic ways to contribute: with patches or pull requests. Both are
+explained on the bioruby wiki at http://bioruby.open-bio.org/wiki.
+
+= LICENSE
+
+If you would like your module to be included in the BioRuby distribution,
+you need to give us right to change the license of your module to make it
+compatible with other modules in BioRuby.
+
+BioRuby was previously distributed under the LGPL license, but now is
+distributed under the same terms as Ruby.
+
+= CODING STYLE
+
+You will need to follow the typical coding styles of the BioRuby modules:
+
+== Use the following naming conventions
+
+* CamelCase for module and class names
+* '_'-separated_lowercase for method names
+* '_'-separated_lowercase for variable names
+* all UPPERCASE for constants
+
+== Indentation must not include tabs
+
+* Use 2 spaces for indentation.
+* Don't replace spaces to tabs.
+
+== Comments
+
+Don't use <tt>=begin</tt> and <tt>=end</tt> blocks for comments.  If you need to
+add comments, include it in the RDoc documentation.
+
+== Documentation should be written in the RDoc format in the source code
+
+The RDoc format is becoming the popular standard for Ruby documentation.
+We are now in transition from the previously used RD format to the RDoc
+format in API documentation.
+
+Additional tutorial documentation and working examples are encouraged
+with your contribution.  You may use the header part of the file for
+this purpose as demonstrated in the previous section.
+
+== Standard documentation
+
+=== of files
+
+Each file should start with a header, which covers the following topics:
+* copyright
+* license
+* description of the file (_not_ the classes; see below)
+* any references, if appropriate
+
+The header should be formatted as follows:
+
+  #
+  # = bio/db/hoge.rb - Hoge database parser classes
+  #
+  # Copyright::  Copyright (C) 2001, 2003-2005 Bio R. Hacker <brh@example.org>,
+  # Copyright::  Copyright (C) 2006 Chem R. Hacker <crh@example.org>
+  #
+  # License::    The Ruby License
+  #
+  # == Description
+  #
+  # This file contains classes that implement an interface to the Hoge database.
+  #
+  # == References
+  #
+  # * Hoge F. et al., The Hoge database, Nucleic. Acid. Res. 123:100--123 (2030)
+  # * http://hoge.db/
+  #
+
+  require 'foo'
+
+  module Bio
+
+    autoload :Bar, 'bio/bar'
+
+  class Hoge
+    :
+  end  # Hoge
+
+  end  # Bio
+
+=== of classes and methods within those files
+
+Classes and methods should be documented in a standardized format, as in the
+following example (from lib/bio/sequence.rb):
+
+  # == Description
+  #
+  # Bio::Sequence objects represent annotated sequences in bioruby.
+  # A Bio::Sequence object is a wrapper around the actual sequence, 
+  # represented as either a Bio::Sequence::NA or a Bio::Sequence::AA object.
+  # For most users, this encapsulation will be completely transparent.
+  # Bio::Sequence responds to all methods defined for Bio::Sequence::NA/AA
+  # objects using the same arguments and returning the same values (even though 
+  # these methods are not documented specifically for Bio::Sequence).
+  #
+  # == Usage
+  # 
+  #   require 'bio'
+  #   
+  #   # Create a nucleic or amino acid sequence
+  #   dna = Bio::Sequence.auto('atgcatgcATGCATGCAAAA')
+  #   rna = Bio::Sequence.auto('augcaugcaugcaugcaaaa')
+  #   aa = Bio::Sequence.auto('ACDEFGHIKLMNPQRSTVWYU')
+  # 
+  #   # Print in FASTA format
+  #   puts dna.output(:fasta)
+  # 
+  #   # Print all codons
+  #   dna.window_search(3,3) do |codon|
+  #     puts codon
+  #   end
+  # 
+  class Sequence
+  
+    # Create a new Bio::Sequence object
+    #
+    #   s = Bio::Sequence.new('atgc')
+    #   puts s                                  # => 'atgc'
+    #
+    # Note that this method does not intialize the contained sequence
+    # as any kind of bioruby object, only as a simple string
+    #
+    #   puts s.seq.class                        # => String
+    #
+    # See Bio::Sequence#na, Bio::Sequence#aa, and Bio::Sequence#auto 
+    # for methods to transform the basic String of a just created 
+    # Bio::Sequence object to a proper bioruby object
+    # ---
+    # *Arguments*:
+    # * (required) _str_: String or Bio::Sequence::NA/AA object
+    # *Returns*:: Bio::Sequence object
+    def initialize(str)
+      @seq = str
+    end
+  
+    # The sequence identifier.  For example, for a sequence
+    # of Genbank origin, this is the accession number.
+    attr_accessor :entry_id
+  
+    # An Array of Bio::Feature objects
+    attr_accessor :features
+  end # Sequence
+
+Preceding the class definition (<tt>class Sequence</tt>), there is at least a 
+description and a usage example. Please use the +Description+ and +Usage+
+headings. If appropriate, refer to other classes that interact with or are
+related to the class.
+
+The code in the usage example should, if possible, be in a format that a user
+can copy-and-paste into a new script to run. It should illustrate the most
+important uses of the class. If possible and if it would not clutter up the
+example too much, try to provide any input data directly into the usage example,
+instead of refering to ARGV or ARGF for input.
+
+  dna = Bio::Sequence.auto('atgcatgcATGCATGCAAAA')
+
+Otherwise, describe the input shortly, for example:
+
+  # input should be string consisting of nucleotides
+  dna = Bio::Sequence.auto(ARGF.read)
+
+Methods should be preceded by a comment that describes what the method does, 
+including any relevant usage examples. (In contrast to the documentation for
+the class itself, headings are not required.) In addition, any arguments should
+be listed, as well as the type of thing that is returned by the method. The
+format of this information is as follows:
+
+  # ---
+  # *Arguments*:
+  # * (required) _str_: String or Bio::Sequence::NA
+  # * (optional) _nr_: a number that means something
+  # *Returns*:: true or false
+
+Attribute accessors can be preceded by a short description.
+
+== Exception handling
+
+Don't use
+
+  $stderr.puts "WARNING"
+
+in your code. Instead, try to avoid printing error messages. For fatal errors,
+use +raise+ with an appropriate message.
+
+== Testing code should use 'test/unit'
+
+Unit tests should come with your modules by which you can assure what
+you meant to do with each method.  The test code is useful to make
+maintenance easy and ensure stability. The use of
+
+  if __FILE__ == $0
+
+is deprecated.
+
+== Using autoload
+
+To quicken the initial load time we have replaced most of 'require' to 
+'autoload' since BioRuby version 0.7.  During this change, we have found
+some tips:
+
+You should not separate the same namespace into several files.
+
+* For example, if you have separated definitions of the Bio::Foo
+  class into two files (e.g. 'bio/foo.rb' and 'bio/bar.rb'), you
+  need to resolve the dependencies (including the load order)
+  yourself.
+
+* If you have a defined Bio::Foo in 'bio/foo.rb' and a defined
+  Bio::Foo::Bar in 'bio/foo/bar.rb' add the following line in the
+  'bio/foo.rb' file:
+
+    autoload :Bar, 'bio/foo/bar'
+    
+You should not put several top level namespaces in one file.
+
+* For example, if you have Bio::A, Bio::B and Bio::C in the file
+  'bio/foo.rb', you need
+
+    autoload :A, 'bio/foo'
+    autoload :B, 'bio/foo'
+    autoload :C, 'bio/foo'
+
+  to load the module automatically (instead of require 'bio/foo').
+  In this case, you should put them under the new namespace like
+  Bio::Foo::A, Bio::Foo::B and Bio::Foo::C in the file 'bio/foo',
+  then use
+
+    autoload :Foo, 'bio/foo'
+
+  so autoload can be written in 1 line.
+
+= NAMESPACE
+
+Your module should be located under the top-level module Bio and put under
+the 'bioruby/lib/bio' directory.  The class/module names and the
+file names should be short and descriptive.
+
+There are already several sub directories in 'bioruby/lib':
+
+  bio/*.rb   -- general and widely used basic classes
+  bio/appl/  -- wrapper and parser for the external applications
+  bio/data/  -- basic biological data
+  bio/db/    -- flatfile database entry parsers
+  bio/io/    -- I/O interfaces for files, RDB, web services etc.
+  bio/util/  -- utilities and algorithms for bioinformatics
+
+If your module doesn't match any of the above, please propose
+an appropriate directory name when you contribute. Please let the staff
+discuss on namespaces (class names), API (method names) before commiting
+a new module or making changes on existing modules.
+
+= MAINTENANCE
+
+Finally, please maintain the code you've contributed. Please let us know (on 
+the bioruby list) before you commit, so that users can discuss on the change.
+