.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Boulder::Blast 3pm"
.TH Boulder::Blast 3pm "2021-01-05" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Boulder::Blast \- Parse and read BLAST files
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Boulder::Blast;
\&
\&  # parse from a single file
\&  $blast = Boulder::Blast\->parse(\*(Aqrun3.blast\*(Aq);
\&
\&  # parse and read a set of blast output files
\&  $stream = Boulder::Blast\->new(\*(Aqrun3.blast\*(Aq,\*(Aqrun4.blast\*(Aq);
\&  while ($blast = $stream\->get) {
\&     # do something with $blast object
\&  }
\&
\&  # parse and read a whole directory of blast runs
\&  $stream = Boulder::Blast\->new(<*.blast>);
\&  while ($blast = $stream\->get) {
\&     # do something with $blast object
\&  }
\&
\&  # parse and read from STDIN
\&  $stream = Boulder::Blast\->new;
\&  while ($blast = $stream\->get) {
\&     # do something with $blast object
\&  }
\&
\&  # parse and read as a filehandle
\&  $stream = Boulder::Blast\->newFh(<*.blast>);
\&  while ($blast = <$stream>) {
\&     # do something with $blast object
\&  }
\&
\&  # once you have a $blast object, you can get info about it:      
\&  $query = $blast\->Blast_query;
\&  @hits  = $blast\->Blast_hits;
\&  foreach $hit (@hits) {
\&     $hit_sequence = $hit\->Name;    # get the ID
\&     $significance = $hit\->Signif;  # get the significance
\&     @hsps = $hit\->Hsps;            # list of HSPs
\&     foreach $hsp (@hsps) {
\&       $query   = $hsp\->Query;      # query sequence
\&       $subject = $hsp\->Subject;    # subject sequence
\&       $signif  = $hsp\->Signif;     # significance of HSP
\&     }
\&  }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \fIBoulder::Blast\fR class parses the output of the \fBWashington
University (\s-1WU\s0)\fR or National Cenber for Biotechnology Information
(\s-1NCBI\s0) series of \s-1BLAST\s0 programs and turns them into \fIStone\fR records.
You may then use the standard Stone access methods to retrieve
information about the \s-1BLAST\s0 run, or add the information to a Boulder
stream.
.PP
The parser works equally well on the contents of a static file, or on
information read dynamically from a filehandle or pipe.
.SH "METHODS"
.IX Header "METHODS"
.SS "\fBparse()\fP Method"
.IX Subsection "parse() Method"
.Vb 2
\&    $stone = Boulder::Blast\->parse($file_path);
\&    $stone = Boulder::Blast\->parse($filehandle);
.Ve
.PP
The \fI\f(BIparse()\fI\fR method accepts a path to a file or a filehandle, parses
its contents, and returns a Boulder Stone object.  The file path may
be absolute or relative to the current directgly.  The filehandle may
be specified as an IO::File object, a FileHandle object, or a
reference to a glob (\f(CW\*(C`\e*FILEHANDLE\*(C'\fR notation).  If you call
\&\fI\f(BIparse()\fI\fR without any arguments, it will try to parse the contents of
standard input.
.SS "\fBnew()\fP Method"
.IX Subsection "new() Method"
.Vb 3
\&    $stream = Boulder::Blast\->new;
\&    $stream = Boulder::Blast\->new($file [,@more_files]);
\&    $stream = Boulder::Blast\->new(\e*FILEHANDLE);
.Ve
.PP
If you wish, you may create the parser first with \fIBoulder::Blast\fR
\&\fI\f(BInew()\fI\fR, and then invoke the parser object's \fI\f(BIparse()\fI\fR method as
many times as you wish to, producing a Stone object each time.
.SH "TAGS"
.IX Header "TAGS"
The following tags are defined in the parsed Blast Stone object:
.SS "Information about the program"
.IX Subsection "Information about the program"
These top-level tags provide information about the version of the
\&\s-1BLAST\s0 program itself.
.IP "Blast_program" 4
.IX Item "Blast_program"
The name of the algorithm used to run the analysis.  Possible values
include:
.Sp
.Vb 11
\&        blastn
\&        blastp
\&        blastx
\&        tblastn
\&        tblastx
\&        fasta3
\&        fastx3
\&        fasty3
\&        tfasta3
\&        tfastx3
\&        tfasty3
.Ve
.IP "Blast_version" 4
.IX Item "Blast_version"
This gives the version of the program in whatever form appears
on the banner page, e.g. \*(L"2.0a19\-WashU\*(R".
.IP "Blast_program_date" 4
.IX Item "Blast_program_date"
This gives the date at which the program was compiled, if and
only if it appears on the banner page.
.SS "Information about the run"
.IX Subsection "Information about the run"
These top-level tags give information about the particular run, such
as the parameters that were used for the algorithm.
.IP "Blast_run_date" 4
.IX Item "Blast_run_date"
This gives the date and time at which the similarity analysis
was run, in the format \*(L"Fri Jul  6 09:32:36 1998\*(R"
.IP "Blast_parms" 4
.IX Item "Blast_parms"
This points to a subrecord containing information about the
algorithm's runtime parameters.  The following subtags are
used.  Others may be added in the future:
.Sp
.Vb 5
\&        Hspmax          the value of the \-hspmax argument
\&        Expectation     the value of E
\&        Matrix          the matrix in use, e.g. BLOSUM62
\&        Ctxfactor       the value of the \-ctxfactor argument
\&        Gapall          The value of the \-gapall argument
.Ve
.SS "Information about the query sequence and subject database"
.IX Subsection "Information about the query sequence and subject database"
Thse top-level tags give information about the query sequence and the
database that was searched on.
.IP "Blast_query" 4
.IX Item "Blast_query"
The identifier for the search sequence, as defined by the
\&\s-1FASTA\s0 format.  This will be the first set of non-whitespace
characters following the \*(L">\*(R" character.  In other words, the search
sequence \*(L"name\*(R".
.IP "Blast_query_length" 4
.IX Item "Blast_query_length"
The length of the query sequence, in base pairs.
.IP "Blast_db" 4
.IX Item "Blast_db"
The Unix filesystem path to the subject database.
.IP "Blast_db_title" 4
.IX Item "Blast_db_title"
The title of the subject database.
.SS "The search results: the \fIBlast_hits\fP tag."
.IX Subsection "The search results: the Blast_hits tag."
Each \s-1BLAST\s0 hit is represented by the tag \fIBlast_hits\fR.  There may be
zero, one, or many such tags.  They will be presented in reverse
sorted order of significance, i.e. most significant hit first.
.PP
Each \fIBlast_hits\fR tag is a Stone subrecord containing the following
subtags:
.IP "Name" 4
.IX Item "Name"
The name/identifier of the sequence that was hit.
.IP "Length" 4
.IX Item "Length"
The total length of the sequence that was hit
.IP "Signif" 4
.IX Item "Signif"
The significance of the hit.  If there are multiple HSPs in the hit,
this will be the most significant (smallest) value.
.IP "Identity" 4
.IX Item "Identity"
The percent identity of the hit.  If there are multiple HSPs, this
will be the one with the highest percent identity.
.IP "Expect" 4
.IX Item "Expect"
The expectation value for the hit.  If there are multiple HSPs, this
will be the lowest expectation value in the set.
.IP "Hsps" 4
.IX Item "Hsps"
One or more sub-sub-tags, pointing to a nested record containing
information about each high-scoring segment pair (\s-1HSP\s0).  See the next
section for details.
.SS "The Hsp records: the \fIHsps\fP tag"
.IX Subsection "The Hsp records: the Hsps tag"
Each \fIBlast_hit\fR tag will have at least one, and possibly several
\&\fIHsps\fR tags, each one corresponding to a high-scoring segment pair
(\s-1HSP\s0).  These records contain detailed information about the hit,
including the alignments.  Tags are as follows:
.IP "Signif" 4
.IX Item "Signif"
The significance (P value) of this \s-1HSP.\s0
.IP "Bits" 4
.IX Item "Bits"
The number of bits of significance.
.IP "Expect" 4
.IX Item "Expect"
Expectation value for this \s-1HSP.\s0
.IP "Identity" 4
.IX Item "Identity"
Percent identity.
.IP "Positives" 4
.IX Item "Positives"
Percent positive matches.
.IP "Score" 4
.IX Item "Score"
The Smith-Waterman alignment score.
.IP "Orientation" 4
.IX Item "Orientation"
The word \*(L"plus\*(R" or \*(L"minus\*(R".  This tag is only present for nucleotide
searches, when the reverse complement match may be present.
.IP "Strand" 4
.IX Item "Strand"
Depending on algorithm used, indicates complementarity of match and
possibly the reading frame.  This is copied out of the blast report.
Possibilities include:
.Sp
.Vb 2
\& "Plus / Minus" "Plus / Plus" \-\- blastn algorithm
\& "+1 / \-2" "+2 / \-2"         \-\- blastx, tblastx
.Ve
.IP "Query_start" 4
.IX Item "Query_start"
Position at which the \s-1HSP\s0 starts in the query sequence (1\-based
indexing).
.IP "Query_end" 4
.IX Item "Query_end"
Position at which the \s-1HSP\s0 stops in the query sequence.
.IP "Subject_start" 4
.IX Item "Subject_start"
Position at which the \s-1HSP\s0 starts in the subject (target) sequence.
.IP "Subject_end" 4
.IX Item "Subject_end"
Position at which the \s-1HSP\s0 stops in the subject (target) sequence.
.IP "Query, Subject, Alignment" 4
.IX Item "Query, Subject, Alignment"
These three tags contain strings which, together, create the gapped
alignment of the query sequence with the subject sequence.
.Sp
For example, to print the alignment of the first \s-1HSP\s0 of the first
match, you might say:
.Sp
.Vb 2
\&  $hsp = $blast\->Blast_hits\->Hsps;
\&  print join("\en",$hsp\->Query,$hsp\->Alignment,$hsp\->Subject),"\en";
.Ve
.PP
See the bottom of this manual page for an example \s-1BLAST\s0 run.
.SH "CAVEATS"
.IX Header "CAVEATS"
This module has been extensively tested with \s-1WUBLAST,\s0 but very little
with \s-1NCBI BLAST.\s0  It probably will not work with \s-1PSI\s0 Blast or other
variants.
.PP
The author plans to adapt this module to parse other formats, as well
as non-BLAST formats such as the output of Fastn.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Boulder, Boulder::GenBank
.SH "AUTHOR"
.IX Header "AUTHOR"
Lincoln Stein <lstein@cshl.org>.
.PP
Copyright (c) 1998\-1999 Cold Spring Harbor Laboratory
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.  See \s-1DISCLAIMER\s0.txt for
disclaimers of warranty.
.SH "EXAMPLE BLASTN RUN"
.IX Header "EXAMPLE BLASTN RUN"
This output was generated by the \fIquickblast.pl\fR program, which is
located in the \fIeg/\fR subdirectory of the \fIBoulder\fR distribution
directory.  It is a typical \fIblastn\fR (nucleotide\->nucleotide) run;
however long lines (usually \s-1DNA\s0 sequences) have been truncated.  Also
note that per the Boulder protocol, the percent sign (%) is escaped in
the usual way.  It will be unescaped when reading the stream
back in.
.PP
.Vb 10
\& Blast_run_date=Fri Nov  6 14:40:41 1998
\& Blast_db_date=2:40 PM EST Nov 6, 1998
\& Blast_parms={
\&   Hspmax=10
\&   Expectation=10
\&   Matrix=+5,\-4
\&   Ctxfactor=2.00
\& }
\& Blast_program_date=05\-Feb\-1998
\& Blast_db= /usr/tmp/quickblast18202aaaa
\& Blast_version=2.0a19\-WashU
\& Blast_query=BCD207R
\& Blast_db_title= test.fasta
\& Blast_query_length=332
\& Blast_program=blastn
\& Blast_hits={
\&   Signif=3.5e\-74
\&   Expect=3.5e\-74,
\&   Name=BCD207R
\&   Identity=100%25
\&   Length=332
\&   Hsps={
\&     Subject=GTGCTTTCAAACATTGATGGATTCCTCCCCTTGACATATATATATACTTTGGGTTCCCGCAA...
\&     Signif=3.5e\-74
\&     Length=332
\&     Bits=249.1
\&     Query_start=1
\&     Subject_end=332
\&     Query=GTGCTTTCAAACATTGATGGATTCCTCCCCTTGACATATATATATACTTTGGGTTCCCGCAA...
\&     Positives=100%25
\&     Expect=3.5e\-74,
\&     Identity=100%25
\&     Query_end=332
\&     Orientation=plus
\&     Score=1660
\&     Strand=Plus / Plus
\&     Subject_start=1
\&     Alignment=||||||||||||||||||||||||||||||||||||||||||||||||||||||||||...
\&   }
\& }
\& =
.Ve
.SH "Example BLASTP run"
.IX Header "Example BLASTP run"
Here is the output from a typical \fIblastp\fR (protein\->protein) run.
Long lines have again been truncated.
.PP
.Vb 10
\& Blast_run_date=Fri Nov  6 14:37:23 1998
\& Blast_db_date=2:36 PM EST Nov 6, 1998
\& Blast_parms={
\&   Hspmax=10
\&   Expectation=10
\&   Matrix=BLOSUM62
\&   Ctxfactor=1.00
\& }
\& Blast_program_date=05\-Feb\-1998
\& Blast_db= /usr/tmp/quickblast18141aaaa
\& Blast_version=2.0a19\-WashU
\& Blast_query=YAL004W
\& Blast_db_title= elegans.fasta
\& Blast_query_length=216
\& Blast_program=blastp
\& Blast_hits={
\&   Signif=0.95
\&   Expect=3.0,
\&   Name=C28H8.2
\&   Identity=30%25
\&   Length=51
\&   Hsps={
\&     Subject=HMTVEFHVTSQSW\-\-\-FGFEDHFHMIIR\-AVNDENVGWGVRYLSMAF
\&     Signif=0.95
\&     Length=46
\&     Bits=15.8
\&     Query_start=100
\&     Subject_end=49
\&     Query=HLTQD\-HGGDLFWGKVLGFTLKFNLNLRLTVNIDQLEWEVLHVSLHF
\&     Positives=52%25
\&     Expect=3.0,
\&     Identity=30%25
\&     Query_end=145
\&     Orientation=plus
\&     Score=45
\&     Subject_start=7
\&     Alignment=H+T + H     W    GF   F++ +R  VN + + W V ++S+ F
\&   }
\& }
\& Blast_hits={
\&   Signif=0.99
\&   Expect=4.7,
\&   Name=ZK896.2
\&   Identity=24%25
\&   Length=340
\&   Hsps={
\&     Subject=FSGKFTTFVLNKDQATLRMSSAEKTAEWNTAFDSRRGFF\-\-\-\-TSGNYGL...
\&     Signif=0.99
\&     Length=101
\&     Bits=22.9
\&     Query_start=110
\&     Subject_end=243
\&     Query=FWGKVLGFTL\-KFNLNLRLTVNIDQLEWEVLHVSLHFWVVEVSTDQTLSVE...
\&     Positives=41%25
\&     Expect=4.7,
\&     Identity=24%25
\&     Query_end=210
\&     Orientation=plus
\&     Score=65
\&     Subject_start=146
\&     Alignment=F GK   F L K    LR++      EW     S   +     T     +...
\&   }
\& }
\& =
.Ve