bio 0.7.0

data/doc/TODO.rd.ja

@@ -0,0 +1,138 @@
+=begin
+
+  $Id: TODO.rd.ja,v 1.16 2004/08/24 00:18:03 k Exp $
+
+  Copyright (C) 2001, 2002 KATAYAMA Toshiaki <k@bioruby.org>
+
+= TODO
+
+* �����꡼��
+
+* �ɥ�����ȹ���
+  * ���塼�ȥꥢ���ɵ�
+  * �Ѹ첽
+  * RDoc
+
+* ����ץ����� (*2tab �Ȥ�)
+  * sample/README.rd[.ja]
+
+* cvs.open-bio.org �Υɥ�����ȹ���
+
+* Bio::SQL update, name space
+
+* Bio::Fetch
+  * E-Utils
+  * http://www.ncbi.nlm.nih.gov/entrez/query/static/eutils_help.html
+
+
+* Bio::Location location coordinate system (style)
+
+* GenBank, EMBL, SPTR, BioSQL �����硢�ե����ޥå�����Ѵ�
+  * genbank/ @moltype
+  * bio/db/seqentry.rb �� bio/seqentry.rb ������˥���ƥ� SeqEntry ����
+    * InternalSeq �Ȥ��Ǥ⡩
+  * lib/bio/db/genbank/, embl/ ��ե��������
+    * Bio::SQL::Sequence ��ޤ᤿������¤
+    * genpept, refseq(NP_)
+    * Bio::Reference ���饹 �� EMBL �ˤ�?
+  * test GenBank >350k
+
+* Blast, Fasta, Hmmer
+  * blast, hmmer �Υ�ݡ��� -> Bio::FlatFile ����⥢������
+  * bio/appl/fasta/report.rb, bio/appl/hmmer/report.rb ����ƥʳ��Ф�
+  * lib/bio/appl/blast/xmlparser.rb  " problem
+  * lib/bio/appl/megablast.rb �ɲá�
+  * Blast HSP tiling [bioperl-l 2002 8/13,4,5 ?]
+    * Bio::Blast::Report::Hit#total_alignment_length
+    * Bio::Blast::Report::Hit#total_identical_residues
+    * Bio::Blast::Report::Hit#total_convserved_residues
+
+* MAFFT, T-Coffee, CLUSTALW �� ���饤�����
+  * ���饤���ȥ��֥�������
+    * class Bio::Alignment ?
+    * class Bio::Alignment::Pairwise or class Bio::PairwiseAlignment ?
+    * class Bio::Alignment::Multiple or class Bio::MultipleAlignment ?
+    * ���饤���ȥӥ塼����ۤ���
+  * Blast refactering
+  * AlignFactory -> SearchIO��
+  * Bio::Align �� Bio::Blast::Report �ʤɤΥ��饤���Ȥ�
+    �ݻ�����ΤˤĤ���
+  * ���饤����ȥ��饹�� CIGAR �ե����ޥå�
+
+* KGML�ѡ���
+  * Pathway���饹��dijkstra -> Graph
+  * Tree���饹
+
+* lib/bio/db/kegg/keggtab.rb �� lib/bio/data/keggorg.rb �����硩
+
+* Bio::LSID [bioperl-l 2002 7/15 seq namespace method]
+
+* �����ǥ��󥰥�������
+  * camelCase �ػ�
+  * = �κ����϶�����
+  * tab �ʤ� 2 ���ڡ�������ǥ��
+  * �ǽ�Ū�ˤ� RDoc �ղá� (Rimport ��Ȥ��Τ���������)
+  * ���饹̾���⥸�塼��̾�� camelCase���������ʸ���� _ �Ƕ��ڤ�
+  * Array, Hash�ʾ�˥ͥ��Ȥ����饯�饹��������
+
+=== DB
+
+* ����ȥ����� (GO etc.) ������
+
+* ������շ� InterPro (incl. Pfam etc.) ������
+
+* SSDB
+
+* COG
+
+* PDB or PDBj �ѡ���
+  * challange CASP? :)
+
+=== ����
+
+* Ruby 1.8
+  * stringIO
+  * autoload
+  * Array.new(num) { Hoge.new }
+
+* ext/
+  * �������٤��᥽�å� C �� ?
+
+* ����֤�ѥ��벽���뤿��Υ��饹
+
+* �ƥ��ȴĶ�������
+  * Test::Unit �Ȥ���
+    * �����ե����롢�ͥåȥ����������ɤ����뤫
+  * ���󥹥ȡ������ make check �ߤ����ʤ��Ȥ򤹤뤫
+
+* ����å�
+  * ���ΤȤ������ޤ�Ȥ����̤Ϥʤ������Τ�ʤ����ɡ� GUI �Ȥ��ǡ�
+
+* �ɥ����������
+  * Thai
+  * Korea
+  * Russia
+  * French
+
+== OTHERS
+
+* midi
+
+* q--p
+  * RSS
+  * tDiary
+
+* gb.bioruby.org �� GFF, DAS �б�
+  * �ݥ������������ץ�ʥ��ޥ�ɥ饤��/CGI��
+  * Ming��
+
+* R, SVM/RVM, ����� ��
+
+* Ruby/Cocoa, Ruby/Gtk �ˤ�� GUI �ʥե����ȥ꡼
+  * gsequence
+  * biograph
+  * GO �� xml �� GtkTree �� ����­��̡�
+
+* ��
+
+=end

data/doc/Tutorial.rd

