/ 
bioperl-gui-0.7
/ Bio::Tk::Hitdisplay

NAME

Bio::Tk::HitDisplay - Frame-based widget for displaying Fasta or Blast hits/HSPs with optional text annotation

SYNOPSIS

use Bio::Tk::HitDisplay;
...
$hds = $parent->HitDisplay(?options?);

DESCRIPTION

HitDisplay is a Frame-based widget which contains a Canvas. When provided with a list of data structures, each representing a hit of a query sequence to a database, it draws:

  • A scale

    This is marked in residues (aa for a protein query, nt for a nucleic acid query)

  • The query sequence

    Represented as a single green line

  • Database hits

    A line for each Fasta hit, or a group of lines for each Blast hit (one per HSP)

The coordinates of the hits/HSPs on the subject sequence (i.e. the sequence in the database) are indicated below the ends of each line.

The HitDisplay delegates all standard options to the Canvas contained within it. The non-standard options for HitDisplay are:

-hitdata => \@hitdata

The structure of each element of this list is quite complex. They are normally generated from object(s) representing Blast or Fasta hits e.g.

Bio::PSU::IO::Blast::Hit
Bio::PSU::IO::Fasta::Hit

by their respective adapters

Bio::PSU::IO::Blast::HitAdapter
Bio::PSU::IO::Fasta::HitAdapter

This is normally hidden, unless you want to go and look.

Each element is a reference to a hash containing the following keys and values:

          { q_id     => 'query id',
	    s_id     => 'subject id',
	    expect   => 'expect value',
	    score    => 'percentage identity',
	    overlap  => 'length of hit',
	    q_len    => 'query length',
	    s_len    => 'subject length',
	    data     => \@data,
            text     => "Some text",
            callback => $callback }

@data is a list of references to lists, each of which contains the coordinates of a single Fasta hit or Blast HSP on both the query and subject sequences. Each innermost list contains 4 values; the start and end coordinates on the query sequence (indices 0 and 1) and the start and end coordinates on the subject sequence (indices 2 and 3). A Blast hit with 3 HSPs will look like this:

[ [ q_start1, q_end1, s_start1, s_end1 ],
  [ q_start2, q_end2, s_start2, s_end2 ],
  [ q_start3, q_end3, s_start3, s_end3 ] ]

The text field may contain any text which should be associated with that hit e.g. a more detailed account of the result or of the subject sequence. The display of this text is bound to a right mouse button click on the subject id in the canvas window. The text will appear just below the hit with one click and a subsequent click will hide it again.

The callback is a code reference which, if defined, will be bound to a left mouse button click on the subject id in the canvas window.

-hitcolours => \%colourhash

The hits or HSPs will be colour-coded according to percentage identity according to the key->value pairs in the colourhash. The default values are:

          { 90 => 'red',
	    80 => 'orange',
	    60 => 'gold',
	    40 => 'yellow' }

This indicates that hits where the query is >= 90% identical to the subject will be red, >= 80% will be orange etc. The hash supplied to -hitcolours will override the defaults.

-interval => integer >= 10

This defines the vertical spacing between hit lines on the canvas. The minimum (and default) value is 10.

Mouse bindings provided:

  • Vertical scrolling

    Wheel-mouse support is provided by binding buttons 4 and 5 to vertical scrolling (standard Z-axis mapping under XFree86 on Linux).

  • Panning

    Holding down the middle mouse button while dragging will pan the canvas in all directions

  • Display/hide all text annotations

    Double-clicking the left mouse button within the canvas will display all text annotations, while double-clicking with the right button will hide them. This is slow at the moment, with more than about 20 hits.

Possible improvements:

  • Speed up opening/closing all text annotations at once

  • Items other than text between the hits

  • Make more of the canvas configurable

    Mouse bindings should be made configurable. Perhaps the canvas items making up each hit should be given a unique tag

METHODS

Interaction with this widget should generally be by means of the standard Perl/Tk options. Internal methods are documented below.

AUTHOR

Keith James (kdj@sanger.ac.uk)

ACKNOWLEDGEMENTS

See Bio::PSU.pod

COPYRIGHT

Copyright (C) 2000 Keith James. All Rights Reserved.

DISCLAIMER

This module is provided "as is" without warranty of any kind. It may redistributed under the same conditions as Perl itself.

Populate

Title   : Populate
Usage   : N/A
Function: Standard composite Frame-based widget setup.
        : See 'man Tk::composite' for details
Returns : Nothing
Args    : Hash reference

draw_align

Title   : draw_align
Usage   : N/A
Function: Draws hit text, line and coords for the hits
Returns : Nothing
Args    : Canvas, hitdata hash reference, left margin for text,
        : x coord for lines, y coord for lines, interval between
        : sets of lines (representing 1 Fasta hit or 1+ Blast
        : HSPs), hitcolours hash reference

h_line

Title   : h_line
Usage   : N/A
Function: Draws a single hit/HSP line with the subject coords
        : below it
Returns : Nothing
Args    : Canvas, hit hash reference, x coord for line,
        : y coord for line, line width, line colour

draw_scale

Title   : draw_scale
Usage   : N/A
Function: Draws scale alongside line representing query
        : sequence
Returns : Nothing
Args    : Canvas, hit hash reference, left margin for text
        : x coord for line, y coord for line

deannotate_hit

Title   : deannotate_hit
Usage   : N/A
Function: Reverses the effect of annotate_hit
Returns : Nothing
Args    : Canvas, text item (subject id), text to be inserted
        : in gap, interval between hits

annotate_hit

Title   : annotate_hit
Usage   : N/A
Function: Displays hit annotation below a hit line by shuffling
        : all canvas elements down the canvas and placing the
        : annotation text in the gap
Returns : Nothing
Args    : Canvas, text item (subject id), text to be inserted
        : in gap, interval between hits