Bio::Graphics::Browser::Plugin -- Base class for gbrowse plugins.
package Bio::Graphics::Browser::Plugin::MyPlugin; use Bio::Graphics::Browser::Plugin; use CGI ':standard'; @ISA = 'Bio::Graphics::Browser::Plugin';
# called by gbrowse to return name of plugin for popup menu sub name { 'Example Plugin' }
# called by gbrowse to return description of plugin sub description { 'This is an example plugin' }
# called by gbrowse to return type of plugin sub type { 'annotator' }
# called by gbrowse to configure default settings for plugin sub config_defaults { my $self = shift; return {foo => $value1, bar => $value2} }
# called by gbrowse to reconfigure plugin settings based on CGI parameters sub reconfigure { my $self = shift; my $current = $self->configuration; $current->{foo} = $self->config_param('foo'); $current->{bar} = $self->config_param('bar'); }
# called by gbrowse to create a <form> fragment for changing settings sub configure_form { my $self = shift; my $current = $self->configuration; my $form = textfield(-name => $self->config_name('foo'), -value => $current->{foo}) . textfield(-name => $self->config_name('bar'), -value => $current->{bar}); return $form; }
# called by gbrowse to annotate the DNA, returning features sub annotate { my $self = shift; my $segment = shift; my $config = $self->configuration; # do something with the sequence segment my @features = do_something(); return \@features; }
This is the base class for Generic Genome Browser plugins. Plugins are perl .pm files that are stored in the gbrowse.conf/plugins directory. Plugins are activated in the gbrowse.conf/ configuration file by including them on the list indicated by the ``plugins'' setting:
plugins = BatchDumper FastaDumper GFFDumper OligoFinder RestrictionAnnotator
Site-specific plugins may be placed in one or more site-specific directories and added to the plugin search path using the plugin_path setting:
plugin_path = /usr/local/gbrowse_plugins
GBrowse currently recognizes four distinct types of plugins:
All plug-ins inherit from Bio::Graphics::Browser::Plugin, which defines reasonable (but uninteresting) defaults for each of the methods. Specific behavior is then implemented by selectively overriding certain methods.
The best way to understand how this works is to look at the source code for some working plugins. Examples provided with the gbrowse distribution include:
The remainder of this document describes the methods available to the programmer.
The initialization methods establish the human-readable name, description, and basic operating parameters of the plugin. They should be overridden in each plugin you write.
name()
Dump <name> Find <name> Annotate <name>
description()
type()
type()
will return ``dumper.''
init()
The following methods give the plugin access to the environment, including the gbrowse page settings, the sequence features database, and the plugin's own configuration settings.
These methods do not generally need to be overridden.
configuration()
See CONFIGURATION METHODS for instructions on how to create and maintain the plugin's persistent configuration information.
The recommended use for this object is to recover plugin-specific settings from the gbrowse configuration file. These can be defined by the gbrowse administrator by placing the following type of stanza into the gbrowse config file:
[GOSearch:plugin] traverse_isa = 1 use_server = http://amigo.geneontology.org
``GOSearch'' is the package name of the plugin, and the ``:plugin'' part of the stanza name tells gbrowse that this is a plugin-private configuration section.
You can now access these settings from within the plugin by using the following idiom:
my $browser_config = $self->browser_config; my $traverse_isa = $browser_config->plugin_setting('traverse_isa'); my $server = $browser_config->plugin_setting('use_server');
This facility is intended to be used for any settings that should not be changed by the end user. Persistent user preferences should be stored in the hash returned by configuration().
All plugins that act as feature dumpers should override one or more of the methods described in this section.
dump($segment)
As described in the Bio::Das::SegmentI manpage, the segment object
represents the region of the genome currently on display in the
gbrowse ``detail'' panel. You may call its seq()
method to return the
sequence as a string, or its features()
method to return a list of
all features that have been annotated onto this segment of the
genome.
At the time that dump()
is called, gbrowse will already have set up
the HTTP header and performed other initialization. The dump()
method merely needs to begin printing output using the appropriate
MIME type. By default, the MIME type is text/plain, but this can be
changed with the mime_type()
method described next.
The following trivial example shows a dump()
method that prints the
name and length of the segment:
sub dump { my $self = shift; my $segment = shift; print "name = ",$segment->seq_id,"\n"; print "length = ",$segment->length,"\n"; }
All finder plugins will need to override one or more of the methods described in this section.
find()
method will be passed a Bio::Das::SegmentI segment
object, as described earlier for the dump()
method. Your code should
search the segment for features of interest, and return an arrayref
of Bio::SeqFeatureI objects (see the Bio::SeqFeatureI manpage).
These synthetic feature objects should indicate the position, name
and type of the features found.
Depending on the type of find you are performing, you might search
the preexisting features on the segment for matches, or create your
own features from scratch in the way that the annotator plugins do.
You may choose to ignore the passed segment and perform the search
on the entire database, which you can obtain using the database()
method call.
To create features from scratch I suggest you use either Bio::Graphics::Feature, or Bio::SeqFeature::Generic to generate the features. See their respective manual pages for details, and the OligoFinder.pm plugin for an example of how to do this.
If the plugin requires user input before it can perform its task,
find()
should return undef. Gbrowse will invoke configure_form()
followed by reconfigure()
in order to prompt the user for input. If
nothing is found, the plugin should return an empty list. The
following is an example of how to prompt the user for input -- in
this case, a gene ontology term:
sub find { my $self = shift; my $segment = shift; # we ignore this! my $config = $self->configuration; my $query = $config->{query} or return undef; # PROMPT FOR INPUT my $database = $self->database; my @features = $database->features(-attributes=>{GO_Term => $query}); return \@features; }
sub configure_form { my $self = shift; return "Enter a GO Term: " . textfield(-name=>$self->config_name('query')); }
sub reconfigure { my $self = shift; my $config = $self->configuration; $config->{query} = $self->config_param('query'); }
See the sections below for more description of the configure_form()
and reconfigure()
methods.
NOTE: If you need to use auxiliary files like BLAST files, you can store the location of those files in the gbrowse .conf file under the stanza [YourPlugin:plugin]:
[YourPlugin:plugin] blast_path = /usr/local/blast/databases
sub find { my $self = shift; my $segment = shift; # ignored my $blast_path = $self->browser_config->plugin_setting('blast_path'); # etc etc etc }
All annotator plugins will need to override the method described in this section.
annotate($segment)
annotate()
method will be invoked with a Bio::Das::SegmentI
segment representing the region of the genome currently on view in
the gbrowse detail panel. The method should create one or more
Bio::Graphics::Feature objects and add them to a
Bio::Graphics::FeatureFile feature set. The latter acts as a
container for a set of sequence features.
The reason that annotate()
returns a Bio::Graphics::FeatureFile
rather than an array of features the way that find()
does is because
Bio::Graphics::FeatureFile also allows you to set up how the
features will be rendered; you can define tracks, assign different
feature types to different tracks, and assign each feature type a
glyph, color, and other options.
See the Bio::Graphics::FeatureFile manpage for details, and the RestrictionAnnotator.pm plugin for an example.
All annotator plugins will need to override the method described in this section.
highlight($feature)
highlight()
method will be invoked with a Bio::Das::FeatureI
object representing one of the features currently being rendered. The
method must either return a color name or undef. In the former case,
the feature will be rendered on top of a rectangular background of the
indicated color. In the latter case no highlighting will be applied.
See Bio::Graphics::Panel for a list of valid color names.
See the AttributeHiliter plugin for an example.
All filter plugins will need to override/implement the method described in this section.
name()
method must return the name (stanza) of the track which
should be filtered.
See the FilterTest plugin for an example.
The following methods can be called to retrieve data about the environment in which the plugin is running. These methods are also used by gbrowse to change the plugin state.
config_defaults()
You will wish to implement this method if the plugin has user-modifiable settings.
configure_form()
It is highly recommended that you use the CGI module to generate the fill-out form. In order to avoid clashing with other parts of gbrowse, plugin fill-out forms must respect a namespacing convention in which the name of each form field is preceded by the plugin package name and a dot. The package name is the last component of the plugin's package; for example ``GoSearch'' is the package name for Bio::Graphics::Browser::Plugin::GoSearch. To represent the ``query'' field of the plugin named ``GOSearch'', the text field must be named ``GOSearch.query''.
To make this easier to do right, the Plugin module provides a method
named config_name()
which will add the prefix for you. Here is how
to use it with the ``query'' example:
$html .= textfield(-name => $self->config_name('query'));
reconfigure()
configure_form()
method, you must also implement
a reconfigure()
method. This method is called after the user submits
the form and should be used to integrate the form values with the
current configuration.
Remember that the form fields are namespaced. You may recover them
using the CGI param()
method by preceding them with the proper
prefix. To make this easier to manage, this module provides a
config_param()
method that manages the namespaces transparently.
Here is a working example:
sub reconfigure { my $self = shift; my $current_configuration = $self->configuration; $current_configuration->{query} = $self->config_param('query'); }
All this does is to retrieve the current configuration by calling
the configuration()
method. The value of the ``query'' key is then
replaced by a fill-out form parameter named ``query'', using
config_param()
instead of the more familiar CGI module's param()
function.
the Bio::Graphics::Browser manpage
Lincoln Stein <lstein@cshl.org>.
Copyright (c) 2003 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.