Bio::A...::nexus(3pm)

💖 Bio::AlignIO::nexus — the NEXUS glow-up 💖

okay bestie, so this page is Bio::A...::nexus(3pm), straight out of the User Contributed Perl Documentation, and it's literally the manual for Bio::AlignIO::nexus. Yes the filename is doing that mysterious abbreviated thing. She's ✨mysterious✨. Anyway. Sit down, grab a strawberry 🍓, and let's get into it.

---

✨ NAME ✨

Bio::AlignIO::nexus — NEXUS format sequence input/output stream. That's the whole vibe: she reads NEXUS, she writes NEXUS, she does not elaborate further. 💅

---

🌸 SYNOPSIS 🌸

okay so here's the thing, and I need you to hear me on this one:

Do not use this module directly. Use it via the Bio::AlignIO class.

fr fr. She's not a solo act, she's a featured artist on the Bio::AlignIO track. So here's how you actually call her:

use Bio::AlignIO;

my $in = Bio::AlignIO->new(-format => 'nexus',
                          -file   => 'aln.nexus');
while( my $aln = $in->next_aln ) {
    # do something with the alignment
}

look at that. clean. iconic. the while loop is the main character honestly 👑

---

🦋 DESCRIPTION 🦋

This object can transform Bio::Align::AlignI objects to and from NEXUS data blocks. That's her whole job and she does it beautifully.

And if you wanna know which NEXUS features are supported? Check the method documentation, bestie — that's where the deets live. 👀

---

🎀 ACKNOWLEDGEMENTS 🎀

shoutout time!! 📣 Will Fisher wrote an excellent standalone NEXUS format parser in Perl called readnexus, and a number of tricks were adapted from it. We love a legend supporting other legends. 🫶

---

💜 FEEDBACK 💜

Support

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

bioperl-l@bioperl.org

and not to the module maintainer directly. Why? Because there are many experienced and responsive experts on there who will look at your problem and quickly address it. (yes, "reponsive" is how it's spelled in the original, we're keeping the typo, it's part of the lore 💀)

And please include a thorough description of the problem with code and data examples if at all possible. Give them the whole picture, they're doing this for free, be a good citizen. 🌈

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

go forth and file, bestie 🐛

---

👑 AUTHORS - Heikki Lehvaslaiho 👑

Email: heikki-at-bioperl-dot-org

(you know the drill, swap the -at- for an @ and the -dot- for a . — iykyk)

---

🌟 APPENDIX 🌟

okay so the rest of the documentation goes deep on each of the object methods. And heads up: internal methods are usually preceded with a _ — that's your little signal that they're backstage, not front row. 🙈

new

Title   : new
Usage   : $alignio = Bio::AlignIO->new(-format => 'nexus', -file => 'filename');
Function: returns a new Bio::AlignIO object to handle clustalw files
Returns : Bio::AlignIO::clustalw object
Args    : -verbose => verbosity setting (-1,0,1,2)
          -file    => name of file to read in or with ">" - writeout
          -fh      => alternative to -file param - provide a filehandle
                      to read from/write to
          -format  => type of Alignment Format to process or produce

          Customization of nexus flavor output

          -show_symbols => print the symbols="ATGC" in the data definition
                           (MrBayes does not like this)
                           boolean [default is 1]
          -show_endblock => print an 'endblock;' at the end of the data
                           (MyBayes does not like this)
                           boolean [default is 1]

so yes, the Function line says clustalw and the Returns line says Bio::AlignIO::clustalw even though we are literally in the nexus page. That's not me, that's the source. We're preserving it exactly, no notes, it's giving copy-paste heritage 💀

and yes, MyBayes in the -show_endblock description is also spelled exactly like that in the original. MrBayes gets the M, MyBayes gets the y. we don't ask questions, we just archive. 🎀

next_aln

Title   : next_aln
Usage   : $aln = $stream->next_aln()
Function: Returns the next alignment in the stream.

          Supports the following NEXUS format features:
          - The file has to start with '#NEXUS'
          - Reads in the name of the alignment from a comment
            (anything after 'TITLE: ') .
          - Sequence names can be given in a taxa block, too.
          - If matchchar notation is used, converts
            them back to sequence characters.
          - Does character conversions specified in the
            NEXUS equate command.
          - Sequence names of type 'Homo sapiens' and
            Homo_sapiens are treated identically.

Returns : L<Bio::Align::AlignI> object
Args    :

okay so this is the one that does the reading. and the feature list?? she's stacked. let's run through it because every single one matters:

• The file has to start with '#NEXUS' — no exceptions, that's the entry fee. 🎟️
• Reads in the name of the alignment from a comment — specifically, anything after 'TITLE: '.
• Sequence names can be given in a taxa block, too.
• If matchchar notation is used, converts them back to sequence characters.
• Does character conversions specified in the NEXUS equate command.
• Sequence names of type 'Homo sapiens' and Homo_sapiens are treated identically. (yes bestie, the space and the underscore are the same girlie, she contains multitudes ✨)

and it hands you back an L<Bio::Align::AlignI> object. Args is empty, she takes nothing, she just delivers.

write_aln

Title   : write_aln
Usage   : $stream->write_aln(@aln)
Function: Writes the $aln object into the stream in interleaved NEXUS
          format. Everything is written into a data block.
          SimpleAlign methods match_char, missing_char and gap_char must be set
          if you want to see them in the output.
Returns : 1 for success and 0 for error
Args    : L<Bio::Align::AlignI> object

the writing side!! 🖊️ She writes the $aln object into the stream in interleaved NEXUS format, and everything goes into a data block.

heads up: SimpleAlign methods match_char, missing_char and gap_char must be set if you want to see them in the output. if you don't set them, they're not showing up, no cap.

Returns 1 for success and 0 for error. binary queen. 👑

flag

Title   : flag
Usage   : $obj->flag($name,$value)
Function: Get/Set a flag value
Returns : value of flag (a scalar)
Args    : on set, new value (a scalar or undef, optional)

get it, set it, move on. the value comes back as a scalar, and when you're setting, the new value is a scalar or undef, and it's optional. lowkey the most chill method on the whole page. 🦋

---

and that's the whole page bestie, we ate and left no crumbs. 🍽️✨

sign-off time: this little love letter comes from perl v5.32.1, dated 2021-08-15, and it's filed under the ever-mysterious Bio::A...::nexus(3pm). stay slay, read your docs, and always check the mailing list first. 💖🎀🦋