bio-graphics 1.0

data/lib/bio-graphics.rb

@@ -0,0 +1,18 @@
+# 
+# = bio-graphics.rb - Loading all Bio::Graphics modules
+#
+# Copyright::   Copyright (C) 2007
+#               Jan Aerts <jan.aerts@bbsrc.ac.uk>
+# License::     The Ruby License
+# 
+begin
+  require 'bio'
+  require 'cairo'
+  rescue nil
+end
+
+require File.dirname(__FILE__) + '/bio/graphics/image_map.rb'
+require File.dirname(__FILE__) + '/bio/graphics/panel.rb'
+require File.dirname(__FILE__) + '/bio/graphics/track.rb'
+require File.dirname(__FILE__) + '/bio/graphics/feature.rb'
+require File.dirname(__FILE__) + '/bio/graphics/ruler.rb'

data/lib/bio/graphics/feature.rb

@@ -0,0 +1,136 @@
+# 
+# = bio/graphics/feature.rb - feature class
+#
+# Copyright::   Copyright (C) 2007
+#               Jan Aerts <jan.aerts@bbsrc.ac.uk>
+# License::     The Ruby License
+# 
+module Bio
+  module Graphics
+    class Panel
+      class Track
+        # The Bio::Graphics::Track::Feature class describes features to be
+        # placed on the graph. See Bio::Graphics documentation for explanation
+        # of interplay between different classes.
+        #
+        # The position of the Feature is a Bio::Locations object to make it possible
+        # to transparently work with simple and spliced features.
+        class Feature
+          # !!Not to be used directly. Use
+          # Bio::Graphics::Panel::Track.add_feature instead!!
+          # A feature can not exist except within the confines of a
+          # Bio::Graphics::Panel::Track object.
+          #
+          #--
+          # This is necessary because the feature needs to know the colour and glyph,
+          # both of which are defined within the panel.
+          #++
+          #
+          # ---
+          # *Arguments*:
+          # * _panel_ (required) :: Bio::Graphics::Panel::Track object that this
+          #   feature belongs to
+          # * _name_ (required) :: Name of the feature
+          # * _location_ :: Bio::Locations object. Default = whole panel, forward strand
+          # * _link_ :: URL for clickable images
+          # *Returns*:: Bio::Graphics::Track::Feature object
+          def initialize(track, name, location = Bio::Locations.new('1..' + track.panel.length.to_s), link = nil)
+            @track = track
+            @name = name
+            @location = location
+            @start = location.collect{|l| l.from}.min.to_i
+            @stop = location.collect{|l| l.to}.max.to_i
+            @strand = location[0].strand.to_i
+            @link = link
+            @pixel_range_collection = Array.new
+            @chopped_at_start = false
+            @chopped_at_stop = false
+            @hidden_subfeatures_at_start = false
+            @hidden_subfeatures_at_stop = false
+
+            # Get all pixel ranges for the subfeatures
+            location.each do |l|
+              #   xxxxxx  [          ]
+              if l.to < track.panel.display_start
+                @hidden_subfeatures_at_start = true
+                next
+              #           [          ]   xxxxx
+              elsif l.from > track.panel.display_stop
+                @hidden_subfeatures_at_stop = true
+                next
+              #      xxxx[xxx       ]
+              elsif l.from < track.panel.display_start and l.to > track.panel.display_start
+                start_pixel = 1
+                stop_pixel = ( l.to - track.panel.display_start ).to_f / track.panel.rescale_factor
+                @chopped_at_start = true
+              #          [      xxxx]xxxx
+              elsif l.from < track.panel.display_stop and l.to > track.panel.display_stop
+                start_pixel = ( l.from - track.panel.display_start ).to_f / track.panel.rescale_factor
+                stop_pixel = track.panel.width
+                @chopped_at_stop = true
+              #      xxxx[xxxxxxxxxx]xxxx
+              elsif l.from < track.panel.display_start and l.to > track.panel.display_stop
+                start_pixel = 1
+                stop_pixel = track.panel.width
+                @chopped_at_start = true
+                @chopped_at_stop = true
+              #          [   xxxxx  ]
+              else
+                start_pixel = ( l.from - track.panel.display_start ).to_f / track.panel.rescale_factor
+                stop_pixel = ( l.to - track.panel.display_start ).to_f / track.panel.rescale_factor
+              end
+              
+              @pixel_range_collection.push(PixelRange.new(start_pixel, stop_pixel))
+              
+            end
+          end
+          
+          # The track that this feature belongs to
+          attr_accessor :track
+          
+          # The name of the feature
+          attr_accessor :name
+          
+          # The location of the feature (which is a Bio::Locations object)
+          attr_accessor :location
+          
+          # The start position of the feature (in bp)
+          attr_accessor :start
+          
+          # The stop position of the feature (in bp)
+          attr_accessor :stop
+          
+          # The strand of the feature
+          attr_accessor :strand
+          
+          # The URL to be followed when the glyph for this feature is clicked
+          attr_accessor :link
+          
+          # The array keeping the pixel ranges for the sub-features. Unspliced
+          # features will just have one element, while spliced features will
+          # have more than one.
+          attr_accessor :pixel_range_collection
+          
+          # Is the first subfeature incomplete?
+          attr_accessor :chopped_at_start
+          
+          # Is the last subfeature incomplete?
+          attr_accessor :chopped_at_stop
+          
+          # Are there subfeatures out of view at the left side of the picture?
+          attr_accessor :hidden_subfeatures_at_start
+          
+          # Are there subfeatures out of view at the right side of the picture?
+          attr_accessor :hidden_subfeatures_at_stop
+
+          class PixelRange
+            def initialize(start_pixel, stop_pixel)
+              @start_pixel, @stop_pixel = start_pixel, stop_pixel
+            end
+            attr_accessor :start_pixel, :stop_pixel
+          end
+        end #Feature
+      end #Track
+    end #Panel
+  end #Graphics
+end #Bio

