RubyGems - bio - Versions diffs - 1.2.1 → 1.3.0 - Mend

bio 1.2.1 → 1.3.0

Files changed (259) hide show

data/ChangeLog +3421 -0
data/KNOWN_ISSUES.rdoc +88 -0
data/README.rdoc +252 -0
data/README_DEV.rdoc +285 -0
data/Rakefile +143 -0
data/bin/bioruby +0 -0
data/bin/br_biofetch.rb +0 -0
data/bin/br_bioflat.rb +12 -1
data/bin/br_biogetseq.rb +0 -0
data/bin/br_pmfetch.rb +4 -3
data/bioruby.gemspec +477 -0
data/bioruby.gemspec.erb +117 -0
data/doc/Changes-0.7.rd +7 -0
data/doc/Changes-1.3.rdoc +239 -0
data/doc/Tutorial.rd +296 -184
data/doc/Tutorial.rd.html +1031 -0
data/doc/Tutorial.rd.ja +111 -45
data/doc/Tutorial.rd.ja.html +2225 -0
data/doc/bioruby.css +281 -0
data/extconf.rb +2 -0
data/lib/bio.rb +29 -4
data/lib/bio/appl/blast.rb +306 -121
data/lib/bio/appl/blast/ddbj.rb +142 -0
data/lib/bio/appl/blast/format0.rb +35 -25
data/lib/bio/appl/blast/format8.rb +2 -2
data/lib/bio/appl/blast/genomenet.rb +263 -0
data/lib/bio/appl/blast/ncbioptions.rb +220 -0
data/lib/bio/appl/blast/remote.rb +106 -0
data/lib/bio/appl/blast/report.rb +260 -9
data/lib/bio/appl/blast/rexml.rb +12 -5
data/lib/bio/appl/blast/rpsblast.rb +277 -0
data/lib/bio/appl/blast/wublast.rb +133 -12
data/lib/bio/appl/blast/xmlparser.rb +35 -18
data/lib/bio/appl/blat/report.rb +46 -5
data/lib/bio/appl/emboss.rb +62 -13
data/lib/bio/appl/fasta.rb +9 -11
data/lib/bio/appl/genscan/report.rb +3 -3
data/lib/bio/appl/hmmer.rb +1 -1
data/lib/bio/appl/hmmer/report.rb +10 -10
data/lib/bio/appl/paml/baseml.rb +95 -0
data/lib/bio/appl/paml/baseml/report.rb +32 -0
data/lib/bio/appl/paml/codeml.rb +242 -0
data/lib/bio/appl/paml/codeml/rates.rb +67 -0
data/lib/bio/appl/paml/codeml/report.rb +67 -0
data/lib/bio/appl/paml/common.rb +348 -0
data/lib/bio/appl/paml/common_report.rb +38 -0
data/lib/bio/appl/paml/yn00.rb +103 -0
data/lib/bio/appl/paml/yn00/report.rb +32 -0
data/lib/bio/appl/psort.rb +2 -2
data/lib/bio/appl/pts1.rb +5 -5
data/lib/bio/appl/tmhmm/report.rb +10 -1
data/lib/bio/command.rb +297 -41
data/lib/bio/compat/features.rb +157 -0
data/lib/bio/compat/references.rb +128 -0
data/lib/bio/db/biosql/biosql_to_biosequence.rb +67 -0
data/lib/bio/db/biosql/sequence.rb +508 -0
data/lib/bio/db/embl/common.rb +28 -12
data/lib/bio/db/embl/embl.rb +107 -9
data/lib/bio/db/embl/embl_to_biosequence.rb +85 -0
data/lib/bio/db/embl/format_embl.rb +190 -0
data/lib/bio/db/embl/sptr.rb +15 -16
data/lib/bio/db/fantom.rb +6 -8
data/lib/bio/db/fasta.rb +10 -507
data/lib/bio/db/fasta/defline.rb +532 -0
data/lib/bio/db/fasta/fasta_to_biosequence.rb +63 -0
data/lib/bio/db/fasta/format_fasta.rb +97 -0
data/lib/bio/db/genbank/common.rb +25 -8
data/lib/bio/db/genbank/format_genbank.rb +187 -0
data/lib/bio/db/genbank/genbank.rb +36 -1
data/lib/bio/db/genbank/genbank_to_biosequence.rb +86 -0
data/lib/bio/db/gff.rb +1791 -119
data/lib/bio/db/kegg/glycan.rb +2 -6
data/lib/bio/db/lasergene.rb +3 -3
data/lib/bio/db/medline.rb +4 -1
data/lib/bio/db/newick.rb +10 -10
data/lib/bio/db/pdb/chain.rb +6 -2
data/lib/bio/db/pdb/pdb.rb +12 -3
data/lib/bio/db/rebase.rb +7 -8
data/lib/bio/db/soft.rb +3 -3
data/lib/bio/feature.rb +1 -88
data/lib/bio/io/biosql/biodatabase.rb +64 -0
data/lib/bio/io/biosql/bioentry.rb +29 -0
data/lib/bio/io/biosql/bioentry_dbxref.rb +11 -0
data/lib/bio/io/biosql/bioentry_path.rb +12 -0
data/lib/bio/io/biosql/bioentry_qualifier_value.rb +10 -0
data/lib/bio/io/biosql/bioentry_reference.rb +10 -0
data/lib/bio/io/biosql/bioentry_relationship.rb +10 -0
data/lib/bio/io/biosql/biosequence.rb +11 -0
data/lib/bio/io/biosql/comment.rb +7 -0
data/lib/bio/io/biosql/config/database.yml +20 -0
data/lib/bio/io/biosql/dbxref.rb +13 -0
data/lib/bio/io/biosql/dbxref_qualifier_value.rb +12 -0
data/lib/bio/io/biosql/location.rb +32 -0
data/lib/bio/io/biosql/location_qualifier_value.rb +11 -0
data/lib/bio/io/biosql/ontology.rb +10 -0
data/lib/bio/io/biosql/reference.rb +9 -0
data/lib/bio/io/biosql/seqfeature.rb +32 -0
data/lib/bio/io/biosql/seqfeature_dbxref.rb +11 -0
data/lib/bio/io/biosql/seqfeature_path.rb +11 -0
data/lib/bio/io/biosql/seqfeature_qualifier_value.rb +20 -0
data/lib/bio/io/biosql/seqfeature_relationship.rb +11 -0
data/lib/bio/io/biosql/taxon.rb +12 -0
data/lib/bio/io/biosql/taxon_name.rb +9 -0
data/lib/bio/io/biosql/term.rb +27 -0
data/lib/bio/io/biosql/term_dbxref.rb +11 -0
data/lib/bio/io/biosql/term_path.rb +12 -0
data/lib/bio/io/biosql/term_relationship.rb +13 -0
data/lib/bio/io/biosql/term_relationship_term.rb +11 -0
data/lib/bio/io/biosql/term_synonym.rb +10 -0
data/lib/bio/io/das.rb +7 -7
data/lib/bio/io/ddbjxml.rb +57 -0
data/lib/bio/io/ensembl.rb +2 -2
data/lib/bio/io/fetch.rb +28 -14
data/lib/bio/io/flatfile.rb +17 -853
data/lib/bio/io/flatfile/autodetection.rb +545 -0
data/lib/bio/io/flatfile/buffer.rb +237 -0
data/lib/bio/io/flatfile/index.rb +17 -7
data/lib/bio/io/flatfile/indexer.rb +30 -12
data/lib/bio/io/flatfile/splitter.rb +297 -0
data/lib/bio/io/hinv.rb +442 -0
data/lib/bio/io/keggapi.rb +2 -2
data/lib/bio/io/ncbirest.rb +733 -0
data/lib/bio/io/pubmed.rb +34 -80
data/lib/bio/io/registry.rb +2 -2
data/lib/bio/io/sql.rb +178 -357
data/lib/bio/io/togows.rb +458 -0
data/lib/bio/location.rb +106 -11
data/lib/bio/pathway.rb +120 -14
data/lib/bio/reference.rb +115 -101
data/lib/bio/sequence.rb +164 -183
data/lib/bio/sequence/adapter.rb +108 -0
data/lib/bio/sequence/common.rb +22 -45
data/lib/bio/sequence/compat.rb +2 -2
data/lib/bio/sequence/dblink.rb +54 -0
data/lib/bio/sequence/format.rb +254 -77
data/lib/bio/sequence/format_raw.rb +23 -0
data/lib/bio/shell.rb +3 -1
data/lib/bio/shell/core.rb +2 -2
data/lib/bio/shell/plugin/entry.rb +33 -4
data/lib/bio/shell/plugin/ncbirest.rb +64 -0
data/lib/bio/shell/plugin/togows.rb +40 -0
data/lib/bio/shell/rails/vendor/plugins/{generators → bioruby/generators}/bioruby/bioruby_generator.rb +0 -0
data/lib/bio/shell/rails/vendor/plugins/{generators → bioruby/generators}/bioruby/templates/_classes.rhtml +0 -0
data/lib/bio/shell/rails/vendor/plugins/{generators → bioruby/generators}/bioruby/templates/_log.rhtml +0 -0
data/lib/bio/shell/rails/vendor/plugins/{generators → bioruby/generators}/bioruby/templates/_methods.rhtml +0 -0
data/lib/bio/shell/rails/vendor/plugins/{generators → bioruby/generators}/bioruby/templates/_modules.rhtml +0 -0
data/lib/bio/shell/rails/vendor/plugins/{generators → bioruby/generators}/bioruby/templates/_variables.rhtml +0 -0
data/lib/bio/shell/rails/vendor/plugins/{generators → bioruby/generators}/bioruby/templates/bioruby-bg.gif +0 -0
data/lib/bio/shell/rails/vendor/plugins/{generators → bioruby/generators}/bioruby/templates/bioruby-gem.png +0 -0
data/lib/bio/shell/rails/vendor/plugins/{generators → bioruby/generators}/bioruby/templates/bioruby-link.gif +0 -0
data/lib/bio/shell/rails/vendor/plugins/{generators → bioruby/generators}/bioruby/templates/bioruby.css +0 -0
data/lib/bio/shell/rails/vendor/plugins/{generators → bioruby/generators}/bioruby/templates/bioruby.rhtml +0 -0
data/lib/bio/shell/rails/vendor/plugins/{generators → bioruby/generators}/bioruby/templates/bioruby_controller.rb +0 -0
data/lib/bio/shell/rails/vendor/plugins/{generators → bioruby/generators}/bioruby/templates/bioruby_helper.rb +0 -0
data/lib/bio/shell/rails/vendor/plugins/{generators → bioruby/generators}/bioruby/templates/commands.rhtml +0 -0
data/lib/bio/shell/rails/vendor/plugins/{generators → bioruby/generators}/bioruby/templates/history.rhtml +0 -0
data/lib/bio/shell/rails/vendor/plugins/{generators → bioruby/generators}/bioruby/templates/index.rhtml +0 -0
data/lib/bio/shell/rails/vendor/plugins/{generators → bioruby/generators}/bioruby/templates/spinner.gif +0 -0
data/lib/bio/tree.rb +4 -2
data/lib/bio/util/color_scheme.rb +2 -2
data/lib/bio/util/contingency_table.rb +2 -2
data/lib/bio/util/restriction_enzyme.rb +2 -2
data/lib/bio/util/restriction_enzyme/single_strand.rb +6 -5
data/lib/bio/version.rb +25 -0
data/rdoc.zsh +8 -0
data/sample/any2fasta.rb +0 -0
data/sample/biofetch.rb +0 -0
data/sample/dbget +0 -0
data/sample/demo_sequence.rb +158 -0
data/sample/enzymes.rb +0 -0
data/sample/fasta2tab.rb +0 -0
data/sample/fastagrep.rb +72 -0
data/sample/fastasort.rb +54 -0
data/sample/fsplit.rb +0 -0
data/sample/gb2fasta.rb +2 -3
data/sample/gb2tab.rb +0 -0
data/sample/gbtab2mysql.rb +0 -0
data/sample/genes2nuc.rb +0 -0
data/sample/genes2pep.rb +0 -0
data/sample/genes2tab.rb +0 -0
data/sample/genome2rb.rb +0 -0
data/sample/genome2tab.rb +0 -0
data/sample/goslim.rb +0 -0
data/sample/gt2fasta.rb +0 -0
data/sample/na2aa.rb +34 -0
data/sample/pmfetch.rb +0 -0
data/sample/pmsearch.rb +0 -0
data/sample/ssearch2tab.rb +0 -0
data/sample/tfastx2tab.rb +0 -0
data/sample/vs-genes.rb +0 -0
data/setup.rb +1596 -0
data/test/data/blast/blastp-multi.m7 +188 -0
data/test/data/command/echoarg2.bat +1 -0
data/test/data/paml/codeml/control_file.txt +30 -0
data/test/data/paml/codeml/output.txt +78 -0
data/test/data/paml/codeml/rates +217 -0
data/test/data/rpsblast/misc.rpsblast +193 -0
data/test/data/soft/GDS100_partial.soft +0 -0
data/test/data/soft/GSE3457_family_partial.soft +0 -0
data/test/functional/bio/appl/test_pts1.rb +115 -0
data/test/functional/bio/io/test_ensembl.rb +123 -80
data/test/functional/bio/io/test_togows.rb +267 -0
data/test/functional/bio/sequence/test_output_embl.rb +51 -0
data/test/functional/bio/test_command.rb +301 -0
data/test/runner.rb +17 -1
data/test/unit/bio/appl/blast/test_ncbioptions.rb +112 -0
data/test/unit/bio/appl/blast/test_report.rb +753 -35
data/test/unit/bio/appl/blast/test_rpsblast.rb +398 -0
data/test/unit/bio/appl/paml/codeml/test_rates.rb +45 -0
data/test/unit/bio/appl/paml/codeml/test_report.rb +45 -0
data/test/unit/bio/appl/paml/test_codeml.rb +174 -0
data/test/unit/bio/appl/test_blast.rb +135 -4
data/test/unit/bio/appl/test_fasta.rb +2 -2
data/test/unit/bio/appl/test_pts1.rb +1 -64
data/test/unit/bio/db/embl/test_common.rb +15 -15
data/test/unit/bio/db/embl/test_embl.rb +4 -4
data/test/unit/bio/db/embl/test_embl_rel89.rb +5 -5
data/test/unit/bio/db/embl/test_embl_to_bioseq.rb +203 -0
data/test/unit/bio/db/embl/test_sptr.rb +38 -1
data/test/unit/bio/db/pdb/test_pdb.rb +2 -2
data/test/unit/bio/db/test_gff.rb +1151 -25
data/test/unit/bio/db/test_medline.rb +127 -0
data/test/unit/bio/db/test_nexus.rb +5 -1
data/test/unit/bio/db/test_prosite.rb +4 -4
data/test/unit/bio/io/flatfile/test_autodetection.rb +375 -0
data/test/unit/bio/io/flatfile/test_buffer.rb +251 -0
data/test/unit/bio/io/flatfile/test_splitter.rb +369 -0
data/test/unit/bio/io/test_ddbjxml.rb +8 -3
data/test/unit/bio/io/test_fastacmd.rb +5 -5
data/test/unit/bio/io/test_flatfile.rb +357 -106
data/test/unit/bio/io/test_soapwsdl.rb +2 -2
data/test/unit/bio/io/test_togows.rb +161 -0
data/test/unit/bio/sequence/test_common.rb +210 -11
data/test/unit/bio/sequence/test_compat.rb +3 -3
data/test/unit/bio/sequence/test_dblink.rb +58 -0
data/test/unit/bio/sequence/test_na.rb +2 -2
data/test/unit/bio/test_command.rb +111 -50
data/test/unit/bio/test_feature.rb +29 -1
data/test/unit/bio/test_location.rb +566 -6
data/test/unit/bio/test_pathway.rb +91 -65
data/test/unit/bio/test_reference.rb +67 -13
data/test/unit/bio/util/restriction_enzyme/analysis/test_calculated_cuts.rb +3 -3
data/test/unit/bio/util/restriction_enzyme/analysis/test_cut_ranges.rb +3 -3
data/test/unit/bio/util/restriction_enzyme/analysis/test_sequence_range.rb +3 -3
data/test/unit/bio/util/restriction_enzyme/double_stranded/test_aligned_strands.rb +4 -3
data/test/unit/bio/util/restriction_enzyme/double_stranded/test_cut_location_pair.rb +3 -3
data/test/unit/bio/util/restriction_enzyme/double_stranded/test_cut_location_pair_in_enzyme_notation.rb +3 -3
data/test/unit/bio/util/restriction_enzyme/double_stranded/test_cut_locations.rb +3 -3
data/test/unit/bio/util/restriction_enzyme/double_stranded/test_cut_locations_in_enzyme_notation.rb +3 -3
data/test/unit/bio/util/restriction_enzyme/single_strand/test_cut_locations_in_enzyme_notation.rb +3 -3
data/test/unit/bio/util/restriction_enzyme/test_analysis.rb +3 -3
data/test/unit/bio/util/restriction_enzyme/test_cut_symbol.rb +4 -4
data/test/unit/bio/util/restriction_enzyme/test_double_stranded.rb +3 -3
data/test/unit/bio/util/restriction_enzyme/test_single_strand.rb +3 -3
data/test/unit/bio/util/restriction_enzyme/test_single_strand_complement.rb +3 -3
data/test/unit/bio/util/restriction_enzyme/test_string_formatting.rb +3 -3
data/test/unit/bio/util/test_restriction_enzyme.rb +3 -3
metadata +202 -167
data/test/unit/bio/appl/blast/test_xmlparser.rb +0 -388

