Ewan Birney

NAME

Bio::Tools::Blast::HTML.pm - Bioperl Utility module for HTML formatting Blast reports

SYNOPSIS

Adding HTML-formatting

    use Bio::Tools::Blast::HTML qw(&get_html_func);

    $func = &get_html_func();

    # Now as each line of the report is read, pass it to &$func($line).

See get_html_func() for details. Also see Bio::Tools::Blast::to_html for an example of usage.

Removing HTML-formatting

    use Bio::Tools::Blast::HTML qw(&strip_html);

    &strip_html(\$blast_report_string)

See strip_html() for details.

INSTALLATION

This module is included with the central Bioperl distribution:

   http://bio.perl.org/Core/Latest
   ftp://bio.perl.org/pub/DIST

Follow the installation instructions included in the README file.

DESCRIPTION

This module can be used to add HTML formatting to or remove HTML formatting from a raw Blast sequence analysis report. Hypertext links to the appropriate database are added for each hit sequence (GenBank, Swiss-Prot, PIR, PDB, SGD).

This module is intended for use by Bio::Tools::Blast.pm and related modules, which provides a front-end to the methods in Bio::Tools::Blast::HTML.pm.

DEPENDENCIES

Bio::Tools::Blast::HTML.pm does not inherit from any other class besides Exporter. It is used by Bio::Tools::Blast.pm only. This class relies on Bio::Tools::WWW.pm to provide key URLS for adding links in the Blast report to specific databases.

The greatest dependency comes from the dynamic state of the web. URLs are are likely to change in the future, so all links cannot be guaranteed to work indefinitely. Feel free to report broken or incorrect database links (FEEDBACK ). Thanks!

SEE ALSO

 Bio::Tools::Blast.pm    - Blast object.
 Bio::Tools::WWW.pm      - URL repository.

 http://bio.perl.org/Projects/modules.html  - Online module documentation
 http://bio.perl.org/Projects/Blast/        - Bioperl Blast Project     
 http://bio.perl.org/                       - Bioperl Project Homepage

FEEDBACK

Mailing Lists

User feedback is an integral part of the evolution of this and other Bioperl modules. Send your comments and suggestions preferably to one of the Bioperl mailing lists. Your participation is much appreciated.

    bioperl-l@bioperl.org          - General discussion
    http://bio.perl.org/MailList.html             - About the mailing lists

Reporting Bugs

Report bugs to the Bioperl bug tracking system to help us keep track the bugs and their resolution. Bug reports can be submitted via email or the web:

    bioperl-bugs@bio.perl.org                   
    http://bio.perl.org/bioperl-bugs/           

AUTHOR

Steve Chervitz, <sac@bioperl.org>

COPYRIGHT

Copyright (c) 1998-2000 Steve Chervitz. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

APPENDIX

Methods beginning with a leading underscore are considered private and are intended for internal use by this module. They are not considered part of the public interface and are described here for documentation purposes only.

get_html_func

 Usage     : $func_ref = &get_html_func( [array_ref] );
           : This method is exported.
 Purpose   : Provides a function that adds HTML formatting to a
           : raw Blast report line-by-line.
           : Utility method used by to_html() in Bio::Tools::Blast.pm.
 Returns   : Reference to an anonymous function to be used while reading in  
           : the raw report. 
           : The function itself operates on the Blast report line-by-line
           : HTML-ifying it and printing it to STDOUT (or saving in the supplied
           : array ref) as it goes:
           :     foreach( @raw_report ) { &$func_ref($_); }
 Argument  : array ref (optional) for storing the HTML-formatted report.
           : If no argument is supplied, HTML output is sent to STDOUT.
 Throws    : Croaks if an argument is supplied and is not an array ref.
           : The anonymous function returned by this method croaks if 
           : the Blast output appears to be HTML-formatted already.
 Comments  : Adapted from a script by Keith Robison  November 1993 
           : krobison@nucleus.harvard.edu; http://golgi.harvard.edu/gilbert.html
           : Modified extensively by Steve Chervitz and Mike Cherry.
           : Some modifications are customizations for BLAST reports served up
           : by the Saccharomyces Genome Database.
           : Feel free to modify or replace portions of this code as necessary
           : to accomodate new BLAST datasets or changes to the Blast format.

See Also : Bio::Tools::Blast::to_html()

_set_markup_data

 Usage     : n/a; utility method used by get_html_func()
 Purpose   : Sets various hashes and regexps used for adding HTML
           : to raw Blast output.
 Returns   : n/a
 Comments  : These items need be set only once. 

See Also : get_html_func()

