bio-alignment 0.0.1.alpha → 0.0.2

data/Gemfile

@@ -1,13 +1,13 @@
 source "http://rubygems.org"
-# Add dependencies required to use your gem here.
-# Example:
-#   gem "activesupport", ">= 2.3.5"
+gem "bio-logger"
+gem "bio", ">= 1.4.2"      # for translation tables 
 
 # Add dependencies to develop your gem here.
 # Include everything needed to run rake, tests, features, etc.
 group :development do
+  gem "bio-bigbio", "> 0.1.3"         # for FASTA files in tests
+  gem "cucumber", ">= 0"
   gem "rspec", "~> 2.3.0"
   gem "bundler", "~> 1.0.0"
   gem "jeweler", "~> 1.7.0"
-  gem "bio", ">= 1.4.2"
 end

data/README.md

@@ -9,20 +9,89 @@ nucleotide quality score, codon annotation). The only requirement is
 that the list is iterable and can be indexed. 
 
 This work is based on Pjotr's experience designing the BioScala
-Alignment handler and BioRuby's PAML support. See also the
-[design document](https://github.com/pjotrp/bioruby-alignment/blob/master/doc/bio-alignment-design.md)
+Alignment handler and BioRuby's PAML support. Read the
+Bio::BioAlignment
+[design
+document](https://github.com/pjotrp/bioruby-alignment/blob/master/doc/bio-alignment-design.md)
+for Ruby.
 
 Note: this software is under active development.
 
 ## Developers
 
-To use the library
+### Codon alignment example
+
+To use the library, load aligned sequences into the Alignment
+matrix. Here we write an amino acid alignment from a codon
+aligmment (note codon gaps are represented by '---')
 
 ```ruby
   require 'bio-alignment'
+  require 'bigbio' # Fasta reader and writer
+
+  aln = Alignment.new
+  fasta = FastaReader.new('codon-alignment.fa')
+  fasta.each do | rec |
+    aln.sequences << CodonSequence.new(rec.id, rec.seq)
+  end
+  # write a matching amino acid alignment
+  fasta = FastaWriter.new('aa-aln.fa')
+  aln.rows.each do | row |
+    fasta.write(row.id, row.to_aa.to_s)
+  end
+```
+
+### Pal2nal
+
+A protein (amino acid) to nucleotide alignment would first load
+the sequences
+
+```ruby
+  aln1 = Alignment.new
+  fasta1 = FastaWriter.new('aa-aln.fa')
+  aln1.rows.each do | row |
+    fasta1.write(row.id, row.to_aa.to_s)
+  end
+  aln2 = Alignment.new
+  fasta2 = FastaReader.new('nt.fa')
+  fasta2.each do | rec |
+    aln2.sequences << Sequence.new(rec.id, rec.seq)
+  end
+```
+
+Write a (simple) version of pal2nal would be something like
+
+```ruby
+  fasta3 = FastaWriter.new('nt-aln.fa')
+  aln.each_with_index do | aaseq, i |
+    ntseq = aln2.sequences[i]
+    aaseq.id.should == ntseq.id
+    codonseq = CodonSequence.new(ntseq.id, ntseq.seq)
+    codon_pos = 0
+    result = []
+    aaseq.each do | aa |
+      result <<
+        if aa.gap?
+          '---'
+        else
+          codon_pos += 1
+          codonseq[codon_pos-1].to_s
+        end
+    end
+    fasta3.write(aaseq.id, result.join(''))
+  end
+```
+
+With aln1 and aln2, the library version is the shorter
+
+```ruby
+  aln3 = aln1.pal2nal(aln2)
+  fasta3 = FastaWriter.new('nt-aln.fa')
+  aln3.each { | rec | fasta3.write(rec) }
 ```
 
-The API doc is online. For more code examples see ./spec/*.rb
+The API documentation is online. For more code examples see ./spec/*.rb and
+./features/*
 
 ## Cite
 

data/Rakefile

@@ -17,8 +17,8 @@ Jeweler::Tasks.new do |gem|
   gem.name = "bio-alignment"
   gem.homepage = "http://github.com/pjotrp/bioruby-alignment"
   gem.license = "MIT"
-  gem.summary = %Q{Multiple sequence alignments (MSA)}
-  gem.description = %Q{Alignment handler for multiple sequence alignments. Support for any nucleotide, amino acid and codon sequences that are lists. I.e. any list with payload can be used, as long as it can be indexed}
+  gem.summary = %Q{Support for multiple sequence alignments (MSA)}
+  gem.description = %Q{Alignment handler for multiple sequence alignments (MSA)}
   gem.email = "pjotr.public01@thebird.nl"
   gem.authors = ["Pjotr Prins"]
   # dependencies defined in Gemfile
@@ -31,12 +31,11 @@ RSpec::Core::RakeTask.new(:spec) do |spec|
   spec.pattern = FileList['spec/**/*_spec.rb']
 end
 
-RSpec::Core::RakeTask.new(:rcov) do |spec|
-  spec.pattern = 'spec/**/*_spec.rb'
-  spec.rcov = true
+require 'cucumber/rake/task'
+Cucumber::Rake::Task.new do |features|
 end
 
-task :default => :spec
+task :default => [ :cucumber, :spec ]
 
 require 'rdoc/task'
 Rake::RDocTask.new do |rdoc|

data/VERSION

@@ -1 +1 @@
-0.0.1.alpha
+0.0.2

data/doc/bio-alignment-design.md

@@ -10,8 +10,9 @@ items in the matrix (mostly because underlying sequences are String
 based). This means a developer has to track information in multiple
 places, for example a base pair quality score. This makes code complex
 and therefore error prone. With bio-alignment elements of the matrix
-can carry information. This means that when the alignment gets edited,
-the element moves, and the information migrates along. For example,
+can carry information. So, when the alignment gets edited,
+the element gets moved or deleted, and the information moves or
+deletes along. For example,
 say we have a nucleotide sequence with pay load
 
     A   G   T    A
@@ -19,14 +20,14 @@ say we have a nucleotide sequence with pay load
     5   9   *    1
 
 most library implementations will have two strings "AGTA" and "59*1".
-Removing the third nucleodide would mean removing it twice, first
-"AGA", next "591". With bio-alignment this is one action because we
-have one object for each element, that contains both values, e.g. the
-payload of T is *. Removing T from the list also removes *.
+Removing the third nucleodide would mean removing it twice, into first
+"AGA", and second "591". With bio-alignment this is one action because we
+have one object for each element that contains both values, e.g. the
+payload of 'T' is '*'. Moving 'T' automatically moves '*'.
 
-In addition bio-alignment deals with codons and codon translation.
+In addition the bio-alignment library deals with codons and codon translation.
 Rather than track mulitiple matrices, the codon is viewed as an element,
-and the translated codon as the pay load. When an alignment gets
+and the translated codon as the pay load. Again, when an alignment gets
 reordered the code only has to do it in one place.
 
 Likewise, an alignment column can have a pay load (e.g. quality score
@@ -36,6 +37,97 @@ matrix element, column, or row 'attributes'.
 
 Many of these ideas came from my work on the [BioScala
 project](https://github.com/pjotrp/bioscala/blob/master/doc/design.txt),
-The BioScala library has the advantage of type safety throughout.
+The BioScala library has the additional advantage of having type
+safety throughout.
+
+## Row or Sequence
+
+Any sequence for an alignment is simply a list of objects. The
+requirement is that the list should be enumerable and can be indexed. This means
+it has to include Enumerable and provide 'each' and '[]' methods. CodonSequence 
+is a good example.
+
+In addition, elements in the list should respond to certain properties (see
+below). 
+
+```ruby
+    codons = CodonSequence.new(rec.id,rec.seq)
+    print codons.id
+    # get first codon
+    print codons.seq[0].to_s
+```
+
+where to_s is defined as part of the Sequence.
+
+Normally, at the sequence level a pay load is possible. This can be a standard
+attribute of the class. If a list of attributes exists in the
+sequence object, it can be used. For Codons we can fetch the amino
+acid with
+
+```ruby
+    print codons.seq[0].to_aa
+```
+
+in fact, because Sequence is indexable we can write directly
+
+```ruby
+    print codons[0].to_aa        # 'M'
+    print codons[0].gap?         # false
+    print codons[0].undefined?   # false
+```
+
+and because CodonSequence is enumerable, and Codon has the to_aa method, we can
+do a fancy
+
+```ruby
+  aaseq = codons.map { | codon | codon.to_aa }.join("")
+```
+
+## Element
+
+Elements in the list should respond to a gap? method, for an alignment
+gap, and the undefined? method for a position that is either an
+element or a gap. Also it should respont to the to_s method.
+
+An element can contain any pay load.  If a list of attributes exists
+in the sequence object, it can be used.
+
+## Column
+
+The column list tracks the columns of the alignment. The requirement
+is that it should be iterable and can be indexed. The Column contains
+no elements, but may point to a list when the alignment is transposed.
+
+## Matrix or MSA
+
+The Matrix consists of a Column list, multiple Sequences, in turn
+consisting of Elements. Accessing the matrix is by Sequence, followed
+by Element.
+
+```ruby
+  require 'bio-alignment'
+  require 'bigbio' # for the Fasta reader
+  include Bio::BioAlignment # Namespace
+  aln = Alignment.new
+  fasta = FastaReader.new('test/data/fasta/codon/codon-alignment.fa')
+  fasta.each do | rec |
+    aln.sequences << rec
+  end
+```
+
+note that MSA understands rec, as long as rec.id and rec.seq exist, and strings
+(req.seq is a String). Alternatively we can convert to a Codon sequence by
+
+```ruby
+  fasta.each do | rec |
+    aln.sequences << CodonSequence.new(rec.id,rec.seq)
+  end
+```
+
+The Matrix can be accessed in transposed fashion, but accessing the normal
+matrix and transposed matrix at the same time is not supported.  Matrix is not
+designed to be transaction safe - though you can copy the Matrix any time.
+
+
 
 Copyright (C) 2012 Pjotr Prins <pjotr.prins@thebird.nl>

data/features/codon-feature.rb

@@ -0,0 +1,48 @@
+$: << 'lib'
+
+require 'bio-alignment'
+require 'bigbio'
+include Bio::BioAlignment # Namespace
+
+Given /^I read an MSA nucleotide FASTA file in the test\/data folder$/ do
+  @aln = Alignment.new
+  fasta = FastaReader.new('test/data/fasta/codon/codon-alignment.fa')
+  fasta.each do | rec |
+    @aln.sequences << CodonSequence.new(rec.id, rec.seq)
+  end
+end
+
+Given /^I iterate the sequence records$/ do
+  @aln.rows.each do | seq |
+    seq.id != nil
+  end
+end
+
+When /^I check the alignment$/ do
+end
+
+Then /^it should contain codons$/ do
+  # first sequence, first codon, translate
+  @aln.rows.first[0].to_aa.should == "M"
+end
+
+Then /^it should translate to an amino acid MSA$/ do
+  aaseq = @aln.rows.first.map { | codon | codon.to_aa }.join("")
+  aaseq[0..15].should == 'MPTRLDIVGNLQFSSS'
+end
+
+Then /^it should write a nucleotide alignment$/ do
+  # Writing is actually handles by a different library
+  fasta = FastaWriter.new('test/data/regression/nt-aln.fa')
+  @aln.rows.each do | row |
+    fasta.write(row)
+  end
+end
+
+Then /^it should write an amino acid alignment$/ do
+  fasta = FastaWriter.new('test/data/regression/aa-aln.fa')
+  @aln.rows.each do | row |
+    fasta.write(row.id, row.to_aa.to_s)
+  end
+end
+

data/features/codon.feature

@@ -0,0 +1,14 @@
+Feature: Read codon file
+  In order to read codon files into a codon alignment
+  I want to read a multi sequences aligned (MSA) nucleodtide FASTA file and store it internally as codons
+
+  Scenario: Support basic FASTA codon MSA
+    Given I read an MSA nucleotide FASTA file in the test/data folder
+    And I iterate the sequence records
+    When I check the alignment 
+    Then it should contain codons
+    And it should translate to an amino acid MSA
+    And it should write a nucleotide alignment 
+    And it should write an amino acid alignment 
+
+

data/features/pal2nal-feature.rb

@@ -0,0 +1,44 @@
+require 'bigbio'
+
+Given /^I have an amino acid alignment$/ do
+  @aln = Alignment.new
+  fasta = FastaReader.new('test/data/fasta/codon/aa-alignment.fa')
+  fasta.each do | rec |
+    @aln.sequences << Sequence.new(rec.id, rec.seq)
+  end
+end
+
+Given /^I have matching nucleotide sequences$/ do
+  @aln2 = Alignment.new
+  fasta = FastaReader.new('test/data/fasta/codon/nt.fa')
+  fasta.each do | rec |
+    @aln2.sequences << Sequence.new(rec.id, rec.seq)
+  end
+end
+
+Then /^I should be able to generate a codon alignment$/ do
+  fasta = FastaWriter.new('test/data/regression/pal2nal.fa')
+  @aln.each_with_index do | aaseq, i |
+    ntseq = @aln2.sequences[i]
+    aaseq.id.should == ntseq.id
+    codonseq = CodonSequence.new(ntseq.id, ntseq.seq)
+
+    codon_pos = 0
+    result = []
+    aaseq.each do | aa |
+      result <<
+        if aa.gap?
+          '---'
+        else
+          codon_pos += 1
+          codonseq[codon_pos-1].to_s
+        end
+    end
+    fasta.write(aaseq.id, result.join(''))
+  end
+end
+
+Then /^I should be able to generate a codon alignment directly with pal2nal$/ do
+  # pal2nal = @aln.pal2nal(@aln1)
+  pending
+end

data/features/pal2nal.feature

@@ -0,0 +1,10 @@
+Feature: pal2nal
+  pal2nal takes a protein (amino acid) alignment and a set of nucleotide 
+  sequences and generates a codon alignment based on those
+
+  Scenario: Convert pal2nal
+    Given I have an amino acid alignment
+    And I have matching nucleotide sequences
+    Then I should be able to generate a codon alignment
+    Then I should be able to generate a codon alignment directly with pal2nal
+

data/lib/bio-alignment.rb

@@ -3,3 +3,5 @@
 #
 
 require 'bio-alignment/alignment'
+require 'bio-alignment/sequence'
+require 'bio-alignment/codonsequence'

data/lib/bio-alignment/alignment.rb

@@ -0,0 +1,22 @@
+# Alignment
+
+module Bio
+  module BioAlignment
+
+    class Alignment
+      include Enumerable
+
+      attr_accessor :sequences
+
+      def initialize
+        @sequences = []
+      end
+
+      alias rows sequences
+
+      def each
+        rows.each { | seq | yield seq }
+      end
+    end
+  end
+end

data/lib/bio-alignment/codonsequence.rb

@@ -0,0 +1,87 @@
+
+require 'bio'
+
+module Bio
+  module BioAlignment
+
+    CODON_TABLE = Bio::CodonTable[1]  # BioRuby Eukaryote table
+
+    # Codon element for the matrix
+    class Codon
+      def initialize codon
+        @codon = codon
+      end
+
+      def gap?
+        @codon == '---'
+      end
+
+      def undefined?
+        aa = CODON_TABLE[@codon]
+        if aa == nil and not gap?
+          return true
+        end
+        false
+      end
+
+      def to_s
+        @codon
+      end
+
+      # lazily convert to Amino acid (once only)
+      def to_aa
+        @aa ||= CODON_TABLE[@codon]
+        if not @aa 
+          if gap?
+            return '-'
+          elsif undefined?
+            return 'X'
+          else
+            raise 'What?'
+          end
+        end
+        @aa
+      end
+    end
+
+    # A CodonSequence supports the concept of codons (triple
+    # nucleotides) for an alignment
+    #
+    class CodonSequence
+      include Enumerable
+
+      attr_reader :id, :seq
+      def initialize id, seq
+        @id = id
+        @seq = []
+        seq.scan(/\S\S\S/).each do | codon |
+          @seq << Codon.new(codon)
+        end
+      end
+
+      def [] index
+        @seq[index]
+      end
+
+      def each
+        @seq.each { | codon | yield codon }
+      end
+
+      def to_s
+        @seq.map { |codon| codon.to_s }.join(' ')
+      end
+
+      # extra methods
+
+      def to_nt
+        @seq.map { |codon| codon.to_s }.join('')
+      end
+        
+      def to_aa
+        @seq.map { |codon| codon.to_aa }.join('')
+      end
+        
+    end
+
+  end
+end