Bio::T...:Consed(3pm)

📦
version 1.7.8 · 3 versions
, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble

💖 NAME 💖

So the manual name up top is Bio::T...:Consed(3pm), filed under User Contributed Perl Documentation — and the actual module living behind that name is Bio::Tools::Alignment::Consed. It's the module that lets you work with objects that come out of consed .ace files. Periodt. 🎀

✨ SYNOPSIS ✨

okay bestie, here's the whole vibe in code form, no notes:

# a report for sequencing stuff
my $o_consed = Bio::Tools::Alignment::Consed->new(
    -acefile => "/path/to/an/acefile.ace.1",
    -verbose => 1);
my $foo = $o_consed->set_reverse_designator("r");
my $bar = $o_consed->set_forward_designator("f");

# get the contig numbers
my @keys = $o_consed->get_contigs();

# construct the doublets
my $setter_doublets = $o_consed->choose_doublets();

# get the doublets
my @doublets = $o_consed->get_doublets();

🦋 DESCRIPTION 🦋

Bio::Tools::Alignment::Consed hands you methods and objects for dealing with the output of the Consed software suite. Basically: it takes an .ace file and gives you back objects for the results. It's giving parser-with-benefits. 💅

Okay so, a word about doublets 🌸 — this module got written to handle a huge EST sequencing operation. In that setup, ESTs were sequenced from the 3' end and from the 5' end of the EST. The whole goal was to find a consensus sequence for those two reads. So a contig of two? That's exactly what we wanted, and that contig should be made up of the forward and reverse reads of a getn clone. For example, say your forward designator is "F" and your reverse designator is "R" — if the two reads chad1F and chad1R are sitting in a single contig (say, Contig 5), then it gets determined that the consensus sequence for Contig 5 will be the sequence for clone chad1. 🔥

Doublets are good! 😌💖

This module parses .ace and related files. There's a detailed list of methods down at the end of this document, and yes we're getting to all of them, don't worry. 🫶

I wrote a detailed rationale for the design that might explain why some things were done the way they were done. That document is beyond the scope of this pod, and it can probably be found in the directory from which this module was 'made', or at http://www.dieselwurks.com/bioinformatics/consedpm_documentation.pdf. 📄

Heads up: the POD in that document might be old, but the original rationale still stands. ⭐

🎀 FEEDBACK 🎀

💌 Mailing Lists

User feedback is literally an integral part of the evolution of this and other Bioperl modules. So 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. There are so many experienced and responsive experts who will be able to look at the problem and quickly address it. 🙌 If at all possible, include a thorough description of the problem with code and data examples — the more detail, the better the glow-up on that bug fix. ✨

🐛 Reporting Bugs

Report bugs to the Bioperl bug tracking system so we can keep track of the bugs and their resolution. Bug reports can be submitted via the web:

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

👑 AUTHOR - Chad Matsalla

Email chad-at-dieselwurks.com 📧

📚 APPENDIX

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

🌟 new()

Title : new(-acefile => $path_to_some_acefile, -verbose => "1")

Usage : $o_consed = Bio::Tools::Alignment::Consed->new(-acefile => $path_to_some_acefile, -verbose => "1");

Function : Constructs the Bio::Tools::Alignment::Consed object. It sets verbosity for the following procedures, if necessary:

  1. Construct a new Bio::Tools::Alignment::Trim object, to handle quality trimming.
  2. Read in the acefile and parse it.

Returns : A reference to a Bio::Tools::Alignment::Consed object. 🫶

Args : A hash. (-acefile) is the filename of an acefile. If a full path is not specified, "./" gets prepended to the filename and used from instantiation all the way until destruction. And if you want Bio::Tools::Alignment::Consed to be noisy while it's parsing the acefile, specify some value for (-verbose). 🔊

🌟 set_verbose()

Title : set_verbose()

Usage : $o_consed->set_verbose(1);

Function : Set the verbosity level for debugging messages. The moment you instantiate the Bio::Tools::Alignment::Consed object, the verbosity level is set to 0 (quiet). 🤫

Returns : 1 or 0.

