bio 1.0.0 → 1.1.0

data/lib/bio/io/ensembl.rb

@@ -0,0 +1,229 @@
+#
+# = bio/io/ensembl.rb - An Ensembl Genome Browser client.
+#
+# Copyright::   Copyright (C) 2006
+#               Mitsuteru C. Nakao <n@bioruby.org>
+# License::     The Ruby License
+#
+# $Id: ensembl.rb,v 1.11 2007/04/05 23:35:41 trevor Exp $
+#
+# == Description
+#
+# Client classes for Ensembl Genome Browser.
+#
+# == Examples
+#
+#  human = Bio::Ensembl.new('Homo_sapiens')
+#  seq = human.exportview(1, 1000, 100000)
+#  gff = human.exportview(1, 1000, 100000, ['gene', 'variation', 'genscan'])
+#
+#  human = Bio::Ensembl.human
+#  seq = human.exportview(1, 1000, 100000)
+#  gff = human.exportview(1, 1000, 100000, ['gene'])
+#
+#  seq = Bio::Ensembl.human.exportview(1, 1000, 100000)
+#  gff = Bio::Ensembl.human.exportview(1, 1000, 100000, ['gene', 'variation', 'genscan'])
+#
+#  
+# == References
+#
+# * Ensembl
+#   http:/www.ensembl.org/
+#
+
+require 'bio/command'
+
+module Bio
+
+# == Description
+#
+# An Ensembl Genome Browser client class.
+#
+# == Examples
+#
+#  human = Bio::Ensembl.new('Homo_sapiens')
+#  seq = human.exportview(1, 1000, 100000)
+#  gff = human.exportview(1, 1000, 100000, ['gene'])
+#
+#  mouse = Bio::Ensembl.new('Mus_musculus')
+#  seq = mouse.exportview(1, 1000, 100000)
+#  gff = mouse.exportview(1, 1000, 100000, ['gene', 'variation', 'genscan'])
+#
+#  rice = Bio::Enesmbl.new('Oryza_sativa', 'http://www.gramene.org')
+#  seq = rice.exportview(1, 1000, 100000)
+#
+# == References
+#
+# * Ensembl
+#   http:/www.ensembl.org/
+#
+# * GRAMENE
+#   http://www.gramene.org/
+#
+class Ensembl
+  
+  ENSEMBL_URL = 'http://www.ensembl.org'
+
+  # Server URL (ex. 'http://www.ensembl.org')
+  attr_reader :server
+
+  # Organism name. (ex. 'Homo_sapiens').
+  attr_reader :organism
+
+  def initialize(organism, server = nil)
+    @server = server || ENSEMBL_URL
+    @organism = organism
+    @uri = [ @server.chomp('/'), @organism ].join('/')
+  end
+
+  def self.human
+    self.new("Homo_sapiens")
+  end
+
+  def self.mouse
+    self.new("Mus_musculus")
+  end
+
+  # Ensembl ExportView Client.
+  #
+  # Retrieve genomic sequence/features from Ensembl ExportView in plain text.
+  # Ensembl ExportView exports genomic data (sequence and features) in 
+  # several file formats including fasta, GFF and tab.
+  #
+  # * ExportViwe (http://www.ensembl.org/Homo_sapiens/exportview).
+  #
+  # == Examples
+  #
+  #   human = Bio::Ensembl.new('Homo_sapiens')
+  #     or
+  #   human = Bio::Ensembl.human
+  #
+  #   # Genomic sequence in Fasta format
+  #   human.exportview(:seq_region_name => 1, 
+  #                    :anchor1 => 1149206, :anchor2 => 1149229)
+  #   human.exportview(1, 1149206, 1149229)
+  #
+  #   # Feature in GFF
+  #   human.exportview(:seq_region_name => 1, 
+  #                    :anchor1 => 1149206, :anchor2 => 1150000, 
+  #                    :options => ['similarity', 'repeat', 
+  #                                 'genscan', 'variation', 'gene'])
+  #   human.exportview(1, 1149206, 1150000, ['variation', 'gene'])
+  #   
+  # Feature in TAB
+  #   human.exportview(:seq_region_name => 1, 
+  #                    :anchor1 => 1149206, :anchor2 => 1150000, 
+  #                    :options => ['similarity', 'repeat', 
+  #                                 'genscan', 'variation', 'gene'],
+  #                    :format => 'tab')
+  #
+  # == Arguments
+  #
+  # Bio::Ensembl#exportview method allow both orderd arguments and 
+  # named arguments. (Note: mandatory arguments are marked by '*').
+  #
+  # === Orderd Arguments
+  #
+  # 1. seq_region_name - Chromosome number (*)
+  # 2. anchor1         - From coordination (*)
+  # 3. anchor2         - To coordination (*)
+  # 4. options         - Features to export (in :format => 'gff' or 'tab')
+  #                      ['similarity', 'repeat', 'genscan', 'variation', 
+  #                       'gene']
+  #
+  # === Named Arguments
+  # 
+  # * :seq_region_name - Chromosome number (*)
+  # * :anchor1         - From coordination (*)
+  # * :anchor2         - To coordination (*)
+  # * :type1           - From coordination type ['bp', ]
+  # * :type2           - To coordination type ['bp', ]
+  # * :upstream        - Bp upstream
+  # * :downstream      - Bp downstream
+  # * :format          - File format ['fasta', 'gff', 'tab']
+  # * :options         - Features to export (for :format => 'gff' or 'tab')
+  #                      ['similarity', 'repeat', 'genscan', 'variation', 
+  #                       'gene']
+  # 
+  def exportview(*args)
+    defaults = {
+      :type1 => 'bp', 
+      :type2 => 'bp', 
+      :downstream => '', 
+      :upstream => '', 
+      :format => 'fasta',
+      :options => [],
+      :action => 'export', 
+      :_format => 'Text', 
+      :output => 'txt', 
+      :submit => 'Continue >>'
+    }
+
+    if args.first.class == Hash
+      options = args.first
+      if options[:options] and options[:format] != 'fasta' and options[:format] != 'tab' 
+        options.update({:format => 'gff'}) 
+      end
+    else
+      options = {
+        :seq_region_name => args[0], 
+        :anchor1 => args[1], 
+        :anchor2 => args[2],
+      }
+
+      case args[3]
+      when Array
+        options.update({:format => 'gff', :options => args[3]}) 
+      when Hash
+        options.update(args[3])
+      end
+
+      if args[4].class == Hash
+        options.update(args[4])
+      end
+    end
+
+    params = defaults.update(options)
+
+    result, = Bio::Command.post_form("#{@uri}/exportview", params)
+
+    return result.body
+  end
+
+end # class Ensembl
+
+end # module Bio
+
+
+
+# Codes for backward-compatibility.
+#
+class Bio::Ensembl
+  EBIServerURI = ENSEMBL_URL
+
+  def self.server_uri(uri = nil)
+    if uri
+      @uri = uri
+    else
+      @uri || EBIServerURI
+    end
+  end
+    
+  class Base
+    def self.exportview(*args)
+      Bio::Ensembl.new(Organism).exportview(*args)
+    end
+  end
+  
+  class Human < Base
+    Organism = Bio::Ensembl.human.organism
+  end
+  
+  class Mouse < Base
+    Organism = Bio::Ensembl.mouse.organism
+  end
+end # class Bio::Ensembl
+
+
+
+