@@ -0,0 +1,1031 @@
+<?xml version="1.0" ?>
+<!DOCTYPE html
+  PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>doc/Tutorial.rd</title>
+<link href="bioruby.css" type="text/css" rel="stylesheet" />
+</head>
+<body>
+<h1><a name="label-0" id="label-0">BioRuby Tutorial</a></h1><!-- RDLabel: "BioRuby Tutorial" -->
+<p>Editor: PjotrPrins &lt;p .at. bioruby.org&gt;</p>
+<ul>
+<li>Copyright (C) 2001-2003 KATAYAMA Toshiaki &lt;k .at. bioruby.org&gt;</li>
+<li>Copyright (C) 2005-2008 Pjotr Prins, Naohisa Goto and others</li>
+</ul>
+<p>The latest version resides in the CVS repository ./doc/<a href="http://cvs.open-bio.org/cgi-bin/viewcvs/viewcvs.cgi/*checkout*/bioruby/doc/Tutorial.rd?rev=HEAD&amp;cvsroot=bioruby&amp;content-type=text/plain">Tutorial.rd</a>. This one was updated:</p>
+<pre>$Id: Tutorial.rd,v 1.22 2008/05/19 12:22:05 pjotr Exp $ </pre>
+<p>in preparation for the <a href="http://hackathon.dbcls.jp/">BioHackathlon 2008</a></p>
+<h2><a name="label-1" id="label-1">Introduction</a></h2><!-- RDLabel: "Introduction" -->
+<p>This is a tutorial for using Bioruby. A basic knowledge of Ruby is required.
+If you want to know more about the programming langauge Ruby we recommend the
+excellent book <a href="http://www.pragprog.com/titles/ruby">Programming Ruby</a>
+by Dave Thomas and Andy Hunt - some of it is online
+<a href="http://www.rubycentral.com/pickaxe/">here</a>.</p>
+<p>For BioRuby you need to install Ruby and the BioRuby package on your computer</p>
+<p>You can check whether Ruby is installed on your computer and what
+version it has with the</p>
+<pre>% ruby -v</pre>
+<p>command. Showing something like:</p>
+<pre>ruby 1.8.5 (2006-08-25) [powerpc-linux]</pre>
+<p>If you see no such thing you'll have to install Ruby using your installation
+manager. For more information see the
+<a href="http://www.ruby-lang.org/en/">Ruby</a> website.</p>
+<p>Once Ruby is works download and install Bioruby using the links on the
+<a href="http://bioruby.org/">Bioruby</a> website.</p>
+<p>A lot of BioRuby's documentation exists in the source code and unit tests. To
+really dive in you will need the latest source code tree. The embedded rdoc
+documentation can be viewed online at
+<a href="http://bioruby.org/rdoc/">bioruby's rdoc</a>. But first lets start!</p>
+<h2><a name="label-2" id="label-2">Trying Bioruby</a></h2><!-- RDLabel: "Trying Bioruby" -->
+<p>Bioruby comes with its own shell. After unpacking the sources run the
+following command</p>
+<pre>./bin/bioruby  or
+ruby -I lib bin/bioruby</pre>
+<p>and you should see a prompt</p>
+<pre>bioruby&gt;</pre>
+<p>Now test the following:</p>
+<pre>bioruby&gt; seq = Bio::Sequence::NA.new("atgcatgcaaaa")
+==&gt; "atgcatgcaaaa"
+bioruby&gt; seq.complement
+==&gt; "ttttgcatgcat"</pre>
+<p>See the the Bioruby shell section below for more tweaking. If you have trouble running
+examples also check the section below on trouble shooting. You can also post a
+question to the mailing list. BioRuby developers usually try to help.</p>
+<h2><a name="label-3" id="label-3">Working with nucleic / amino acid sequences (Bio::Sequence class)</a></h2><!-- RDLabel: "Working with nucleic / amino acid sequences (Bio::Sequence class)" -->
+<p>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).</p>
+<pre>bioruby&gt; seq = Bio::Sequence::NA.new("atgcatgcaaaa")
+==&gt; "atgcatgcaaaa"
+# complemental sequence (Bio::Sequence::NA object)
+bioruby&gt; seq.complement
+==&gt; "ttttgcatgcat"
+bioruby&gt; seq.subseq(3,8) # gets subsequence of positions 3 to 8
+==&gt; "gcatgc"
+bioruby&gt; seq.gc_percent
+==&gt; 33
+bioruby&gt; seq.composition
+==&gt; {"a"=&gt;6, "c"=&gt;2, "g"=&gt;2, "t"=&gt;2}
+bioruby&gt; seq.translate
+==&gt; "MHAK"
+bioruby&gt; seq.translate(2)        # translate from frame 2
+==&gt; "CMQ"
+bioruby&gt; seq.translate(1,11)     # codon table 11
+==&gt; "MHAK"
+bioruby&gt; seq.translate.codes
+==&gt; ["Met", "His", "Ala", "Lys"]
+bioruby&gt; seq.translate.names
+==&gt; ["methionine", "histidine", "alanine", "lysine"]
+bioruby&gt;  seq.translate.composition
+==&gt; {"K"=&gt;1, "A"=&gt;1, "M"=&gt;1, "H"=&gt;1}
+bioruby&gt; seq.translate.molecular_weight
+==&gt; 485.605
+bioruby&gt; seq.complement.translate
+==&gt; "FCMH"</pre>
+<p>get a random sequence with the same NA count:</p>
+<pre>bioruby&gt; counts = {'a'=&gt;seq.count('a'),'c'=&gt;seq.count('c'),'g'=&gt;seq.count('g'),'t'=&gt;seq.count('t')}
+==&gt; {"a"=&gt;6, "c"=&gt;2, "g"=&gt;2, "t"=&gt;2}
+bioruby!&gt; randomseq = Bio::Sequence::NA.randomize(counts)
+==!&gt; "aaacatgaagtc"
+bioruby!&gt; print counts
+a6c2g2t2
+bioruby!&gt; p counts
+{"a"=&gt;6, "c"=&gt;2, "g"=&gt;2, "t"=&gt;2}</pre>
+<p>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</p>
+<pre>% ri puts
+% ri p
+% ri File.open</pre>
+<p>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.</p>
+<p>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#[].</p>
+<p>Please take note that the Ruby's string's are base 0 - i.e. the first letter
+has index 0, for example:</p>
+<pre>bioruby&gt; s = 'abc'
+==&gt; "abc"
+bioruby&gt; s[0].chr
+==&gt; "a"
+bioruby&gt; s[0..1]
+==&gt; "ab"</pre>
+<p>So when using String methods, you should subtract 1 from positions
+conventionally used in biology.  (subseq method will throw an exception if you
+specify positions smaller than or equal to 0 for either one of the "from" or
+"to".)</p>
+<p>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+.</p>
+<p>Show average percentage of GC content for 20 bases (stepping the default one base at a time)</p>
+<pre>bioruby&gt; seq = Bio::Sequence::NA.new("atgcatgcaattaagctaatcccaattagatcatcccgatcatcaaaaaaaaaa")
+==&gt; "atgcatgcaattaagctaatcccaattagatcatcccgatcatcaaaaaaaaaa"
+bioruby&gt; a=[]; seq.window_search(20) { |s| a.push s.gc_percent }
+bioruby&gt; a
+==&gt; [30, 35, 40, 40, 35, 35, 35, 30, 25, 30, 30, 30, 35, 35, 35, 35, 35, 40, 45, 45, 45, 45, 40, 35, 40, 40, 40, 40, 40, 35, 35, 35, 30, 30, 30]</pre>
+<p>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,</p>
+<p>Shows translation results for 15 bases shifting a codon at a time</p>
+<pre>bioruby&gt; a = []
+bioruby&gt; seq.window_search(15, 3) do |s|
+bioruby&gt;   a.push s.translate
+bioruby&gt; end
+bioruby&gt; a
+==&gt; ["MHAIK", "HAIKL", "AIKLI", "IKLIP", "KLIPI", "LIPIR", "IPIRS", "PIRSS", "IRSSR", "RSSRS", "SSRSS", "SRSSK", "RSSKK", "SSKKK"]</pre>
+<p>Finally, the window_search method returns the last leftover
+subsequence. This allows for example</p>
+<p>Divide a genome sequence into sections of 10000bp and
+output FASTA formatted sequences (line width 60 chars). The 1000bp at the
+start and end of each subsequence overlapped. At the 3' end of the sequence
+the leftover is also added:</p>
+<pre>i = 1
+textwidth=60
+remainder = seq.window_search(10000, 9000) do |s|
+  puts s.to_fasta("segment #{i}", textwidth)
+  i += 1
+end
+if remainder
+  puts remainder.to_fasta("segment #{i}", textwidth)
+end</pre>
+<p>If you don't want the overlapping window, set window size and stepping
+size to equal values.</p>
+<p>Other examples</p>
+<p>Count the codon usage</p>
+<pre>bioruby&gt; codon_usage = Hash.new(0)
+bioruby&gt; seq.window_search(3, 3) do |s|
+bioruby&gt;   codon_usage[s] += 1
+bioruby&gt; end
+bioruby&gt; codon_usage
+==&gt; {"cat"=&gt;1, "aaa"=&gt;3, "cca"=&gt;1, "att"=&gt;2, "aga"=&gt;1, "atc"=&gt;1, "cta"=&gt;1, "gca"=&gt;1, "cga"=&gt;1, "tca"=&gt;3, "aag"=&gt;1, "tcc"=&gt;1, "atg"=&gt;1}</pre>
+<p>Calculate molecular weight for each 10-aa peptide (or 10-nt nucleic acid)</p>
+<pre>bioruby&gt; a = []
+bioruby&gt; seq.window_search(10, 10) do |s|
+bioruby&gt;   a.push s.molecular_weight
+bioruby&gt; end
+bioruby&gt; a
+==&gt; [3096.2062, 3086.1962, 3056.1762, 3023.1262, 3073.2262]</pre>
+<p>In most cases, sequences are read from files or retrieved from databases.
+For example:</p>
+<pre>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</pre>
+<p>Save the program as na2aa.rb. Prepare a nucleic acid sequence
+described below and saves it as my_naseq.txt:</p>
+<pre>gtggcgatctttccgaaagcgatgactggagcgaagaaccaaagcagtgacatttgtctg
+atgccgcacgtaggcctgataagacgcggacagcgtcgcatcaggcatcttgtgcaaatg
+tcggatgcggcgtga</pre>
+<p>na2aa.rb translates a nucleic acid sequence to a protein sequence.
+For example, translates my_naseq.txt:</p>
+<pre>% ruby na2aa.rb my_naseq.txt</pre>
+<p>or use a pipe!</p>
+<pre>% cat my_naseq.txt|ruby na2aa.rb</pre>
+<p>Outputs</p>
+<pre>VAIFPKAMTGAKNQSSDICLMPHVGLIRRGQRRIRHLVQMSDAA*</pre>
+<p>You can also write this, a bit fanciful, as a one-liner script.</p>
+<pre>% ruby -r bio -e 'p Bio::Sequence::NA.new($&lt;.read).translate' my_naseq.txt</pre>
+<p>In the next section we will retrieve data from databases instead of using raw
+sequence files. One generic example of the above can be found in
+./sample/na2aa.rb.</p>
+<h2><a name="label-4" id="label-4">Parsing GenBank data (Bio::GenBank class)</a></h2><!-- RDLabel: "Parsing GenBank data (Bio::GenBank class)" -->
+<p>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/)</p>
+<p>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.</p>
+<p>A first attempt could be to use the Bio::GenBank class for reading in
+the data:</p>
+<pre>#!/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 "&gt;#{gb.accession} "         # Accession
+  puts gb.definition                # Definition
+  puts gb.naseq                     # Nucleic acid sequence
+                                    # (Bio::Sequence::NA object)
+end</pre>
+<p>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:</p>
+<pre>#!/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</pre>
+<p>For example, in turn, reading FASTA format files:</p>
+<pre>#!/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</pre>
+<p>In above two scripts, the first arguments of Bio::FlatFile.new are
+database classes of BioRuby. This is expanded on in a later section.</p>
+<p>Again another option is to use the Bio::DB.open class:</p>
+<pre>#!/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</pre>
+<p>Next, we are going to parse the GenBank 'features', which is normally
+very complicated:</p>
+<pre>#!/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 "&gt;NA splicing('#{position}') : #{gene_info}"
+    puts gb.naseq.splicing(position)
+    # shows amino acid sequence translated from nucleic acid sequence
+    puts "&gt;AA translated by splicing('#{position}').translate"
+    puts gb.naseq.splicing(position).translate
+    # shows amino acid sequence in the database entry (/translation=)
+    puts "&gt;AA original translation"
+    puts hash['translation']
+  end
+end</pre>
+<p>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)</p>
+<p>Bio::Sequence#splicing splices subsequence from nucleic acid sequence
+according to location information used in GenBank, EMBL and DDBJ.</p>
+<p>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.</p>
+<p>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.</p>
+<p>Splice according to location string used in a GenBank entry</p>
+<pre>naseq.splicing('join(2035..2050,complement(1775..1818),13..345')</pre>
+<p>Generate Bio::Locations object and pass the splicing method</p>
+<pre>locs = Bio::Locations.new('join((8298.8300)..10206,1..855)')
+naseq.splicing(locs)</pre>
+<p>You can also use the splicing method for amino acid sequences
+(Bio::Sequence::AA objects).</p>
+<p>Splicing peptide from a protein (e.g. signal peptide)</p>
+<pre>aaseq.splicing('21..119')</pre>
+<h3><a name="label-5" id="label-5">More databases</a></h3><!-- RDLabel: "More databases" -->
+<p>Databases in BioRuby are essentially accessed like that of GenBank
+with classes like Bio::GenBank, Bio::KEGG::GENES. A full list can be found in
+the ./lib/bio/db directory of the BioRuby source tree.</p>
+<p>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</p>
+<p>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).</p>
+<pre>ff = Bio::FlatFile.new(Bio::DatabaseClass, ARGF)</pre>
+<p>Isn't it wonderful that Bio::FlatFile automagically recognizes each
+database class?</p>
+<pre>#!/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</pre>
+<p>An example that can take any input, filter using a regular expression to output
+to a FASTA file can be found in sample/any2fasta.rb. With this technique it is
+possible to write a Unix type grep/sort pipe for sequence information. One
+example using scripts in the BIORUBY sample folder:</p>
+<pre>fastagrep.rb '/At|Dm/' database.seq | fastasort.rb</pre>
+<p>greps the database for Arabidopsis and Drosophila entries and sorts the output
+to FASTA.</p>
+<p>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).</p>
+<ul>
+<li>entry_id --&gt; gets ID of the entry</li>
+<li>definition --&gt; gets definition of the entry</li>
+<li>reference --&gt; gets references as Bio::Reference object</li>
+<li>organism --&gt; gets species</li>
+<li>seq, naseq, aaseq --&gt; returns sequence as corresponding sequence object</li>
+</ul>
+<p>Refer to the documents of each database to find the exact naming
+of the included methods.</p>
+<p>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.</p>
+<h3><a name="label-6" id="label-6">Alignments (Bio::Alignment)</a></h3><!-- RDLabel: "Alignments (Bio::Alignment)" -->
+<p>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:</p>
+<pre>bioruby&gt; seqs = [ 'atgca', 'aagca', 'acgca', 'acgcg' ]
+bioruby&gt; seqs = seqs.collect{ |x| Bio::Sequence::NA.new(x) }
+# creates alignment object
+bioruby&gt; a = Bio::Alignment.new(seqs)
+bioruby&gt; a.consensus
+==&gt; "a?gc?"
+# shows IUPAC consensus
+a.consensus_iupac
+==&gt; "ahgcr"
+# iterates over each seq
+a.each { |x| p x }
+# ==&gt;
+#    "atgca"
+#    "aagca"
+#    "acgca"
+#    "acgcg"
+# iterates over each site
+a.each_site { |x| p x }
+# ==&gt;
+#    ["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)</pre>
+<h2><a name="label-7" id="label-7">Restriction Enzymes (Bio::RE)</a></h2><!-- RDLabel: "Restriction Enzymes (Bio::RE)" -->
+<p>BioRuby has extensive support for restriction enzymes (REs). It contains a full
+library of commonly used REs (from REBASE) which can be used to cut single
+stranded RNA or dubbel stranded DNA into fragments. To list all enzymes:</p>
+<pre>rebase = Bio::RestrictionEnzyme.rebase
+rebase.each do |enzyme_name, info|
+  p enzyme_name
+end</pre>
+<p>and cut a sequence with an enzyme follow up with:</p>
+<pre>res = seq.cut_with_enzyme('EcoRII', {:max_permutations =&gt; 0},
+  {:view_ranges =&gt; true})
+if res.kind_of? Symbol #error
+   err = Err.find_by_code(res.to_s)
+   unless err
+     err = Err.new(:code =&gt; res.to_s)
+   end
+end
+res.each do |frag|
+   em = EnzymeMatch.new
+   em.p_left = frag.p_left
+   em.p_right = frag.p_right
+   em.c_left = frag.c_left
+   em.c_right = frag.c_right
+   em.err = nil
+   em.enzyme = ar_enz
+   em.sequence = ar_seq
+   p em
+ end</pre>
+<h2><a name="label-8" id="label-8">Sequence homology search by using the FASTA program (Bio::Fasta)</a></h2><!-- RDLabel: "Sequence homology search by using the FASTA program (Bio::Fasta)" -->
+<p>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.</p>
+<h3><a name="label-9" id="label-9">using FASTA in local machine</a></h3><!-- RDLabel: "using FASTA in local machine" -->
+<p>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. </p>
+<pre>#!/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)
+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 '&gt;') 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 &lt; 0.0001
+      # shows identifier of query and hit, E-value, start and
+      # end positions of homologous region
+      print "#{hit.query_id} : evalue #{hit.evalue}\t#{hit.target_id} at "
+      p hit.lap_at
+    end
+  end
+end</pre>
+<p>We named above script as f_search.rb. You can execute as follows:</p>
+<pre>% ./f_search.rb query.pep target.pep &gt; f_search.out</pre>
+<p>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.</p>
+<pre>seq = "&gt;test seq\nYQVLEEIGRGSFGSVRKVIHIPTKKLLVRKDIKYGHMNSKE"
+seq.fasta(factory)</pre>
+<p>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:</p>
+<pre>factory = Bio::Fasta.local('fasta34', 'target.pep', '-b 10')
+factory.ktup = 1</pre>
+<p>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:</p>
+<pre>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        # sequence of homologous region
+  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 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</pre>
+<p>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.</p>
+<p>If you need original output text of FASTA program you can use the "output"
+method of the factory object after the "query" method.</p>
+<pre>report = factory.query(entry)
+puts factory.output</pre>
+<h3><a name="label-10" id="label-10">using FASTA from a remote internet site</a></h3><!-- RDLabel: "using FASTA from a remote internet site" -->
+<ul>
+<li>Note: Currently, only GenomeNet (fasta.genome.jp) is</li>
+</ul>
+<p>supported. check the class documentation for updates.</p>
+<p>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.</p>
+<p>Available databases in GenomeNet:</p>
+<ul>
+<li>Protein database
+<ul>
+<li>nr-aa, genes, vgenes.pep, swissprot, swissprot-upd, pir, prf, pdbstr</li>
+</ul></li>
+<li>Nucleic acid database
+<ul>
+<li>nr-nt, genbank-nonst, gbnonst-upd, dbest, dbgss, htgs, dbsts,
+      embl-nonst, embnonst-upd, genes-nt, genome, vgenes.nuc</li>
+</ul></li>
+</ul>
+<p>Select the databases you require.  Next, give the search program from
+the type of query sequence and database.</p>
+<ul>
+<li>When query is a amino acid sequence
+<ul>
+<li>When protein database, program is "fasta".</li>
+<li>When nucleic database, program is "tfasta".</li>
+</ul></li>
+<li>When query is a nucleic acid sequence
+<ul>
+<li>When nucleic database, program is "fasta".</li>
+<li>(When protein database, you would fail to search.)</li>
+</ul></li>
+</ul>
+<p>For example:</p>
+<pre>program = 'fasta'
+database = 'genes'
+factory = Bio::Fasta.remote(program, database)</pre>
+<p>and try out the same commands as with the local search shown earlier.</p>
+<h2><a name="label-11" id="label-11">Homology search by using BLAST (Bio::Blast class)</a></h2><!-- RDLabel: "Homology search by using BLAST (Bio::Blast class)" -->
+<p>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!</p>
+<p>For example the BLAST version of f_search.rb is:</p>
+<pre># create BLAST factory object
+factory = Bio::Blast.local('blastp', ARGV.pop)</pre>
+<p>For remote execution of BLAST in GenomeNet, Bio::Blast.remote is used.
+The parameter "program" is different from FASTA - as you can expect:</p>
+<ul>
+<li>When query is a amino acid sequence
+<ul>
+<li>When protein database, program is "blastp".</li>
+<li>When nucleic database, program is "tblastn".</li>
+</ul></li>
+<li>When query is a nucleic acid sequence
+<ul>
+<li>When protein database, program is "blastx"</li>
+<li>When nucleic database, program is "blastn".</li>
+<li>("tblastx" for six-frame search.)</li>
+</ul></li>
+</ul>
+<p>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.</p>
+<p>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.</p>
+<p>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.</p>
+<pre>report.each do |hit|
+  puts hit.bit_score
+  puts hit.query_seq
+  puts hit.midline
+  puts hit.target_seq
+  puts hit.evalue
+  puts hit.identity
+  puts hit.overlap
+  puts hit.query_id
+  puts hit.query_def
+  puts hit.query_len
+  puts hit.target_id
+  puts hit.target_def
+  puts hit.target_len
+  puts hit.query_start
+  puts hit.query_end
+  puts hit.target_start
+  puts hit.target_end
+  puts hit.lap_at
+end</pre>
+<p>For simplicity and API compatibility, some information such as score
+are extracted from the first Hsp (High-scoring Segment Pair).</p>
+<p>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:</p>
+<ul>
+<li>In a Bio::Blast::Report object, @iteratinos is an array of
+    Bio::Blast::Report::Iteration objects.
+<ul>
+<li>In a Bio::Blast::Report::Iteration object, @hits is an array of
+      Bio::Blast::Report::Hits objects.
+<ul>
+<li>In a Bio::Blast::Report::Hits object, @hsps is an array of
+        Bio::Blast::Report::Hsp objects.</li>
+</ul></li>
+</ul></li>
+</ul>
+<p>See bio/appl/blast.rb and bio/appl/blast/*.rb for more information.</p>
+<h3><a name="label-12" id="label-12">Parsing existing BLAST output files</a></h3><!-- RDLabel: "Parsing existing BLAST output files" -->
+<p>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.</p>
+<pre>#!/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 &lt; 0.001
+  end
+end</pre>
+<p>Save the script as hits_under_0.001.rb and to process BLAST output
+files *.xml, you can</p>
+<pre>% ruby hits_under_0.001.rb *.xml</pre>
+<p>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.</p>
+<h3><a name="label-13" id="label-13">Add remote BLAST search sites</a></h3><!-- RDLabel: "Add remote BLAST search sites" -->
+<pre>Note: this section is an advanced topic</pre>
+<p>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:</p>
+<ul>
+<li>the calling CGI (command-line options must be processed for the site).</li>
+<li>make sure you get BLAST output text as supported format by BioRuby
+    (e.g. "-m 8", "-m 7" or default("-m 0")).</li>
+</ul>
+<p>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):</p>
+<pre>factory = Bio::Blast.remote(program, db, option, 'MYSITE')</pre>
+<p>When you write above routines, please send to the BioRuby project and
+they may be included.</p>
+<h2><a name="label-14" id="label-14">Generate a reference list using PubMed (Bio::PubMed)</a></h2><!-- RDLabel: "Generate a reference list using PubMed (Bio::PubMed)" -->
+<p>Below script is an example which seaches PubMed and creates a reference list.</p>
+<pre>#!/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</pre>
+<p>We named the script pmfetch.rb.</p>
+<pre>% ./pmfetch.rb 11024183 10592278 10592173</pre>
+<p>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.</p>
+<p>A keyword search is also available.</p>
+<pre>#!/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</pre>
+<p>We named the script pmsearch.rb.</p>
+<pre>% ./pmsearch.rb genome bioinformatics</pre>
+<p>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.</p>
+<p>(EDITORs NOTE: do we have some simple object that can be queried for
+author, title etc.?)</p>
+<p>Nowadays using NCBI E-Utils is recommended. Use Bio::PubMed.esearch
+and Bio::PubMed.efetch instead of above methods.</p>
+<pre>#!/usr/bin/env ruby
+require 'bio'
+keywords = ARGV.join(' ')
+options = {
+  'maxdate' =&gt; '2003/05/31',
+  'retmax' =&gt; 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</pre>
+<p>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.</p>
+<p>See the <a href="http://eutils.ncbi.nlm.nih.gov/entrez/query/static/eutils_help.html">help page of
+E-Utils</a>
+for more details.</p>
+<h3><a name="label-15" id="label-15">More about BibTeX</a></h3><!-- RDLabel: "More about BibTeX" -->
+<p>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.</p>
+<pre>% ./pmfetch.rb 10592173 &gt;&gt; genoinfo.bib
+% ./pmsearch.rb genome bioinformatics &gt;&gt; genoinfo.bib</pre>
+<p>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:</p>
+<p>Save this to hoge.tex:</p>
+<pre>\documentclass{jarticle}
+\begin{document}
+\bibliographystyle{plain}
+foo bar KEGG database~\cite{PMID:10592173} baz hoge fuga.
+\bibliography{genoinfo}
+\end{document}</pre>
+<p>Then,</p>
+<pre>% latex hoge
+% bibtex hoge # processes genoinfo.bib
+% latex hoge  # creates bibliography list
+% latex hoge  # inserts correct bibliography reference</pre>
+<p>Now, you get hoge.dvi and hoge.ps - the latter you can view any
+Postscript viewer.</p>
+<h3><a name="label-16" id="label-16">Bio::Reference#bibitem</a></h3><!-- RDLabel: "Bio::Reference#bibitem" -->
+<p>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</p>
+<pre>puts reference.bibtex</pre>
+<p>to</p>
+<pre>puts reference.bibitem</pre>
+<p>Output documents should be bundled in \begin{thebibliography}
+and \end{thebibliography}. Save the following to hoge.tex</p>
+<pre>\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}</pre>
+<p>and run</p>
+<pre>% latex hoge   # creates bibliography list
+% latex hoge   # inserts corrent bibliography reference</pre>
+<h1><a name="label-17" id="label-17">OBDA</a></h1><!-- RDLabel: "OBDA" -->
+<p>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).</p>
+<ul>
+<li>BioRegistry (Directory)
+<ul>
+<li>Mechanism to specify how and where to retrieve sequence data for each database.</li>
+</ul></li>
+<li>BioFlat
+<ul>
+<li>Flatfile indexing by using binary tree or BDB(Berkeley DB).</li>
+</ul></li>
+<li>BioFetch
+<ul>
+<li>Server-client model for getting entry from database via http.</li>
+</ul></li>
+<li>BioSQL
+<ul>
+<li>Schemas to store sequence data to relational database such as
+    MySQL and PostgreSQL, and methods to retrieve entries from the database.</li>
+</ul></li>
+</ul>
+<p>Here we give a quick overview. Check out
+<a href="http://obda.open-bio.org/">&lt;URL:http://obda.open-bio.org/&gt;</a> for more extensive details.</p>
+<p>The specification is stored on CVS repository at cvs.open-bio.org,
+also available via http from:
+<a href="http://cvs.open-bio.org/cgi-bin/viewcvs/viewcvs.cgi/obda-specs/?cvsroot=obf-common">&lt;URL:http://cvs.open-bio.org/cgi-bin/viewcvs/viewcvs.cgi/obda-specs/?cvsroot=obf-common&gt;</a></p>
+<h2><a name="label-18" id="label-18">BioRegistry</a></h2><!-- RDLabel: "BioRegistry" -->
+<p>BioRegistry allows for locating retrieval methods and database
+locations through configuration files.  The priorities are</p>
+<ul>
+<li>The file specified with method's parameter</li>
+<li>~/.bioinformatics/seqdatabase.ini</li>
+<li>/etc/bioinformatics/seqdatabase.ini</li>
+<li>http://www.open-bio.org/registry/seqdatabase.ini</li>
+</ul>
+<p>Note that the last locaation refers to www.open-bio.org and is only used
+when all local configulation files are not available.</p>
+<p>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.</p>
+<p>The syntax of the configuration file is called a stanza format. For example</p>
+<pre>[DatabaseName]
+protocol=ProtocolName
+location=ServeName</pre>
+<p>You can write a description like above entry for every database.</p>
+<p>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.</p>
+<p>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:</p>
+<ul>
+<li>index-flat</li>
+<li>index-berkeleydb</li>
+<li>biofetch</li>
+<li>biosql</li>
+<li>bsane-corba</li>
+<li>xembl</li>
+</ul>
+<p>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.</p>
+<p>Here an example. Create a Bio::Registry object. It reads the configuration
+files:</p>
+<pre>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')</pre>
+<p>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.</p>
+<p>After that, you can use get_by_id method and some specific methods.
+Please refer to below documents.</p>
+<h2><a name="label-19" id="label-19">BioFlat</a></h2><!-- RDLabel: "BioFlat" -->
+<p>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.</p>
+<pre>% br_bioflat.rb --makeindex database_name [--format data_format] filename...</pre>
+<p>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.</p>
+<p>Search and retrieve data from database:</p>
+<pre>% br_bioflat.rb database_name identifier</pre>
+<p>For example, to create index of GenBank files gbbct*.seq and get entry
+from the database:</p>
+<pre>% br_bioflat.rb --makeindex my_bctdb --format GenBank gbbct*.seq
+% br_bioflat.rb my_bctdb A16STM262</pre>
+<p>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".</p>
+<pre>% br_bioflat.rb --makeindex-bdb database_name [--format data_format] filename...</pre>
+<h2><a name="label-20" id="label-20">BioFetch</a></h2><!-- RDLabel: "BioFetch" -->
+<pre>Note: this section is an advanced topic</pre>
+<p>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.</p>
+<p>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.</p>
+<p>Here are some methods to retrieve entries from our BioFetch server.</p>
+<ol>
+<li><p>Using a web browser</p>
+<pre>http://bioruby.org/cgi-bin/biofetch.rb</pre></li>
+<li><p>Using the br_biofetch.rb command</p>
+<pre>% br_biofetch.rb db_name entry_id</pre></li>
+<li><p>Directly using Bio::Fetch in a script</p>
+<pre>serv = Bio::Fetch.new(server_url)
+entry = serv.fetch(db_name, entry_id)</pre></li>
+<li><p>Indirectly using Bio::Fetch via BioRegistry in script</p>
+<pre>reg = Bio::Registry.new
+serv = reg.get_database('genbank')
+entry = serv.get_by_id('AA2CG')</pre></li>
+</ol>
+<p>If you want to use (4), you, obviously, have to include some settings
+in seqdatabase.ini. E.g.</p>
+<pre>[genbank]
+protocol=biofetch
+location=http://bioruby.org/cgi-bin/biofetch.rb
+biodbname=genbank</pre>
+<h3><a name="label-21" id="label-21">The combination of BioFetch, Bio::KEGG::GENES and Bio::AAindex1</a></h3><!-- RDLabel: "The combination of BioFetch, Bio::KEGG::GENES and Bio::AAindex1" -->
+<p>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.</p>
+<pre>#!/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</pre>
+<p>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.)</p>
+<h2><a name="label-22" id="label-22">BioSQL</a></h2><!-- RDLabel: "BioSQL" -->
+<p>to be written...</p>
+<h2><a name="label-23" id="label-23">The BioRuby example programs</a></h2><!-- RDLabel: "The BioRuby example programs" -->
+<p>Some sample programs are stored in ./samples/ directory. Run for example:</p>
+<pre>./sample/na2aa.rb test/data/fasta/example1.txt </pre>
+<h2><a name="label-24" id="label-24">Unit testing and doctests</a></h2><!-- RDLabel: "Unit testing and doctests" -->
+<p>BioRuby comes with an extensive testing framework with over 1300 tests and 2700
+assertions. To run the unit tests:</p>
+<pre>cd test
+ruby runner.rb</pre>
+<p>We have also started with doctest for Ruby. We are porting the examples
+in this tutorial to doctest - more info upcoming.</p>
+<h2><a name="label-25" id="label-25">Further reading</a></h2><!-- RDLabel: "Further reading" -->
+<p>See the BioRuby in anger Wiki.  A lot of BioRuby's documentation exists in the
+source code and unit tests. To really dive in you will need the latest source
+code tree. The embedded rdoc documentation can be viewed online at
+<a href="http://bioruby.org/rdoc/">&lt;URL:http://bioruby.org/rdoc/&gt;</a>.</p>
+<h2><a name="label-26" id="label-26">BioRuby Shell</a></h2><!-- RDLabel: "BioRuby Shell" -->
+<p>The BioRuby shell implementation you find in ./lib/bio/shell. It is very interesting
+as it uses IRB (the Ruby intepreter) which is a powerful environment described in
+<a href="http://ruby-doc.org/docs/ProgrammingRuby/html/irb.html">Programming Ruby's irb chapter</a>. IRB commands can directly be typed in the shell, e.g.</p>
+<pre>bioruby!&gt; IRB.conf[:PROMPT_MODE]
+==!&gt; :PROMPT_C</pre>
+<p>optionally you also may want to install the optional Ruby readline support -
+with Debian libreadline-ruby. To edit a previous line you may have to press
+line down (arrow down) first.</p>
+<h1><a name="label-27" id="label-27">Helpful tools</a></h1><!-- RDLabel: "Helpful tools" -->
+<p>Apart from rdoc you may also want to use rtags - which allows jumping around
+source code by clicking on class and method names. </p>
+<pre>cd bioruby/lib
+rtags -R --vi</pre>
+<p>For a tutorial see <a href="http://rtags.rubyforge.org/">&lt;URL:http://rtags.rubyforge.org/&gt;</a></p>
+<h1><a name="label-28" id="label-28">APPENDIX</a></h1><!-- RDLabel: "APPENDIX" -->
+<h2><a name="label-29" id="label-29">KEGG API</a></h2><!-- RDLabel: "KEGG API" -->
+<p>Please refer to KEGG_API.rd.ja (English version: <a href="http://www.genome.jp/kegg/soap/doc/keggapi_manual.html">&lt;URL:http://www.genome.jp/kegg/soap/doc/keggapi_manual.html&gt;</a> ) and</p>
+<ul>
+<li><a href="http://www.genome.jp/kegg/soap/">&lt;URL:http://www.genome.jp/kegg/soap/&gt;</a></li>
+</ul>
+<h2><a name="label-30" id="label-30">Comparing BioProjects</a></h2><!-- RDLabel: "Comparing BioProjects" -->
+<p>For a quick functional comparison of BioRuby, BioPerl, BioPython and Bioconductor (R) see <a href="http://sciruby.codeforpeople.com/sr.cgi/BioProjects">&lt;URL:http://sciruby.codeforpeople.com/sr.cgi/BioProjects&gt;</a></p>
+<h2><a name="label-31" id="label-31">Using BioRuby with R</a></h2><!-- RDLabel: "Using BioRuby with R" -->
+<p>Using Ruby with R Pjotr wrote a section on SciRuby. See <a href="http://sciruby.codeforpeople.com/sr.cgi/RubyWithRlang">&lt;URL:http://sciruby.codeforpeople.com/sr.cgi/RubyWithRlang&gt;</a></p>
+<h2><a name="label-32" id="label-32">Using BioPerl or BioPython from Ruby</a></h2><!-- RDLabel: "Using BioPerl or BioPython from Ruby" -->
+<p>At the moment there is no easy way of accessing BioPerl from Ruby. The best way, perhaps, is to create a Perl server that gets accessed through XML/RPC or SOAP.</p>
+<h2><a name="label-33" id="label-33">Installing required external library</a></h2><!-- RDLabel: "Installing required external library" -->
+<p>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.</p>
+<p>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.</p>
+<h2><a name="label-34" id="label-34">Trouble shooting</a></h2><!-- RDLabel: "Trouble shooting" -->
+<ul>
+<li>Error: in `require': no such file to load -- bio (LoadError)</li>
+</ul>
+<p>Ruby fails to find the BioRuby libraries - add it to the RUBYLIB path, or pass
+it to the interpeter. For example:</p>
+<pre>ruby -I~/cvs/bioruby/lib yourprogram.rb</pre>
+<h2><a name="label-35" id="label-35">Modifying this page</a></h2><!-- RDLabel: "Modifying this page" -->
+<p>IMPORTANT NOTICE: This page is maintained in the BioRuby CVS
+repository. Please edit the file there otherwise changes may get
+lost. See <!-- Reference, RDLabel "BioRuby Developer Information" doesn't exist --><em class="label-not-found">BioRuby Developer Information</em><!-- Reference end --> for CVS and mailing list
+access.</p>
+</body>
+</html>