Args : The verbosity levels are:

  • 0 — quiet 🤫
  • 1 — noisy 📣
  • 2 — noisier 📢
  • 3 — annoyingly noisy 💀🔊

This method for setting verbosity has largely been superseded by a sub-by-sub way, where for every sub you can provide a (-verbose) switch. I'm converting this bit-by-bit, so do not be surprised if some subs do not honour this. 🙈

🌟 get_filename()

Title : get_filename()

Usage : $o_consed->get_filename();

Function : Returns the name of the acefile being used by the Bio::Tools::Alignment::Consed object.

Returns : A scalar containing the name of a file. 📁

Args : None.

🌟 count_sequences_with_grep()

Title : count_sequences_with_grep()

Usage : $o_consed->count_sequences_with_grep();

Function : Uses /bin/grep to scan through the files in the ace project dir and count sequences in those files. I used this method while developing this module to verify that I was getting all of the sequences. It works, but it is (I think) unix-like platform dependent. 🐧

Returns : A scalar containing the number of sequences in the ace project directory.

Args : None.

If you are on a non-UNIX platform, you really do not have to use this. It is more of a debugging routine designed to address very specific problems.

This method was reimplemented to be platform independent with a pure perl implementation. So the above note can be ignored. 😌✨

🌟 get_path()

Title : get_path()

Usage : $o_consed->get_path();

Function : Returns the path to the acefile this object is working with.

Returns : Scalar. The path to the working acefile. 🛤️

Args : None.

🌟 get_contigs()

Title : get_contigs()

Usage : $o_consed->get_contigs();

Function : Return the keys to the Bio::Tools::Alignment::Consed object.

Returns : An array containing the keynames in the Bio::Tools::Alignment::Consed object.

Args : None.

This would normally be used to get the keynames for some sort of iterator. These keys are worthless in general day-to-day use, because in the Consed acefile they are simply Contig1, Contig2, ... 💀

🌟 get_class($contig_keyname)

Title : get_class($contig_keyname)

Usage : $o_consed->get_class($contig_keyname);

Function : Return the class name for this contig.

Returns : A scalar representing the class of this contig.

Args : None.

Notes :

🌟 get_quality_array($contig_keyname)

Title : get_quality_array($contig_keyname)

Usage : $o_consed->get_quality_array($contig_keyname);

Function : Returns the quality for the consensus sequence for the given contig as an array. See get_quality_scalar to get this as a scalar.

Returns : An array containing the quality for the consensus sequence with the given keyname.

Args : The keyname of a contig. Note: this is a keyname. The key would normally come from get_contigs.

It returns an array, not a reference. Is this a bug? thinking... No. Well, maybe. 🤔 Why was this developed like this? I was using FreezeThaw for object persistence, and when it froze out these arrays it took a long time to thaw it. Much better as a scalar.

See get_quality_scalar()

🌟 get_quality_scalar($contig_keyname)

Title : get_quality_scalar($contig_keyname)

Usage : $o_consed->get_quality_scalar($contig_keyname);

Function : Returns the quality for the consensus sequence for the given contig as a scalar. See get_quality_array to get this as an array.

Returns : An scalar containing the quality for the consensus sequence with the given keyname.

Args : The keyname of a contig. Note this is a keyname. The key would normally come from get_contigs.

Why was this developed like this? I was using FreezeThaw for object persistence, and when it froze out these arrays it took a coon's age to thaw it. Much better as a scalar. 🐢

See get_quality_array()

🌟 freeze_hash()

Title : freeze_hash()

Usage : $o_consed->freeze_hash();

Function : Uses Ilya's FreezeThaw module to create a persistent data object for this Bio::Tools::Alignment::Consed data structure. In the case of AAFC, we use Bio::Tools::Alignment::Consed to pre-process bunches of sequences, freeze the structures, and send in a harvesting robot later to do database stuff. 🤖

Returns : 0 or 1;

Args : None.

This procedure was removed so Consed.pm won't require FreezeThaw. 🫡

🌟 get_members($contig_keyname)

Title : get_members($contig_keyname)

