Bio::G...reFile(3pm)

📦

version 2.40 · 2 versions

2.40 · debian bookworm, debian trixie, ubuntu jammy, ubuntu noble (latest)
2.40 · ubuntu resolute, ubuntu stonking

, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble

💖 Bio::Graphics::FeatureFile 💖

okay bestie, welcome to Bio::Graphics::FeatureFile(3pm) from the User Contributed Perl Documentation — yes that's the whole manual name, we're fancy like that 💅. This is part one of three, so buckle up, hydrate, and let's get into it.

✨ NAME ✨

Bio::Graphics::FeatureFile — a whole set of Bio::Graphics features, all chillin' in a file 🎀

🌸 SYNOPSIS 🌸

use Bio::Graphics::FeatureFile;
my $data  = Bio::Graphics::FeatureFile->new(-file => 'features.txt');

# create a new panel and render contents of the file onto it
my $panel = $data->new_panel;
my $tracks_rendered = $data->render($panel);

# or do it all in one step
my ($tracks_rendered,$panel) = $data->render;

# for more control, render tracks individually
my @feature_types = $data->types;
for my $type (@feature_types) {
   my $features = $data->features($type);
   my %options  = $data->style($type);
   $panel->add_track($features,%options);  # assuming we have a Bio::Graphics::Panel
}

# get individual settings
my $est_fg_color = $data->setting(EST => 'fgcolor');

# or create the FeatureFile by hand

# add a type
$data->add_type(EST => {fgcolor=>'blue',height=>12});

# add a feature
my $feature = Bio::Graphics::Feature->new(
                                            # params
                                         ); # or some other SeqI
$data->add_feature($feature=>'EST');

🦋 DESCRIPTION 🦋

So like, Bio::Graphics::FeatureFile reads and parses files that describe sequence features and how you want them rendered. It's giving "I contain multitudes" because it accepts both GFF format and a more human-friendly file format (which we'll get into below, bestie, don't worry). Once you've got yourself a FeatureFile object all initialized, you can interrogate it about its constituent features and their settings, or straight up render the entire file onto a Bio::Graphics::Panel. Iconic behaviour, honestly. 👑

This module is lowkey a precursor of Jason Stajich's Bio::Annotation::Collection class, and it fulfills a similar function — storing a collection of sequence features. But — and this is the plot twist — it also stores rendering information about the features, and it does not currently follow the CollectionI interface. So it's the same vibe but not the same interface, iykyk. 🫶

🌈 The File Format 🌈

There are exactly two types of entry in the file format, bestie:

feature entries 🧬
formatting entries 🎨

