Bio::Tk::SeqCanvas.pm - Graphical display of SeqI compliant objects
Mark Wilkinson (mwilkinson@gene.pbi.nrc.ca), David Block (dblock@gene.pbi.nrc.ca) Plant Biotechnology Institute, National Research Council of Canada. Copyright (c) National Research Council of Canada, October, 2000.
Anyone who intends to use and uses this software and code acknowledges and agrees to the following: The National Research Council of Canada (herein "NRC") disclaims any warranties, expressed, implied, or statutory, of any kind or nature with respect to the software, including without limitation any warranty or merchantability or fitness for a particular purpose. NRC shall not be liable in any event for any damages, whether direct or indirect, consequential or incidental, arising from the use of the software.
# To create a BioSeq map and return a handle to the map object:
use Tk;
Begin();
MainLoop;
sub Begin {
# set up the Tk Windows
my $MW = MainWindow = MainWindow->new (-title => "Map Of BioSeq Object");
my $Frame = $MW->Frame()->pack(-side => 'top');
my $lblSysMess = $MW->Label()->pack(-side => 'bottom', -fill => 'both');
# create a BioSeq object
my $SIO = Bio::SeqIO->new(-file=> 'genbankfile.gb', -format => 'GenBank');
my $SeqObj = $SIO->next_seq();
my $axis_length = 800; # how large I want the final map to be
# Draw the Map
$MapObj = SeqCanvas->new(
$axis_length,
$Frame,
$lblSysMess,
$SeqObj,
-orientation => 'vertical'
label => 'primary_id');
# SeqCanvas returns object reference for success
# returns -1 for failed initiation - no $SeqObj supplied
# returns -2 for bad sequence object
# returns -3 sequence has length 0
# returns -4 if orientation is uninterpretable
# returns -5 if supplied frame object is not a TK::frame
}
Creates an interactive scalable/zoomable map of all features and subfeatures of a Bio::SeqI compliant object. Basic functionality for selecting single and multiple map objects is inherent in the object itself: left-mouse click to select, SHIFT-left-mouse to select multiple. All other Tk Events are passed back up to the MainWindow object and can be trapped/bound by the user as they see fit. Colors and axis-offsets of mapped objects are assigned based on the "source" tag of the feature object. These are assigned "on the fly" based on whatever is contained in the BioSeq object provided.
This module requires an updated version of Gregg Helt's original BioTkPerl modules(version 0.81) which are available from BioPerl. The original BioTkPerl (version 0.80) is Copyright (c) Gregg Helt, 1995; Version 0.81 was generated by Mark Wilkinson, PBI-NRC, Oct., 2000.
Zooming routines/events in this module are conceptually based on the Zoom routines from Genotator (Copyright (c) 1996, The Regents of the University of California. Harris, N.L. (1997), Genome Research 7(7):754-762)
Mark Wilkinson (mwilkinson@gene.pbi.nrc.ca) and Dave Block (dblock@gene.pbi.nrc.ca)
Description of Object tags, SeqCanvas Methods, and trapping Mouse events.
Each map-widget has several "reliable" tags attached to it. These tags are FIDxxxx, Source and Strand, Type, and Canvas, where:
So for example, a map widget might have the tags :
FID22354 (no space)
Source GeneMarkHMM (single space separated)
Strand + (single space separated)
Type exon ( " )
Canvas draft ( " )
If your BioSeq Features are being derived from an external database, it is possible to also include the unique index number of that database entry as a fourth tag on the associated map-widget. To do so, create your SeqFeature objects with an additional tag "id", where the unique databse index number is the value of this tag. This index number is then attached to the widget as a fourth tag with the form:
DB_ID xxxxx (x's represent the unique index value)
The values of these three/four tags can be retrieved for any selected object using the getSelectedTags function (see below) in order to relate mapped objects back to their original database entries. Using the selectWithTag or recolorWithTag routines (see below) requires that you pass the **full tag** as the desired selection (eg. pass "Source GeneMarkHMM" not just "GeneMarkHMM")
Title : new
Usage : $MapObj= SeqCanvas->new(
$axis_length,
$Frame,
[$lblSysMess | undef],
$SeqObj,
-orientation => ['horizontal'|'vertical']
[, label => $tag])
Function : create a map from the Feature object provided
Returns : Handle to the Map object
Args :
axis_length in pixels,
a Tk::Frame object,
a Tk::Label or undef,
a BioSeqI compliant object,
the orientation for the map,
optionally the SeqFeature tag you wish to
use as the label
Title : mapFeatures
Usage : $FeatureIDs = $MapObj->mapFeatures('draft'|'finished',
\@FeatureObj)
Function : map SeqFeature objects to the 'draft'(white) or
'finished' (blue) maps
Returns : reference to a list of the FeatureID's of the mapped Features
Args : 'draft'|'finished', \@FeatureObj
Title : unmapFeatures Usage : my $FeatureObjsRef = $MapObj->unmapFeatures(\@FeatureIDs) Function : to remove mapped features from the map display Returns : referenced list of removed $FeatureObj objects
Title : getSelectedIDs
Usage : $FeatureIDs = $MapObj->getSelectedIDs
Function : to retrieve the FeatureID's of
all currently selected mapped objects
Returns : reference to a list of FeatureID's
Args : none
Title : getSelectedTags
Usage : ($FeatureID, $strand, $source,
$type, $canvas [, $DB_ID]) = $MapObj->getSelectedTags
Returns : FeatureID, Source, Strand, Type (i.e. Primary_tag),
Canvas ('draft' or 'finished'),
and Database_Index (if available).
Comment : This is to be used for single-selection events only!
Args : none
Title : getIDsWithTag Usage : $FeatureIDs = $MapObj->getIDsWithTag(\@taglist) Function : to retrieve the FeatureID's of all currently selected mapped objects Returns : reference to a list of FeatureID's Args : a reference to a list of tags (see discussion of proper tag format above)
Title : getSelectedFeatures
Usage : $FeatureHashRef = $MapObj->getSelectedFeatures
Returns : a reference to a hash where the FeatureID is the key,
and the Bio::SeqFeature Object is the value
Args : none
Title : getFeaturesWithTag
Usage : $FeatureHashRef = $MapObj->getFeaturesWithTag(\@taglist)
Returns : a reference to a hash where the FeatureID is the
key, and the Bio::SeqFeature Object is the value
Args : reference to a list of valid tags
(see discussion of proper tag format)
Title : clearSelections Usage : $MapObj->clearSelections Function : Clear all selection boxes and "selected" status of all Features. Returns : nothing Args : none
Title : selectFeatures
Usage : $MapObj->selectFeatures(\@FeatureIDs)
Function : "select" all Features with @FeatureID id's
Args : @FeatureIDs - a list of valid
FeatureIDs (of the form FIDnnn where nnn is a unique integer)
Title : selectWithTag Usage : $MapObj->selectWithTag(\@tag_list [,'draft'|'finished']) Function : "select" all features which have any of @tag_list tags. Args : @taglist, and optional 'draft' or 'finished' which map
Title : recolorWithTag
Usage : $MapObj->recolorWithTag('#XXXXXX'|'default', 'draft'|'finished', \@tag_list)
Function : change the color of mapped objects having one of @tag_list tags.
Returns : nothing
Args :
First arg:hex-reference to an RGB color value, or 'default'.
Second arg: the canvas ('draft', or 'finished')
Third arg: a referenced list of tags.
Title : assignCustomColors Usage : $MapObj->assignCustomColors($top) Function : change the default map-color for a selected widgets "Source" tag. Returns : nothing Args : a reference to a Tk::MainWindow object (new or existing).
Title : is_draft_feature Usage : $result = $MapObj->is_draft_feature($FeatureID) Function : check if a $FeatureID is on the draft (white) map. Returns : 1 for true, undef for false Args : the FeatureID you are querying
Title : is_finished_feature Usage : $result = $MapObj->is_finished_feature($FeatureID) Function : check if $FeatureID is on the finished (blue) map. Returns : 1 for true, undef for false Args : the FeatureID you are querying
The SeqCanvas both internally responds to mouse events, and sets "tags" on the mapped feature in response to mouse events such that the user can "trap" these events in the top-level windowing system and evaluate which mapped feature the user was manupulating.
Clicking or shift-Clicking the left mouse button over a mapped feature causes the feature(s) to become "selected". A selected object is displayed on the screen with a black box surrounding the object, and the object becomes tagged with a testable tag "selected" (use the getSelectedFeatures or getSelectedIDs to retrieve additional information about this object)
Both Double-clicking and Shift Double-Clicking the mouse over an object selects that (single) mapped feature. All other features become unselected.
Used to select multiple objects. Any object touched by the bounding box will be included in the selection.
As the mouse pointer enters the mapped widget, the tag "Mouse_over" is added to this object. information about this object could be retrieved by, for example, calling the getIDsWithTag(["Mouse_over"]) method. This tag is removed when the mouse pointer leaves the mapped-feature space. Bind the <Movement> event in the top-level windowing system to track the mouse movements if you wish to monitor the Mouse-Over widget events.
