--
= README.rdoc - README for BioRuby
Copyright:: Copyright (C) 2001-2007 Toshiaki Katayama <k@bioruby.org>,
            Copyright (C) 2008      Jan Aerts <jandot@bioruby.org>
            Copyright (C) 2011-2012 Naohisa Goto <ng@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-2012 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

See RELEASE_NOTES.rdoc for news and important changes in this version.

=== Documents in this distribution

==== Release notes, important changes and issues

README.rdoc:: This file. General information and installation procedure.
RELEASE_NOTES.rdoc:: News and important changes in this release.
KNOWN_ISSUES.rdoc:: Known issues and bugs in BioRuby.
doc/RELEASE_NOTES-1.4.2.rdoc:: News and incompatible changes from 1.4.1 to 1.4.2.
doc/RELEASE_NOTES-1.4.1.rdoc:: News and incompatible changes from 1.4.0 to 1.4.1.
doc/RELEASE_NOTES-1.4.0.rdoc:: News and incompatible changes from 1.3.1 to 1.4.0.
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.
doc/ChangeLog-before-1.4.2:: changes before 1.4.2.
doc/ChangeLog-before-1.3.1:: changes before 1.3.1.
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.

==== Sample codes

In sample/, There are many sample codes and demo scripts.

=== 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/

Mirror site is available, hosted on Open Bioinformatics Foundation (OBF).

* http://bioruby.open-bio.org/

== WHERE TO OBTAIN

=== WWW

The stable release is freely available from the BioRuby website.

* http://bioruby.org/archive/

=== RubyGems

{RubyGems (packaging system for Ruby)}[http://rubygems.org/] 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


== REQUIREMENTS

* Ruby 1.8.6 or later (except Ruby 1.9.0) -- http://www.ruby-lang.org/
  * Ruby 1.9.3-p194 or later, or Ruby 1.8.7-p358 or later is recommended.
  * See KNOWN_ISSUES.rdoc for Ruby version specific problems.


== OPTIONAL REQUIREMENTS

Some optional libraries can be utilized to extend BioRuby's functionality.
If your needs meets the following conditions, install them by using RubyGems,
or download and install from the "Ruby Application Archive" (RAA) at
http://raa.ruby-lang.org/, RubyForge at http://rubyforge.org/, GitHub at
http://github.com/, or the following web sites.

For faster parsing of the BLAST XML output format:

* {RAA:xmlparser}[http://raa.ruby-lang.org/project/xmlparser/]
  * For Ruby 1.8: {gem install xmlparser}[http://rubygems.org/gems/xmlparser]
  * For Ruby 1.9: http://www.yoshidam.net/Ruby.html#xmlparser
  * In both cases, {The Expat XML Parser}[http://expat.sourceforge.net/]
    and C compiler will be required.

Creating faster flatfile index using Berkley DB:

* {GitHub:ruby-bdb}[https://github.com/knu/ruby-bdb]
  (which took over {RAA:bdb}[http://raa.ruby-lang.org/project/bdb/])
  (No RubyGems available)
  * {Oracle Berkeley DB}[http://www.oracle.com/technetwork/database/berkeleydb/index.html] and C compiler will be required.
  
Accessing BioSQL database created by other Open Bio* libraries:

* {gem install activerecord}[http://rubygems.org/gems/activerecord]
  and at least one driver (or adapter):
  * {gem install mysql}[http://rubygems.org/gems/mysql] or
    {gem install mysql2}[http://rubygems.org/gems/mysql2]
  * {gem install pg}[http://rubygems.org/gems/pg]
  * {gem install sqlite-ruby}[http://rubygems.org/gems/sqlite-ruby] or
    {gem install sqlite3}[http://rubygems.org/gems/sqlite3]
  * {gem install activerecord-oracle_enhanced-adapter}[http://rubygems.org/gems/activerecord-oracle_enhanced-adapter]

For parsing PhyloXML format files:

* {gem install libxml-ruby}[http://rubygems.org/gems/libxml-ruby]
  * {GNOME Libxml2 XML toolkit}[http://xmlsoft.org/] and C compiler will be
    required.

(Only for Ruby 1.9.x) For using SOAP web services e.g. KEGG API:

* {gem install soap4r-ruby1.9}[https://rubygems.org/gems/soap4r-ruby1.9]
  * For Ruby 1.8.x, SOAP4R is bundled within the Ruby 1.8.x release.


== INSTALL

=== INSTALL by using RubyGems (recommended)

If you are using RubyGems, just type

  % gem install bio

Alternatively, manually download bio-X.X.X.gem from 
http://rubyforge.org/projects/bioruby/ and install it by using gems command.

RubyGems is bundled with Ruby 1.9.1 or later. For Ruby 1.8.7 or earlier,
download and install RubyGems from http://rubygems.org/ .

=== INSTALL without RubyGems

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

  % ruby setup.rb --help

for more details.


=== Running self-test

To check if bioruby works fine on a machine, self-test codes are bundled.
Note that some tests may need internet connection.

To run tests,

 % ruby test/runner.rb

If you are using Ruby 1.8.x and you want to use components installed by using
RubyGems, explicit loading of RubyGems may be needed.

 % ruby -rubygems test/runner.rb

Alternatively, testrb, the test runner command of ruby, can be used.

 % testrb test/

With testrb, you can select tests to run, for example,

 % testrb test/unit

For those familiar with Rake,

 % rake test

also works.

Before reporting test failure, please check KNOWN_ISSUES.rdoc about known
platform-dependent issues.  We are happy if you write patches to solve the
issues.


== 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 on Ruby 1.8.x

With RubyGems on Ruby 1.8.x, you may need to load 'rubygems' library before
using 'bio'. This may not be needed, depending on settings of Ruby.

  #!/usr/bin/env ruby
  require 'rubygems'
  require 'bio'


== PLUGIN (Biogem)

Many plugins (called Biogem) are now available. See http://biogems.info/
for list of plugins and related software utilizing BioRuby.

* http://biogems.info/

To develop your own plugin, see "Plugins" pages of BioRuby Wiki.

* http://bioruby.open-bio.org/wiki/Plugins

== LICENSE

BioRuby can be freely distributed under the same terms as Ruby.
See the file COPYING (or COPYING.ja written in Japanese).

As written in the file COPYING, see the file LEGAL for files distributed
under different license. For example, setup.rb which comes from
{RAA:setup}[http://raa.ruby-lang.org/project/setup/] developed by Minero Aoki
(http://i.loveruby.net/en/projects/setup/) is licensed under LGPL 2.1.


== REFERENCE

If you use BioRuby in academic research, please consider citing the following
publication.

* BioRuby: Bioinformatics software for the Ruby programming language.
  Naohisa Goto, Pjotr Prins, Mitsuteru Nakao, Raoul Bonnal, Jan Aerts and 
  Toshiaki Katayama.
  Bioinformatics (2010) 26(20): 2617-2619.
  * {doi: 10.1093/bioinformatics/btq475}[http://bioinformatics.oxfordjournals.org/content/26/20/2617]
  * {PMID: 20739307}[http://www.ncbi.nlm.nih.gov/pubmed/20739307]


== CONTACT

Current staff of the BioRuby project can be reached by sending e-mail
to <staff@bioruby.org>.

