wwood-bioruby 1.2.11

data/README.rdoc

@@ -0,0 +1,205 @@
+Copyright (C) 2001-2007 Toshiaki Katayama <k@bioruby.org>
+              2008      Jan Aerts <jandot@bioruby.org>
+
+= BioRuby
+
+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
+
+BioRuby's official website is at ((<URL:http://bioruby.org/>)).
+You will find links to related resources including downloads,
+mailing lists, Wiki documentation etc. in the top page.
+
+  * ((<URL:http://bioruby.org/>))
+
+
+== WHERE TO OBTAIN
+
+--- WWW
+
+The stable release is freely available from the BioRuby website.
+
+  * ((<URL:http://bioruby.org/archive/>))
+
+--- git
+
+If you need the latest development version, this is provided at
+
+  * ((<URL: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 
+
+  * ((<URL: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
+
+--- RubyGems
+
+((<RubyGems|URL:http://rubyforge.org/projects/rubygems/>)) version of
+the BioRuby package is also available for easy installation.
+
+  * ((<URL:http://rubyforge.org/projects/bioruby/>))
+
+
+== REQUIREMENTS
+
+* Ruby 1.8.2 or later -- ((<URL:http://www.ruby-lang.org/>))
+  (Ruby 1.8.5 or later is recommended)
+
+== 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 ((<URL:http://raa.ruby-lang.org/>)).
+
+For faster parsing of the BLAST XML output format:
+
+  * [RAA:xmlparser]
+
+Creating faster flatfile index using Berkley DB:
+
+  * [RAA:bdb]
+
+Accessing BioSQL database created by other Open Bio* libraries:
+
+  * ActiveRecord ((<URL:http://rubyforge.org/projects/activerecord/>))
+    and at least one driver (or adapter) from MySQL/Ruby
+    ((<URL:http://rubyforge.org/projects/mysql-ruby/>)),
+    postgres-pr ((<URL:http://rubyforge.org/projects/postgres-pr>)),
+    or ActiveRecord Oracle enhanced adapter
+    ((<URL:http://rubyforge.org/projects/oracle-enhanced/>)).
+  * For BioRuby 1.2.1 or older version, Ruby/DBI
+    ((<URL:http://rubyforge.org/projects/ruby-dbi>) and
+    at least one driver from MySQL/Ruby, postgres-pr, or
+    ruby-oci8 ((<URL:http://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 ((<URL: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_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] developed by Minero Aoki.
+
+
+== 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.
+