ruby-ensembl-api 0.9.6 → 1.0

data/lib/ensembl/core/transcript.rb

@@ -4,11 +4,11 @@
 # Copyright::   Copyright (C) 2007 Jan Aerts <http://jandot.myopenid.com>
 # License::     The Ruby License
 #
+# @author Jan Aerts
 nil
 module Ensembl
   nil
   module Core
-    # = DESCRIPTION
     # The Intron class describes an intron.
     # 
     # This class does _not_ use ActiveRecord and is only defined within the API.
@@ -18,7 +18,7 @@ module Ensembl
     # to a SeqRegion object and a Slice can be created for objects o this
     # class. See Sliceable and Slice for more information.
     # 
-    # = USAGE
+    # @example
     #  exon1 = Ensembl::Core::Exon.find(292811)
     #  exon2 = Ensembl::Core::Exon.find(292894)
     #  intron = Ensembl::Core::Intron.new(exon1,exon2)
@@ -55,7 +55,6 @@ module Ensembl
 
     end
     
-    # = DESCRIPTION
     # The Transcript class provides an interface to the transcript
     # table. This table contains mappings of transcripts for a Gene to a
     # SeqRegion.
@@ -68,7 +67,7 @@ module Ensembl
     # to a SeqRegion object and a Slice can be created for objects of this
     # class. See Sliceable and Slice for more information.
     #
-    # = USAGE
+    # @example
     #  #TODO
     class Transcript < DBConnection
       include Sliceable
@@ -97,9 +96,8 @@ module Ensembl
 
       # The Transcript#exons method returns the exons for this transcript in
       # the order of their ranks in the exon_transcript table.
-      # ---
-      # *Arguments*:: none
-      # *Returns*:: sorted array of Exon objects
+      # 
+      # @return [Array<Exon>] Sorted array of Exon objects
       def exons
         if @exons.nil?
           @exons = self.exon_transcripts(:include => [:exons]).sort_by{|et| et.rank.to_i}.collect{|et| et.exon}
@@ -108,9 +106,8 @@ module Ensembl
       end
 
       # The Transcript#introns methods returns the introns for this transcript
-      # ---
-      # *Arguments*:: none
-      # *Returns*:: sorted array of Intron objects
+      # 
+      # @return [Array<Intron>] Sorted array of Intron objects
       def introns
         if @introns.nil?
           @introns = Array.new
@@ -125,14 +122,12 @@ module Ensembl
       end
       
       # The Transcript#stable_id method returns the stable ID of the transcript.
-      # ---
-      # *Arguments*:: none
-      # *Returns*:: String
+      # 
+      # @return [String] Ensembl stable ID of the transcript.
       def stable_id
       	return self.transcript_stable_id.stable_id
       end
 
-      # = DESCRIPTION
       # The Transcript#display_label method returns the default name of the transcript.
       def display_label
         return Xref.find(self.display_xref_id).display_label
@@ -141,7 +136,6 @@ module Ensembl
       alias :label :display_label
       alias :name :display_label
 
-      # = DESCRIPTION
       # The Transcript#find_all_by_stable_id class method returns an array of
       # transcripts with the given stable_id. If none were found, an empty
       # array is returned.
@@ -155,7 +149,6 @@ module Ensembl
       	return answer
       end
       
-      # = DESCRIPTION
       # The Transcript#find_all_by_stable_id class method returns a
       # transcripts with the given stable_id. If none was found, nil is returned.
       def self.find_by_stable_id(stable_id)
@@ -167,7 +160,6 @@ module Ensembl
         end
       end
       
-      # = DESCRIPTION
       # The Transcript#find_by_stable_id class method fetches a Transcript object based on
       # its stable ID (i.e. the "ENST" accession number). If the name is
       # not found, it returns nil.
@@ -180,7 +172,6 @@ module Ensembl
         end
       end
       
-      # = DESCRIPTION
       # The Transcript#seq method returns the full sequence of all concatenated
       # exons.
       def seq
@@ -193,7 +184,6 @@ module Ensembl
         return @seq
       end
 
-      # = DESCRIPTION
       # The Transcript#cds_seq method returns the coding sequence of the transcript,
       # i.e. the concatenated sequence of all exons minus the UTRs.
       def cds_seq
