Help-Site Computer Manuals
  Algorithms & Data Structures   Programming Languages   Revision Control
  Cameras   Computers   Displays   Keyboards & Mice   Motherboards   Networking   Printers & Scanners   Storage
  Windows   Linux & Unix   Mac




Mark Wilkinson (, David Block ( 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;



 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=> '', -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(





                        -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 ( and Dave Block (


Description of Object tags, SeqCanvas Methods, and trapping Mouse events.

Object Tags:

Each map-widget has several ``reliable'' tags attached to it. These tags are FIDxxxx, Source and Strand, Type, and Canvas, where:

  • FIDxxxx is the unique identifier for that particular map-widget over all maps (even in multiple windows)

  • Source is derived from the ``source'' tag of the SeqFeature object this widget represents

  • Strand is derived from the ``strand'' tag of the SeqFeature object, converted into the GFF standard of +/-/. to represent the three possible strand values.

  • Type isthe feature type, derived from the primary_tag of the SeqFeature object

  • Map is either 'draft' or 'finished' to represent an object on the white or blue maps respectively

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(



                                [$lblSysMess | undef],


                                -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',


 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.

Mouse-Click and Drag

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.