Bio::SeqIO::scf(3pm)

💖 Bio::SeqIO::scf — the .scf file glow-up 💖

okay bestie, quick vibe check: this page is Bio::SeqIO::scf(3pm), and it lives in the User Contributed Perl Documentation section of the perl manual. yes, that's the whole header. we're keeping it, we're just saying it cuter. ✨

---

🌸 NAME 🌸

Bio::SeqIO::scf — the .scf file input/output stream. it's giving "trace files but make it a Perl object" 💅

---

🦋 SYNOPSIS 🦋

okay so, genuinely, do not use this module directly. like. at all. not the move, bestie.

use it through the Bio::SeqIO class instead, and go read Bio::SeqIO for the actual deets. that's it, that's the whole synopsis, no cap.

---

🎀 DESCRIPTION 🎀

this object can transform .scf files to and from Bio::Seq::SequenceTrace objects. the way it just does that. iconic.

also, there are mechanisms present to retrieve trace data from scf files. so if you came here for trace data, you're in the right place, periodt. 👑

---

💌 FEEDBACK 💌

🌈 Mailing Lists 🌈

user feedback is an integral part of the evolution of this and other Bioperl modules — literally, the glow-up is a group project. send your comments and suggestions preferably to one of the Bioperl mailing lists. your participation is much appreciated, fr fr. 🫶

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. (yes, "reponsive" — that's the original's spelling, we don't fix, we just report. 💀) please include a thorough description of the problem with code and data examples if at all possible. receipts help everyone, bestie.

🐛 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

---

✨ AUTHOR — Chad Matsalla ✨

Chad Matsalla — bioinformatics@dieselwurks.com

---

👑 CONTRIBUTORS 👑

Jason Stajich, jason@bioperl.org Tony Cox, avc@sanger.ac.uk Heikki Lehvaslaiho, heikki-at-bioperl-dot-org Nancy Hansen, nhansen at mail.nih.gov

the squad. the ensemble cast. we love them. 🌟

---

🔥 APPENDIX 🔥

the rest of the documentation details each of the object methods. internal methods are usually preceded with a _ (iykyk — that underscore is the "don't touch, that's backstage" marker).

⭐ next_seq()

• Title: next_seq()
• Usage: $scf = $stream->next_seq()
• Function: returns the next scf sequence in the stream
• Returns: a Bio::Seq::SequenceTrace object
• Args: NONE
• Notes: Fills the interface specification for SeqIO.

The SCF specification does not provide for having more then one sequence in a given scf. So once the filehandle has been open and passed to SeqIO do not expect to run this function more then once on a given scf unless you embraced and extended the SCF standard. SCF comments are accessible through the Bio::SeqI interface method annotation().

lowkey important: one scf = one sequence. don't come back for seconds unless you've gone off-spec and built your own thing. 🙈

🧚 _get_v3_quality()

• Title: _get_v3_quality()
• Usage: $self->_get_v3_quality()
• Function: Set the base qualities from version3 scf
• Returns: Nothing. Alters $self.
• Args: None.
• Notes: (nothing here, it's a mystery, it's minimalism)

🌸 _get_v3_peak_indices($buffer)

• Title: _get_v3_peak_indices($buffer)
• Usage: $self->_get_v3_peak_indices($buffer);
• Function: Unpacks the base accuracies for version3 scf
• Returns: Nothing. Alters $self
• Args: A scalar containing binary data.
• Notes: (nada)

💜 _get_v3_base_accuracies($buffer)

• Title: _get_v3_base_accuracies($buffer)
• Usage: $self->_get_v3_base_accuracies($buffer)
• Function: Set the base accuracies for version 3 scf's
• Returns: Nothing. Alters $self.
• Args: A scalar containing binary data.
• Notes: (empty, and that's okay)

🍓 _get_comments($buffer)

• Title: _get_comments($buffer)
• Usage: $self->_get_comments($buffer);
• Function: Gather the comments section from the scf and parse it into its components.
• Returns: a Bio::Annotation::Collection object
• Args: The buffer. It is expected that the buffer contains a binary string for the comments section of an scf file according to the scf file specifications.
• Notes: (nothing)

🦋 _get_header()

• Title: _get_header($buffer)
• Usage: $self->_get_header($buffer);
• Function: Gather the header section from the scf and parse it into its components.
• Returns: Reference to a hash containing the header components.
• Args: The buffer. It is expected that the buffer contains a binary string for the header section of an scf file according to the scf file specifications.
• Notes: None.

🎀 _parse_v2_bases($buffer)

• Title: _parse_v2_bases($buffer)
• Usage: $self->_parse_v2_bases($buffer);
• Function: Gather the bases section from the scf and parse it into its components.
• Returns: (the original leaves this blank, so we leave it blank — respecting the silence 🫡)
• Args: The buffer. It is expected that the buffer contains a binary string for the bases section of an scf file according to the scf file specifications.
• Notes: None.

🌈 _parse_v2_traces(@traces_array)

• Title: _pares_v2_traces(\@traces_array)
• Usage: $self->_parse_v2_traces(\@traces_array);
• Function: Parses an scf Version2 trace array into its base components.
• Returns: Nothing. Modifies $self.
• Args: A reference to an array of the unpacked traces section of an scf version2 file.

psst — the Title says _pares_v2_traces but the Usage says _parse_v2_traces. that typo is canon, we keep it. 💀

✨ get_header()

• Title: get_header()
• Usage: %header = %{$obj->get_header()};
• Function: Return the header for this scf.
• Returns: A reference to a hash containing the header for this scf.
• Args: None.
• Notes: (vibes only)

💖 get_comments()

• Title: get_comments()
• Usage: %comments = %{$obj->get_comments()};
• Function: Return the comments for this scf.
• Returns: A Bio::Annotation::Collection object
• Args: None.
• Notes: (nothing, and honestly? valid)

🔥 write_seq

• Title: write_seq(-target => $swq, <comments>)
• Usage:

$obj->write_seq(
    -target => $swq,
    -version => 2,
    -CONV => "Bioperl-Chads Mighty SCF writer.");

• Function: Write out an scf.
• Returns: Nothing.
• Args: Requires: a reference to a Bio::Seq::Quality object to form the basis for the scf.

if -version is provided, it should be "2" or "3". A SCF of that version will be written.

Any other arguments are assumed to be comments and are put into the comments section of the scf. Read the specifications for scf to decide what might be good to put in here.

• Notes:

For best results, use a SequenceTrace object.

The things that you need to write an scf: a) sequence b) quality c) peak indices d) traces