They can occur in any order. No rules, only vibes. (There's a full example in the Appendix if you want the deluxe tour.)

🎀 Formatting Entries 🎀

Formatting entries look like this:

[Stanza Name]
option1 = value1
option2 = value2
option3 = value3

[Stanza Name 2]
option1 = value1
option2 = value2
...

There can be zero or more stanzas, each with a unique name. The names can contain any character except the [ ] characters (so don't be chaotic). Each stanza consists of one or more option = value pairs, where the option and the value are separated by an = sign and optional whitespace.

Values can be continued across multiple lines by indenting the continuation lines by one or more spaces, like:

[Named Genes]
feature = gene
glyph   = transcript2
description = These are genes that have been named
  by the international commission on gene naming
  (The Hague).

Typically configuration stanzas will consist of several Bio::Graphics formatting options. And here's the glow-up moment: a -option=>$value pair passed to Bio::Graphics::Panel->add_track() becomes a option=value pair in the feature file. Same energy, different outfit. 💅

🧬 Feature Entries 🧬

Feature entries can take several forms. At their simplest, they look like this:

Gene   B0511.1 Chr1:516..11208

Which means: a feature of type Gene and name B0511.1 occupies the range between bases 516 and 11208 on a sequence entry named Chr1. Slay. ✨

Columns are separated using whitespace (tabs or spaces). And if you've got embedded whitespace you need to protect, you can escape it using quote marks or backslashes:

Gene "My Favorite Gene" Chr1:516..11208

📍 Specifying Positions and Ranges 📍

A feature position is specified using a sequence ID (a genbank accession number, a chromosome name, a contig, or any other meaningful reference system), followed by a colon and a position range. Ranges are two integers separated by double dots or the hyphen. Examples: "Chr1:516..11208", "ctgA:1-5000". Negative coordinates are allowed, as in "Chr1:-187..1000".

A discontinuous range (aka a "split location") uses commas to separate the ranges. For example:

Gene B0511.1  Chr1:516..619,3185..3294,10946..11208

In the case of a split location, the sequence id only has to appear in front of the first range. Efficiency queen. 👑

Alternatively, a split location can be indicated by repeating the feature's type and name on multiple adjacent lines:

Gene   B0511.1 Chr1:516..619
Gene   B0511.1 Chr1:3185..3294
Gene   B0511.1 Chr1:10946..11208

And if all the locations are on the same reference sequence, you can specify a default chromosome using a reference=<seqid>:

reference=Chr1
Gene   B0511.1 516..619
Gene   B0511.1 3185..3294
Gene   B0511.1 10946..11208

The default seqid is in effect until the next reference line appears. So it's like a little state machine moment. No cap. 🦋

🏷️ Feature Tags 🏷️

Tags can be added to features by adding a fourth column consisting of tag=value pairs:

Gene  B0511.1  Chr1:516..619,3185..3294 Note="Putative primase"

Tags and their values take any form you want, and multiple tags can be separated by semicolons. You can also repeat tags multiple times:

Gene  B0511.1  Chr1:516..619,3185..3294 GO_Term=GO:100;GO_Term=GO:2087

Several tags have special meanings, bestie, listen up:

Type — the primary tag for a subfeature.
Score — the score of a feature or subfeature.
Phase — the phase of a feature or subfeature.
URL — a URL to link to (via the Bio::Graphics library).
Note — a note to attach to the feature for display by the Bio::Graphics library.

For example, in the common case of an mRNA, you can use the Type tag to distinguish the parts of the mRNA into UTR and CDS:

mRNA B0511.1 Chr1:1..100 Type=UTR
mRNA B0511.1 Chr1:101..200,300..400,500..800 Type=CDS
mRNA B0511.1 Chr1:801..1000 Type=UTR

The top level feature's primary tag will be mRNA, and its subparts will have types UTR and CDS as indicated. Additional tags that are placed in the first line of the feature will be applied to the top level. In this example, the note "Putative primase" will be applied to the mRNA at the top level of the feature:

mRNA B0511.1 Chr1:1..100 Type=UTR;Note="Putative primase"
mRNA B0511.1 Chr1:101..200,300..400,500..800 Type=CDS
mRNA B0511.1 Chr1:801..1000 Type=UTR

👯 Feature Groups 👯

Features can be grouped so that they are rendered by the group glyph. To start a group, create a two-column feature entry showing the group type and a name for the group. Then follow it with a list of feature entries with a blank type. For example:

EST    yk53c10
       yk53c10.3       15000-15500,15700-15800
       yk53c10.5       18892-19154

This example is declaring that the ESTs named yk53c10.3 and yk53c10.5 belong to the same group named yk53c10. Friendship bracelets, but for features. 🫶

💬 Comments 💬

Lines that begin with the # sign are treated as comments and ignored. When a # sign appears within a line, everything to the right of the symbol is also ignored — unless it looks like an HTML fragment or an HTML color, e.g.:

# this is ignored
[Example]
glyph   = generic   # this comment is ignored
bgcolor = #FF0000
link    = http://www.google.com/search?q=$name#results

⚠️ Be careful, bestie, because the processing of # signs uses a regexp heuristic. To be safe, always put a space after the # sign to make sure it is treated as a comment. It's giving "the parser is doing its best" 😭

📎 The `#include` and `#exec` Directives 📎

The special comment #include 'filename' acts like the C preprocessor directive and will insert the contents of a named file into the position at which it occurs. Relative paths will be treated relative to the file in which the #include occurs. Nested #include directives (a #include located in a file that is itself an include file) are #allowed. You may also use one of the shell wildcard characters * and #? to include all matching files in a directory.

The following are examples of valid #include directives:

#include "/usr/local/share/my_directives.txt"
#include 'my_directives.txt'
#include chromosome3_features.gff3
#include gff.d/*.conf

You can enclose the file path in single or double quotes as shown above. If there are no spaces in the filename, the quotes are optional. The #include directive is case insensitive, allowing you to use #INCLUDE or #Include if you prefer. Do it your way. ✨

😭 Include file processing is not very smart and will not catch all circular #include references. You have been warned! (Consider this your dramatic warning of the day. 💀)

The special comment #exec 'command' will spawn a shell and incorporate the output of the command into the configuration file. This command will be executed quite frequently, so it is suggested that any time-consuming processing that does not need to be performed on the fly each time should be cached in a local file. Future you says thank you. 🎀

🛠️ METHODS 🛠️

`$version = Bio::Graphics::FeatureFile->version`

Return the version number — needed for API checking by GBrowse. 📌

`$features = Bio::Graphics::FeatureFile->new(@args)`

Create a new Bio::Graphics::FeatureFile using @args to initialize the object. Arguments are -name=>value pairs:

-file — Read data from a file path or filehandle. Use "-" to read from standard input.
-text — Read data from a text scalar.
-allow_whitespace — If true, relax GFF2 and GFF3 parsing rules to allow columns to be delimited by whitespace rather than tabs.
-map_coords — Coderef containing a subroutine to use for remapping all coordinates.
-smart_features — Flag indicating that the features created by this module should be made aware of the FeatureFile object by calling their configurator() method.
-safe — Indicates that the contents of this file is trusted. Any option value that begins with the string "sub {" or \&subname will be evaluated as a code reference. 🔥
-safe_world — If the -safe option is not set, and -safe_world is set to a true value, then Bio::Graphics::FeatureFile will evaluate "sub {}" options in a Safe::World environment with minimum permissions. Subroutines will be able to access and interrogate Bio::DB::SeqFeature objects and perform basic Perl operations, but will have no ability to load or access other modules, to access the file system, or to make system calls. This feature depends on availability of the CPAN-installable Safe::World module. 🧚

okay bestie we're only like a third of the way through, don't you dare close the tab — more is coming 💖✨

Okay bestie, more options coming at you, stay with me 💅

The -file and -text arguments are mutually exclusive, and if you pass both, -file wins — it straight up supersedes the other one. No cap.

-map_coords points to a coderef with this signature:

($newref,[$start1,$end1],[$start2,$end2]....)
          = coderef($ref,[$start1,$end1],[$start2,$end2]...)

If you wanna see how people use this to do wonderful stuff, go look at Bio::Graphics::Browser (it's part of the generic genome browser package). It's giving inspiration, fr. ✨

The -smart_features flag is used by the generic genome browser to give features a way to access the link-generation code. See gbrowse for how that actually works. 🦋

If the file is trusted, and there's an option named "init_code" in the [GENERAL] section of the file, it will be evaluated as perl code immediately after parsing. You can use this to declare global variables and subroutines for use in option values. Iconic behaviour honestly 🫶

🎀 `$features = Bio::Graphics::FeatureFile->new_from_cache(@args)`

Like new() but it caches the parsed file in /tmp/bio_graphics_ff_cache_* (where * is the UID of the current user). This can speed up parsing tremendously for files that have many includes. Main character speed boost, periodt. 🔥

Note that the presence of an #exec statement always invalidates the cache and causes a full parse. So no sneaky shortcut there, bestie 😭

🌸 `$mtime = Bio::Graphics::FeatureFile->file_mtime($path)`

Returns the modification time of the indicated feature file without doing a full parse. It takes into account the various #include and #exec directives and returns the maximum mtime of any of the included files. Any #exec directive will return the current time. Super useful for caching the parsed data structure. 💖

🦋 `($rendered,$panel,$tracks) = $features->render([$panel, $position_to_insert, $options, $max_bump, $max_label, $selector])`

Render features in the data set onto the indicated Bio::Graphics::Panel. If no panel is specified, it creates one. All arguments are optional. ✨

$panel is a Bio::Graphics::Panel that has previously been created and configured.
$position_to_insert indicates the position at which to start inserting new tracks. The last current track on the panel is assumed.
$options is a scalar used to control automatic expansion of the tracks: 0=auto, 1=compact, 2=expanded, 3=expand and label, 4=hyperexpand, 5=hyperexpand and label.
$max_bump and $max_label indicate the maximum number of features before bumping and labeling are turned off.
$selector is a code ref that can be used to filter which features to render. It receives a feature and should return true to include the feature and false to exclude it.

In a scalar context it returns the number of tracks rendered. In a list context, it returns a three-element list containing the number of features rendered, the created panel, and an array ref of all the track objects created. So versatile, we love her 💜

Instead of a Bio::Graphics::Panel object, you can provide a hash reference containing the arguments that you would pass to Bio::Graphics::Panel->new(). For example, to render an SVG image, you could do this:

my ($tracks_rendered,$panel) = $data->render({-image_class=>'GD::SVG'});
print $panel->svg;

🌈 `$error = $features->error([$error])`

Get/set the current error message. Simple as that 🎀

🍓 `$smart_features = $features->smart_features([$flag]`

Get/set the "smart_features" flag. If this is set, then any features added to the featurefile object will have their configurator() method called using the featurefile object as the argument.

💅 `$flat = $features->allow_whitespace([$new_flag])`

If true, then GFF3 and GFF2 parsing is relaxed to allow whitespace to delimit the columns. Default is false. Relaxed queen behaviour, but only if you ask 🫶

👑 `$features->add_feature($feature [=>$type])`

Add a new Bio::FeatureI object to the set. If $type is specified, the object's primary_tag() will be set to that type. Otherwise, the method will use the feature's existing primary_tag() to index and store the feature.

🧚 `$features->add_type($type=>$hashref)`

Add a new feature type to the set. The type is a string, such as "EST". The hashref is a set of key=>value pairs indicating options to set on the type. Example:

$features->add_type(EST => { glyph => 'generic', fgcolor => 'blue'})

When a feature of type "EST" is rendered, it will use the generic glyph and have a foreground color of blue. Cute, consistent, slay 💙

⭐ `$features->set($type,$tag,$value)`

Change an individual option for a particular type. For example, this will change the foreground color of EST features to my favorite color:

$features->set('EST',fgcolor=>'chartreuse')

💜 `$value = $features->setting($stanza => $option)`

In the two-element form, the setting() method returns the value of an option in the configuration stanza indicated by $stanza. For example:

$value = $features->setting(general => 'height')

will return the value of the "height" option in the [general] stanza.

Call with one element to retrieve all the option names in a stanza:

@options = $features->setting('general');

Call with no elements to retrieve all stanza names:

@stanzas = $features->setting;

🎀 fallback_setting()

$value = $browser->setting(gene => 'fgcolor');

Tries to find the setting for the designated label (e.g. "gene") first. If this fails, it looks in [TRACK DEFAULTS]. If that fails, it looks in [GENERAL]. It's giving fallback queen — never leaves you hanging 💖

🌸 `$value = $features->code_setting($stanza=>$option);`

This works like setting() except that it is also able to evaluate code references. These are options whose values begin with the characters "sub {". In this case the value will be passed to an eval() and the resulting codereference returned.

Use this with care! Like, actually. This is the risky part bestie 😭

🦋 `$value = $features->safe_setting($stanza=>$option);`

This works like code_setting() except that it evaluates anonymous code references in a "Safe::World" compartment. This depends on the Safe::World module being installed and the -safe_world option being set to true during object construction.

✨ `$flag = $features->safe([$flag]);`

This gets or sets a "safe" flag. If the safe flag is set, then calls to setting() will invoke code_setting(), allowing values that begin with the string "sub {" to be interpreted as anonymous subroutines.

This is a potential security risk when used with untrusted files of features, so use it with care. Fr fr, don't be reckless with this one 🙈

💅 `$flag = $features->safe_world([$flag]);`

This gets or sets a "safe_world" flag. If the safe_world flag is set, then values that begin with the string "sub {" will be evaluated in a "safe" compartment that gives minimal access to the system.

This is not a panacea for security risks, so use with care. It's a vibe, not a force field, okay? 🫶

🌈 `$features->set_callback_source($type,$tag,$value)`

🌈 `$features->get_callback_source($type,$tag)`

These routines are used internally to get and set the source of a sub {} callback. Backstage crew only, no need to touch 💜

🍓 `@args = $features->style($type)`

Given a feature type, returns a list of track configuration arguments suitable for passing to the Bio::Graphics::Panel->add_track() method.

🧚 `$glyph = $features->glyph($type);`

Return the name of the glyph corresponding to the given type (same as $features->setting($type=>'glyph')).

👑 `@types = $features->configured_types()`

Return a list of all the feature types currently known to the feature file set. Roughly equivalent to:

@types = grep {$_ ne 'general'} $features->setting;

⭐ `@types = $features->types()`

This is similar to the previous method, but will return all feature types, including those that are not configured with a stanza. No filter, no gatekeeping, everyone's invited 💖

💜 `$features = $features->features($type)`

Return a list of all the feature types of type "$type". If the featurefile object was created by parsing a file or text scalar, then the features will be of type Bio::Graphics::Feature (which follow the Bio::FeatureI interface). Otherwise the list will contain objects of whatever type you added with calls to add_feature().

Two APIs:

1) original API:

   # Reference to an array of all features of type "$type"
   $features = $features-E<gt>features($type)

   # Reference to an array of all features of all types
   $features = $features-E<gt>features()

   # A list when called in a list context
   @features = $features-E<gt>features()

2) Bio::Das::SegmentI API:

    @features = $features-E<gt>features(-type=>['list','of','types']);

    # variants
    $features = $features-E<gt>features(-type=>['list','of','types']);
    $features = $features-E<gt>features(-type=>'a type');
    $iterator = $features-E<gt>features(-type=>'a type',-iterator=>1);

    $iterator = $features-E<gt>features(-type=>'a type',-seq_id=>$id,-start=>$start,-end=>$end);

🌸 `@features = $features->features($type)`

🎀 get_seq_stream

Title: get_seq_stream
Usage: $stream = $s->get_seq_stream(@args)
Function: get a stream of features that overlap this segment
Returns: a Bio::SeqIO::Stream-compliant stream
Args: see below
Status: Public

This is the same as feature_stream(), and is provided for Bioperl compatibility. Use like this:

$stream = $s->get_seq_stream('exon');
while (my $exon = $stream->next_seq) {
   print $exon->start,"\n";
}

🦋 get_feature_by_name

Usage: $db->get_feature_by_name(-name => $name)
Function: fetch features by their name
Returns: a list of Bio::DB::GFF::Feature objects
Args: the name of the desired feature
Status: public

This method can be used to fetch a named feature from the file. 🔍

The full syntax is as follows. Features can be filtered by their reference, start and end positions:

@f = $db->get_feature_by_name(-name  => $name,
                              -ref   => $sequence_name,
                              -start => $start,
                              -end   => $end);

This method may return zero, one, or several Bio::Graphics::Feature objects. So check what you got before you assume, okay bestie? 💖

`search_notes` 🔍

Title — search_notes
Usage — @search_results = $db->search_notes("full text search string",$limit)
Function — searches the notes for a text string, like ctrl-F but make it database ✨
Returns — an array of results
Args — the full text search string, plus an optional row limit
Status — public

Every single row of that returned array is an arrayref, and it's giving three fields, bestie:

column 1 — the Display name of the feature
column 2 — The text of the note
column 3 — A relevance score.

`get_feature_stream()`, `top_SeqFeatures()`, `all_SeqFeatures()` 🫶

These are provided for compatibility with older BioPerl and/or Bio::DB::GFF APIs. They're here so your old code doesn't have to go through it, yk?

@refs = $features->refs — returns the list of reference sequences referred to by this data file.
$min = $features->min — returns the minimum coordinate of the leftmost feature in the data set.
$max = $features->max — returns the maximum coordinate of the rightmost feature in the data set.
$mtime = $features->mtime
$atime = $features->atime
$ctime = $features->ctime
$size = $features->size — returns stat() information about the data file, for featurefile objects created using the -file option. Size is in bytes. mtime, atime, and ctime are in seconds since the epoch.
$label = $features->feature2label($feature) — given a feature, it figures out which configuration stanza describes it best. It uses the feature's type() method if it has one (that's the DasI interface), or its primary_tag() method otherwise.
$link = $features->link_pattern($linkrule,$feature,$panel) — given a feature, it tries to generate a URL to link out from it. This uses the 'link' option, if one is present. It's a convenience method for the generic genome browser, bestie 💅
$citation = $features->citation($feature) — given a feature, it tries to generate a citation for it, using the "citation" option if one is present. Also a convenience for the generic genome browser.
$name = $features->name([$feature]) — get/set the name of this feature set. Convenience method, very useful for keeping track of multiple feature sets. Main character bookkeeping energy 👑

