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>.