data/lib/bio/io/fastacmd.rb

@@ -4,36 +4,42 @@
 # Copyright::  Copyright (C) 2005, 2006
 #              Shuji SHIGENOBU <shige@nibb.ac.jp>,
 #              Toshiaki Katayama <k@bioruby.org>,
-#              Mitsuteru C. Nakao <n@bioruby.org>
-# Lisence::    LGPL
+#              Mitsuteru C. Nakao <n@bioruby.org>,
+#              Jan Aerts <jan.aerts@bbsrc.ac.uk>
+# License::    The Ruby License
 #
-# $Id: fastacmd.rb,v 1.10 2006/01/28 08:12:21 nakao Exp $
+# $Id: fastacmd.rb,v 1.16 2007/04/05 23:35:41 trevor Exp $
 #
-# == Description
+
+require 'bio/db/fasta'
+require 'bio/io/flatfile'
+require 'bio/command'
+
+module Bio
+class Blast
+
+# = DESCRIPTION
 #
-# Retrives FASTA formatted sequences from a blast database using 
+# Retrieves FASTA formatted sequences from a blast database using 
 # NCBI fastacmd command.
 # 
 # This class requires 'fastacmd' command and a blast database  
 # (formatted using the '-o' option of 'formatdb').
 #
-# == Examples
+# = USAGE
+#  require 'bio'
+#  
+#  fastacmd = Bio::Blast::Fastacmd.new("/db/myblastdb")
 #
