Bio::AlignIO(3pm)

💖 Bio::AlignIO — the manual, but make it make sense 💖

Bio::AlignIO — the handler for AlignIO formats. This is Bio::AlignIO(3pm), the User Contributed Perl Documentation version, and bestie, we are getting through this together.

---

✨ NAME ✨

Bio::AlignIO — the Handler for AlignIO Formats. That's it, that's the name, she's a handler and she handles. 👑

---

🌈 SYNOPSIS 🌈

Okay so here's the vibe. You want in, you want out, you want it converted:

use Bio::AlignIO;

$inputfilename = "testaln.fasta";
$in  = Bio::AlignIO->new(-file   => $inputfilename ,
                         -format => 'fasta');
$out = Bio::AlignIO->new(-file   => ">out.aln.pfam" ,
                         -format => 'pfam');

while ( my $aln = $in->next_aln() ) {
    $out->write_aln($aln);
}

OR — because there's always an OR, she's flexible like that — you can do the filehandle thing:

use Bio::AlignIO;

open MYIN, '<', 'testaln.fasta' or die "Could not read file 'testaln.fasta': $!\n";
$in  = Bio::AlignIO->newFh(-fh     => \*MYIN,
                           -format => 'fasta');
open my $MYOUT, '>', 'testaln.pfam' or die "Could not write file 'testaln.pfam': $!\n";
$out = Bio::AlignIO->newFh(-fh     =>  $MYOUT,
                           -format => 'pfam');

# World's smallest Fasta<->pfam format converter:
print $out $_ while <$in>;

Not me showing you the world's smallest Fasta<->pfam format converter like it's nothing. She ate and left no crumbs. 🔥

---

🦋 DESCRIPTION 🦋

Bio::AlignIO is a handler module for the formats in the AlignIO set — like, for example, Bio::AlignIO::fasta. It is the officially sanctioned way of getting at the alignment objects. And the resulting alignment? It's a Bio::Align::AlignI-compliant object. Periodt. 💅

The idea is simple, bestie: you request an object for a particular format. All the objects have a notion of an internal file that is read from or written to. A particular AlignIO object instance is configured for either input or output — think of it as a stream object, because that's literally what it is.

Each object has functions:

$stream->next_aln();

And:

$stream->write_aln($aln);

Also:

$stream->type() # returns 'INPUT' or 'OUTPUT'

As an added bonus 🎁 — you can recover a filehandle that is tied to the AlignIO object, which means you get to use the standard <> and print operations to read and write alignment objects:

use Bio::AlignIO;

# read from standard input
$stream = Bio::AlignIO->newFh(-format => 'Fasta');

while ( $aln = <$stream> ) {
         # do something with $aln
}

And:

print $stream $aln; # when stream is in output mode

Bio::AlignIO is patterned on the Bio::SeqIO module and shares most of its features. But there's one significant difference, and it's kind of the whole personality: Bio::AlignIO usually handles IO for only a single alignment at a time, whereas Bio::SeqIO handles IO for multiple sequences in a single stream. Why? Because simultaneously handling multiple sequences is a common requirement, and simultaneous handling of multiple alignments is... not. It's giving "I'm not doing all that."

The only current exception is the format "bl2seq", which parses results of the BLAST "bl2seq" program and which may produce several alignment pairs. This set of alignment pairs can be read using multiple calls to next_aln. She's got range, okay? ✨

---

🎀 CONSTRUCTORS 🎀

💜 Bio::AlignIO->new()

$seqIO = Bio::AlignIO->new(-file => 'filename',   -format=>$format);
$seqIO = Bio::AlignIO->new(-fh   => \*FILEHANDLE, -format=>$format);
$seqIO = Bio::AlignIO->new(-format => $format);
$seqIO = Bio::AlignIO->new(-fh => \*STDOUT, -format => $format);

The new class method constructs a new Bio::AlignIO object. The returned object can be used to retrieve or print alignment objects. new accepts the following parameters:

