Bio::S...::fastq(3pm)

💖 Bio::S...::fastq — that's Bio::S...::fastq(3pm) bestie, from the User Contributed Perl Documentation section ✨

Okay so real talk, the title up top is the short version — the whole vibe is Bio::SeqIO::fastq and it's your girl for reading and writing FASTQ streams. Let's get into it 🫶

---

🌸 NAME 🌸

Bio::SeqIO::fastq — fastq sequence input/output stream. That's the whole job, and she does it flawlessly 💅

---

✨ SYNOPSIS ✨

Fair warning bestie, this first chunk is FASTQ parsing ONLY:

  ################## pertains to FASTQ parsing only ##################

  # grabs the FASTQ parser, specifies the Illumina variant
  my $in = Bio::SeqIO->new(-format    => 'fastq-illumina',
                           -file      => 'mydata.fq');

  # simple 'fastq' format defaults to 'sanger' variant
  my $out = Bio::SeqIO->new(-format    => 'fastq',
                            -file      => '>mydata.fq');

  # $seq is a Bio::Seq::Quality object
  while (my $seq = $in->next_seq) {
      $out->write_seq($seq);  # convert Illumina 1.3 to Sanger format
  }

  # for 4x faster parsing, one can do something like this for raw data
  use Bio::Seq::Quality;

  # $data is a hash reference containing all arguments to be passed to
  # the Bio::Seq::Quality constructor
  while (my $data = $in->next_dataset) {
      # process $data, such as trim, etc
      my $seq = Bio::Seq::Quality->new(%$data);

      # for now, write_seq only accepts Bio::Seq::Quality, but may be modified
      # to allow raw hash references for speed
      $out->write_seq($data);
  }

4x faster parsing? We love a speed queen 🏃♀️💨

---

🦋 DESCRIPTION 🦋

This object can transform Bio::Seq and Bio::Seq::Quality objects to and from FASTQ flat file databases. No cap.

FASTQ is a file format used frequently at the Sanger Centre and in next-gen sequencing to bundle a FASTA sequence and its quality data all cute together. A typical FASTQ entry takes the form:

  @HCDPQ1D0501
  GATTTGGGGTTCAAAGCAGTATCGATCAAATAGTAAATCCATTTGTTCAACTCACAGTTT.....
  +HCDPQ1D0501
  !''*((((***+))%%%++)(%%%%).1***-+*''))**55CCF>>>>>>CCCCCCC65.....

where:

• @ = descriptor, followed by one or more sequence lines
• + = optional descriptor (if present, must match first one), followed by one or more qual lines

Bestie listen: when writing FASTQ output, the redundant descriptor following the + is by default left off to save disk space. Slay, we love an efficient icon. But if you need it, you can set the quality_header() flag in order for this to be printed 💾

🧬 FASTQ and Bio::Seq::Quality mapping 🧬

FASTQ files have sequence and quality data on single line or multiple lines, and the quality values are single-byte encoded. The data maps very simply to Bio::Seq::Quality instances:

• first non-whitespace chars in descriptor → id^
• descriptor line → desc^
• sequence lines → seq
• quality → qual*
• FASTQ variant → namespace

^ first nonwhitespace chars are id(), everything else after (to end of line) is in desc()

• Converted to PHRED quality scores where applicable ('solexa')

🌈 FASTQ variants 🌈

This parser supports all variants of FASTQ, including Illumina v 1.0 and 1.3, periodt:

• sanger — original
• solexa — Solexa, Inc. (2004), aka Illumina 1.0
• illumina — Illumina 1.3

You can specify the variant by either passing the additional -variant parameter to the constructor:

  my $in = Bio::SeqIO->new(-format    => 'fastq',
                           -variant   => 'solexa',
                           -file      => 'mysol.fq');

or by passing the format and variant together (Bio::SeqIO will now handle this and convert it accordingly to the proper argument):

  my $in = Bio::SeqIO->new(-format    => 'fastq-solexa',
                           -file      => 'mysol.fq');

Variants can be converted back and forth from one another; however, due to the difference in scaling for solexa quality reads, converting from 'illumina' or 'sanger' FASTQ to solexa is not recommended 🙅♀️