• You can write an scf with just a and b by passing in a Bio::Seq::Quality object — false traces will be synthesized for you. 🪄

bestie, that last bit is genuinely the moment: missing traces? it makes them up. just don't be shocked when they're synthetic.

💜 _get_binary_header()

• Title: _get_binary_header();
• Usage: $self->_get_binary_header();
• Function: Provide the binary string that will be used as the header for a scfv2 document.
• Returns: A binary string.
• Args: None. Uses the entries in the $self->{'header'} hash. These are set on construction of the object (hopefully correctly!).
• Notes: (the "hopefully correctly!" is doing so much heavy lifting and we respect it 😭)

🌸 _get_binary_traces($version,$ref)

• Title: _set_binary_tracesbases($version,$ref)
• Usage: $self->_set_binary_tracesbases($version,$ref);
• Function: Constructs the trace and base strings for all scfs
• Returns: Nothing. Alters self.
• Args: $version - "2" or "3" $sequence - a scalar containing arbitrary sequence data $ref - a reference to either a SequenceTraces or a SequenceWithQuality object.
• Notes: This is a really complicated thing. 💀

"This is a really complicated thing." — the author, keeping it 100. that's the whole note. no further explanation offered.

🦋 _make_trace_string($version)

• Title: _make_trace_string($version)
• Usage: $self->_make_trace_string($version)
• Function: Merges trace data for the four bases to produce an scf trace string. requires $version
• Returns: Nothing. Alters $self.
• Args: $version - a version number. "2" or "3"
• Notes: (silence)