@@ -202,21 +192,18 @@ module Ensembl
         return self.seq[(self.coding_region_cdna_start - 1), cds_length]
       end
       
-      # = DESCRIPTION
       # The Transcript#five_prime_utr_seq method returns the sequence of the
       # 5'UTR of the transcript.
       def five_prime_utr_seq
         return self.seq[0, self.coding_region_cdna_start - 1]
       end
 
-      # = DESCRIPTION
       # The Transcript#three_prime_utr_seq method returns the sequence of the
       # 3'UTR of the transcript.
       def three_prime_utr_seq
         return self.seq[self.coding_region_cdna_end..-1]
       end
 
-      # = DESCRIPTION
       # The Transcript#protein_seq method returns the sequence of the
       # protein of the transcript.
       def protein_seq
@@ -224,7 +211,6 @@ module Ensembl
       end
 
 
-      # = DESCRIPTION
       # The Transcript#coding_region_genomic_start returns the start position
       # of the CDS in genomic coordinates. Note that, in contrast to
       # Transcript#coding_region_cdna_start, the CDS start position is _always_
@@ -240,7 +226,6 @@ module Ensembl
         end
       end
 
-      # = DESCRIPTION
       # The Transcript#coding_region_genomic_end returns the stop position
       # of the CDS in genomic coordinates. Note that, in contrast to
       # Transcript#coding_region_cdna_end, the CDS stop position is _always_
@@ -256,7 +241,6 @@ module Ensembl
         end
       end
       
-      # = DESCRIPTION
       # The Transcript#coding_region_cdna_start returns the start position
       # of the CDS in cDNA coordinates. Note that, in contrast to the
       # Transcript#coding_region_genomic_start, the CDS start position is
@@ -277,7 +261,6 @@ module Ensembl
         
       end
       
-      # = DESCRIPTION
       # The Transcript#coding_region_cdna_end returns the stop position
       # of the CDS in cDNA coordinates. Note that, in contrast to the
       # Transcript#coding_region_genomic_end, the CDS start position is
@@ -298,11 +281,10 @@ module Ensembl
       end
 
 
-      # = DESCRIPTION
       # The Transcript#exon_for_position identifies the exon that covers a given
       # genomic position. Returns the exon object, or nil if in intron.
       def exon_for_genomic_position(pos)
-        if pos < coding_region_genomic_start or pos > coding_region_genomic_end
+        if pos < self.seq_region_start or pos > self.seq_region_end
           raise RuntimeError, "Position has to be within transcript"
         end
         self.exons.each do |exon|
@@ -313,7 +295,6 @@ module Ensembl
         return nil
       end
 
-      # = DESCRIPTION
       # The Transcript#exon_for_position identifies the exon that covers a given
       # position of the cDNA.
       def exon_for_cdna_position(pos)
@@ -329,90 +310,93 @@ module Ensembl
         raise RuntimeError, "Position outside of cDNA scope"
       end
 
-      # = DESCRIPTION
       # The Transcript#cdna2genomic method converts cDNA coordinates to
       # genomic coordinates for this transcript.
-      # ---
-      # *Arguments*:
-      # * position:: position on the cDNA (required)
-      # *Returns*:: integer
+      # 
+      # @param [Integer] pos Position on the cDNA
+      # @return [Integer] Position on the genomic DNA
       def cdna2genomic(pos)
         #FIXME: Still have to check for when pos is outside of scope of cDNA.
         # Identify the exon we're looking at.
         exon_with_target = self.exon_for_cdna_position(pos)
         
         accumulated_position = 0
-        self.exons.each do |exon|
+        ex = self.exons.sort_by {|e| e.seq_region_start}
+        ex.reverse! if self.strand == -1
+        ex.each do |exon|  
           if exon == exon_with_target
-            answer = exon.start + ( pos - accumulated_position )
-            return answer
+            length_to_be_taken_from_exon = pos - (accumulated_position + 1)
+            if self.strand == -1
+              return exon.seq_region_end - length_to_be_taken_from_exon
+            else
+              return exon.seq_region_start + length_to_be_taken_from_exon
+            end
           else
-            accumulated_position += exon.length
+            accumulated_position += exon.length 
           end
         end
       end
       