• -file — a file path to be opened for reading or writing. The usual Perl conventions apply, so know your prefixes, bestie:

'file'       # open file for reading
'>file'      # open file for writing
'>>file'     # open file for appending
'+<file'     # open file read/write
'command |'  # open a pipe from the command
'| command'  # open a pipe to the command

• -fh — you may provide new() with a previously-opened filehandle. For example, to read from STDIN:

$seqIO = Bio::AlignIO->new(-fh => \*STDIN);

Heads up, bestie: you must pass filehandles as references to globs. No exceptions, no shortcuts. 🙈

If neither a filehandle nor a filename is specified, then the module will read from the @ARGV array or STDIN, using the familiar <> semantics. Main character energy: if you don't tell her where to go, she'll figure it out. 💅

• -format — specify the format of the file. Supported formats include:

bl2seq      Bl2seq Blast output
clustalw    clustalw (.aln) format
emboss      EMBOSS water and needle format
fasta       FASTA format
maf         Multiple Alignment Format
mase        mase (seaview) format
mega        MEGA format
meme        MEME format
msf         msf (GCG) format
nexus       Swofford et al NEXUS format
pfam        Pfam sequence alignment format
phylip      Felsenstein PHYLIP format
prodom      prodom (protein domain) format
psi         PSI-BLAST format
selex       selex (hmmer) format
stockholm   stockholm format

Currently only those formats which were implemented in Bio::SimpleAlign have been incorporated into Bio::AlignIO. Specifically, "mase", "stockholm" and "prodom" have only been implemented for input. See the specific module (e.g. Bio::AlignIO::prodom) for notes on supported versions. 👀

If no format is specified and a filename is given, then the module will attempt to deduce it from the filename suffix. If this is unsuccessful, "fasta" format is assumed. She's got a default and she's sticking to it.

The format name is case insensitive — "FASTA", "Fasta" and "fasta" are all treated equivalently. Slay, no gatekeeping on capitalization. ✨

🌸 Bio::AlignIO->newFh()

$fh = Bio::AlignIO->newFh(-fh   => \*FILEHANDLE, -format=>$format);
# read from STDIN or use @ARGV:
$fh = Bio::AlignIO->newFh(-format => $format);

This constructor behaves like new, but returns a tied filehandle rather than a Bio::AlignIO object. You can read sequences from this object using the familiar <> operator, and write to it using print. The usual array and $_ semantics work. For example, you can read all sequence objects into an array like this:

@sequences = <$fh>;

Other operations, such as read(), sysread(), write(), close(), and printf() are not supported. Don't ask her to do those, she will simply not. 💀

• -flush — by default, all files (or filehandles) opened for writing alignments will be flushed after each write_aln(), making the file immediately usable. If you do not need this facility and would like to marginally improve the efficiency of writing multiple sequences to the same file (or filehandle), pass the -flush option '0' or any other value that evaluates as defined but false:

my $clustal = Bio::AlignIO->new( -file   => "<prot.aln",
                                 -format => "clustalw" );
my $msf = Bio::AlignIO->new(-file   => ">prot.msf",
                            -format => "msf",
                            -flush  => 0 ); # go as fast as we can!
while($seq = $clustal->next_aln) { $msf->write_aln($seq) }

Look at that # go as fast as we can! comment. She's speed. 🏎️✨

---

👑 OBJECT METHODS 👑

See below for more detailed summaries. The main methods are:

• $alignment = $AlignIO->next_aln() — fetch an alignment from a formatted file. Get in, get your alignment, get out. 🦋
• $AlignIO->write_aln($aln) — write the specified alignment to a file.. (yes, two periods, we keep it exactly as it is, no notes 💅)
• TIEHANDLE(), READLINE(), PRINT() — these provide the tie interface. See perltie for more details.

---

💌 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. Fr fr, they want to hear from you. 🫶

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. The more context you give, the faster the glow-up on that bug fix. ✨

🐛 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 - Peter Schattner 🌟

Email: schattner@alum.mit.edu

---

💐 CONTRIBUTORS 💐

