Bio::Graphics::FeatureUser(Contributed Perl DocumBio::Graphics::FeatureFile(3)NAMEBio::Graphics::FeatureFile-- A set of Bio::Graphics features, stored
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
The Bio::Graphics::FeatureFile module reads and parses files that
describe sequence features and their renderings. It accepts both GFF
format and a more human-friendly file format described below. Once a
FeatureFile object has been initialized, you can interrogate it for its
consistuent features and their settings, or render the entire file onto
a Bio::Graphics::Panel.
This module is a precursor of Jason Stajich's
Bio::Annotation::Collection class, and fulfills a similar function of
storing a collection of sequence features. However, it also stores
rendering information about the features, and does not currently follow
the CollectionI interface.
The File Format
There are two types of entry in the file format: feature entries, and
formatting entries. They can occur in any order. See the Appendix for
a full example.
Formatting Entries
Formatting entries are in the form:
[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. 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, as in:
[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. A -option=>$value pair passed to
Bio::Graphics::Panel->add_track() becomes a "option=value" pair in the
feature file.
Feature Entries
Feature entries can take several forms. At their simplest, they look
like this:
Gene B0511.1 Chr1:516..11208
This means that a feature of type "Gene" and name "B0511.1" occupies
the range between bases 516 and 11208 on a sequence entry named Chr1.
Columns are separated using whitespace (tabs or spaces). Embedded
whitespace can be escaped 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 ("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.
Alternatively, a split location can be indicated by repeating the
features 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
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.
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:
Tag Meaning
--- -------
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. Follow this 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.
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, 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.
The #include and #exec Directives
The special comment "#include 'filename'" acts like the C preprocessor
directive and will insert the comments 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.
Include file processing is not very smart and will not catch all
circular #include references. You have been warned!
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.
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:
Argument Value
-------------
-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 evalute "sub {}" options in a L<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 L<Safe::World>
module.
The -file and -text arguments are mutually exclusive, and -file
will supersede the other if both are present.
-map_coords points to a coderef with the following signature:
($newref,[$start1,$end1],[$start2,$end2]....)
= coderef($ref,[$start1,$end1],[$start2,$end2]...)
See the Bio::Graphics::Browser (part of the generic genome browser
package) for an illustration of how to use this to do wonderful
stuff.
The -smart_features flag is used by the generic genome browser to
provide features with a way to access the link-generation code.
See gbrowse for how this works.
If the file is trusted, and there is 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.
$features = Bio::Graphics::FeatureFile->new_from_cache(@args)
Like new() but 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.
Note that the presence of an #exec statement always invalidates the
cache and causes a full parse.
$mtime = Bio::Graphics::FeatureFile->file_mtime($path)
Return the modification time of the indicated feature file without
performing a full parse. This 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. This is 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, 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 returns the number of tracks rendered. In a
list context, returns a three-element list containing the number of
features rendered, the created panel, and an array ref of all the
track objects created.
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.
$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.
$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.
$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 designated label (e.g. "gene") first. If
this fails, looks in [TRACK DEFAULTS]. If this fails, looks in
[GENERAL].
$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!
$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 and "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.
$flag = $features->safe_world([$flag]);
This gets or sets and "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.
$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.
@args = $features->style($type)
Given a feature type, returns a list of track configuration
arguments suitable for 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.
$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)
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().
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.
search_notes
Title : search_notes
Usage : @search_results = $db->search_notes("full text search string",$limit)
Function: Search the notes for a text string
Returns : array of results
Args : full text search string, and an optional row limit
Status : public
Each row of the returned array is a arrayref containing the following
fields:
column 1 Display name of the feature
column 2 The text of the note
column 3 A relevance score.
get_feature_stream(), top_SeqFeatures(), all_SeqFeatures()
Provided for compatibility with older BioPerl and/or Bio::DB::GFF APIs.
@refs = $features->refs
Return the list of reference sequences referred to by this data
file.
$min = $features->min
Return the minimum coordinate of the leftmost feature in the data
set.
$max = $features->max
Return 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, determines the configuration stanza that bests
describes it. Uses the feature's type() method if it has it (DasI
interface) or its primary_tag() method otherwise.
$link = $features->link_pattern($linkrule,$feature,$panel)
Given a feature, tries to generate a URL to link out from it. This
uses the 'link' option, if one is present. This method is a
convenience for the generic genome browser.
$citation = $features->citation($feature)
Given a feature, tries to generate a citation for it, using the
"citation" option if one is present. This method is a convenience
for the generic genome browser.
$name = $features->name([$feature])
Get/set the name of this feature set. This is a convenience method
useful for keeping track of multiple feature sets.
Appendix -- Sample Feature File
# 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
Bio::Graphics::Panel, Bio::Graphics::Glyph,
Bio::DB::SeqFeature::Store::FeatureFileLoader, Bio::Graphics::Feature,
Bio::Graphics::FeatureFileAUTHOR
Lincoln Stein <lstein@cshl.org>.
Copyright (c) 2001 Cold Spring Harbor Laboratory
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.
perl v5.14.1 2011-07-22 Bio::Graphics::FeatureFile(3)