-#    database = ARGV.shift || "/db/myblastdb"
-#    entry_id = ARGV.shift || "sp:128U_DROME"
-#    ent_list = ["sp:1433_SPIOL", "sp:1432_MAIZE"]
+#  entry = fastacmd.get_by_id("sp:128U_DROME")
+#  fastacmd.fetch("sp:128U_DROME")
+#  fastacmd.fetch(["sp:1433_SPIOL", "sp:1432_MAIZE"])
 #
-#    fastacmd = Bio::Blast::Fastacmd.new(database)
+#  fastacmd.fetch(["sp:1433_SPIOL", "sp:1432_MAIZE"]).each do |fasta|
+#    puts fasta
+#  end
 #
-#    entry = fastacmd.get_by_id(entry_id)
-#    fastacmd.fetch(entry_id)
-#    fastacmd.fetch(ent_list)
-#
-#    fastacmd.fetch(ent_list).each do |fasta|
-#      puts fasta
-#    end
-#
-# == References
+# = REFERENCES
 #
 # * NCBI tool
 #   ftp://ftp.ncbi.nih.gov/blast/executables/LATEST/ncbi.tar.gz
@@ -41,78 +47,65 @@
 # * fastacmd.html
 #   http://biowulf.nih.gov/apps/blast/doc/fastacmd.html
 #
-#--
-#
-#  This library is free software; you can redistribute it and/or
-#  modify it under the terms of the GNU Lesser General Public
-#  License as published by the Free Software Foundation; either
-#  version 2 of the License, or (at your option) any later version.
-#
-#  This library is distributed in the hope that it will be useful,
-#  but WITHOUT ANY WARRANTY; without even the implied warranty of
-#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-#  Lesser General Public License for more details.
-#
-#  You should have received a copy of the GNU Lesser General Public
-#  License along with this library; if not, write to the Free Software
-#  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
-#
-#++
-#
-
-require 'bio/db/fasta'
-require 'bio/io/flatfile'
-require 'bio/command'
-
-module Bio
-class Blast
-
-# NCBI fastacmd wrapper class
-#
 class Fastacmd
 
   include Enumerable
-  include Bio::Command::Tools
 
   # Database file path.
   attr_accessor :database
 
-  # fastcmd command file path.
+  # fastacmd command file path.
   attr_accessor :fastacmd
 
+  # This method provides a handle to a BLASTable database, which you can then
+  # use to retrieve sequences.
   # 
-  attr_accessor :errorlog
-
-  # Initalize a fastacmd object.
-  #    
-  #    fastacmd = Bio::Blast::Fastacmd.new("/db/myblastdb")
+  # Prerequisites:
+  # * You have created a BLASTable database with the '-o T' option.
+  # * You have the NCBI fastacmd tool installed.
+  #
+  # For example, suppose the original input file looks like:
+  #  >my_seq_1
+  #  ACCGACCTCCGGAACGGATAGCCCGACCTACG
+  #  >my_seq_2
+  #  TCCGACCTTTCCTACCGCACACCTACGCCATCAC
+  #  ...
+  # and you've created a BLASTable database from that with the command
+  #  cd /my_dir/
+  #  formatdb -i my_input_file -t Test -n Test -o T
+  # then you can get a handle to this database with the command
+  #  fastacmd = Bio::Blast::Fastacmd.new("/my_dir/Test")
+  # ---
+  # *Arguments*:
+  # * _database_:: path and name of BLASTable database
   def initialize(blast_database_file_path)
     @database = blast_database_file_path
     @fastacmd = 'fastacmd'
   end
 
 