Usage : $o_consed->get_members($contig_keyname);

Function : Return the names of the reads in this contig.

Returns : An array containing the names of the reads in this contig.

Args : The keyname of a contig. Note this is a keyname. The keyname would normally come from get_contigs.

See get_contigs()

🌟 get_members_by_name($some_arbitrary_name)

Title : get_members_by_name($some_arbitrary_name)

Usage : $o_consed->get_members_by_name($some_arbitrary_name);

Function : Return the names of the reads in a contig. This is the name given to $contig{key} based on what is in the contig. This is different from the keys retrieved through get_contigs().

Returns : An array containing the names of the reads in the contig with this name.

Args : The name of a contig. Not a key, but a name.

Highly inefficient. use some other method if possible. 🐌 See get_contigs()

🌟 get_contig_number_by_name($some_arbitrary_name)

Title : get_contig_number_by_name($some_arbitrary_name)

Usage : $o_consed->get_contig_number_by_name($some_arbitrary_name);

Function : Return the names of the reads in a contig. This is the name given to $contig{key} based on what is in the contig. This is different from the keys retrieved through get_contigs().

Returns : An array containing the names of the reads in the contig with this name.

Args : The name of a contig. Not a key, but a name.

See get_contigs()

🌟 get_sequence($contig_keyname)

Title : get_sequence($contig_keyname)

Usage : $o_consed->get_sequence($contig_keyname);

Function : Returns the consensus sequence for a given contig.

Returns : A scalar containing a sequence. 🧬

Args : The keyname of a contig. Note this is a key. The key would normally come from get_contigs.

see get_contigs() ✨

🎀 set_final_sequence($some_sequence) 🎀

  • Title: set_final_sequence($name,$some_sequence)
  • Usage: $o_consed->set_final_sequence($name,$some_sequence);
  • Function: a manual, hands-on-the-wheel way to set the sequence for a given key in the contig hash. Rarely used, fr fr.
  • Returns: 0 or 1
  • Args: the name (not the keyname, bestie — the name) of a contig, plus an arbitrary string.

A method with a questionable and somewhat mysterious origin. May raise the dead or something like that. 🙈

🦋 _read_file() 🦋

  • Title: _read_file();
  • Usage: _read_file();
  • Function: an internal subroutine that reads in an acefile and parses it into a Bio::Tools::Alignment::Consed object.
  • Returns: 0 or 1.
  • Args: nothing.

