Boulder::Blast(3pm)

💖 Boulder::Blast 💖

ok so this is the manual page for Boulder::Blast, and it lives in section 3pm of the Perl docs (yes, "User Contributed Perl Documentation", iconic behavior) ✨. It's a Perl module. It parses BLAST files. Let's gooo 🦋

---

🌸 NAME 🌸

Boulder::Blast — parse and read BLAST files 🧬✨

---

🎀 SYNOPSIS 🎀

bestie, here's the whole vibe. Every line, exactly as it is, no edits:

  use Boulder::Blast;

  # parse from a single file
  $blast = Boulder::Blast->parse('run3.blast');

  # parse and read a set of blast output files
  $stream = Boulder::Blast->new('run3.blast','run4.blast');
  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
     }
  }

notice how it does single files, whole piles of files, directories, STDIN, and filehandles? it's giving versatility 💅

---

💫 DESCRIPTION 💫

So. The Boulder::Blast class parses the output of the Washington University (WU) or National Cenber for Biotechnology Information (NCBI) series of BLAST programs, and turns them into Stone records 🪨✨. Once you've got that, you can use the standard Stone access methods to pull info about the BLAST run, or yeet the info into a Boulder stream. Obsessed.

And here's the slay part: the parser works equally well on the contents of a static file, or on information read dynamically from a filehandle or pipe. It does not care. Main character energy fr fr 🫶

---

🔥 METHODS 🔥

🍓 parse() Method 🍓

$stone = Boulder::Blast->parse($file_path);
$stone = Boulder::Blast->parse($filehandle);

The parse() method takes either a path to a file or a filehandle, parses whatever's inside, and hands you back a Boulder Stone object 💎. The file path can be absolute, or relative to the current directgly — wait, that's a typo in the original, it means the current directory, bestie, iykyk 😭.

