Bio::V...on::IO(3pm)

💖 Bio::Variation::IO — the handler for sequence variation IO formats 💖

okay bestie, gather round, because this is the module that handles all the sequence variation IO formats, and honestly? it's giving main character energy. it lives in the Bio::V...on::IO slot of the perl manual pages, version 3pm, and it is so ready to be your new fave. 🦋

---

✨ NAME ✨

Bio::Variation::IO — Handler for sequence variation IO Formats 🎀

---

🌸 SYNOPSIS 🌸

    use Bio::Variation::IO;

    $in  = Bio::Variation::IO->new(-file => "inputfilename" ,
                                   -format => 'flat');
    $out = Bio::Variation::IO->new(-file => ">outputfilename" ,
                                   -format => 'xml');

    while ( my $seq = $in->next() ) {
           $out->write($seq);
    }

  # or

    use Bio::Variation::IO;

    #input file format can be read from the file extension (dat|xml)
    $in  = Bio::Variation::IO->newFh(-file => "inputfilename");
    $out = Bio::Variation::IO->newFh(-format => 'xml');

    # World's shortest flat<->xml format converter:
    print $out $_ while <$in>;

---

💅 DESCRIPTION 💅

So Bio::Variation::IO is the handler module for all the formats in the Variation IO set — like, say, Bio::Variation::IO::flat. And it's the officially sanctioned way to get at the format objects, which is what most people should be using. no cap. 👑

The structure, the conventions, and most of the actual code are inherited from Bio::SeqIO. the one big plot twist: instead of next_seq and write_seq, you just drop the _seq from the method names. that's it, that's the difference, periodt.

The whole vibe is: you request a stream object for a particular format. Every stream object has a notion of an internal file that gets read from or written to. And a particular SeqIO object instance is configured for either input or output — not both, bestie, pick a lane. A specific example of a stream object is the Bio::Variation::IO::flat object. 💖

Each stream object has these functions:

   $stream->next();

and

   $stream->write($seqDiff);

also

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

As an added bonus, you can recover a filehandle that's tied to the SeqIO object, which means you get to use the standard <> and print operations to read and write sequence objects. obsessed. 😭✨

    use Bio::Variation::IO;

    $stream = Bio::Variation::IO->newFh(-format => 'flat');
    # read from standard input

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

and

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

which makes this the simplest ever reformatter:

    #!/usr/local/bin/perl

    $format1 = shift;
    $format2 = shift;

    use Bio::Variation::IO;

    $in  = Bio::Variation::IO->newFh(-format => $format1 );
    $out = Bio::Variation::IO->newFh(-format => $format2 );

    print $out $_ while <$in>;

---

🎀 CONSTRUCTORS 🎀

🌈 Bio::Variation::IO->new()

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

The new() class method constructs a brand new Bio::Variation::IO object. ✨ The object it hands back can be used to retrieve or print BioSeq objects. new() accepts these parameters:

• -file — a file path to be opened for reading or writing. the usual Perl conventions apply, and they are, in order:

      '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::Variation::IO->new(-fh => \*STDIN);

⚠️ note that you must pass filehandles as references to globs. not vibes. actual references to globs.

if neither a filehandle nor a filename is specified, then the module will read from the @ARGV array or STDIN, using the familiar <> semantics. 💫

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

      flat        pseudo EMBL format
      xml         seqvar xml format

if no format is specified and a filename is given, then the module will attempt to deduce it from the filename. and if that fails? Fasta format is assumed. (yes really, even here, we love a plot twist 🙈)

the format name is case insensitive, bestie. 'FLAT', 'Flat' and 'flat' are all supported. slay. 💅

🦋 Bio::Variation::IO->newFh()

   $fh = Bio::Variation::IO->newFh(-fh   => \*FILEHANDLE, -format=>$format);
   $fh = Bio::Variation::IO->newFh(-format => $format);
   # etc.

   #e.g.
   $out = Bio::Variation::IO->newFh( '-FORMAT' => 'flat');
   print $out $seqDiff;

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

  @mutations = <$fh>;

💀 heads up though: other operations, such as read(), sysread(), write(), close(), and printf() are not supported. they're just not invited to the party.

---

🌟 OBJECT METHODS 🌟

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

🍓 $sequence = $seqIO->next()

Fetch the next sequence from the stream. simple as that. ✨

🍓 $seqIO->write($sequence [,$another_sequence,...])

Write the specified sequence(s) to the stream. yes, plural, you can pile them in. 💖

🍓 TIEHANDLE(), READLINE(), PRINT()

These provide the tie interface. See perltie for more details. iykyk. 🧚

---

💌 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 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. please include a thorough description of the problem with code and data examples if at all possible. the more deets the better, 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 — Heikki Lehvaslaiho 👑

Email: heikki-at-bioperl-dot-org

---

📖 APPENDIX 📖

The rest of the documentation details each of the object methods. internal methods are usually preceded with a _ — that's the secret handshake. 🤫

⭐ new

 Title   : new
 Usage   : $stream = Bio::Variation::IO->new(-file => $filename, -format => 'Format')
 Function: Returns a new seqstream
 Returns : A Bio::Variation::IO::Handler initialised with the appropriate format
 Args    : -file => $filename
           -format => format
           -fh => filehandle to attach to

⭐ format

 Title   : format
 Usage   : $format = $stream->format()
 Function: Get the variation format
 Returns : variation format
 Args    : none

⭐ next

 Title   : next
 Usage   : $seqDiff = $stream->next
 Function: reads the next $seqDiff object from the stream
 Returns : a Bio::Variation::SeqDiff object
 Args    :

⭐ write

 Title   : write
 Usage   : $stream->write($seq)
 Function: writes the $seq object into the stream
 Returns : 1 for success and 0 for error
 Args    : Bio::Variation::SeqDiff object

⭐ _guess_format

 Title   : _guess_format
 Usage   : $obj->_guess_format($filename)
 Function:
 Example :
 Returns : guessed format of filename (lower case)
 Args    :

---

and that's the whole page, bestie!! 🎀 this lil legend was brought to you by perl v5.32.1, dated 2021-12-02, and it's still out here doing the most for Bio::V...on::IO(3pm). go forth and convert some formats. mwah. 💖✨🦋