Jason Stajich, jason@bioperl.org

---

🦋 APPENDIX 🦋

okay bestie, this is the deep lore section. every single object method gets its own little spotlight here. the internal ones (the ones with a _ in front) are like, the backstage crew — you're not really supposed to talk to them directly, but they're slaying back there keeping everything running 💅

---

✨ new ✨

• Title — new
• Usage —

$stream = Bio::AlignIO->new(-file => $filename,
                            -format => 'Format')

• Function — hands you back a brand new seqstream, fresh out of the box 🎀
• Returns — a Bio::AlignIO::Handler all set up with the right format, like it already knows the vibe
• Args —
  • -file => $filename
  • -format => format
  • -fh => filehandle to attach to
  • -displayname_flat => 1 [optional] — use this if you want to force the displayname to not show start/end information. no start/end, just the name, clean and minimal, it's giving minimalism ✨

---

💖 newFh 💖

• Title — newFh
• Usage —

$fh = Bio::AlignIO->newFh(-file=>$filename,-format=>'Format')

• Function — does a new() and then an fh() right after, two-for-one combo deal 🫶
• Example —

$fh = Bio::AlignIO->newFh(-file=>$filename,-format=>'Format')
$sequence = <$fh>;   # read a sequence object
print $fh $sequence; # write a sequence object

• Returns — a filehandle tied to the Bio::AlignIO::Fh class
• Args — (nothing, bestie, it's empty)

---

🌸 fh 🌸

• Title — fh
• Usage — $obj->fh
• Function — (the original leaves this one blank, so like... same energy, no notes 🙈)
• Example —

$fh = $obj->fh;      # make a tied filehandle
$sequence = <$fh>;   # read a sequence object
print $fh $sequence; # write a sequence object

• Returns — a filehandle tied to the Bio::AlignIO::Fh class
• Args — (also empty, it's a mystery on purpose iykyk)

---

🎀 format 🎀

• Title — format
• Usage — $format = $stream->format()
• Function — gets you the alignment format
• Returns — the alignment format
• Args — none

---

🧚 _load_format_module 🧚

• Title — _load_format_module
• Usage — *INTERNAL AlignIO stuff*
• Function — loads up (like use) a module at run time on demand. lazy loading but make it fashion 💅
• Example — (blank)
• Returns — (blank)
• Args — (blank)

---

⭐ next_aln ⭐

• Title — next_aln
• Usage — $aln = stream->next_aln
• Function — reads the next $aln object off the stream, one at a time, no greediness
• Returns — a Bio::Align::AlignI compliant object
• Args — (nope, nothing)

---

🔥 write_aln 🔥

• Title — write_aln
• Usage — $stream->write_aln($aln)
• Function — writes that $aln object straight into the stream
• Returns — 1 for success and 0 for error (binary queen 👑)
• Args — Bio::Seq object

---

🌈 _guess_format 🌈

• Title — _guess_format
• Usage — $obj->_guess_format($filename)
• Function — (blank in the original, she's mysterious)
• Example — (blank)
• Returns — guessed format of filename (lower case)
• Args — (blank)

---

💜 force_displayname_flat 💜

• Title — force_displayname_flat
• Usage — $obj->force_displayname_flat($newval)
• Function — (blank)
• Example — (blank)
• Returns — value of force_displayname_flat (a scalar)
• Args — on set, new value (a scalar or undef, optional)

---

🍓 alphabet 🍓

• Title — alphabet
• Usage — $obj->alphabet($newval)
• Function — get/set the alphabet, for the purpose of passing it to Bio::LocatableSeq creation
• Example — $obj->alphabet('dna');
• Returns — value of alphabet (a scalar)
• Args — on set, new value (a scalar or undef, optional)

---

and that's the whole page bestie!! 😭💖 you made it all the way through, I'm so proud. this one's from the perl v5.32.1 era, dated 2021-08-15, and it lives at Bio::AlignIO(3pm). go forth and align your sequences, you absolute icon 🧬✨🦋