Bio::FeatureIO(3pm)

NAME 💖

okay bestie, gather round, because this is the manual page for Bio::FeatureIO(3pm) — the handler for FeatureIO, and honestly? it's iconic. it's the officially sanctioned way to get at all the FeatureIO format modules, and yes, you're gonna want to use it. 🎀

---

✨ SYNOPSIS ✨

like, here's the whole vibe in one go:

use Bio::FeatureIO;

#read from a file
$in  = Bio::FeatureIO->new(-file => "my.gff" , -format => 'GFF');

#read from a filehandle
$in  = Bio::FeatureIO->new(-fh => \*GFF , -format => 'GFF');

#read features already attached to a sequence
my $feat = Bio::FeatureIO->new(-seq => $seq , -format => 'features');

#read new features for existing sequence
my $seq = Bio::FeatureIO->new(-seq => $seq , -format => 'Das');

#write out features
$out = Bio::FeatureIO->new(-file    => ">outputfilename" ,
                           -format  => 'GFF' ,
                           -version => 3);

while ( my $feature = $in->next_feature() ) {
  $out->write_feature($feature);
}

no cap, that loop right there is the entire plot of your bioinformatics pipeline. 💅

---

🌸 DESCRIPTION 🌸

so Bio::FeatureIO is an I/O iterator subsystem for genomic sequence features. it's the handler module for all the formats in the FeatureIO set (think Bio::FeatureIO::GFF and friends), and it is the officially sanctioned way of getting at the format objects — which, bestie, means it's what most people should be using. periodt.

the way to think about the whole Bio::FeatureIO system is like biological filehandles. they get attached to filehandles with smart formatting rules (GFF format, BED format, you know the drill), and they can either read or write feature objects — that's Bio::SeqFeature objects, or more correctly, objects implementing Bio::FeatureHolderI, of which Bio::SeqFeature is one such object. and if you wanna know what to do with a Bio::SeqFeatureI object, go read Bio::SeqFeatureI. iykyk. 📖

the idea is that 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. a particular FeatureIO object instance is configured for either input or output. a specific example of a stream object is the Bio::FeatureIO::gff object. slay.

each stream object has these functions:

$stream->next_feature();
$stream->write_feature($feature);

---

🦋 SUPPORTED FORMATS 🦋

here's the lineup, name and module, no gatekeeping:

• BED — bed.pm
• GFF — gff.pm
• GTF — gtf.pm
• InterPro (IPRScan 4.0) — interpro.pm
• PTT (NCBI protein table) — ptt.pm

---

👑 CONSTRUCTORS 👑

🌈 Bio::FeatureIO->new()

$featureIO = Bio::FeatureIO->new(-file => 'filename',   -format=>$format);
$featureIO = Bio::FeatureIO->new(-fh   => \*FILEHANDLE, -format=>$format);
$featureIO = Bio::FeatureIO->new(-seq  => $seq,         -format=>$format);

the new() class method constructs a new Bio::FeatureIO object. the returned object can be used to retrieve or print Seq objects. new() accepts the following parameters:

💜 -file

a file path to be opened for reading or writing. the usual Perl conventions apply, and yes they go hard:

'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:

$featio = Bio::FeatureIO->new(-fh => \*STDIN);

note: you must pass filehandles as references to globs. no exceptions bestie.

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

a string filehandle is handy if you want to modify the output in the memory, before printing it out. the following program reads in EMBL formatted entries from a file and prints them out in fasta format with some HTML tags (yes, really, and we're reproducing it exactly as it is, don't come for me):

use Bio::FeatureIO;
use IO::String;
my $in  = Bio::FeatureIO->new('-file' => "my.gff" ,
                          '-format' => 'EMBL');
while ( my $f = $in->next_feature() ) {
    # the output handle is reset for every file
    my $stringio = IO::String->new($string);
    my $out = Bio::FeatureIO->new('-fh' => $stringio,
                              '-format' => 'gtf');
    # output goes into $string
    $out->write_feature($f);
    # modify $string
    $string =~ s|(>)(\w+)|$1<font color="Red">$2</font>|g;
    # print into STDOUT
    print $string;
}

🧚 -format

specify the format of the file. see above for the list of supported formats. ✨

💀 -flush

by default, all files (or filehandles) opened for writing sequences will be flushed after each write_seq() (which makes the file immediately usable). if you don't 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 $f1 = Bio::FeatureIO->new -file   => "<a.f1",
                            -format => "f1";
