bio-graphics 1.2 → 1.4

data/doc/created.rid

@@ -1 +1 @@
-Thu Oct 18 18:24:47 +0100 2007
+Thu, 24 Jan 2008 20:03:24 +0000

data/doc/files/README_DEV.html

@@ -56,7 +56,7 @@
     </tr>
     <tr class="top-aligned-row">
       <td><strong>Last Update:</strong></td>
-      <td>Thu Oct 18 14:49:59 +0100 2007</td>
+      <td>Thu Jan 24 20:01:38 +0000 2008</td>
     </tr>
     </table>
   </div>
@@ -69,15 +69,75 @@
   <div id="contextContent">
 
     <div id="description">
-      <p>
-Copyright (C) 2007 Jan Aerts &lt;jan.aerts@bbsrc.ac.uk&gt;
+      <pre>
+ #
+ # = README.DEV - Information for developers
+ #
+ # Copyright::   Copyright (C) 2007, 2008
+ #               Jan Aerts &lt;jan.aerts@bbsrc.ac.uk&gt;
+ # License::     The Ruby License
+ #
+</pre>
+<h1>README for developers</h1>
+<p>
+This README is mainly meant to explain (a) how the code works (rather than
+how to <em>use</em> the library), and (b) how to contribute to the project.
+</p>
+<h2>ABOUT ARGUMENTS</h2>
+<p>
+As there can be a host of optional arguments for several of the methods
+(e.g. Track#add_feature), it becomes unwieldy to have them all defined
+using the standard ruby way. The Track#add_feature method for example would
+then have been defined like this:
+</p>
+<pre>
+  def add_feature(feature_object, label = 'anonymous', link = nil, glyph = @glyph, colour = @colour)
+    ...
+  end
+</pre>
+<p>
+So if the user would like to use all default settings except for the
+colour, he&#8216;d have to specify all those defaults:
+</p>
+<pre>
+  my_track.add_feature(my_feature_object, 'anonymous', nil, my_track.glyph, [0,1,1])
+</pre>
+<p>
+To make the library a bit more userfriendly, I&#8216;ve decided to use
+keyword arguments for all optional arguments. The above line then becomes:
+</p>
+<pre>
+  my_track.add_feature(my_feature_object, :colour =&gt; [0,1,1])
+</pre>
+<p>
+The construct you&#8216;ll see for this is as follows (for Track#new):
 </p>
-<h2>README for developers</h2>
+<pre>
+  def initialize(panel, name, opts = {})
+    @panel = panel
+    @name = name
+
+    opts = {
+      :label =&gt; true,
+      :glyph =&gt; :generic,
+      :colour =&gt; [0,0,1]
+    }.merge(opts)
+
+    @show_label = opts[:label]
+    @glyph = opts[:glyph]
+    @colour = opts[:colour]
+
+    ...
+  end
+</pre>
 <p>
-This README is mainly meant to explain how the code works (rather than how
-to <em>use</em> the library). It should help if you&#8216;re interested in
-contributing, or if you think you found a bug.
+Basically, this means that the &#8216;panel&#8217; and &#8216;name&#8217;
+arguments are mandatory and the other ones are optional. Which optional
+arguments are excepted should be listed in the description comments just
+above the method code. The Hash#merge that&#8216;s used here just assigns
+default values for each arguments that is not mentioned.
 </p>
+<h2>A. FLOW OF THE CODE</h2>
 <h3>Overview</h3>
 <p>
 I&#8216;ve tried to document as much as possible in the code itself, see
@@ -87,43 +147,29 @@ However, the bigger picture can not be explained that way.
 </p>
 <h3>The files</h3>
 <p>
-There&#8216;s one file for each class: panel, track, feature, ruler and
-image_map. See the tutorial on a breakdown what each of these do. All of
-these except the image_map make up a picture. The image_map is used to
-describe the HTML map that can be created to make a picture clickable.
+There&#8216;s one file for each class: panel, track, feature, subfeature,
+ruler and image_map. See the tutorial on a breakdown what each of these do.
+All of these except the image_map make up a picture. The image_map is used
+to describe the HTML map that can be created to make a picture clickable.
 </p>
 <p>
-Classes are embedded in each other: instead of
+Classes are:
 </p>
 <pre>
   Bio::Graphics::Panel
   Bio::Graphics::Ruler
   Bio::Graphics::Track
   Bio::Graphics::Feature
+  Bio::Graphics::SubFeature
+  several Bio::Graphics::Glyph::&lt;something&gt;
 </pre>
-<p>
-we have:
-</p>
-<pre>
-  Bio::Graphics::Panel
-  Bio::Graphics::Panel::Ruler
-  Bio::Graphics::Panel::Track
-  Bio::Graphics::Panel::Track::Feature
-</pre>
-<p>
-There&#8216;s a reason for this. A track can only exist within the confines
-of a panel (i.e. a panel is a container for tracks), and a feature can only
-exist within the confines of a track. In addition, there are quite some
-instances where information from the panel is necessary for the track, and
-from the track for the features.
-</p>
 <h3>The workflow</h3>
 <h4>1. Creating the panel</h4>
 <p>
 The user has to start with a
 </p>
 <pre>
-  my_panel = Bio::Graphics::Panel.new(length, width, clickable, display_start, display_stop)
+  my_panel = Bio::Graphics::Panel.new(length, width, clickable, display_start, display_stop, verticle)
 </pre>
 <p>
 When this happens, among other things, the instance variable @tracks is
@@ -157,16 +203,27 @@ own, they can only be created by using a Panel method rather than a Track
 method.
 </p>
 <pre>
-  my_track_1 = my_panel.add_track(name, label = false, feature_colour = [0,0,1], feature_glyph = 'generic')
+  my_track_1 = my_panel.add_track(name, label = false, feature_glyph = :generic, feature_colour = [0,0,1])
 </pre>
 <p>
+Feature_glyph and feature_colour are the default values to use for all
+features in this track.
+</p>
+<p>
+The feature_glyph can either be one of the approved symbols (:generic,
+:spliced, &#8230;; see documentation Bio::Graphics::Panel#add_track) or a
+hash. The keys of the hash refer to the types of subfeature; the values are
+these symbols again. For how that&#8216;s used, see below (5. Drawing the
+thing).
+</p>
+<p>
 This creates a new Track object and adds it to the @tracks array of the
 Panel object. Several instance variables are set for the Track object,
 including @features (which is an array of Feature objects for that track)
 and @number_of_feature_rows. Every time a feature cannot be drawn because
 it would overlap with another one, it will be &#8216;bumped&#8217; down
 until it can be drawn. This effectively results in <em>rows</em> that
-contain the features. The @number_of_feature_rows is just the number of
+contain the features. The @number_of_feature_rows is just this number of
 rows (to be able to calculate the height of the track afterwards).
 </p>
 <pre>
@@ -182,14 +239,17 @@ latter has to be accessible to be able to assign features to it.
 <h4>3. Adding features to a track</h4>
 <p>
 Same thing as adding a track to a panel: the feature can only be added by
-the user by using the Track#add_feature method. Parameters are the name of
-the feature, the location and the link.
+the user by using the Track#add_feature method. Arguments are a <a
+href="../classes/Bio/Feature.html">Bio::Feature</a> object (which itself
+has a type and location), a label, and the glyph and colour. The glyph can
+either be one of the approved symbols, or a hash (see 2. Adding tracks to
+the panel).
 </p>
 <p>
-The location of a feature can be something like
-&#8216;complement(join(10..20,50..70))&#8217;. To be able to parse this, I
-use the Bio::Locations object from bioruby (see <a
-href="http://www.bioruby.org">www.bioruby.org</a>). A Bio::Locations
+The location of a <a href="../classes/Bio/Feature.html">Bio::Feature</a>
+object can be something like &#8216;complement(join(10..20,50..70))&#8217;.
+To be able to parse this, I use the Bio::Locations object from bioruby (see
+<a href="http://www.bioruby.org">www.bioruby.org</a>). A Bio::Locations
 (plural) object contains one or more Bio::Location (singular) objects,
 which are the subfeatures: 10..20 and 50..70. It&#8216;s these
 Bio::Location objects we use to calculate the ultimate start and stop of
@@ -201,7 +261,20 @@ The Track#add_feature method returns the Track object itself.
 <p>
 Now let&#8216;s look at the other end: the Feature object that gets
 created. In the Feature#initialize method, you&#8216;ll notice, apart from
-the obvious variables, the following instances variables:
+the obvious variables, the following instances variables: @subfeatures,
+@left_pixel_of_subfeatures and @right_pixel_of_subfeatures. The
+@subfeatures thing is quite important. In some cases (e.g. mRNAs that
+consist of 5&#8216;UTR, CDS and 3&#8216;UTR), we will want to make a
+distinction between the UTRs and the CDS for drawing (see TUTORIAL). To
+make this possible, we will have Feature#new always create an Array of
+SubFeature objects. Often this array will only contain one object. Drawing
+of the glyphs is done on a subfeature-by-subfeature basis. The
+@left_pixel_of_subfeatures and @right_pixel_of_subfeatures just represent
+the outermost pixels for this feature.
+</p>
+<h4>4. Creating subfeatures (done automatically by Feature#new)</h4>
+<p>
+For each subfeature#new several instance variables are created:
 @pixel_range_collection, @chopped_at_start, @chopped_at_stop,
 @hidden_subfeatures_at_start and @hidden_subfeatures_at_stop. Let&#8216;s
 take these one by one:
@@ -220,8 +293,9 @@ picture but actually extends outwith the view, the start pixel will become
 </p>
 <p>
 These start and stop positions are used to create
-Bio::Graphics::Panel::Track::PixelRange objects. Unspliced objects will
-have an array @pixel_range_collection with just one element.
+Bio::Graphics::Panel::Track::Feature::SubFeature::PixelRange objects.
+Unspliced objects will have an array @pixel_range_collection with just one
+element.
 </p>
 <h5>@chopped_at_start and @chopped_at_stop</h5>
 <p>
@@ -229,7 +303,7 @@ Suppose you&#8216;ve got a directed feature (so one with an arrow), and the
 3&#8217; end falls outside of the view. What would happen, is that the
 3&#8217; end that&#8216;s out of view would be chopped of (that&#8216;s
 good), but also that the end of the glyph (which is <em>not</em> the end of
-the feature) becomes an arrow. I don&#8216;t want that. Instead, the arrow
+the feature) becomes an arrow. We don&#8216;t want that; instead, the arrow
 should be removed.
 </p>
 <p>
@@ -247,12 +321,13 @@ However, if an exon is outside of the viewing area, this line is not drawn.
 The @hidden_subfeatures_at_start and @hidden_subfeatures_at_stop are just
 flags to capture this.
 </p>
-<h4>4. Drawing the thing</h4>
+<h4>5. Drawing the thing</h4>
 <p>
-The Cairo library (<a
-href="http://cairographics.org">cairographics.org</a>) is used for the
-actual drawing. The main concepts in the Cairo drawing model are (please
-also see <a
+The Cairo and Pango libraries (<a
+href="http://cairographics.org">cairographics.org</a>, <a
+href="http://www.pango.org">www.pango.org</a>) are used for the actual
+drawing. The main concepts in the Cairo drawing model are (please also see
+<a
 href="http://cairographics.org/tutorial">cairographics.org/tutorial</a>):
 </p>
 <ul>
@@ -280,7 +355,7 @@ have to do: create a Cairo::ImageSurface and connect a Cairo::Context to
 it.
 </p>
 <p>
-Now let&#8216;s walk through the code itself&#8230;
+Now let&#8216;s walk through the drawing code itself&#8230;
 </p>
 <p>
 When a user draws a panel, the first thing that happens, is the creation of
@@ -318,19 +393,21 @@ the height of the numbers.
 <h5>Drawing the tracks</h5>
 <p>
 Drawing each track starts out with the general header: a line above it and
-the title. Obviously, the more challenging part is drawing the features
-themselves.
+the title. We also &#8216;translate&#8217; the track down to not let it
+overlap with previously drawn tracks. Obviously, the more challenging part
+is drawing the features themselves.
 </p>
+<h5>Drawing the (sub)features.</h5>
 <p>
 First thing we have to do, is figure out what the <b>vertical</b>
 <b>coordinates</b> of the glyph should be (i.e. the row). To keep track of
 what parts of the screen are already occupied by features (so that we know
-when a new feature has to be bumped down), I make use of a <b>grid</b>. The
-grid is basically a hash with the keys being the row number, and the values
-arrays of ranges. (These ranges use basepair units rather than pixels, but
-that&#8216;s completely arbitrary.) For each feature, we first check if we
-can draw it at the top of the track (i.e. row 1) and if we can&#8216;t move
-it down a row at a time until there&#8216;s room for it.
+when a new feature has to be bumped down), we make use of a <b>grid</b>.
+The grid is basically a hash with the keys being the row number, and the
+values arrays of ranges. (These ranges use basepair units rather than
+pixels, but that&#8216;s completely arbitrary.) For each feature, we first
+check if we can draw it at the top of the track (i.e. row 1) and if we
+can&#8216;t move it down a row at a time until there&#8216;s room for it.
 </p>
 <p>
 So for example, suppose we&#8216;ve already drawn two features that have
@@ -351,28 +428,38 @@ like:
            2 =&gt; [(125..175)] }
 </pre>
 <p>
-So now we know what the vertical coordinates of the glyph should be. Next
-step is to check if there&#8216;s reasons we would like to <b>change</b>
-<b>the</b> <b>requested</b> <b>glyph</b> <b>type</b> <b>from</b>
-<b>directed</b> <b>to</b> <b>undirected</b>. If the user asks for directed
-glyphs (i.e. ones with an arrow at the end), but the view is zoomed
-<em>way</em> out, there&#8216;s no way the arrow will be visible. If
+So now we know what the vertical coordinates of the glyph should be. But
+the <a
+href="../classes/Bio/Graphics/Feature.html">Bio::Graphics::Feature</a> does
+not do the drawing&#8230; The reason for this is that a Feature can have
+SubFeatures (e.g. a transcript feature can have UTR and CDS subfeatures).
+If that&#8216;s not the case, the Feature is seen as having one SubFeature.
+</p>
+<p>
+Next step is to check if there&#8216;s reasons we would like to
+<b>change</b> <b>the</b> <b>requested</b> <b>glyph</b> <b>type</b>
+<b>from</b> <b>directed</b> <b>to</b> <b>undirected</b>. If the user asks
+for directed glyphs (i.e. ones with an arrow at the end), but the view is
+zoomed <em>way</em> out, there&#8216;s no way the arrow will be visible. If
 we&#8216;d try to draw that arrow anyway, it would become bigger than the
 feature itself. Another reason would be if the feature&#8216;s 3&#8217; end
 extends outwith the picture.
 </p>
 <p>
-Finally, we can <b>draw</b>. The actual drawing bit should be quite
-self-explanatory (<em>move_to</em>, <em>line_to</em>, &#8230;).
+Finally, we can <b>draw</b>. As there are several types of glyphs, this is
+handled by a Glyph object. These are defined in the lib/bio/graphics/glyphs
+directory. These files are automatically read when requiring
+lib/bio-graphics. The actual drawing bit should be quite self-explanatory
+(<em>move_to</em>, <em>line_to</em>, &#8230;).
 </p>
 <p>
-For the spliced features (<em>spliced</em> itself and
-<em>directed_spliced</em>), we first draw the components (i.e. the exons)
-keeping track of the start and stop positions of the gaps (i.e. introns).
-We then add the connections in those gaps. In addition, we draw a line that
-extends to the side of the picture if there are exons out of view. This
-flag was set when the feature was created (see above:
-@hidden_subfeatures_at_start and @hidden_subfeatures_at_stop).
+For the spliced features (:spliced and :directed_spliced), we first draw
+the components (i.e. the exons) keeping track of the start and stop
+positions of the gaps (i.e. introns). We then add the connections in those
+gaps. In addition, we draw a line that extends to the side of the picture
+if there are exons out of view. This flag was set when the feature was
+created (see above: @hidden_subfeatures_at_start and
+@hidden_subfeatures_at_stop).
 </p>
 <p>
 When the user wants a clickable map, we also have to record that this
@@ -392,6 +479,248 @@ panel as a source to be transferred on that new destination.
 <p>
 And we just write the PNG to a file. If the user wanted a clickable map,
 also create the HTML file.
+</p>
+<h2>B. CONTRIBUTING TO THE PROJECT</h2>
+<p>
+(This text is adapted from the bioruby README.DEV)
+</p>
+<p>
+There are many possible ways to contribute to the <a
+href="../classes/Bio/Graphics.html">Bio::Graphics</a> project, such as:
+</p>
+<ul>
+<li>Join the discussion on the BioRuby mailing list
+
+</li>
+<li>Send a bug report or write a bug fix patch
+
+</li>
+<li>Add and correct documentation
+
+</li>
+<li>Develop code for new features, etc.
+
+</li>
+</ul>
+<p>
+All of these are welcome! However, this document describes the last option,
+how to contribute your code to <a
+href="../classes/Bio/Graphics.html">Bio::Graphics</a>.
+</p>
+<h2>Coding style</h2>
+<p>
+You will need to follow the typical coding styles of the BioRuby modules:
+</p>
+<h3>Use the following naming conventions</h3>
+<ul>
+<li>CamelCase for module and class names
+
+</li>
+<li>&#8216;_&#8217;-separated_lowercase for method names
+
+</li>
+<li>&#8216;_&#8217;-separated_lowercase for variable names
+
+</li>
+<li>all UPPERCASE for constants
+
+</li>
+</ul>
+<h3>Indentation must not include tabs</h3>
+<ul>
+<li>Use 2 spaces for indentation.
+
+</li>
+<li>Don&#8216;t replace spaces to tabs.
+
+</li>
+</ul>
+<h3>Comments</h3>
+<p>
+Don&#8216;t use <tt>=begin</tt> and <tt>=end</tt> blocks for comments. If
+you need to add comments, include it in the RDoc documentation.
+</p>
+<h3>Tutorials</h3>
+<p>
+Additional tutorial documentation and working examples are encouraged with
+your contribution. You may use the header part of the file for this
+purpose.
+</p>
+<h3>Standard documentation</h3>
+<h4>of files</h4>
+<p>
+Each file should start with a header, which covers the following topics:
+</p>
+<ul>
+<li>copyright
+
+</li>
+<li>license
+
+</li>
+<li>description of the file (<em>not</em> the classes; see below)
+
+</li>
+<li>any references, if appropriate
+
+</li>
+</ul>
+<p>
+The header should be formatted as follows:
+</p>
+<pre>
+  #
+  # = bio/graphics/ruler - class to draw ruler
+  #
+  # Copyright::  Copyright (C) 2001, 2003-2005 Bio R. Hacker &lt;brh@example.org&gt;,
+  # Copyright::  Copyright (C) 2006 Chem R. Hacker &lt;crh@example.org&gt;
+  #
+  # License::    The Ruby License
+  #
+  # == Description
+  #
+  # This file contains classes that implement the ruler of a graphic.
+  #
+  module Bio
+    module Graphics
+      class Ruler
+
+      end
+    end
+  end
+</pre>
+<h4>of classes and methods within those files</h4>
+<p>
+Classes and methods should be documented in a standardized format, as in
+the following example (from bioruby&#8216;s lib/bio/graphics/sequence.rb):
+</p>
+<pre>
+  # == Description
+  #
+  # Bio::Sequence objects represent annotated sequences in bioruby.
+  # A Bio::Sequence object is a wrapper around the actual sequence,
+  # represented as either a Bio::Sequence::NA or a Bio::Sequence::AA object.
+  # For most users, this encapsulation will be completely transparent.
+  # Bio::Sequence responds to all methods defined for Bio::Sequence::NA/AA
+  # objects using the same arguments and returning the same values (even though
+  # these methods are not documented specifically for Bio::Sequence).
+  #
+  # == Usage
+  #
+  #   require 'bio'
+  #
+  #   # Create a nucleic or amino acid sequence
+  #   dna = Bio::Sequence.auto('atgcatgcATGCATGCAAAA')
+  #   rna = Bio::Sequence.auto('augcaugcaugcaugcaaaa')
+  #   aa = Bio::Sequence.auto('ACDEFGHIKLMNPQRSTVWYU')
+  #
+  #   # Print in FASTA format
+  #   puts dna.output(:fasta)
+  #
+  #   # Print all codons
+  #   dna.window_search(3,3) do |codon|
+  #     puts codon
+  #   end
+  #
+  class Sequence
+
+    # Create a new Bio::Sequence object
+    #
+    #   s = Bio::Sequence.new('atgc')
+    #   puts s                                  # =&gt; 'atgc'
+    #
+    # Note that this method does not intialize the contained sequence
+    # as any kind of bioruby object, only as a simple string
+    #
+    #   puts s.seq.class                        # =&gt; String
+    #
+    # See Bio::Sequence#na, Bio::Sequence#aa, and Bio::Sequence#auto
+    # for methods to transform the basic String of a just created
+    # Bio::Sequence object to a proper bioruby object
+    # ---
+    # *Arguments*:
+    # * (required) _str_: String or Bio::Sequence::NA/AA object
+    # *Returns*:: Bio::Sequence object
+    def initialize(str)
+      @seq = str
+    end
+
+    # The sequence identifier.  For example, for a sequence
+    # of Genbank origin, this is the accession number.
+    attr_accessor :entry_id
+
+    # An Array of Bio::Feature objects
+    attr_accessor :features
+  end # Sequence
+</pre>
+<p>
+Preceding the class definition (<tt>class Sequence</tt>), there is at least
+a description and a usage example. Please use the <tt>Description</tt> and
+<tt>Usage</tt> headings. If appropriate, refer to other classes that
+interact with or are related to the class.
+</p>
+<p>
+The code in the usage example should, if possible, be in a format that a
+user can copy-and-paste into a new script to run. It should illustrate the
+most important uses of the class. If possible and if it would not clutter
+up the example too much, try to provide any input data directly into the
+usage example, instead of refering to ARGV or ARGF for input.
+</p>
+<pre>
+  dna = Bio::Sequence.auto('atgcatgcATGCATGCAAAA')
+</pre>
+<p>
+Otherwise, describe the input shortly, for example:
+</p>
+<pre>
+  # input should be string consisting of nucleotides
+  dna = Bio::Sequence.auto(ARGF.read)
+</pre>
+<p>
+Methods should be preceded by a comment that describes what the method
+does, including any relevant usage examples. (In contrast to the
+documentation for the class itself, headings are not required.) In
+addition, any arguments should be listed, as well as the type of thing that
+is returned by the method. The format of this information is as follows:
+</p>
+<pre>
+  # ---
+  # *Arguments*:
+  # * (required) _str_: String or Bio::Sequence::NA
+  # * (optional) _nr_: a number that means something
+  # *Returns*:: true or false
+</pre>
+<p>
+Attribute accessors can be preceded by a short description.
+</p>
+<h3>Exception handling</h3>
+<p>
+Don&#8216;t use
+</p>
+<pre>
+  $stderr.puts &quot;WARNING&quot;
+</pre>
+<p>
+in your code. Instead, try to avoid printing error messages. For fatal
+errors, use <tt>raise</tt> with an appropriate message.
+</p>
+<h3>Testing code should use &#8216;test/unit&#8216;</h3>
+<p>
+Unit tests should come with your modules by which you can assure what you
+meant to do with each method. The test code is useful to make maintenance
+easy and ensure stability. The use of
+</p>
+<pre>
+  if __FILE__ == $0
+</pre>
+<p>
+is deprecated.
+</p>
+<h2>Maintenance</h2>
+<p>
+Finally, please maintain the code you&#8216;ve contributed. Please let us
+know (on the bioruby list) before you commit, so that users can discuss on
+the change.
 </p>
 
     </div>