-      # = DESCRIPTION
       # The Transcript#cds2genomic method converts CDS coordinates to
       # genomic coordinates for this transcript.
-      # ---
-      # *Arguments*:
-      # * pos:: position on the CDS (required)
-      # *Returns*:: 
+      # 
+      # @param [Integer] pos Position on the CDS
+      # @return [Integer] Position on the genomic DNA
       def cds2genomic(pos)
         return self.cdna2genomic(pos + self.coding_region_cdna_start)
       end
       
-      # = DESCRIPTION
       # The Transcript#pep2genomic method converts peptide coordinates to
       # genomic coordinates for this transcript.
-      # ---
-      # *Arguments*:
-      # * pos:: position on the peptide (required)
-      # *Returns*:: 
+      # 
+      # @param [Integer] pos Aminoacid position on the protein
+      # @return [Integer] Position on the genomic DNA
       def pep2genomic(pos)
         raise NotImplementedError
       end
 
-      # = DESCRIPTION
       # The Transcript#genomic2cdna method converts genomic coordinates to
       # cDNA coordinates for this transcript.
-      # ---
-      # *Arguments*:
-      # * pos:: position on the chromosome (required)
-      # *Returns*:: 
+      # 
+      # @param [Integer] pos Position on the genomic DNA
+      # @return [Integer] Position on the cDNA
       def genomic2cdna(pos)
         #FIXME: Still have to check for when pos is outside of scope of cDNA.
         # Identify the exon we're looking at.
         exon_with_target = self.exon_for_genomic_position(pos)
         
         accumulated_position = 0
-        self.exons.each do |exon|
-          if exon == exon_with_target
-            accumulated_position += ( pos - exon.start )
+        ex = self.exons.sort_by {|e| e.seq_region_start}
+        ex.reverse! if self.strand == -1
+        ex.each do |exon|
+          if exon.stable_id == exon_with_target.stable_id
+            if self.strand == 1
+              accumulated_position += ( pos - exon.start) +1
+            else
+              accumulated_position += ( exon.stop - pos ) +1
+            end  
             return accumulated_position
           else
-            accumulated_position += exon.length
+              accumulated_position += exon.length 
           end
         end
         return RuntimeError, "Position outside of cDNA scope"
       end
 
-      # = DESCRIPTION
       # The Transcript#genomic2cds method converts genomic coordinates to
       # CDS coordinates for this transcript.
-      # ---
-      # *Arguments*:
-      # * pos:: position on the chromosome (required)
-      # *Returns*:: 
+      # 
+      # @param [Integer] pos Position on the genomic DNA
+      # @return [Integer] Position on the CDS
       def genomic2cds(pos)
         return self.genomic2cdna(pos) - self.coding_region_cdna_start
       end
 
-      # = DESCRIPTION
       # The Transcript#genomic2pep method converts genomic coordinates to
       # peptide coordinates for this transcript.
-      # ---
+      # 
+      # @param [Integer] pos Base position on the genomic DNA
+      # @return [Integer] Aminoacid position in the protein
       # *Arguments*:
       # * pos:: position on the chromosome (required)
       # *Returns*:: 
@@ -422,4 +406,4 @@ module Ensembl
 
     end
   end
-end
+end

data/lib/ensembl/core/transform.rb

@@ -4,13 +4,13 @@
 # Copyright::   Copyright (C) 2007 Jan Aerts <http://jandot.myopenid.com>
 # License::     The Ruby License
 #
+# @author Jan Aerts
 nil
 module Ensembl
   nil
   module Core
     nil
     module Sliceable
-      # = DESCRIPTION
       # The #transform method is used to transfer coordinates for a feature
       # from one coordinate system to another. It basically creates a clone of
       # the original feature and changes the seq_region, start position, stop
@@ -42,8 +42,7 @@ module Ensembl
       # At the moment, transformations can only be done if the two coordinate
       # systems are linked directly in the 'assembly' table.
       #
-      # = USAGE
-      #
+      # @example
       #  # Get a gene in cow and transform to scaffold level
       #  # (i.e. going from a high rank coord system to a lower rank coord
       #  # system)
@@ -60,11 +59,10 @@ module Ensembl
       #  puts target_gene.seq_region_end    #--> 1982868
       #  puts target_gene.seq_region_strand #--> 1
       #