The filehandle can be an IO::File object, a FileHandle object, or a reference to a glob (that's the "\*FILEHANDLE" notation, keep it exact please 💅).

And if you call parse() with no arguments at all? It'll try to parse the contents of standard input. Bold. Love that for it.

🦋 new() Method 🦋

$stream = Boulder::Blast->new;
$stream = Boulder::Blast->new($file [,@more_files]);
$stream = Boulder::Blast->new(\*FILEHANDLE);

If you want, you can create the parser first with Boulder::Blast new(), and then invoke the parser object's parse() method as many times as you wish, producing a Stone object each time. So you can be like "okay parser, do it again" and it does ✨

---

👑 TAGS 👑

These are the tags that get defined in the parsed Blast Stone object, bestie. Buckle up, there are a lot, and we're listing all of them because we respect completeness here 🎀

💜 Information about the program 💜

These top-level tags give you the tea about the version of the BLAST program itself.

• Blast_program — the name of the algorithm used to run the analysis. Possible values include:

blastn
blastp
blastx
tblastn
tblastx
fasta3
fastx3
fasty3
tfasta3
tfastx3
tfasty3

• Blast_version — the version of the program, in whatever form appears on the banner page, e.g. "2.0a19-WashU".
• Blast_program_date — the date at which the program was compiled, if and only if it appears on the banner page. No banner, no date. Periodt.

🌈 Information about the run 🌈

These top-level tags are all about the particular run — like, the parameters that were used for the algorithm. Very behind-the-scenes, very exclusive 💅

• Blast_run_date — the date and time at which the similarity analysis was run, in the format "Fri Jul 6 09:32:36 1998" (yes that's a double space, it's giving Jul␣␣6 and we're not touching it).
• Blast_parms — this points to a subrecord containing info about the algorithm's runtime parameters. These are the subtags used, and note: others may be added in the future, so don't come for me if there's more later 🙈

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

🧚 Information about the query sequence and subject database 🧚

(Original says "Thse" — a little typo moment, we're keeping the meaning and moving on 💀) These top-level tags give you the info about the query sequence and the database that got searched.

• Blast_query — the identifier for the search sequence, as defined by the FASTA format. This will be the first set of non-whitespace characters following the ">" character. In other words: the search sequence "name".
• Blast_query_length — the length of the query sequence, in base pairs.
• Blast_db — the Unix filesystem path to the subject database.
• Blast_db_title — the title of the subject database.

⭐ The search results: the Blast_hits tag ⭐

Each BLAST hit is represented by the tag Blast_hits. There may be zero, one, or many such tags. They come in reverse sorted order of significance, i.e. the most significant hit first. So the bestie is always at the front of the line 👑

Each Blast_hits tag is a Stone subrecord containing these subtags:

• Name — the name/identifier of the sequence that was hit.
• Length — the total length of the sequence that was hit.
• Signif — the significance of the hit. If there are multiple HSPs in the hit, this is the most significant (smallest) value.
• Identity — the percent identity of the hit. If there are multiple HSPs, this is the one with the highest percent identity.
• Expect — the expectation value for the hit. If there are multiple HSPs, this is the lowest expectation value in the set.
• Hsps — one or more sub-sub-tags, pointing to a nested record containing info about each high-scoring segment pair (HSP). Details are in the next section, keep reading bestie 🫶

💀 The Hsp records: the Hsps tag 💀

Every Blast_hit tag will have at least one, and possibly several, Hsps tags — each one corresponding to a high-scoring segment pair (HSP). These records are the detailed lore about the hit, alignments included. Tags are as follows:

• Signif — the significance (P value) of this HSP.
• Bits — the number of bits of significance.
• Expect — expectation value for this HSP.
• Identity — percent identity.
• Positives — percent positive matches.
• Score — the Smith-Waterman alignment score.
• Orientation — the word "plus" or "minus". This tag is only present for nucleotide searches, when the reverse complement match may be present.
• Strand — depending on the algorithm used, this indicates the complementarity of the match and possibly the reading frame. It's copied straight out of the blast report. Possibilities include:

 "Plus / Minus" "Plus / Plus" -- blastn algorithm
 "+1 / -2" "+2 / -2"         -- blastx, tblastx

• Query_start — position at which the HSP starts in the query sequence (1-based indexing, no zero-indexing nonsense here).
• Query_end — position at which the HSP stops in the query sequence.
• Subject_start — position at which the HSP starts in the subject (target) sequence.
• Subject_end — position at which the HSP stops in the subject (target) sequence.
• Query, Subject, Alignment — these three tags contain strings which, together, create the gapped alignment of the query sequence with the subject sequence. Cute little trio, they work as a team ✨

For example, to print the alignment of the first HSP of the first match, you might say:

$hsp = $blast->Blast_hits->Hsps;
print join("\n",$hsp->Query,$hsp->Alignment,$hsp->Subject),"\n";

See the bottom of this manual page for an example BLAST run 👀

---

🙈 CAVEATS 🙈

Real talk time, bestie, and this part matters:

• This module has been extensively tested with WUBLAST, but very little with NCBI BLAST. And it probably will not work with PSI Blast or other variants. So like, don't be surprised, okay? 😭
• The author plans to adapt this module to parse other formats, as well as non-BLAST formats such as the output of Fastn. Future plans, slay, but not yet.

---

🌟 SEE ALSO 🌟

Boulder, Boulder::GenBank

---

💅 AUTHOR 💅

Lincoln Stein <lstein@cshl.org>.

Copyright (c) 1998-1999 Cold Spring Harbor Laboratory

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See DISCLAIMER.txt for disclaimers of warranty.

---

🧬 EXAMPLE BLASTN RUN 🧬

This output was generated by the quickblast.pl program, which is located in the eg/ subdirectory of the Boulder distribution directory. It's a typical blastn (nucleotide->nucleotide) run; however, long lines (usually DNA sequences) have been truncated. Also note that per the Boulder protocol, the percent sign (%) is escaped in the usual way. It'll be unescaped when reading the stream back in. No cap 💯

 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=||||||||||||||||||||||||||||||||||||||||||||||||||||||||||...
   }
 }
 =

---

and that's part 1 bestie — more is coming, so don't go anywhere 🫶✨

🌈 Example BLASTP run 🌈

Okay bestie, now for the other flavor 💅 — here's what a typical blastp run looks like (that's protein ➡️ protein, in case you forgot already). And yeah, same deal as before: the long lines got chopped off with ... because this page is not about to be six miles wide. Not a bug, it's a vibe. 🫶

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     +...
  }
}
=

Look at that structure go 😭💖 — Blast_parms doing its settings thing up top, then two whole Blast_hits blocks stacked one after the other, each one carrying its own Hsps bundle, and then that lone little = sitting there at the end like the final mic drop 🎤✨. That's a nested vibe, and now you know exactly what it looks like when it lands on your screen.

Lowkey important: those %25 bits? That is literally, character for character what shows up. Do not "helpfully" rewrite them to %. Copy what you see, bestie. 🙈

---

And that's the whole page, you made it 🎀💜 Go forth and parse some BLAST output, you absolute legend 👑.

Signing off from perl v5.34.0, dated 2022-06-08 — yep, this is Boulder::Blast(3pm), and she ate. No crumbs. Periodt. 💅🌸