🎀 _get_binary_comments(@comments)

• Title: _get_binary_comments(\@comments)
• Usage: $self->_get_binary_comments(\@comments);
• Function: Provide a binary string that will be the comments section of the scf file. See the scf specifications for detailed specifications for the comments section of an scf file. Hint: CODE=something\nBODE=something\n\0
• Returns: (blank in the original — we hold the space 🫶)
• Args: A reference to an array containing comments.
• Notes: None.

🌈 _delta(@trace_data,$direction)

• Title: _delta(\@trace_data,$direction)
• Usage: $self->_delta(\@trace_data,$direction);
• Function: (the original is blank here, so it stays blank — respect the void ✨)
• Returns: A reference to an array containing modified trace values.
• Args: A reference to an array containing trace data and a string indicating the direction of conversion. ("forward" or "backward").
• Notes: This code is taken from the specification for SCF3.2. http://www.mrc-lmb.cam.ac.uk/pubseq/manual/formats_unix_4.html

💖 _unpack_magik($buffer)

• Title: _unpack_magik($buffer)
• Usage: $self->_unpack_magik($buffer)
• Function: What unpack specification should be used? Try them all.
• Returns: Nothing.
• Args: A buffer containing arbitrary binary data.
• Notes: Eliminate the ambiguity and the guesswork. Used in the adaptation of _delta(), mostly.

"Try them all." ma'am. ma'am that is a strategy. and it's named magik with a k. obsessed. 🪄✨

🔥 read_from_buffer($filehandle,$buffer,$length)

• Title: read_from_buffer($filehandle,$buffer,$length)
• Usage: $self->read_from_buffer($filehandle,$buffer,$length);
• Function: Read from the buffer.
• Returns: $buffer, containing a read of $length
• Args: a filehandle, a buffer, and a read length
• Notes: I just got tired of typing "unless (length($buffer) == $length)" so I put it here.

the most relatable origin story in the entire Bioperl codebase, ngl. 😭

🧚 _dump_keys()

• Title: _dump_keys()
• Usage: &_dump_keys($a_reference_to_some_hash)
• Function: Dump out the keys in a hash.
• Returns: Nothing.
• Args: A reference to a hash.
• Notes: A debugging method.

🍓 _dump_base_accuracies()

• Title: _dump_base_accuracies()
• Usage: $self->_dump_base_accuracies();
• Function: Dump out the v3 base accuracies in an easy to read format.
• Returns: Nothing.
• Args: None.
• Notes: A debugging method.

💜 _dump_peak_indices_incoming()

• Title: _dump_peak_indices_incoming()
• Usage: $self->_dump_peak_indices_incoming();
• Function: Dump out the v3 peak indices in an easy to read format.
• Returns: Nothing.
• Args: None.
• Notes: A debugging method.

🌸 _dump_base_accuracies_incoming()

• Title: _dump_base_accuracies_incoming()
• Usage: $self->_dump_base_accuracies_incoming();
• Function: Dump out the v3 base accuracies in an easy to read format.
• Returns: Nothing.
• Args: None.
• Notes: A debugging method.

🎀 _dump_comments()

• Title: _dump_comments()
• Usage: $self->_dump_comments();
• Function: Debug dump the comments section from the scf.
• Returns: Nothing.
• Args: Nothing.
• Notes: None.

---

and that's the whole page, bestie!! 🎉 this was perl v5.32.1, dated 2021-08-15, and it's the Bio::SeqIO::scf(3pm) page from User Contributed Perl Documentation. go read Bio::SeqIO, don't call this module directly, and stay hydrated. mwah 💋✨🦋