🧚 APPENDIX -- SAMPLE FEATURE FILE 🧚

Okay so here's the whole thing laid out, no cap:

# file begins
[general]
pixels = 1024
bases = 1-20000
reference = Contig41
height = 12

[mRNA]
glyph = gene
key   = Spliced genes

[Cosmid]
glyph = segments
fgcolor = blue
key = C. elegans conserved regions

[EST]
glyph = segments
bgcolor= yellow
connector = dashed
height = 5;

[FGENESH]
glyph = transcript2
bgcolor = green
description = 1

mRNA B0511.1 Chr1:1..100 Type=UTR;Note="putative primase"
mRNA B0511.1 Chr1:101..200,300..400,500..800 Type=CDS
mRNA B0511.1 Chr1:801..1000 Type=UTR

reference = Chr3
Cosmid B0511   516..619
Cosmid B0511   3185..3294
Cosmid B0511   10946..11208
Cosmid B0511   13126..13511
Cosmid B0511   11394..11539
EST    yk260e10.5      15569..15724
EST    yk672a12.5      537..618,3187..3294
EST    yk595e6.5       552..618
EST    yk595e6.5       3187..3294
EST    yk846e07.3      11015..11208
EST    yk53c10
       yk53c10.3       15000..15500,15700..15800
       yk53c10.5       18892..19154