data/lib/bio/graphics/image_map.rb

@@ -0,0 +1,37 @@
+#
+# = bio/graphics/image_map.rb - create the image map for clickable images
+#
+# Copyright::   Copyright (C) 2007
+#               Jan Aerts <jan.aerts@bbsrc.ac.uk>
+# License::     Ruby's
+class ImageMap
+  def initialize
+    @elements = Array.new
+  end
+  attr_accessor :elements
+
+  def to_s
+    output = Array.new
+    output.push('<map name="image_map" border="1">')
+    @elements.each do |e|
+      output.push(e.to_s)
+    end
+    output.push('</map>')
+    return output.join("\n")
+  end
+
+
+  class ImageMapElement
+    def initialize(left, top, right, bottom, url = nil)
+      @left, @top, @right, @bottom = left, top, right, bottom
+      @url = ( url.nil? ) ? '' : url
+    end
+    attr_accessor :left, :top, :right, :bottom, :url
+
+    def to_s
+      unless @url == ''
+        return '<area shape="rect" coords="' + @left.to_s + ' ' + @top.to_s + ' ' + @right.to_s + ' ' + @bottom.to_s + '" href="' + @url + '"/>'
+      end
+    end
+  end
+end

data/lib/bio/graphics/panel.rb

@@ -0,0 +1,205 @@
+# 
+# = bio/graphics/panel - panel class
+#
+# Copyright::   Copyright (C) 2007
+#               Jan Aerts <jan.aerts@bbsrc.ac.uk>
+# License::     The Ruby License
+#
+module Bio
+  # = DESCRIPTION
+  # The Bio::Graphics set of objects allow for creating simple images that
+  # display features on a linear map. A picture consists of:
+  # * one *panel*: container of all tracks
+  # * one or more *tracks*: container of the features. Multiple tracks
+  #   can exist in the same graphic to allow for differential visualization of
+  #   different feature types (e.g. genes as blue rectangles and polymorphisms
+  #   as red triangles)
+  # * one or more *features* in each track: these are the actual features that
+  #   you want to display (e.g. 'gene 1', 'SNP 123445')
+  # * a *ruler* on top of the panel: is added automatically
+  #
+  # Schematically:
+  #  panel
+  #    +-> track 1
+  #    |     +-> feature 1
+  #    |     +-> feature 2
+  #    |     +-> feature 3
+  #    +-> track 2
+  #    |     +-> feature 4
+  #    |     +-> feature 5
+  #    +-> ruler
+  #
+  # = USAGE
+  #   # Create a panel for something with a length of 653. This could be a
+  #   # sequence of 653 bp, but also a genetic map of 653 cM.
+  #   g = Bio::Graphics::Panel.new(653)
+  #
+  #   # Add the first track (e.g. 'genes')
+  #   track1 = g.add_track('genes')
+  #
+  #   # And put features in that track
+  #   track1.add_feature('gene1',250,375)
+  #   track1.add_feature('gene2',54,124)
+  #   track1.add_feature('gene3',100,500)
+  #
+  #   # Add a second track (e.g. 'polymorphisms')
+  #   track2 = g.add_track('polymorphisms','red','triangle')
+  #
+  #   # And put features on this one
+  #   track2.add_feature('polymorphism 1',56,56)
+  #   track2.add_feature('polymorphism 2',103,103)
+  #
+  #   # Create the actual image as SVG text
+  #   g.draw('my_picture.png')
+  #
+  # = FUTURE PROSPECTS
+  # Any help from other developers is welcomed to work on these features:
+  # * Would be nice if this module would be easily accessible from any object
+  #   that implements bioruby's Bio::Map::ActsAsMap.
+  #
+  module Graphics
+
+    # The defaults
+    DEFAULT_PANEL_WIDTH = 800  # How many pixels wide do we want the picture to be?
+    TRACK_HEADER_HEIGHT = 12   # The track header will contain the title.
+    FEATURE_HEIGHT = 10        # The height in pixels of a glyph.
+    FEATURE_V_DISTANCE = 5     # The vertical distance in pixels between glyphs
+    FEATURE_ARROW_LENGTH = 5   # In pixels again.
+    RULER_TEXT_HEIGHT = 10     # And again...
+    RULER_MIN_DISTANCE_TICKS_PIXEL = 5  # There should be at least 5 pixels between
+                                        #   consecutive ticks. This is used for the
+                                        #   calculation of tick distance.
+
+    # The Bio::Graphics::Panel class describes the complete graph and contains
+    # all tracks. See Bio::Graphics documentation for explanation of interplay
+    # between different classes.
+    class Panel
+      # Create a new Bio::Graphics::Panel object
+      #
+      #   g = Bio::Graphics::Panel.new(456)
+      #
+      # The height of the image is calculated automatically depending on how many
+      # tracks and features it contains. The width of the image defaults to 800 pt
+      # but can be set manually by using a second argument:
+      #
+      #   g = Bio::Graphics::Panel.new(456, 400)
+      #
+      #
+      # See also: Bio::Graphics::Track, BioExt::Graphics::Feature
+      # ---
+      # *Arguments*:
+      # * _length_ :: length of the thing you want to visualize, e.g for
+      #   visualizing a sequence that is 3.24 kb long, use 324.
+      # * _width_ :: width of the resulting image in pt. This should be a string
+      #   and not an integer. Default = '800' (Notice the quotes...).
+      # * _clickable_ :: whether the picture should have clickable glyphs or not
+      #   (default: false) If set to true, a html file will be created with
+      #   the map.
+      # * _display_start_ :: start coordinate to be displayed (default: 1)
+      # * _display_stop_ :: stop coordinate to be displayed (default: length of sequence)
+      # *Returns*:: Bio::Graphics::Panel object
+      def initialize(length, width = DEFAULT_PANEL_WIDTH, clickable = false, display_start = nil, display_stop = nil)
+        @length = length.to_i
+        @width = width.to_i
+        @tracks = Array.new
+        @number_of_times_bumped = 0
+        @clickable = clickable
+        @image_map = ( clickable ) ? ImageMap.new : nil
+        @display_start = ( display_start.nil? ) ? 0 : display_start
+        @display_stop = ( display_stop.nil? ) ? @length : display_stop
+        if @display_stop <= @display_start
+          raise "[ERROR] Start coordinate to be displayed has to be smaller than stop coordinate."
+        end
+        @rescale_factor = (@display_stop - @display_start).to_f / @width
+      end
+      attr_accessor :length, :width, :height, :rescale_factor, :tracks, :number_of_times_bumped, :clickable, :image_map, :display_start, :display_stop
+
+      # Adds a Bio::Graphics::Track container to this panel. A panel contains a
+      # logical grouping of features, e.g. (for sequence annotation:) genes,
+      # polymorphisms, ESTs, etc.
+      #
+      #  est_track = g.add_track('ESTs')
+      #  gene_track = g.add_track('genes')
+      #
+      # ---
+      # *Arguments*:
+      # * _name_ (required) :: Name of the track to be displayed (e.g. 'genes')
+      # * _colour_ :: Colour to be used to draw the features within the track.
+      #   Default = 'blue'
+      # * _glyph_ :: Glyph to use for drawing the features. Options are:
+      #   'generic', 'directed_generic', 'spliced', 'directed_spliced' and
+      #   'triangle'. Triangles can be used
+      #   for features whose start and stop positions are the same (e.g. SNPs).
+      #   If you try to draw a feature that is longer with triangles, an error
+      #   will be shown.
+      # *Returns*:: Bio::Graphics::Track object that has just been created
+      def add_track(name, feature_colour = [0,0,1], feature_glyph = 'generic')
+        @tracks.push(Bio::Graphics::Panel::Track.new(self, name, feature_colour, feature_glyph))
+        return @tracks[-1]
+      end
+
+      # Create the drawing
+      #--
+      # The fact that display_start and display_stop can be set has two
+      # consequences:
+      #  1. not all features are drawn
+      #  2. the x-coordinate of all glyphs has to be corrected
+      #++
+      def draw(file_name)
+        # Create a panel that is huge vertically
+        huge_height = 2000
+
+        huge_panel_drawing = nil
+        huge_panel_drawing = Cairo::ImageSurface.new(1, @width, huge_height)
+
+        background = Cairo::Context.new(huge_panel_drawing)
+        background.set_source_rgb(1,1,1)
+        background.rectangle(0,0,@width,huge_height).fill
+
+        # Add ruler
+        vertical_offset = 0
+        ruler = Bio::Graphics::Panel::Ruler.new(self)
+        ruler.draw(huge_panel_drawing, vertical_offset)
+        vertical_offset += ruler.height
+
+        # Add tracks
+        @tracks.each do |track|
+          track.draw(huge_panel_drawing, vertical_offset)
+          @number_of_times_bumped += track.number_of_times_bumped
+          vertical_offset += ( track.number_of_times_bumped*(FEATURE_HEIGHT+FEATURE_V_DISTANCE+5)) + 10 # '10' is for the header
+        end
+
+        # And create a smaller version of the panel
+        height = ruler.height
+        @number_of_times_bumped.times do
+          height += 20
+        end
+        @tracks.length.times do #To correct for the track headers
+          height += 10
+        end
+
+        resized_panel_drawing = nil
+        resized_panel_drawing = Cairo::ImageSurface.new(1, @width, height)
+        resizing_context = Cairo::Context.new(resized_panel_drawing)
+        resizing_context.set_source(huge_panel_drawing, 0,0)
+        resizing_context.rectangle(0,0,@width, height).fill
+
+        # And print to file
+        resized_panel_drawing.write_to_png(file_name)
+        if @clickable # create png and map
+          html_filename = file_name.sub(/\.[^.]+$/, '.html')
+          html = File.open(html_filename,'w')
+          html.puts "<html>"
+          html.puts "<body>"
+          html.puts @image_map.to_s
+          html.puts "<img border='1' src='" + file_name + "' usemap='#image_map' />"
+          html.puts "</body>"
+          html.puts "</html>"
+        end
+      end
+
+
+
+    end #Panel
+  end #Graphics
+end #Bio

