README

= BioRuby

BioRuby project aims to implement integrated environment for Bioinformatics.

Object oriented scripting language Ruby has many good points suitable for
bioinfomatics research.  Powerful regular expressions like Perl, purely
object oriented, simple and very clean syntax -- easy to learn for beginners,
easy to use for biologists, powerful enough for 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 any information you need.  Biological sequences are
treated with Ruby's powerful string methods and regular expressions.  Daily
tools like Blast, Fasta and Hmmer programs can be executed and the results
are fully parsed to extract scores and/or alignments.  BioRuby also supports
some databases and web services developed in Japan such as KEGG, AAindex,
and DBGET etc.


== WHERE TO GET

* WWW -- ((<URL:http://bioruby.org/>))

    http://bioruby.org/archive/

* CVS -- ((<URL:http://cvs.bioruby.org/>))

    % cvs -d :pserver:anonymous@cvs.bioruby.org:/export/cvs login
    CVS password: (no password is required, just push return)
    % cvs -d :pserver:anonymous@cvs.bioruby.org:/export/cvs co bioruby


== REQUIREMENTS

* Ruby 1.6.6 or newer -- ((<URL:http://www.ruby-lang.org/>))


== OPTIONAL REQUIREMENTS

* Ruby library -- ((<URL:http://raa.ruby-lang.org/>))

  * [RAA:strscan] for parsing Blast default output.
  * [RAA:rexml] for parsing Blast XML output and using DAS.
  * [RAA:xmlparser] can be used for faster Blast XML parsing.
  * [RAA:ruby-dbi] and at least one driver from [RAA:mysql-ruby],
    [RAA:postgres], [RAA:oracle] to use with BioSQL.
  * [RAA:bdb] for faster flat file indexing.
  * [RAA:pp] for pretty print in debug.
  * [RAA:soap4r] (version >= 1.4.8.1) for KEGG API. Note that libraries
    which SOAP4R depends such as [RAA:date2], [RAA:devel-logger],
    [RAA:http-access] (version >= j) with one of [RAA:xmlscan], [RAA:rexml],
    [RAA:rexml-stable], [RAA:xmlparser], [RAA:nqxml] are also needed.

  Note that 'strscan', 'rexml', 'pp', 'date2' and 'xmlscan' are 
  included in the Ruby 1.8.0 distibution (you don't need to install
  them by yourself).

* External applications can be used if installed

  * Blast (version >= 2.2.5) for blast execution on local computer
  * FASTA for fasta, ssearch execution on local computer
  * HMMER for hmmsearch, hmmpfam execution on local computer


== INSTALL

In the bioruby source directory (such as bioruby-x.x.x/), run install.rb
as follows:

  % ruby install.rb config
  % ruby install.rb setup
  % su
  # ruby install.rb install

If you are using Mac OS X, you should use 'sudo' command instead of 'su'.

  % ruby install.rb config
  % ruby install.rb setup
  % sudo ruby install.rb install

You can try

  % ruby install.rb --help

for more details.


If you want to use the OBDA (Open Bio Database Access) to obtain database
entries, copy a sample config file

  etc/bioinformatics/seqdatabase.ini

to

  /etc/bioinformatics/seqdatabase.ini	(system wide configuration)

or

  ~/.bioinformatics/seqdatabase.ini	(personal configuration)

and chage the contens according to your preference.  For more
informations on the OBDA, see ((<URL:http://obda.open-bio.org/>)).


== USAGE

You can load all BioRuby classes just by require 'bio' and all the
BioRuby classes are defined under the module Bio for the name space.
See the documentation for each class.

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


== LICENCE

GPL for applications, LGPL for libraries.  Note that, install.rb
included in the BioRuby package comes from [RAA:setup] by Minero Aoki.


== AUTHORS

* KATAYAMA Toshiaki <k@bioruby.org>, project leader
* Yoshinori K. Okuji <okuji@enbug.org>
* Mitsuteru C. Nakao <n@bioruby.org>
* KAWASHIMA Shuichi <s@bioruby.org>
* GOTO Naohisa <ng@bioruby.org>

  * and many others on the Internet...