_markup_database

 Usage     : n/a; utility method used by get_html_func()
 Purpose   : Converts a cryptic database ID into a readable name.
 Returns   : n/a
 Comments  : This is used for converting local database IDs into
           : understandable terms. At present, it only recognizes
           : databases used locally at SGD. 

See Also : get_html_func()

_markup_report

 Usage     : n/a; utility function used by get_html_func()
 Purpose   : Adds HTML links to aid navigation of raw Blast output.
 Returns   : n/a
 Comments  : HTML-formatting is dependent on the Blast server that
           : provided the Blast report. Currently, this function can handle reports
           : produced by NCBI and SGD. Feel free to modify this function
           : to accomodate reports produced by other servers/sites.
           :
           : This function is simply a collection of substitution regexps 
           : that recognize and modify the relevant lines of the Blast report. 
           : All non-header lines of the report are passed through this function,
           : only the ones that match will get modified.
           :
           : The general scheme for adding links is as follows:
           : (Some of the SGD markups do not follow this scheme precisely
           :  but this is the general trend.)
           :
           : For description lines in the summary table at the top of report:
           :
           : DB:SEQUENCE_ID  DESCRIPTION   SIGNIF_VAL
           :        DB          = links to the indicated database (if not Gen/Embl/Ddbj).
           :        SEQUENCE_ID = links to GenBank entry for the sequence.
           :        SIGNIF_VAL  = internal link to relevant alignment section.
           :
           : For the alignment sections in the body of the report:
           :
           : DB:SEQUENCE_ID  (Back | Top) DESCRIPTION 
           :        DB          = links to the indicated database (if not Gen/Embl/Ddbj).
           :        SEQUENCE_ID = links to GenBank entry for the sequence.
           :        SIGNIF_VAL  = internal link to alignment section.
           :        Back        = internal link to description line in summary section.
           :        Top         = internal link to top of page.
           :
           : 'DB' links are created for PDB, PIR, and SwissProt sequences.
           :
           : RE_PARSING HTML-FOMRATTED REPORTS:
           : ----------------------------------
           : HTML-formatted reports generated by this module, as well as reports
           : obtained from the NCBI servers, should be parsable
           : by Bio::Tools::Blast.pm. Parsing HTML-formatted reports is
           : slow, however, since the HTML must be removed prior to parsing.
           : Parsing HTML-formatted reports is dependent on the specific structure
           : of the HTML and is generally not recommended.
           : 
           : Note that since URLs can change without notice, links will need updating.
           : The links are obtained from Bio::Tools::WWW.pm updating that module
           : will update this as well.
           :
 Bugs      : Some links to external databases are incorrect
           : (in particular, for 'bbs' and 'prf' databases on NCBI Blast reports.
           : Some links may fail as a result of the dynamic nature of the web.
           : Hypertext links are not added to hits without database ids.

See Also : get_html_func(), Bio::Tools::WWW.pm, strip_html()

_prog_ref_html

 Usage     : n/a; utility method used by get_html_func().
 Purpose   : Get a special alert for BLAST reports against all of GenBank/EMBL.
 Returns   : string with HTML

See Also : get_html_func()

_genbank_alert

 Usage     : n/a; utility method used by get_html_func().
 Purpose   : Get a special alert for BLAST reports against all of GenBank/EMBL.
 Returns   : string with HTML

See Also : get_html_func()

strip_html

 Usage     : $boolean = &strip_html( string_ref );
           : This method is exported.
 Purpose   : Removes HTML formatting from a supplied string.
           : Attempts to restore the Blast report to enable
           : parsing by Bio::Tools::Blast.pm.
 Returns   : Boolean: true if string was stripped, false if not.
 Argument  : string_ref = reference to a string containing the whole Blast
           :              report.
 Throws    : Croaks if the argument is not a scalar reference.
 Comments  : Based on code originally written by Alex Dong Li
           : (ali@genet.sickkids.on.ca).
           : This method does some Blast-specific stripping 
           : (adds back a '>' character in front of each HSP 
           : alignment listing).
           :   
           : THIS METHOD IS HIGHLY ERROR-PRONE!
           :
           : Removal of the HTML tags and accurate reconstitution of the
           : non-HTML-formatted report is highly dependent on structure of
           : the HTML-formatted version. For example, it assumes that first 
           : line of each alignment section (HSP listing) starts with a
           : <a name=..> anchor tag. This permits the reconstruction of the 
           : original report in which these lines begin with a ">".
           : This is required for parsing.
           :
           : If the structure of the Blast report itself is not intended to
           : be a standard, the structure of the HTML-formatted version
           : is even less so. Therefore, the use of this method to
           : reconstitute parsable Blast reports from HTML-format versions
           : should be considered a temorary solution.

See Also : Bio::Tools::Blast::parse()