EST    yk53c10.5       16032..16105
SwissProt      PECANEX 13153-13656     Note="Swedish fish"
FGENESH        "Predicted gene 1"      1-205,518-616,661-735,3187-3365,3436-3846       "Pfam domain"
# file ends

👀 SEE ALSO 👀

Go read these next, they're literally the friends of this module 🌈

Bio::Graphics::Panel
Bio::Graphics::Glyph
Bio::DB::SeqFeature::Store::FeatureFileLoader
Bio::Graphics::Feature
Bio::Graphics::FeatureFile

💖 AUTHOR 💖

Lincoln Stein <lstein@cshl.org>. 🫶

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See DISCLAIMER.txt for disclaimers of warranty.

And that's the whole page, bestie, we ate and left no crumbs 💅✨ This lil' rendering is from perl v5.30.0 and it's dated 2019-11-25 — shoutout to Bio::G...reFile(3pm) for being iconic, you're welcome, bye 🎀🦋

📦 where this page comes from

debian bookworm: libbio-graphics-perl 2.40-6 · Perl
debian trixie: libbio-graphics-perl 2.40-6 · Perl
ubuntu jammy: libbio-graphics-perl 2.40-6 · Perl
ubuntu noble: libbio-graphics-perl 2.40-6 · Perl
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms

