NAME
Bio::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 moduel 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.
Feature entries can take several forms. At their simplest, they look like this:
Gene B0511.1 516-11208
This means that a feature of type "Gene" and name "B0511.1" occupies the range between bases 516 and 11208. A range can be specified equally well using a hyphen, or two dots as in 516..11208. Negative coordinates are allowed, such as -187..1000.
A discontinuous range ("split location") uses commas to separate the ranges. For example:
Gene B0511.1 516-619,3185-3294,10946-11208
Alternatively, the locations can be split by repeating the features type and name on multiple adjacent lines:
Gene B0511.1 516-619
Gene B0511.1 3185-3294
Gene B0511.1 10946-11208
A comment can be added to features by adding a fourth column. These comments will be rendered as under-the-glyph descriptions by those glyphs that honor descriptions:
Gene B0511.1 516-619,3185-3294,10946-11208 "Putative primase"
Columns are separated using whitespace, not (necessarily) tabs. Embedded whitespace can be escaped using quote marks or backslashes in the same way as in the shell:
'Putative Gene' my\ favorite\ gene 516-11208
Features can be grouped so that they are rendered by the "group" glyph (so far this has only been used to relate 5' and 3' ESTs). 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.
METHODS
- $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. -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.
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.
- ($rendered,$panel) = $features->render([$panel])
-
Render features in the data set onto the indicated Bio::Graphics::Panel. If no panel is specified, creates one.
In a scalar context returns the number of tracks rendered. In a list context, returns a two-element list containing the number of features rendered and the panel. Use this form if you want the panel created for you.
- $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.
- $features->add_feature($feature [=>$type])
-
Add a new Bio::FeatureI object to the set. If $type is specified, the object will be added with the indicated type. Otherwise, the feature's primary_tag() method will be invoked to get the type.
- $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;
- $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!
- $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.
- @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);
- @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_stream(), top_SeqFeatures(), all_SeqFeatures()
Provided for compatibility with older BioPerl and/or Bio::DB::GFF APIs.
- $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->make_link($feature)
-
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
[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
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 Swedish fish
FGENESH Predicted gene 1 1-205,518-616,661-735,3187-3365,3436-3846 Pfam domain
FGENESH Predicted gene 2 5513-6497,7968-8136,8278-8383,8651-8839,9462-9515,10032-10705,10949-11340,11387-11524,11765-12067,12876-13577,13882-14121,14169-14535,15006-15209,15259-15462,15513-15753,15853-16219 Mysterious
FGENESH Predicted gene 3 16626-17396,17451-17597
FGENESH Predicted gene 4 18459-18722,18882-19176,19221-19513,19572-19835 Transmembrane protein
# file ends
SEE ALSO
Bio::Graphics::Panel, Bio::Graphics::Glyph, Bio::Graphics::Feature, Bio::Graphics::FeatureFile
AUTHOR
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.