-      # ---
-      # *Arguments*:
-      # * coord_system_name:: name of coordinate system to transform to
-      #   coordinates to
-      # *Returns*:: nil or an object of the same class as self
+      # @param [String] coord_system_name Name of the coordinate system to
+      #   transform the coordinates to
+      # @return Nil or an object of the same class
+      #   as self
       def transform(coord_system_name)
         #-
         # There are two things I can do:

data/lib/ensembl/db_connection.rb

@@ -9,7 +9,7 @@
 
 
 require 'rubygems'
-require 'activerecord'
+require 'active_record'
 
 module Ensembl
   DB_ADAPTER = 'mysql'
@@ -39,43 +39,43 @@ module Ensembl
 
   module DBRegistry 
     # = DESCRIPTION
-    # The Ensembl::Registry::Base is a generic super class providing general methods 
+    # The Ensembl::Registry::Base is a super class providing general methods 
     # to get database and connection info.
-    #
     class Base < ActiveRecord::Base
+        
       self.abstract_class = true
       self.pluralize_table_names = false
       def self.get_info
         host,user,password,db_name,port = self.retrieve_connection.instance_values["connection_options"]
+        db_name =~/(\w+_\w+)_(core|variation|funcgen|compara)_(\d+)_\S+/
+        species,release = $1,$3 # just works for standard Ensembl database names
+        if species.nil? and release.nil? then
+          raise NameError, "Can't get database name from #{db_name}. Are you using non conventional names?"
+        else
+          return host,user,password,db_name,port,species,release.to_i
+        end
       end
       # = DESCRIPTION
-      # Class method to retrieve the name of a database, using species, release and connection parameters
-      # passed by the user.
-      #      
-      def self.get_name_from_db(match,species,release,args)
+      # Method to retrieve the name of a database, using species, release and connection parameters
+      # passed by the user.    
+      def self.get_name_from_db(db_type,species,release,args)
         species = species.underscore # Always in lowercase. This keeps things simple when dealing with complex species names like in Ensembl Genomes database
-        dummy_db = DummyDBConnection.connect(args) 
+        dummy_db = DummyDBConnection.connect(args)
         dummy_connection = dummy_db.connection
-        
         # check if a database exists with exactly the species name passed (regular way)
-        db_name = dummy_connection.select_values("SHOW DATABASES LIKE '%#{species}_#{match}_#{release.to_s}%'")[0]
-        
+        db_name = dummy_connection.select_values("SHOW DATABASES LIKE '%#{species}_#{db_type}_#{release.to_s}%'")[0]
         # if a database is not found and we are working on Ensembl Genomes database...
         if db_name.nil? and args[:ensembl_genomes] then
           words = species.split(/_/)
           first = words.shift
           # ...try to find a collection database using the first name of the species passed (convention used for collection databases)
