  $Id: README,v 1.17 2007/12/07 02:00:42 k Exp $

  Copyright (C) 2001-2008 Toshiaki Katayama <k@bioruby.org>

BioRuby

BioRuby is an open source Ruby library for developing bioinformatics software. Object oriented scripting language Ruby has many features suitable for bioinfomatics 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 softwares for the 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 the BioRuby.

FOR MORE INFORMATION

BioRuby‘s official website is located at bioruby.org/ and you will find links to the related resouces including downloads, mailing lists, documentation etc. in the top page.

bioruby.open-bio.org/

BioRuby Wiki

bioruby.open-bio.org/wiki/

BioRuby API

bioruby.rubyforge.org/

RubyForge project page (Bug report, Feature request, RubyGems archive)

www.rubyforge.org/projects/bioruby/

WHERE TO OBTAIN

WWW

The stable release is freely available from the BioRuby website.

bioruby.org/archive/

CVS

If you need the latest development version, anonymous CVS is provided at

cvs.bioruby.org/

and can 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 version of the BioRuby package is also available for easy installation.

rubyforge.org/projects/bioruby/

REQUIREMENTS

Ruby 1.8.2 or later — www.ruby-lang.org/ (Ruby 1.8.4 or later is recommended)

Note: BioRuby is not tested with Ruby 1.9.0 or later.

OPTIONAL REQUIREMENTS

Some optional libraries can be utilized to extend BioRuby‘s functionality. If your needs meets the following conditions, install them from the RAA (Ruby Application Archive) at raa.ruby-lang.org/ or from RubyForge at www.rubyforge.org/ as RubyGems packages.

For faster parsing of the BLAST XML output format:

xmlparser

Creating faster flatfile index using Berkley DB:

Accessing BioSQL database created by other Open Bio* libraries: (BioSQL functionality will be replaced by ActiveRecord shortly)

ruby-dbi and at least one driver from

Accessing BioMoby web service:

libxml-ruby

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 your operating system supports ‘sudo’ command (such as Mac OS X), try the following procedure instead of the above.

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

You can run tests by

  % ruby install.rb test

and run

  % ruby install.rb --help

for more details.

RubyGems

If you are using RubyGems, just type

  % sudo gem install bio

SETUP

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

  bioruby-x.x.x/etc/bioinformatics/seqdatabase.ini

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

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

and chage the contens according to your preference. For more informations on the OBDA, see ((<URL: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'

Also read other documentations in the ‘doc’ directory.

  bioruby-x.x.x/doc/

RubyGems

In RubyGems, you need to load ‘rubygems’ library before using ‘bio’.

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

LICENSE

BioRuby can be freely distributed under the same terms as Ruby.

Note that, install.rb included in the BioRuby package comes from setup developed by Minero Aoki, and modified by Moses Hohman.

CONTACT

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