The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
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