-          db_name = dummy_connection.select_values("SHOW DATABASES").select {|d| d=~/#{first}.*_collection_#{match}_#{release.to_s}/}[0]
+          db_name = dummy_connection.select_values("SHOW DATABASES").select {|d| d=~/#{first}.*_collection_#{db_type}_#{release.to_s}/}[0]
           # if a collection database match is found, then look inside to find the species
           if db_name != nil then
             dummy_db.disconnect! # close the generic connection with the host
             args[:database] = db_name
             dummy_db = DummyDBConnection.connect(args) # open a new connection directly with the collection database
-            others = ''
-            words.each do |w|
-              others << " #{w}"
-            end
-            species_name = "#{first}#{others}" # transform the species name, so it can match the species names stored in the collection database
+            species_name = species.gsub(first,first[0..0]) # transform the species name, so it can match the species names stored in the collection database
             Ensembl::SESSION.collection_species = species_name # set the species used for this session, so it's easier to fetch slices from the genome of that species
             
             # check that the species passed is present in the collection database, otherwise returns a warning
@@ -87,6 +87,34 @@ module Ensembl
         return db_name
       end
       
+      def self.generic_connect(db_type, species, release, args = {})
+        Ensembl::SESSION.reset
+        db_name = nil
+        # if the connection is established with Ensembl Genomes, set the default port and host
+        if args[:ensembl_genomes] then
+          args[:port] = EG_PORT
+          args[:host] = EG_HOST
+        end    
+        if args[:port].nil? then
+          args[:port] = ( release > 47 ) ? 5306 : 3306
+        end
+        if args[:database]
+          db_name = args[:database]
+        else 
+          db_name = self.get_name_from_db(db_type,species,release,args) # try to find the corresponding database 
+        end 
+        establish_connection(
+                            :adapter => args[:adapter] || Ensembl::DB_ADAPTER,
+                            :host => args[:host] || Ensembl::DB_HOST,
+                            :database => db_name,
+                            :username => args[:username] || Ensembl::DB_USERNAME,
+                            :password => args[:password] || Ensembl::DB_PASSWORD,
+                            :port => args[:port]
+                          )
+        
+        self.retrieve_connection # Check if the connection is working       
+      end      
+      
     end
     
   end
@@ -116,44 +144,16 @@ module Ensembl
       # *Arguments*:
       # * species:: species to connect to. Arguments should be in snake_case
       # * ensembl_release:: the release of the database to connect to
-      #  (default = 50)
+      #  (default = 50)      
       def self.connect(species, release = Ensembl::ENSEMBL_RELEASE, args = {})
-        Ensembl::SESSION.reset
-        db_name = nil
-        # if the connection is established with Ensembl Genomes, set the default port and host
-        if args[:ensembl_genomes]
-          args[:port] = EG_PORT
-          args[:host] = EG_HOST
-        end    
-        if args[:port].nil? then
-          args[:port] = ( release > 47 ) ? 5306 : 3306
-        end
-        if args[:database]
-          db_name = args[:database]
-        else 
-          db_name = self.get_name_from_db('core',species,release,args) # try to find the corresponding core database
-        end 
-        establish_connection(
-                            :adapter => args[:adapter] || Ensembl::DB_ADAPTER,
-                            :host => args[:host] || Ensembl::DB_HOST,
-                            :database => db_name,
-                            :username => args[:username] || Ensembl::DB_USERNAME,
-                            :password => args[:password] || Ensembl::DB_PASSWORD,
-                            :port => args[:port]
-                          )
-        
-        self.retrieve_connection # Checkout that the connection is working       
+        self.generic_connect('core',species, release,args)
       end
       
-      
-      # = DESCRIPTION
-      # Simple wrapper for the normal DBConnection.connect() method. This is used to set the connection directly
-      # with the Ensembl Genomes database host
-      #
-      def self.ensemblgenomes_connect(species, release = Ensembl::ENSEMBL_RELEASE, args = {})
+      def self.ensemblgenomes_connect(species, release = Ensembl::ENSEMBL_RELEASE, args={})
         args[:ensembl_genomes] = true
-        self.connect(species,release,args)
+        self.generic_connect('core',species,release,args)
       end
+
       
     end # Core::DBConnection
 
@@ -185,29 +185,13 @@ module Ensembl
       # * ensembl_release:: the release of the database to connect to
       #  (default = 50)
       def self.connect(species, release = Ensembl::ENSEMBL_RELEASE, args = {})
-        Ensembl::SESSION.reset
-        args[:species] = species
-        if args[:port].nil? then
-          args[:port] = ( release > 47 ) ? 5306 : 3306
-        end
-        db_name = nil
-        if args[:database]
-          db_name = args[:database]
-        else
-          db_name = self.get_name_from_db('variation',species,release,args)  # try to find the corresponding variation database
-        end
-        establish_connection(
-                            :adapter => args[:adapter] || Ensembl::DB_ADAPTER,
-                            :host => args[:host] || Ensembl::DB_HOST,
-                            :database => db_name,
-                            :username => args[:username] || Ensembl::DB_USERNAME,
-                            :password => args[:password] || Ensembl::DB_PASSWORD,
-                            :port => args[:port]
-                          )
-          
-        self.retrieve_connection # Checkout that the connection is working
-        
+        self.generic_connect('variation',species, release, args)
       end
+      
+      def self.ensemblgenomes_connect(species, release = Ensembl::ENSEMBL_RELEASE, args={})
+        args[:ensembl_genomes] = true
+        self.generic_connect('variation',species,release,args)
+      end      
 
     end # Variation::DBConnection