Bio::G...reFile(3pm)

💖 Bio::Graphics::FeatureFile 💖

✨ NAME ✨

🌸 SYNOPSIS 🌸

🦋 DESCRIPTION 🦋

🌈 The File Format 🌈

🎀 Formatting Entries 🎀

🧬 Feature Entries 🧬

📍 Specifying Positions and Ranges 📍

🏷️ Feature Tags 🏷️

👯 Feature Groups 👯

💬 Comments 💬

📎 The #include and #exec Directives 📎

🛠️ METHODS 🛠️

$version = Bio::Graphics::FeatureFile->version

$features = Bio::Graphics::FeatureFile->new(@args)

🎀 $features = Bio::Graphics::FeatureFile->new_from_cache(@args)

🌸 $mtime = Bio::Graphics::FeatureFile->file_mtime($path)

🦋 ($rendered,$panel,$tracks) = $features->render([$panel, $position_to_insert, $options, $max_bump, $max_label, $selector])

🌈 $error = $features->error([$error])

🍓 $smart_features = $features->smart_features([$flag]

💅 $flat = $features->allow_whitespace([$new_flag])

👑 $features->add_feature($feature [=>$type])

🧚 $features->add_type($type=>$hashref)

⭐ $features->set($type,$tag,$value)

💜 $value = $features->setting($stanza => $option)