@@ -0,0 +1,1138 @@
+=begin
+
+  $Id: Tutorial.rd,v 1.9 2005/11/01 04:31:48 nakao Exp $
+
+Copyright (C) 2001-2003 KATAYAMA Toshiaki <k@bioruby.org>
+
+Translated into English: Naohisa Goto <ng@bioruby.org>
+
+Edited by:               PjotrPrins
+
+NOTE: This page is a work in progress at this point
+
+IMPORTANT NOTICE: This page is maintained in the BioRuby CVS
+repository. Please edit the file there otherwise changes may get
+lost. See ((<BioRuby Developer Information>)) for CVS and mailing list
+access.
+
+= BioRuby Tutorial
+
+== Introduction
+
+This is a tutorial for using Bioruby. For BioRuby you need to install
+Ruby and the BioRuby package on your computer. For each following the
+instruction on the respective websites. (EDITOR's NOTE: include URL's)
+
+(EDITOR's NOTE: describe rdoc use for individual classes)
+
+For further information on the Ruby language see the section 'Further
+reading' at the end.
+
+You can check whether Ruby is installed on your computer and what
+version it has with the
+
+	% ruby -v
+
+command. Showing something like:
+
+  ruby 1.8.2 (2005-04-11) [powerpc-linux]
+
+
+== Trying Bioruby
+
+Bioruby comes with its own shell. After unpacking the sources run the
+following command
+
+  $BIORUBY/bin/bioruby
+
+and you should see a prompt
+
+  bioruby>
+
+Now test the following:
+
+  bioruby> seq = Bio::Sequence::NA.new("atgcatgcaaaa")
+  bioruby> puts seq
+  atgcatgcaaaa
+  bioruby> puts seq.complement 
+  ttttgcatgcat
+
+== Working with nucleic / amino acid sequences (Bio::Sequence class)
+
+The Bio::Sequence class allows the usual sequence transformations and
+translations.  In the example below the DNA sequence "atgcatgcaaaa" is
+converted into the complemental strand, spliced into a subsequence,
+next the nucleic acid composition is calculated and the sequence is
+translated into the amino acid sequence, the molecular weight
+calculated, and so on. When translating into amino acid sequences the
+frame can be specified and optionally the condon table selected (as
+defined in codontable.rb).
+
+
+    #!/usr/bin/env ruby
+
+    require 'bio'
+
+    seq = Bio::Sequence::NA.new("atgcatgcaaaa")
+
+    puts seq                            # original sequence
+    puts seq.complement                 # complemental sequence (Bio::Sequence::NA object)
+    puts seq.subseq(3,8)                # gets subsequence of positions 3 to 8
+
+    p seq.gc_percent                    # GC percent (BioRuby 0.6.X: Float, BioRuby 0.7 or later: Integer)
+    p seq.composition                   # nucleic acid compositions (Hash)
+
+    puts seq.translate                  # translation (Bio::Sequence::AA object)
+    puts seq.translate(2)               # translation from frame 2 (default is frame 1)
+    puts seq.translate(1,11)            # using codon table No.11 (see http://www.ncbi.nlm.nih.gov/Taxonomy/Utils/wprintgc.cgi)
+
+    p seq.translate.codes               # shows three-letter codes (Array)
+    p seq.translate.names               # shows amino acid names (Array)
+    p seq.translate.composition         # amino acid compositions (Hash)
+    p seq.translate.molecular_weight    # calculating molecular weight (Float)
+
+    puts seq.complement.translate       # translation of complemental strand
+
+The p, print and puts methods are standard Ruby ways of outputting to
+the screen. If you want to know more about standard Ruby commands you
+can use the 'ri' command on the command line (or the help command in
+Windows). For example
+
+  % ri puts
+  % ri p
+  % ri File.open
+
+Nucleic acid sequence is an object of +Bio::Sequence::NA+ class, and
+amino acid sequence is an object of +Bio::Sequence::AA+ class.  Shared
+methods are in the parent +Bio::Sequence+ class.
+
+As Bio::Sequence class inherits Ruby's String class, you can use
+String class methods. For example, to get a subsequence, you can
+not only use subseq(from, to) but also String#[].
+
+Please take note that the Ruby's string's are base 0 - i.e. the first letter
+has index 0, for example:
+
+  s = 'abc'
+  puts s[0..0]
+
+  >a
+
+So when using String methods, you should subtract 1 from positions
+conventionally used in biology.  (subseq method returns nil if you
+specify positions smaller than or equal to 0 for either one of the
+"from" or "to".)
+
+(EDITOR'S NOTE: should 'subseq' not throw an exception instead?)
+
+The window_search(window_size, step_size) method shows a typical Ruby
+way of writing concise and clear code using 'closures'. Each sliding
+window creates a subsequence which is supplied to the enclosed block
+through a variable named +s+.
+
+* Shows average percentage of GC content for 100 bases (stepping
+the default one base at a time)
+
+    seq.window_search(100) do |s|
+      puts s.gc_percent
+    end
+
+Since the class of each subsequence is the same as original sequence
+(Bio::Sequence::NA or Bio::Sequence::AA or Bio::Sequence), you can
+use all methods on the subsequence. For example,
+
+* Shows translation results for 15 bases shifting a codon at a time
+
+    seq.window_search(15, 3) do |s|
+      puts s.translate
+    end
+
+Finally, the window_search method returns the last leftover
+subsequence. This allows for example
+
+* Divide a genome sequence into sections of 10000bp and
+  output FASTA formatted sequences. The 1000bp at the start and end of
+	each subsequence overlapped. At the 3' end of the sequence the
+  leftover subsequence shorter than 10000bp is also added
+
+    i = 1
+    remainder = seq.window_search(10000, 9000) do |s|
+      puts s.to_fasta("segment #{i}", 60)
+      i += 1
+    end
+    puts remainder.to_fasta("segment #{i}", 60)
+
+If you don't want the overlapping window, set window size and stepping
+size to equal values.
+
+Other examples
+
+* Count the codon usage
+
+    codon_usage = Hash.new(0)
+    seq.window_search(3, 3) do |s|
+      codon_usage[s] += 1
+    end
+
+* Calculate molecular weight for each 10-aa peptide (or 10-nt nucleic acid)
+
+    seq.window_search(10, 10) do |s|
+      puts s.molecular_weight
+    end
+
+In most cases, sequences are read from files or retrieved from databases.
+For example:
+
+    require 'bio'
+
+    input_seq = ARGF.read       # reads all files in arguments
+
+    my_naseq = Bio::Sequence::NA.new(input_seq)
+    my_aaseq = my_naseq.translate
+
+    puts my_aaseq
+
+Save the program as na2aa.rb. Prepare a nucleic acid sequence
+described below and saves it as my_naseq.txt:
+
+      gtggcgatctttccgaaagcgatgactggagcgaagaaccaaagcagtgacatttgtctg
+      atgccgcacgtaggcctgataagacgcggacagcgtcgcatcaggcatcttgtgcaaatg
+      tcggatgcggcgtga
+
+na2aa.rb translates a nucleic acid sequence to a protein sequence.
+For example, translates my_naseq.txt:
+
+    % ruby na2aa.rb my_naseq.txt
+
+Outputs
+
+    VAIFPKAMTGAKNQSSDICLMPHVGLIRRGQRRIRHLVQMSDAA*
+
+You can also write this, a bit fanciful, as a one-liner script.
+
+    % ruby -r bio -e 'p Bio::Sequence::NA.new($<.read).translate' my_naseq.txt
+
+In the next section we will retrieve data from databases instead of
+using raw sequence files.
+
+== Parsing GenBank data (Bio::GenBank class)
+
+We assume that you already have some GenBank data files. (If you don't,
+download some .seq files from ftp://ftp.ncbi.nih.gov/genbank/)
+
+As an example we fetch the ID, definition and sequence of each entry
+from the GenBank format and convert it to FASTA. This is also an example
+script in the BioRuby distribution.
+
+A first attempt could be to use the Bio::GenBank class for reading in
+the data:
+
+    #!/usr/bin/env ruby
+
+    require 'bio'
+
+    # Read all lines from STDIN split by the GenBank delimiter
+    while entry = gets(Bio::GenBank::DELIMITER)
+      gb = Bio::GenBank.new(entry)      # creates GenBank object
+
+      print ">#{gb.accession} "         # Accession
+      puts gb.definition                # Definition
+      puts gb.naseq                     # Nucleic acid sequence (Bio::Sequence::NA object)
+    end
+
+But that has the disadvantage the code is tied to GenBank input. A more
+generic method is to use Bio::FlatFile which allows you to use different
+input formats:
+
+    #!/usr/bin/env ruby
+  
+    require 'bio'
+    
+    ff = Bio::FlatFile.new(Bio::GenBank, ARGF)
+    ff.each_entry do |gb|
+      definition = "#{gb.accession} #{gb.definition}"
+      puts gb.naseq.to_fasta(definition, 60)
+    end
+
+For example, in turn, reading FASTA format files:
+
+    #!/usr/bin/env ruby
+
+    require 'bio'
+
+    ff = Bio::FlatFile.new(Bio::FastaFormat, ARGF)
+    ff.each_entry do |f|
+      puts "definition : " + f.definition
+      puts "nalen      : " + f.nalen.to_s
+      puts "naseq      : " + f.naseq
+    end
+
+In above two scripts, the first arguments of Bio::FlatFile.new are
+database classes of BioRuby. This is expanded on in a later section.
+
+Again another option is to use the Bio::DB.open class:
+
+    #!/usr/bin/env ruby
+
+    require 'bio'
+
+    ff = Bio::GenBank.open("gbvrl1.seq")
+    ff.each_entry do |gb|
+      definition = "#{gb.accession} #{gb.definition}"
+      puts gb.naseq.to_fasta(definition, 60)
+    end
+
+(TRANSLATOR'S NOTE: Bio::DB.open have not been used so well.)
+(EDITOR's NOTE: Test code)
+
+Next, we are going to parse the GenBank 'features', which is normally
+very complicated:
+
+    #!/usr/bin/env ruby
+
+    require 'bio'
+
+    ff = Bio::FlatFile.new(Bio::GenBank, ARGF)
+
+    # iterates over each GenBank entry
+    ff.each_entry do |gb|
+
+      # shows accession and organism
+      puts "# #{gb.accession} - #{gb.organism}"
+
+      # iterates over each element in 'features'
+      gb.features.each do |feature|
+        position = feature.position
+        hash = feature.assoc            # put into Hash
+
+        # skips the entry if "/translation=" is not found
+        next unless hash['translation']
+
+        # collects gene name and so on and joins it into a string
+        gene_info = [
+          hash['gene'], hash['product'], hash['note'], hash['function']
+        ].compact.join(', ')
+
+        # shows nucleic acid sequence
+        puts ">NA splicing('#{position}') : #{gene_info}"
+        puts gb.naseq.splicing(position)
+
+        # shows amino acid sequence translated from nucleic acid sequence
+        puts ">AA translated by splicing('#{position}').translate"
+        puts gb.naseq.splicing(position).translate
+
+        # shows amino acid sequence in the database entry (/translation=)
+        puts ">AA original translation"
+        puts hash['translation']
+      end
+    end
+
+* Note: In this example Feature#assoc method makes a Hash from a
+  feature object. It is useful because you can get data from the hash
+  by using qualifiers as keys.
+  (But there is a risk some information is lost when two or more
+  qualifiers are the same. Therefore an Array is returned by
+  Feature#feature)
+
+Bio::Sequence#splicing splices subsequence from nucleic acid sequence
+according to location information used in GenBank, EMBL and DDBJ.
+
+When the specified translation table is different from the default
+(universal), or when the first codon is not "atg" or the protein
+contains selenocysteine, the two amino acid sequences will differ.
+
+The Bio::Sequence#splicing method takes not only DDBJ/EMBL/GenBank
+feature style location text but also Bio::Locations object. For more
+information about location format and Bio::Locations class, see
+bio/location.rb.
+
+* Splice according to location string used in a GenBank entry
+
+    naseq.splicing('join(2035..2050,complement(1775..1818),13..345')
+
+* Generate Bio::Locations object and pass the splicing method
+
+    locs = Bio::Locations.new('join((8298.8300)..10206,1..855)')
+    naseq.splicing(locs)
+
+You can also use the splicing method for amino acid sequences
+(Bio::Sequence::AA objects).
+
+* Splicing peptide from a protein (e.g. signal peptide)
+
+    aaseq.splicing('21..119')
+
+(EDITOR's NOTE: why use STRINGs here?)
+
+=== More databases
+
+Databases in BioRuby are essentially accessed like that of GenBank
+with classes like Bio::GenBank, Bio::KEGG::GENES,
+(EDITOR's NOTE: include complete list)
+
+In many cases the Bio::DatabaseClass acts as a factory pattern
+and recognises the database type automatically - returning a
+parsed object. For example using Bio::FlatFile
+
+Bio::FlatFile class as described above. The first argument of the
+Bio::FlatFile.new is database class name in BioRuby (such as Bio::GenBank,
+Bio::KEGG::GENES and so on).
+
+    ff = Bio::FlatFile.new(Bio::DatabaseClass, ARGF)
+
+Isn't it wonderful that Bio::FlatFile automagically recognizes each
+database class?
+
+    #!/usr/bin/env ruby
+
+    require 'bio'
+
+    ff = Bio::FlatFile.auto(ARGF)
+    ff.each_entry do |entry|
+      p entry.entry_id          # identifier of the entry
+      p entry.definition        # definition of the entry
+      p entry.seq               # sequence data of the entry
+    end
+
+Other methods to extract specific data from database objects can be
+different between databases, though some methods are common (see the
+guidelines for common methods as described in bio/db.rb).
+
+  * entry_id --> gets ID of the entry
+  * definition --> gets definition of the entry
+  * reference --> gets references as Bio::Reference object
+  * organism --> gets species
+  * seq, naseq, aaseq --> returns sequence as corresponding sequence object
+
+Refer to the documents of each database to find the exact naming
+of the included methods.
+
+In principal BioRuby uses the following conventions: when a method
+name is plural the method returns some object as an Array. For
+example, some classes have a "references" method which returns
+multiple Bio::Reference objects as an Array. And some classes have a
+"reference" method which returns a single Bio::Reference object.
+
+=== Alignments (Bio::Alignment)
+
+Bio::Alignment class in bio/alignment.rb is a container class like Ruby's Hash,
+Array and BioPerl's Bio::SimpleAlign.  A very simple example is:
+
+  require 'bio'
+
+  seqs = [ 'atgca', 'aagca', 'acgca', 'acgcg' ]
+  seqs = seqs.collect{ |x| Bio::Sequence::NA.new(x) }
+
+  # creates alignment object
+  a = Bio::Alignment.new(seqs)
+
+  # shows consensus sequence
+  p a.consensus             # ==> "a?gc?"
+
+  # shows IUPAC consensus
+  p a.consensus_iupac       # ==> "ahgcr"
+
+  # iterates over each seq
+  a.each { |x| p x }
+    # ==>
+    #    "atgca"
+    #    "aagca"
+    #    "acgca"
+    #    "acgcg"
+  # iterates over each site
+  a.each_site { |x| p x }
+    # ==>
+    #    ["a", "a", "a", "a"]
+    #    ["t", "a", "c", "c"]
+    #    ["g", "g", "g", "g"]
+    #    ["c", "c", "c", "c"]
+    #    ["a", "a", "a", "g"]
+
+  # doing alignment by using CLUSTAL W.
+  # clustalw command must be installed.
+  factory = Bio::ClustalW.new
+  a2 = a.do_align(factory)
+
+
+== Sequence homology search by using the FASTA program (Bio::Fasta)
+
+Let's start with a query.pep file which contains a sequence in FASTA
+format.  In this example we are going to execute a homology search
+from a remote internet site or on your local machine. Note that you
+can use the ssearch program instead of fasta when you use them in your
+local machine.
+
+=== using FASTA in local machine
+
+Install the fasta program on your machine (the command name looks like
+fasta34. FASTA can be downloaded from ftp://ftp.virginia.edu/pub/fasta/).
+First, you must prepare your FASTA-formatted database sequence file
+target.pep and FASTA-formatted query.pep.  (TRANSLATOR'S NOTE: I think
+we should provide sample data to readers.)
+
+    #!/usr/bin/env ruby
+
+    require 'bio'
+
+    # Creates FASTA factory object ("ssearch" instead of "fasta34" can also work)
+    factory = Bio::Fasta.local('fasta34', ARGV.pop)
+    (EDITOR's NOTE: not consistent pop command)
+
+    # Reads FASTA-formatted files (TRANSLATOR'S NOTE: something wrong in Japanese text)
+    ff = Bio::FlatFile.new(Bio::FastaFormat, ARGF)
+
+    # Iterates over each entry. the variable "entry" is a Bio::FastaFormat object.
+    ff.each do |entry|
+      # shows definition line (begins with '>') to the standard error output
+      $stderr.puts "Searching ... " + entry.definition
+
+      # executes homology search. Returns Bio::Fasta::Report object.
+      report = factory.query(entry)
+
+      # Iterates over each hit
+      report.each do |hit|
+        # If E-value is smaller than 0.0001
+        if hit.evalue < 0.0001
+          # shows identifier of query and hit, E-value, start and end positions of homologous region (TRANSLATOR'S NOTE: should I change Japanese document?)
+          print "#{hit.query_id} : evalue #{hit.evalue}\t#{hit.target_id} at "
+          p hit.lap_at
+        end
+      end
+    end
+
+We named above script as f_search.rb. You can execute as follows:
+
+    % ./f_search.rb query.pep target.pep > f_search.out
+
+In above script, the variable "factory" is a factory object for executing
+FASTA many times easily. Instead of using Fasta#query method,
+Bio::Sequence#fasta method can be used.
+(TRANSLATOR'S NOTE: Bio::Sequence#fasta are not so frequently used.)
+
+    seq = ">test seq\nYQVLEEIGRGSFGSVRKVIHIPTKKLLVRKDIKYGHMNSKE"
+    seq.fasta(factory)
+
+When you want to add options to FASTA command, you can set the
+third argument of Bio::Fasta.local method. For example, setting ktup to 1
+and getting top-10 hits:
+
+    factory = Bio::Fasta.local('fasta34', 'target.pep', '-b 10')
+    factory.ktup = 1
+
+Bio::Fasta#query returns Bio::Fasta::Report object.
+We can get almost all information described in FASTA report text
+with the Report object. For example, getting information for hits:
+
+
+    report.each do |hit|
+      puts hit.evalue           # E-value
+      puts hit.sw               # Smith-Waterman score (*)
+      puts hit.identity         # % identity
+      puts hit.overlap          # length of overlapping region
+      puts hit.query_id         # identifier of query sequence
+      puts hit.query_def        # definition(comment line) of query sequence
+      puts hit.query_len        # length of query sequence
+      puts hit.query_seq        # query sequence (TRANSLATOR'S NOTE: sequence of homologous region of query sequence)
+      puts hit.target_id        # identifier of hit sequence
+      puts hit.target_def       # definition(comment line) of hit sequence
+      puts hit.target_len       # length of hit sequence
+      puts hit.target_seq       # hit sequence (TRANSLATOR'S NOTE: sequence of homologous region of hit sequence)
+      puts hit.query_start      # start position of homologous region in query sequence
+      puts hit.query_end        # end position of homologous region in query sequence
+      puts hit.target_start     # start posiotion of homologous region in hit(target) sequence
+      puts hit.target_end       # end position of homologous region in hit(target) sequence
+      puts hit.lap_at           # array of above four numbers
+    end
+
+Most of above methods are common with the Bio::Blast::Report described
+below. Please refer to document of Bio::Fasta::Report class for
+FASTA-specific details.
+
+If you need original output text of FASTA program you can use the "output"
+method of the factory object after the "query" method.
+
+    report = factory.query(entry)
+    puts factory.output
+
+
+=== using FASTA from a remote internet site
+
+* Note: Currently, only GenomeNet (fasta.genome.jp) is
+supported. check the class documentation for updates.
+
+For accessing a remote site the Bio::Fasta.remote method is used
+instead of Bio::Fasta.local.  When using a remote method, the
+databases available may be limited, but, otherwise, you can do the
+same things as with a local method.
+
+Available databases in GenomeNet:
+
+  * Protein database
+    * nr-aa, genes, vgenes.pep, swissprot, swissprot-upd, pir, prf, pdbstr
+
+  * Nucleic acid database
+    * nr-nt, genbank-nonst, gbnonst-upd, dbest, dbgss, htgs, dbsts,
+      embl-nonst, embnonst-upd, genes-nt, genome, vgenes.nuc
+
+Select the databases you require.  Next, give the search program from
+the type of query sequence and database.
+
+  * When query is a amino acid sequence
+    * When protein database, program is "fasta".
+    * When nucleic database, program is "tfasta".
+
+  * When query is a nucleic acid sequence
+    * When nucleic database, program is "fasta".
+    * (When protein database, you would fail to search.)
+
+For example:
+
+    program = 'fasta'
+    database = 'genes'
+
+    factory = Bio::Fasta.remote(program, database)
+
+and try out the same commands as with the local search shown earlier.
+
+== Homology search by using BLAST (Bio::Blast class)
+
+The BLAST interface is very similar to that of FASTA and
+both local and remote execution are supported. Basically
+replace above examples Bio::Fasta with Bio::Blast!
+
+For example the BLAST version of f_search.rb is:
+
+    # create BLAST factory object
+    factory = Bio::Blast.local('blastp', ARGV.pop)
+
+For remote execution of BLAST in GenomeNet, Bio::Blast.remote is used.
+The parameter "program" is different from FASTA - as you can expect:
+
+  * When query is a amino acid sequence
+    * When protein database, program is "blastp".
+    * When nucleic database, program is "tblastn".
+
+  * When query is a nucleic acid sequence
+    * When protein database, program is "blastx"
+    * When nucleic database, program is "blastn".
+    * ("tblastx" for six-frame search.)
+
+Bio::BLAST uses "-m 7" XML output of BLAST by default when either
+XMLParser or REXML (both of them are XML parser libraries for Ruby -
+of the two XMLParser is the fastest) is installed on your computer. In
+Ruby version 1.8.0, or later, REXML is bundled with Ruby's
+distribution.
+
+When no XML parser library is present, Bio::BLAST uses "-m 8" tabular
+deliminated format. Available information is limited with the
+"-m 8" format so installing an XML parser is recommended.
+
+Again, the methods in Bio::Fasta::Report and Bio::Blast::Report (and
+Bio::Fasta::Report::Hit and Bio::Blast::Report::Hit) are similar.
+There are some additional BLAST methods, for example, bit_score and
+midline.
+
+    report.each do |hit|
+      puts hit.bit_score        # bit score (*)
+      puts hit.query_seq        # query sequence (TRANSLATOR'S NOTE: sequence of homologous region of query sequence)
+      puts hit.midline          # middle line string of alignment of homologous region (*)
+      puts hit.target_seq       # hit sequence (TRANSLATOR'S NOTE: sequence of homologous region of query sequence)
+
+      puts hit.evalue           # E-value
+      puts hit.identity         # % identity
+      puts hit.overlap          # length of overlapping region
+      puts hit.query_id         # identifier of query sequence
+      puts hit.query_def        # definition(comment line) of query sequence
+      puts hit.query_len        # length of query sequence
+      puts hit.target_id        # identifier of hit sequence
+      puts hit.target_def       # definition(comment line) of hit sequence
+      puts hit.target_len       # length of hit sequence
+      puts hit.query_start      # start position of homologous region in query sequence
+      puts hit.query_end        # end position of homologous region in query sequence
+      puts hit.target_start     # start position of homologous region in hit(target) sequence
+      puts hit.target_end       # end position of homologous region in hit(target) sequence
+      puts hit.lap_at           # array of above four numbers
+    end
+
+For simplicity and API compatibility, some information such as score
+are extracted from the first Hsp (High-scoring Segment Pair).
+
+Check the documentation for Bio::Blast::Report to see what can be
+retrieved. For now suffice to state that Bio::Blast::Report has a
+hierarchical structure mirroring the general BLAST output stream:
+
+  * In a Bio::Blast::Report object, @iteratinos is an array of
+    Bio::Blast::Report::Iteration objects.
+    * In a Bio::Blast::Report::Iteration object, @hits is an array of
+      Bio::Blast::Report::Hits objects.
+      * In a Bio::Blast::Report::Hits object, @hsps is an array of
+        Bio::Blast::Report::Hsp objects.
+
+See bio/appl/blast.rb and bio/appl/blast/*.rb for more information.
+
+=== Parsing existing BLAST output files
+
+When you already have BLAST output files and you want to parse them,
+you can directly create Bio::Blast::Report objects without the
+Bio::Blast factory object. For this purpose use Bio::Blast.reports,
+which supports the "-m 0" default and "-m 7" XML type output format.
+
+    #!/usr/bin/env ruby
+
+    require 'bio'
+
+    # Iterates over each XML result.
+    # The variable "report" is a Bio::Blast::Report object.
+    Bio::Blast.reports(ARGF) do |report|
+      puts "Hits for " + report.query_def + " against " + report.db
+      report.each do |hit|
+        print hit.target_id, "\t", hit.evalue, "\n" if hit.evalue < 0.001
+      end
+    end
+
+Save the script as hits_under_0.001.rb and to process BLAST output
+files *.xml, you can
+
+   % ruby hits_under_0.001.rb *.xml
+
+Sometimes BLAST XML output may be wrong and can not be parsed. We
+recommended to install BLAST 2.2.5 or later, and try combinations of
+the -D and -m options when you encounter problems.
+
+
+=== Add remote BLAST search sites
+
+  Note: this section is an advanced topic
+
+Here a more advanced application for using BLAST sequence homology
+search services. BioRuby currently only supports GenomeNet. If you
+want to add other sites, you must write the following:
+
+  * the calling CGI (command-line options must be processed for the site).
+  * make sure you get BLAST output text as supported format by BioRuby
+    (e.g. "-m 8", "-m 7" or default("-m 0")).
+
+In addition, you must write a private class method in Bio::Blast
+named "exec_MYSITE" to get query sequence and to pass the result to
+Bio::Blast::Report.new(or Bio::Blast::Default::Report.new):
+
+    factory = Bio::Blast.remote(program, db, option, 'MYSITE')
+
+When you write above routines, please send to the BioRuby project and
+they may be included.
+
+== Generate a reference list using PubMed (Bio::PubMed)
+
+Below script is an example which seaches PubMed and creates a reference list.
+
+    #!/usr/bin/env ruby
+
+    require 'bio'
+
+    ARGV.each do |id|
+      entry = Bio::PubMed.query(id)     # searches PubMed and get entry
+      medline = Bio::MEDLINE.new(entry) # creates Bio::MEDLINE object from entry text
+      reference = medline.reference     # converts into Bio::Reference object
+      puts reference.bibtex             # shows BibTeX formatted text
+    end
+
+We named the script pmfetch.rb.
+
+    % ./pmfetch.rb 11024183 10592278 10592173
+
+To give some PubMed ID (PMID) in arguments, the script retrieves informations
+from NCBI, parses MEDLINE format text, converts into BibTeX format and
+shows them.
+
+A keyword search is also available.
+
+    #!/usr/bin/env ruby
+
+    require 'bio'
+
+    # Concatinates argument keyword list to a string
+    keywords = ARGV.join(' ')
+
+    # PubMed keyword search
+    entries = Bio::PubMed.search(keywords)
+
+    entries.each do |entry|
+      medline = Bio::MEDLINE.new(entry) # creates Bio::MEDLINE object from text
+      reference = medline.reference     # converts into Bio::Reference object
+      puts reference.bibtex             # shows BibTeX format text
+    end
+
+We named the script pmsearch.rb.
+
+    % ./pmsearch.rb genome bioinformatics
+
+To give keywords in arguments, the script searches PubMed by given
+keywords and shows bibliography informations in a BibTex format. Other
+output formats are also avaialble like the bibitem method described
+below. Some journal formats like nature and nar can be used, but lack
+bold and italic font output.
+
+(EDITORs NOTE: do we have some simple object that can be queried for
+author, title etc.?)
+
+Nowadays using NCBI E-Utils is recommended. Use Bio::PubMed.esearch
+and Bio::PubMed.efetch instead of above methods.
+
+
+    #!/usr/bin/env ruby
+
+    require 'bio'
+
+    keywords = ARGV.join(' ')
+
+    options = {
+      'maxdate' => '2003/05/31',
+      'retmax' => 1000,
+    }
+
+    entries = Bio::PubMed.esearch(keywords, options)
+
+    Bio::PubMed.efetch(entries).each do |entry|
+      medline = Bio::MEDLINE.new(entry)
+      reference = medline.reference
+      puts reference.bibtex
+    end
+
+The script works same as pmsearch.rb. But, by using NCBI E-Utils, more
+options are available. For example published dates to search and
+maximum number of hits to show results can be specified.
+
+See the ((<help page of
+E-Utils|URL:http://eutils.ncbi.nlm.nih.gov/entrez/query/static/eutils_help.html>))
+for more details.
+
+
+
+=== More about BibTeX
+
+In this section, we explain the simple usage of TeX for the BibTeX format
+bibliography list collected by above scripts. For example, to save
+BibTeX format bibliography data to a file named genoinfo.bib.
+
+    % ./pmfetch.rb 10592173 >> genoinfo.bib
+    % ./pmsearch.rb genome bioinformatics >> genoinfo.bib
+
+The BibTeX can be used with Tex or LaTeX to form bibliography
+information with your journal article. For more information
+on BibTex see (EDITORS NOTE: insert URL). A quick example:
+
+Save this to hoge.tex:
+
+    \documentclass{jarticle}
+    \begin{document}
+    \bibliographystyle{plain}
+    foo bar KEGG database~\cite{PMID:10592173} baz hoge fuga.
+    \bibliography{genoinfo}
+    \end{document}
+
+Then,
+
+    % latex hoge
+    % bibtex hoge # processes genoinfo.bib
+    % latex hoge  # creates bibliography list
+    % latex hoge  # inserts correct bibliography reference
+
+Now, you get hoge.dvi and hoge.ps - the latter you can view any
+Postscript viewer.
+
+=== Bio::Reference#bibitem
+
+When you don't want to create a bib file, you can use
+Bio::Reference#bibitem method instead of Bio::Reference#bibtex.
+In above pmfetch.rb and pmsearch.rb scripts, change
+
+    puts reference.bibtex
+to
+    puts reference.bibitem
+
+
+Output documents should be bundled in \begin{thebibliography}
+and \end{thebibliography}. Save the following to hoge.tex
+
+    \documentclass{jarticle}
+    \begin{document}
+    foo bar KEGG database~\cite{PMID:10592173} baz hoge fuga.
+
+    \begin{thebibliography}{00}
+
+    \bibitem{PMID:10592173}
+    Kanehisa, M., Goto, S.
+    KEGG: kyoto encyclopedia of genes and genomes.,
+    {\em Nucleic Acids Res}, 28(1):27--30, 2000.
+
+    \end{thebibliography}
+    \end{document}
+
+and run
+
+    % latex hoge   # creates bibliography list
+    % latex hoge   # inserts corrent bibliography reference
+
+
+= OBDA
+
+OBDA (Open Bio Database Access) is a standardized method of sequence
+database access developed by the Open Bioinformatics Foundation.  It
+was created during the BioHackathon by BioPerl, BioJava, BioPython,
+BioRuby and other projects' members (2002).
+
+* BioRegistry (Directory)
+  * Mechanism to specify how and where to retrieve sequence data for each database.
+
+* BioFlat
+  * Flatfile indexing by using binary tree or BDB(Berkeley DB).
+
+* BioFetch
+  * Server-client model for getting entry from database via http.
+
+* BioSQL
+  * Schemas to store sequence data to relational database such as
+    MySQL and PostgreSQL, and methods to retrieve entries from the database.
+
+Here we give a quick overview. Check out
+((<URL:http://obda.open-bio.org/>)) for more extensive details.
+
+The specification is stored on CVS repository at cvs.open-bio.org,
+also available via http from:
+((<URL:http://cvs.open-bio.org/cgi-bin/viewcvs/viewcvs.cgi/obda-specs/?cvsroot=obf-common>))
+
+== BioRegistry
+
+BioRegistry allows for locating retrieval methods and database
+locations through configuration files.  The priorities are
+
+  * The file specified with method's parameter
+  * ~/.bioinformatics/seqdatabase.ini
+  * /etc/bioinformatics/seqdatabase.ini
+  * http://www.open-bio.org/registry/seqdatabase.ini
+
+Note that the last locaation refers to www.open-bio.org and is only used
+when all local configulation files are not available.
+
+In the current BioRuby implementation all local configulation files
+are read. For databases with the same name settings encountered first
+are used. This means that if you don't like some settings of a
+database in system global configuration file
+(/etc/bioinformatics/seqdatabase.ini), you can easily override it by
+writing settings to ~/.bioinformatics/seqdatabase.ini.
+
+The syntax of the configuration file is called a stanza format. For example
+
+    [DatabaseName]
+    protocol=ProtocolName
+    location=ServeName
+
+You can write a description like above entry for every database.
+
+The database name is a local label for yourself, so you can name it
+freely and it can differ from the name of the actual databases. In the
+actual specification of BioRegistry where there are two or more
+settings for a database of the same name, it is proposed that
+connection to the database is tried sequentially with the order
+written in configuration files. However, this has not (yet) been
+implemented in BioRuby.
+
+In addition, for some protocol, you must set additional options
+other than locations (e.g. user name of MySQL). In the BioRegistory
+specification, current available protocols are:
+
+  * index-flat
+  * index-berkeleydb
+  * biofetch
+  * biosql
+  * bsane-corba
+  * xembl
+
+In BioRuby, you can use index-flat, index-berkleydb, biofetch and biosql.
+Note that the BioRegistry specification sometimes gets updated and BioRuby
+does not always follow quickly.
+
+Here an example. Create a Bio::Registry object. It reads the configuration
+files:
+
+    reg = Bio::Registry.new
+
+    # connects to the database "genbank"
+    serv = reg.get_database('genbank')
+
+    # gets entry of the ID
+    entry = serv.get_by_id('AA2CG')
+
+
+The variable "serv" is a server object corresponding to the setting
+written in configuration files. The class of the object is one of
+Bio::SQL, Bio::Fetch, and so on. Note that Bio::Registry#get_database("name")
+returns nil if no database is found.
+
+After that, you can use get_by_id method and some specific methods.
+Please refer to below documents.
+
+== BioFlat
+
+BioFlat is a mechanism to create index files of flat files and to retrieve
+these entries fast. There are two index types. index-flat is a simple index
+performing binary search without using an external library of Ruby. index-berkeleydb
+uses Berkeley DB for indexing - but requires installing bdb on your computer,
+as well as the BDB Ruby package. For creating the index itself, you can use
+br_bioflat.rb command bundled with BioRuby.
+
+    % br_bioflat.rb --makeindex database_name [--format data_format] filename...
+
+The format can be omitted because BioRuby has autodetection.  If that
+does not work you can try specifying data format as a name of BioRuby
+database class.
+
+Search and retrieve data from database:
+
+    % br_bioflat.rb database_name identifier
+
+For example, to create index of GenBank files gbbct*.seq and get entry
+from the database:
+
+    % br_bioflat.rb --makeindex my_bctdb --format GenBank gbbct*.seq
+    % br_bioflat.rb my_bctdb A16STM262
+
+If you have Berkeley DB on your system and installed the bdb extension
+module of Ruby (see http://raa.ruby-lang.org/project/bdb/), you can
+create and search indexes with Berkeley DB - a very fast alternative
+that uses little computer memory. When creating the index, use the
+"--makeindex-bdb" option instead of "--makeindex".
+
+    % br_bioflat.rb --makeindex-bdb database_name [--format data_format] filename...
+
+== BioFetch
+
+  Note: this section is an advanced topic
+
+BioFetch is a database retrieval mechanism via CGI.  CGI Parameters,
+options and error codes are standardized.  There client access via
+http is possible giving the database name, identifiers and format to
+retrieve entries.
+
+The BioRuby project has a BioFetch server in bioruby.org. It uses
+GenomeNet's DBGET system as a backend. The source code of the
+server is in sample/ directory. Currently, there are only two
+BioFetch servers in the world: bioruby.org and EBI.
+
+Here are some methods to retrieve entries from our BioFetch server.
+
+(1) Using a web browser
+
+      http://bioruby.org/cgi-bin/biofetch.rb
+
+(2) Using the br_biofetch.rb command
+
+      % br_biofetch.rb db_name entry_id
+
+(3) Directly using Bio::Fetch in a script
+
+      serv = Bio::Fetch.new(server_url)
+      entry = serv.fetch(db_name, entry_id)
+
+(4) Indirectly using Bio::Fetch via BioRegistry in script
+
+      reg = Bio::Registry.new
+      serv = reg.get_database('genbank')
+      entry = serv.get_by_id('AA2CG')
+
+If you want to use (4), you, obviously, have to include some settings
+in seqdatabase.ini. E.g.
+
+    [genbank]
+    protocol=biofetch
+    location=http://bioruby.org/cgi-bin/biofetch.rb
+    biodbname=genbank
+
+=== The combination of BioFetch, Bio::KEGG::GENES and Bio::AAindex1
+
+Bioinformatics is often about glueing things together. Here we give an
+example to get the bacteriorhodopsin gene (VNG1467G) of the archaea
+Halobacterium from KEGG GENES database and to get alpha-helix index
+data (BURA740101) from the AAindex (Amino acid indices and similarity
+matrices) database, and show the helix score for each 15-aa length
+overlapping window.
+
+    #!/usr/bin/env ruby
+
+    require 'bio'
+
+    entry = Bio::Fetch.query('hal', 'VNG1467G')
+    aaseq = Bio::KEGG::GENES.new(entry).aaseq
+
+    entry = Bio::Fetch.query('aax1', 'BURA740101')
+    helix = Bio::AAindex1.new(entry).index
+
+    position = 1
+    win_size = 15
+
+    aaseq.window_search(win_size) do |subseq|
+      score = subseq.total(helix)
+      puts [ position, score ].join("\t")
+      position += 1
+    end
+
+The special method Bio::Fetch.query uses preset BioFetch server
+in bioruby.org. (The server internally get data from GenomeNet.
+Because the KEGG/GENES database and AAindex database are not available
+from other BioFetch servers, we used bioruby.org server with
+Bio::Fetch.query method.)
+
+== BioSQL
+
+to be written...
+
+== The BioRuby example programs
+
+Some sample programs are stored in samples/ directry.
+Some programs are obsolete. Since samples are not enough,
+practical and interesting samples are welcome.
+
+to be written...
+
+(EDITOR's NOTE: I would like some examples automatically
+included - with output)
+
+== Further reading
+
+See the BioRuby in anger Wiki and the class documentation for more
+information on BioRuby.
+
+The best book to get for understanding and getting productive with the
+Ruby language is 'Programming Ruby' by Dave Thomas and Andy
+Hunt. Strongly recommended!
+
+= APPENDIX
+
+== KEGG API
+
+Please refer to KEGG_API.rd.ja (TRANSLATOR'S NOTE: English version: ((<URL:http://www.genome.jp/kegg/soap/doc/keggapi_manual.html>)) ) and
+
+  * ((<URL:http://www.genome.jp/kegg/soap/>))
+
+== Using BioRuby with R
+
+The R libraries can be accessed from Ruby using the @@FIXME
+package. This allows at least use of the standard R library
+functions. Unfortunately there is no binding for dynamic R - so at
+this point you'll have to create some command line interface.
+
+== Using BioPerl from Ruby
+
+== Installing required external library
+
+At this point for using BioRuby no additional libraries are needed.
+This may change, so keep an eye on the Bioruby website. Also when
+a package is missing BioRuby should show an informative message.
+
+At this point installing third party Ruby packages can be a bit
+painful, as the gem standard for packages evolved late and some still
+force you to copy things by hand. Therefore read the README's
+carefully that come with each package.
+
+=end
+