---

📬 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://bioperl.org/wiki/Mailing_lists  - About the mailing lists

🫶 Support 🫶

Please direct usage questions or support issues to the mailing list:

bioperl-l@bioperl.org

rather than to the module maintainer directly. Many experienced and reponsive experts will be able look at the problem and quickly address it. Please include a thorough description of the problem with code and data examples if at all possible. (Yes they wrote "reponsive", we're keeping it, it's canon 🎀)

🐛 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 the web:

  https://github.com/bioperl/bioperl-live/issues

---

👑 AUTHORS - Chris Fields (taken over from Tony Cox) 👑

Email: cjfields at bioperl dot org

---

📖 APPENDIX 📖

The rest of the documentation details each of the object methods. Internal methods are usually preceded with a _ (iykyk 💅)

⭐ Bio::SeqIO interface methods ⭐

next_seq

• Title : next_seq
• Usage : $seq = $stream->next_seq()
• Function : returns the next sequence in the stream
• Returns : Bio::Seq::Quality object
• Args : NONE
• Status : Stable

write_seq

• Title : write_seq
• Usage : $stream->write_seq(@seq)
• Function : writes the $seq object into the stream
• Returns : 1 for success and 0 for error
• Args : Bio::Seq::Quality
• Note : This now conforms to SeqIO spec (module output is same format as next_seq)
• Status : Stable

variant

• Title : variant
• Usage : $format = $obj->variant();
• Function : Get and set method for the quality sequence variant. This is important for indicating the encoding/decoding to be used for quality data.

Current values accepted are:

• 'sanger' (original FASTQ) ASCII encoding from 33-126, PHRED quality score from 0 to 93
• 'solexa' (aka illumina1.0) ASCII encoding from 59-104, SOLEXA quality score from -5 to 40
• 'illumina' (aka illumina1.3) ASCII encoding from 64-104, PHRED quality score from 0 to 40

(Derived from the MAQ website):

For 'solexa', scores are converted to PHRED qual scores using:

    $Q = 10 * log(1 + 10 ** (ord($sq) - 64) / 10.0)) / log(10)

• Returns : string
• Args : new value, string

🧚 Plugin-specific methods 🧚

next_dataset

• Title : next_dataset
• Usage : $obj->next_dataset
• Function : returns a hash reference containing the parsed data
• Returns : hash reference
• Args : none
• Status : Stable

write_fastq

• Title : write_fastq
• Usage : $stream->write_fastq(@seq)
• Function : writes the $seq object into the stream
• Returns : 1 for success and 0 for error
• Args : Bio::Seq::Quality object
• Status : Deprecated (delegates to write_seq) 💀

write_fasta

• Title : write_fasta
• Usage : $stream->write_fasta(@seq)
• Function : writes the $seq object into the stream
• Returns : 1 for success and 0 for error
• Args : Bio::Seq object
• Note : This method does not currently delegate to Bio::SeqIO::fasta (maybe it should?). Not sure whether we should keep this as a convenience method.
• Status : Unstable

write_qual

• Title : write_qual
• Usage : $stream->write_qual(@seq)
• Function : writes the $seq object into the stream
• Returns : 1 for success and 0 for error
• Args : Bio::Seq::Quality object
• Note : This method does not currently delegate to Bio::SeqIO::qual (maybe it should?). Not sure whether we should keep this as a convenience method.
• Status : Unstable

validate

• Title : validate
• Usage : $obj->validate(0)
• Function : flag for format/qual range validation - default is 1, validate
• Returns : Bool (0/1)
• Args : Bool (0/1)
• Status : Stable (may be moved to interface)

quality_header

• Title : quality_header
• Usage : $obj->quality_header
• Function : flag for printing quality header - default is 0, no header
• Returns : Bool (0/1)
• Args : Bool (0/1)
• Status : Unstable (name may change dep. on feedback)

---

And that's the whole page bestie, you ate that 💅✨

Sign-off szn: this lil masterpiece is perl v5.32.1, dated 2021-08-15, and it's Bio::S...::fastq(3pm) — go forth and parse, main character 🌈🦋💖