my $f2 = Bio::FeatureIO->new -file   => ">a.f2",
                            -format => "f2",
                            -flush  => 0; # go as fast as we can!

while($feature = $f1->next_feature) { $f2->write_feature($feature) }

---

🎀 Bio::FeatureIO->newFh()

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

this constructor behaves like new(), but returns a tied filehandle rather than a Bio::FeatureIO 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:

@features = <$fh>;

other operations, such as read(), sysread(), write(), close(), and printf() are not supported. sorry babe, those just aren't on the menu. 🙈

---

💅 OBJECT METHODS 💅

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

• next_feature — fetch the next feature from the stream.
• write_feature — write the specified feature(s) to the stream.
• feature_factory — this gets/sets the specific Bio::Factory::FeatureFactoryI

the following methods delegate to the inter

yeah bestie it literally just ends there in the original, mid-sentence, the sentence said "the inter" and dipped 💀 keeping it verbatim because facts are facts.

• feature_class — set the specific Bio::SeqFeatureI class to return
• type_features — boolean flag, ensures the returned features are typed
• unflatten_features — ensure the returned features are unflattened

⭐ 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. 🥹

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 detail 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:

http://bugzilla.open-bio.org/

---

👑 AUTHOR - Allen Day 👑

email allenday@ucla.edu

---

to be continued, bestie — part 2 is coming and we are not done yet 💖✨

📎 APPENDIX 💖

The rest of the docs spill all the tea on each object method. Internal methods are usually preceded with a _, so if you see one, just know it's private-ish. 🫶

---

new ✨

• Title: new
• Usage: $stream = Bio::FeatureIO->new(-file => $filename, -format => 'Format')
• Function: hands you back a brand-new feature stream, all set up in whatever format you asked for. 💅
• Returns: a Bio::FeatureIO stream, initialized with the appropriate format.
• Args: named parameters, bestie:
  • -file => $filename
  • -fh => filehandle to attach to
  • -format => format

---

newFh 🌸

• Title: newFh
• Usage: $fh = Bio::FeatureIO->newFh(-file=>$filename,-format=>'Format')
• Function: literally does a new() followed by an fh(). Two steps, one vibe. ✨
• Example:

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

• Returns: a filehandle tied to the Bio::FeatureIO::Fh class.
• Args:

See Bio::FeatureIO::Fh

---

fh 🎀

• Title: fh
• Usage: $obj->fh
• Function:
• Example:

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

• Returns: a filehandle tied to the Bio::FeatureIO class.
• Args: none

---

next_feature 🔥

• Title: next_feature
• Usage: $feature = stream->next_feature
• Function: reads the next feature object from the stream and returns it.

Okay but listen: certain driver modules may encounter entries in the stream that are either misformatted or that use syntax not yet understood by the driver. If that kind of incident is recoverable — like by dismissing a feature of a feature table or some other non-mandatory part of an entry — the driver will issue a warning. In the case of a non-recoverable situation, an exception will be thrown. And bestie, do not assume you can resume parsing the same stream after catching that exception. Also note: you can always turn recoverable errors into exceptions by calling $stream->verbose(2). 😭

• Returns: a Bio::SeqFeatureI feature object.
• Args: none

See Bio::Root::RootI, Bio::SeqFeatureI

---

write_feature 💖

• Title: write_feature
• Usage: $stream->write_feature($feature)
• Function: writes the $feature object into the stream.
• Returns: 1 for success and 0 for error.
• Args: Bio::SeqFeature object

---

_load_format_module 🧚

• Title: _load_format_module
• Usage: *INTERNAL FeatureIO stuff*
• Function: loads up (like use) a module at run time on demand.
• Example:
• Returns:
• Args:

---

seq 🦋

• Title: seq
• Usage: $obj->seq() OR $obj->seq($newSeq)
• Example:
• Returns: Bio::SeqI object
• Args: newSeq (optional)

---

_filehandle 💀

• Title: _filehandle
• Usage: $obj->_filehandle($newval)
• Function: This method is deprecated. Call _fh() instead. 🚫
• Example:
• Returns: value of _filehandle
• Args: newvalue (optional)

---

_guess_format 🌈

• Title: _guess_format
• Usage: $obj->_guess_format($filename)
• Function: guesses format based on file suffix.
• Example:
• Returns: guessed format of filename (lower case)
• Args:
• Notes: See "SUPPORTED FORMATS"

---

This page is from perl v5.30.0, dated 2020-01-13, and it's Bio::FeatureIO(3pm) — bye bestie, go parse something iconic! 💅✨