data/lib/bio/graphics/ruler.rb

@@ -0,0 +1,96 @@
+# 
+# = bio/graphics/ruler - ruler class
+#
+# Copyright::   Copyright (C) 2007
+#               Jan Aerts <jan.aerts@bbsrc.ac.uk>
+# License::     The Ruby License
+#
+module Bio
+  module Graphics
+    class Panel
+      # The Bio::Graphics::Ruler class describes the ruler to be drawn on the
+      # graph. This is created automatically when creating the picture by using
+      # Bio::Graphics::Panel.to_svg. See BioExt::Graphics documentation for
+      # explanation of interplay between different classes.
+      #--
+      # TODO: the ruler might be implemented as a special case of a track, so
+      # it would inherit from it (class Ruler < Bio::Graphics::Panel::Track).
+      # But I haven't really thought this through yet.
+      #++
+      class Ruler
+        # Creates a new Bio::Graphics::Panel::Ruler object.
+        # ---
+        # *Arguments*:
+        # * _panel_ (required) :: Bio::Graphics::Panel object that this ruler
+        #   belongs to
+        # * _colour_ :: colour of the ruler. Default = 'black'
+        # *Returns*:: Bio::Graphics::Ruler object
+        def initialize(panel, colour = [0,0,0])
+          @panel = panel
+          @name = 'ruler'
+          @colour = colour
+        end
+        attr_accessor :panel, :name, :colour, :height, :minor_tick_distance, :major_tick_distance
+
+        def calculate_tick_distance
+          min_tick_distance_requirement_met = false
+          self.minor_tick_distance = 1 # in basepairs.
+          while ! min_tick_distance_requirement_met
+            if self.minor_tick_distance/panel.rescale_factor >= RULER_MIN_DISTANCE_TICKS_PIXEL
+              min_tick_distance_requirement_met = true
+            else
+              self.minor_tick_distance = self.minor_tick_distance*5
+            end
+          end
+
+          self.major_tick_distance = self.minor_tick_distance * 10
+        end
+
+        def draw(panel_drawing, vertical_offset)
+          ruler_drawing = Cairo::Context.new(panel_drawing)
+
+          self.calculate_tick_distance
+
+          # Draw line
+          ruler_drawing.move_to(0,10)
+          ruler_drawing.line_to(panel.width, 10)
+          ruler_drawing.stroke
+
+          # Draw ticks
+          #  * Find position of first tick.
+          #    Most of the time, we don't want the first tick on the very first
+          #    basepair of the view. Suppose that would be position 333 in the
+          #    sequence. Then the numbers under the major tickmarks would be:
+          #    343, 353, 363, 373 and so on. Instead, we want 350, 360, 370, 380.
+          #    So we want to find the position of the first tick.
+          first_tick_position = panel.display_start
+          while first_tick_position.modulo(minor_tick_distance) != 0
+            first_tick_position += 1
+          end
+          
+          #  * And start drawing the rest.
+          first_tick_position.step(panel.display_stop, minor_tick_distance) do |tick|
+            tick_pixel_position = (tick - panel.display_start) / panel.rescale_factor
+            ruler_drawing.move_to(tick_pixel_position.floor, 5)
+            if tick.modulo(major_tick_distance) == 0
+              ruler_drawing.rel_line_to(0, 15)
+              
+              # Draw tick number
+              ruler_drawing.select_font_face('Georgia', 1, 1)
+              ruler_drawing.set_font_size(RULER_TEXT_HEIGHT)
+              ruler_drawing.move_to(tick_pixel_position.floor, 20 + RULER_TEXT_HEIGHT)
+              ruler_drawing.show_text(tick.to_i.to_s)
+            else
+              ruler_drawing.rel_line_to(0, 5)
+              
+            end
+            ruler_drawing.stroke
+          end
+          
+
+          @height = 25 + RULER_TEXT_HEIGHT
+        end
+      end #Ruler
+    end #Panel
+  end #Graphics
+end #Bio