This routine creates and saves the filhandle for reading the files in {fh}. (yes, "filhandle". we keep it, it's iconic 💅)

🌸 set_reverse_designator($some_string) 🌸

  • Title: set_reverse_designator($some_string)
  • Usage: $o_consed->set_reverse_designator($some_string);
  • Function: sets the designator for the reverse read of contigs in this Bio::Tools::Alignment::Consed object. It's what decides whether contigs holding two reads can be named at all.
  • Returns: the value of $o_consed->{reverse_designator}, so you can peek and confirm it actually got set properly.
  • Args: an arbitrary string.

May be useful only to me. shrug 🫶

🌈 set_forward_designator($some_string) 🌈

  • Title: set_forward_designator($some_string)
  • Usage: $o_consed->set_forward_designator($some_string);
  • Function: sets the designator for the forward read of contigs in this Bio::Tools::Alignment::Consed object. Same deal — it's part of deciding whether two-read contigs get a name.
  • Returns: the value of $o_consed->{forward_designator}, so you can verify it took.
  • Args: an arbitrary string.

May be useful only to me. shrug 🫶

💀 set_designator_ignore_case("yes") 💀

  • Title: set_designator_ignore_case("yes")
  • Usage: $o_consed->set_designator_ignore_case("yes");
  • Function: deprecated.
  • Returns: deprecated.
  • Args: deprecated.

Deprecated. Really. Trust me. 🙈

🧚 set_trim_points_singlets_and_singletons() 🧚

  • Title: set_trim_points_singlets_and_singletons()
  • Usage: $o_consed->set_trim_points_singlets_and_singletons();
  • Function: sets the trim points for singlets and singletons based on quality. It uses the Bio::Tools::Alignment::Trim object.
  • Returns: nothing.
  • Args: none.
⚠️ Use at your own risk, bestie, because the Bio::Tools::Alignment::Trim object was designed specifically for me and is mysterious in its ways. Every time somebody other then me uses it a swarm of locusts decends on a small Central American village so do not say you weren't warned. 😭

Working on exceptions and warnings here.

See Bio::Tools::Alignment::Trim for more information. 💜

🍓 set_trim_points_doublets() 🍓

  • Title: set_trim_points_doublets()
  • Usage: $o_consed->set_trim_points_doublets();
  • Function: sets the trim points for doublets based on quality. Uses the Bio::Tools::Alignment::Trim object.
  • Returns: nothing.
  • Args: none.
  • Notes: working on exceptions here.
⚠️ Again: use at your own risk, because the Bio::Tools::Alignment::Trim object was designed specifically for me and is mysterious in its ways. Every time somebody other then me uses it you risk a biblical plague being loosed on your city. 😭

See Bio::Tools::Alignment::Trim for more information. 💜

⭐ get_trimmed_sequence_by_name($name) ⭐

  • Title: get_trimmed_sequence_by_name($name)
  • Usage: $o_consed->get_trimmed_sequence_by_name($name);
  • Function: returns the trimmed_sequence of a contig whose {name} eq $name.
  • Returns: a scalar — the trimmed sequence.
  • Args: the {name} of a contig.
  • Notes: (nothing, it's just vibing)

🎀 set_dash_present_in_sequence_name("yes") 🎀

  • Title: set_dash_present_in_sequence_name("yes")
  • Usage: $o_consed->set_dash_present_in_sequence_name("yes");
  • Function: deprecated. Part of an uncompleted thought. ("Oooh! Shiny!") ✨
  • Returns: nothing.
  • Args: "yes" to set {dash_present_in_sequence_name} to 1
  • Notes: (nope)

🔥 set_doublets() 🔥

  • Title: set_doublets()
  • Usage: $o_consed->set_doublets();
  • Function: finds pairs that have similar names, marks them as doublets and sets the {name}.
  • Returns: 0 or 1.
  • Args: none.

A complicated subroutine that iterates over the Bio::Tools::Alignment::Consed looking for contigs of 2. If the forward and reverse designator are removed from each of the reads in {'member_array'} and the remaining reads are the same, {name} is set to that name and the contig's class is set as "doublet". If any of those cases fail, the contig is marked as a "pair". Periodt. 💅

🦋 set_singlets 🦋

  • Title: set_singlets
  • Usage: $o_consed->set_singlets();
  • Function: reads in a singlets file and places them into the Bio::Tools::Alignment::Consed object.
  • Returns: nothing.
  • Args: a scalar to turn on verbose parsing of the singlets file.
  • Notes: (empty, we leave it that way)

🌸 get_singlets() 🌸

  • Title: get_singlets()
  • Usage: $o_consed->get_singlets();
  • Function: returns the keynames of the singlets.
  • Returns: an array containing the keynames of all Bio::Tools::Alignment::Consed sequences in the class "singlet".
  • Args: none.
  • Notes: (none)

💜 set_quality_by_name($name,$quality) 💜

  • Title: set_quality_by_name($name,$quality)
  • Usage: $o_consed->set_quality_by_name($name,$quality);
  • Function: deprecated. Makes the contig with {name} have {'quality'} of $quality. Probably used for testing.
  • Returns: nothing.
  • Args: the name of a contig and a scalar for its quality.
  • Notes: deprecated.

🧚 set_singlet_quality() 🧚

  • Title: set_singlet_quality()
  • Usage: $o_consed->set_singlet_quality();
  • Function: for each singlet, it goes to the appropriate file in phd_dir and reads in the phred quality for that read, then drops it into {'quality'}.
  • Returns: 0 or 1.
  • Args: none.
  • Notes: this is the next subroutine that will receive substantial revision in the next little while. It really should eval the creation of Bio::Tools::Alignment::Phred objects and go from there. 🫶

💀 set_contig_quality() 💀

  • Title: set_contig_quality()
  • Usage: $o_consed->set_contig_quality();
  • Function: deprecated.
  • Returns: deprecated.
  • Args: deprecated.
  • Notes: deprecated. Really. Trust me. 🙈

🌈 get_multiplets() 🌈

  • Title: get_multiplets()
  • Usage: $o_consed->get_multiplets();
  • Function: returns the keynames of the multiplets.
  • Returns: returns an array containing the keynames of all Bio::Tools::Alignment::Consed sequences in the class "multiplet".
  • Args: none.
  • Notes: (nada)

⭐ get_all_members() ⭐

  • Title: get_all_members()
  • Usage: @all_members = $o_consed->get_all_members();
  • Function: returns a list of all of the read names in the Bio::Tools::Alignment::Consed object.
  • Returns: an array containing all of the elements in all of the {'member_array'}s.
  • Args: none.
  • Notes: (none)

🎀 sum_lets($total_only) 🎀

  • Title: sum_lets($total_only)
  • Usage: $statistics = $o_consed->sum_lets($total_only);
  • Function: gives you the numbers on how many sequences were accounted for in the Bio::Tools::Alignment::Consed object.
  • Returns: if a scalar is present, it returns the total number of sequences accounted for in all classes. If no scalar is passed, then it returns a string that looks like this:
Singt/singn/doub/pair/mult/total : 2,0,1(2),0(0),0(0),4

This example means the following: there were 1 singlets. There were 0 singletons. There were 1 doublets for a total of 2 sequences in this class. There were 0 pairs for a total of 0 sequences in this class. There were 0 multiplets for a total of 0 sequences in this class. There were a total of 4 sequences accounted for in the Bio::Tools::Alignment::Consed object.

  • Args: a scalar is optional, to change the way the numbers are returned.
  • Notes: (empty)

🍓 write_stats() 🍓

  • Title: write_stats()
  • Usage: $o_consed->write_stats();
  • Function: writes a file called statistics containing numbers similar to those provided in sum_lets().
  • Returns: nothing. It writes a file in $o_consed->{path} containing something like this:
0,0,50(100),0(0),0(0),100

Where the numbers provided are in the format described in the documentation for sum_lets().

  • Args: none.
  • Notes: this might break platform independence, I do not know. 😭

See sum_lets(). 💜

🦋 get_singletons() 🦋

  • Title: get_singletons()
  • Usage: @singletons = $o_consed->get_singletons();
  • Function: returns the keynames of the singletons.
  • Returns: returns an array containing the keynames of all Bio::Tools::Alignment::Consed sequences in the class "singleton".
  • Args: none.
  • Notes: (none)

🌸 get_pairs() 🌸

  • Title: get_pairs()
  • Usage: @pairs = $o_consed->get_pairs();
  • Function: returns the keynames of the pairs.
  • Returns: returns an array containing the keynames of all Bio::Tools::Alignment::Consed sequences in the class "pair".
  • Args: none.
  • Notes: (none)

💜 get_name($contig_keyname) 💜

  • Title: get_name($contig_keyname)
  • Usage: $name = $o_consed->get_name($contig_keyname);
  • Function: returns the {name} for $contig_keyname.
  • Returns: a string. ({name})
  • Args: a contig keyname.
  • Notes: (nope)

🧚 _get_contig_name(\@array_containing_reads) 🧚

  • Title: _get_contig_name(\@array_containing_reads)
  • Usage: $o_consed->_get_contig_name(\@array_containing_reads);
  • Function: the logic for the set_doublets subroutine.
  • Returns: the name for this contig.
  • Args: a reference to an array containing read names.
  • Notes: depends on reverse_designator. Be sure this is set the way you intend. 👑

🔥 get_doublets() 🔥

  • Title: get_doublets()
  • Usage: @doublets = $o_consed->get_doublets();
  • Function: returns the keynames of the doublets.
  • Returns: returns an array containing the keynames of all Bio::Tools::Alignment::Consed sequences in the class "doublet".
  • Args: none.
  • Notes: (none)

👑 dump_hash() 👑

  • Title: dump_hash()
  • Usage: $o_consed->dump_hash();
  • Function: uses dumpvar.pl to dump out the Bio::Tools::Alignment::Consed object to STDOUT.
  • Returns: nothing.
  • Args: none.
  • Notes: I used this a lot in debugging. 🫶

🌸 dump_hash_compact()

  • Title: dump_hash_compact()
  • Usage: $o_consed->dump_hash_compact();
  • Function: Dumps out the Bio::Tools::Alignment::Consed object in a compact way.
  • Returns: Nothing. Nada. Zero. 🫙
  • Args: Nothing.
  • Notes: Cleaner than dumpValue() and dumpHash(), ok? Bestie I used this one a lot while debugging. Like, constantly. It was my emotional support dumper. 💅

🧚 get_phreds()

  • Title: get_phreds()
  • Usage: @phreds = $o_consed->get_phreds();
  • Function: For every single doublet in the Bio::Tools::Alignment::Consed hash, it goes and gets the phreds for the top read and the bottom read, then drops them into {top_phreds} and {bottom_phreds}. ✨
  • Returns: Nothing.
  • Args: Nothing.

This one requires parse_phd() and reverse_and_complement(). And yes, the author is fully aware that pulling qualities on demand would be so much more elegant, but there were certain "features" in the acefile that demanded a lil extra detailed work to actually get the qualities for certain parts of the consensus sequence. So to make sure it was done right, they wrote things that do all the steps, then used dump_hash() and checked every single one to confirm expected behavior. Never changed it since. So there you are. 😌

🍓 parse_phd($read_name)

  • Title: parse_phd($read_name)
  • Usage: $o_consed->parse_phd($read_name);
  • Function: Sucks in the entire contents of a .phd file. 😮‍💨
  • Returns: A reference to an array holding the quality values for that read.
  • Args: The name of a read.
  • Notes: Ngl this is a significantly weak subroutine, because it was always intended that these functions — along with the functions that get_phreds() provides — would get moved into the Bio::SeqIO:phd module. That's done now, but the Bio::Tools::Alignment::Consed module was never rewritten to reflect the change. 💀

See Bio::SeqIO::phd for more info, bestie.

🦋 reverse_and_complement(\@source)

  • Title: reverse_and_complement(\@source)
  • Usage: $reference_to_array = $o_consed->reverse_and_complement(\@source);
  • Function: A stub for the recursive routine reverse_recurse(). 🫶
  • Returns: A reference to a reversed and complemented array of phred data.
  • Args: A reference to an array of phred data.
  • Notes: (there's literally nothing here, and honestly? iconic of it)

💜 reverse_recurse($r_source,$r_destination)

  • Title: reverse_recurse(\@source,\@destination)
  • Usage: $o_consed->reverse_recurse(\@source,\@destination);
  • Function: A recursive routine that reverses and complements an array of phred data. 🔁
  • Returns: A reference to an array containing the reversed phred data.
  • Args: A reference to a source array, and a reverence to a destination array.
Recursion is kewl, but honestly this sub should probably be _reverse_recurse. Just saying. 🤷‍♀️

🌈 show_missing_sequence()

  • Title: show_missing_sequence();
  • Usage: $o_consed->show_missing_sequence();
  • Function: Used by set_trim_points_doublets() to fill in quality values wherever consed (phrap?) set them to 0 at the beginning and/or end of the consensus sequences. ✨
  • Returns: Nothing.
  • Args: None.

Only acts on doublets. And bestie, it is really very somewhat quite ugly. A disgusting kludge. (insert pride here) 💅 It was written stepwise with no real plan, because it was not really evident why consed (phrap?) was doing this in the first place. 😭

And that's a wrap on the whole page, bestie!! 🌸🫶 This little masterpiece ships as part of perl v5.32.1, dated 2021-08-15, and it's filed under the Bio::T...:Consed(3pm) name up in the User Contributed Perl Documentation section. Go forth and parse those acefiles. Periodt. 👑💖

📦 where this page comes from