-  # get an entry_id and returns a Bio::FastaFormat object.
-  #
-  #   entry_id = "sp:128U_DROME"
-  #   entry = fastacmd.get_by_id(entry_id)
+  # Get the sequence of a specific entry in the BLASTable database.
+  # For example:
+  #  entry = fastacmd.get_by_id("sp:128U_DROME")
+  # ---
+  # *Arguments*:
+  # * _id_: id of an entry in the BLAST database
+  # *Returns*:: a Bio::FastaFormat object
   def get_by_id(entry_id)
     fetch(entry_id).shift
   end
 
-  # get one or more entry_id and returns an Array of Bio::FastaFormat objects.
-  #
-  # Fastacmd#fetch(entry_id) returns an Array of a Bio::FastaFormat
-  # object even when the result is a single entry.
+  # Get the sequence for a _list_ of IDs in the database.
   #
-  #    p fastacmd.fetch(entry_id)
-  #
-  # Fastacmd#fetch method also accepts a list of entry_id and returns
-  # an Array of Bio::FastaFormat objects.
-  #    
-  #    ent_list = ["sp:1433_SPIOL", "sp:1432_MAIZE"]
-  #    p fastacmd.fetch(ent_list)
+  # For example:
+  #  p fastacmd.fetch(["sp:1433_SPIOL", "sp:1432_MAIZE"])
   #
+  # This method always returns an array of Bio::FastaFormat objects, even when 
+  # the result is a single entry.
+  # ---
+  # *Arguments*:
+  # * _ids_: list of IDs to retrieve from the database
+  # *Returns*:: array of Bio::FastaFormat objects
   def fetch(list)
     if list.respond_to?(:join)
       entry_id = list.join(",")
@@ -121,24 +114,24 @@ class Fastacmd
     end
 
     cmd = [ @fastacmd, '-d', @database, '-s', entry_id ]
-    call_command_local(cmd) do |inn, out|
-      inn.close_write
-      Bio::FlatFile.new(Bio::FastaFormat, out).to_a
+    Bio::Command.call_command(cmd) do |io|
+      io.close_write
+      Bio::FlatFile.new(Bio::FastaFormat, io).to_a
     end
   end
 
-  # Iterates each entry.
-  #
-  # You can also iterate on all sequences in the database!
-  #    fastacmd.each do |fasta|
-  #      p [ fasta.definition[0..30], fasta.seq.size ]
-  #    end
+  # Iterates over _all_ sequences in the database.
   #
+  #  fastacmd.each_entry do |fasta|
+  #    p [ fasta.definition[0..30], fasta.seq.size ]
+  #  end
+  # ---
+  # *Returns*:: a Bio::FastaFormat object for each iteration
   def each_entry
-    cmd = [ @fastacmd, '-d', @database, '-D', 'T' ]
-    call_command_local(cmd) do |inn, out|
-      inn.close_write
-      Bio::FlatFile.open(Bio::FastaFormat, out) do |f|
+    cmd = [ @fastacmd, '-d', @database, '-D', '1' ]
+    Bio::Command.call_command(cmd) do |io|
+      io.close_write
+      Bio::FlatFile.open(Bio::FastaFormat, io) do |f|
         f.each_entry do |entry|
           yield entry
         end
@@ -153,4 +146,18 @@ end # class Fastacmd
 end # class Blast
 end # module Bio
 
+if $0 == __FILE__
+  fastacmd = Bio::Blast::Fastacmd.new("/path_to_my_db/db_name")
+  seq = fastacmd.get_by_id('id_of_entry1')
+  puts seq.class
+  puts seq
+  
+  seqs = fastacmd.fetch(['id_of_entry1','id_of_entry2'])
+  seqs.each do |seq|
+    puts seq
+  end
 
+  fastacmd.each_entry do |fasta|
+    puts fasta.seq.size.to_s + "\t" + fasta.definition
+  end
+end