METHODS
The remainder of this document describes the methods available to the programmer.new()
my $browser = Legacy::Graphics::Browser->new();
Create a new Legacy::Graphics::Browser object. The object is initially empty. This is done automatically by gbrowse.
url_label()
my $url_label = $browser->url_label($yucky_url);
Creates a label.alias for URL strings starting with 'http' or 'ftp'. The last word (following a '/') in the url is used for the label. Returns a string ``url:label''.
read_configuration()
my $success = $browser->read_configuration('/path/to/gbrowse.conf');
Parse the files in the gbrowse.conf configuration directory. This is done automatically by gbrowse. Returns a true status code if successful.
$conf_dir = dir()
Returns the directory path that this config is attached to.sources()
@sources = $browser->sources;
Returns the list of symbolic names for sources. The symbolic names are derived from the configuration file name by:
1) stripping off the .conf extension. 2) removing the pattern "^\d+\."
This means that the configuration file ``03.fly.conf'' will have the symbolic name ``fly''.
source()
$source = $browser->source; $source = $browser->source($new_source);
Sets or gets the current source. The default source will the first one found in the gbrowse.conf directory when sorted alphabetically.
If you attempt to set an invalid source, the module will issue a warning and will return undef.
setting()
$value = $browser->setting(general => 'stylesheet');
$value = $browser->setting(gene => 'fgcolor');
$value = $browser->setting('stylesheet');
The setting() method returns the value of one of the current source configuration settings. setting() takes two arguments. The first argument is the name of the stanza in which the configuration option is located. The second argument is the name of the setting. Stanza and option names are case sensitive, with the exception of the ``general'' section, which is automatically folded to lowercase.
If only one argument is provided, then the ``general'' stanza is assumed.
Option values are folded in such a way that newlines and tabs become single spaces. For example, if the ``default features'' option is defined like this:
default features = Transcripts
Genes
Scaffolds
Then the value retrieved by
$browser->setting('general'=>'default features');
will be the string ``Transcripts Genes Scaffolds''. Note that it is your responsibility to split this into a list. I suggest that you use Text::Shellwords to split the list in such a way that quotes and escapes are preserved.
Because of the default, you could also fetch this information without explicitly specifying the stanza. Combined with shellwords gives the idiom:
@defaults = shellwords($browser->setting('default features'));
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].
plugin_setting()
$value = = $browser->plugin_setting("option_name");
When called in the context of a plugin, returns the setting for the requested option. The option must be placed in a [PluginName:plugin] configuration file section:
[MyPlugin:plugin] foo = bar
Now within the MyPlugin.pm plugin, you may call $browser->plugin_setting('foo') to return value ``bar''.
db_settings()
@args = $browser->db_settings;
Returns the appropriate arguments for connecting to Bio::DB::GFF. It can be used this way:
$db = Bio::DB::GFF->new($browser->dbgff_settings);
gbrowse_root()
$root = $browser->gbrowse_root()
Return the setting of ``gbrowse root''
relative_path()
$relative_path = $browser->relative_path('gbrowse.css');
Add the setting of ``gbrowse root'' to the indicated path, if relative. Otherwise pass through unchanged.
relative_path_setting()
$relative_path = $browser->relative_path_setting('stylesheet');
Like relative_path(), but works on a named setting rather than an actual path or directory.
version()
$version = $browser->version
This is a shortcut method that returns the value of the ``version'' option in the general section. The value returned is the version of the data source.
description()
$description = $browser->description
This is a shortcut method that returns the value of the ``description'' option in the general section. The value returned is a human-readable description of the data source.
$time = $browser->remember_settings_time
Return the relative time (in CGI ``expires'' format) to maintain information about the current page settings, including plugin configuration.$time = $browser->remember_source_time
Return the relative time (in CGI ``expires'' format) to maintain information on which source the user is viewing.$language = $browser->language([$new_language])
Get/set an associated Legacy::Graphics::Browser::I18n language translation object.$french = $browser->tr($english)
Translate message into currently-set language, with fallback to POSIX, via associated Legacy::Graphics::Browser::I18n language translation object.$section_setting = $browser->section_setting($section_name)
Returns ``open'' ``closed'' or ``off'' for the named section. Named sections are:
instructions search overview details tracks display add tracks
labels()
@track_labels = $browser->labels
This method returns the names of each of the track stanzas, hereinafter called ``track labels'' or simply ``labels''. These labels can be used in subsequent calls as the first argument to setting() in order to retrieve track-specific options.
default_labels()
@default_labels = $browser->default_labels
This method returns the labels for each track that is turned on by default.
label2type()
@feature_types = $browser->label2type($label,$lowres);
Given a track label, this method returns a list of the corresponding sequence feature types in a form that can be passed to Bio::DB::GFF. The optional $lowres flag can be used to tell label2type() to select a set of features that are suitable when viewing large sections of the sequence (it is up to the person who writes the configuration file to specify this).
type2label()
$label = $browser->type2label($type);
Given a feature type, this method translates it into a track label.
feature2label()
$label = $browser->feature2label($feature [,$length]);
Given a Bio::DB::GFF::Feature (or anything that implements a type() method), this method returns the corresponding label. If an optional length is provided, the method takes semantic zooming into account.
citation()
$citation = $browser->citation($label)
This is a shortcut method that returns the citation for a given track label. It simply calls $browser->setting($label=>'citation');
width()
$width = $browser->width
This is a shortcut method that returns the width of the display in pixels.
header()
$header = $browser->header;
This is a shortcut method that returns the header HTML for the gbrowse page.
footer()
$footer = $browser->footer;
This is a shortcut method that returns the footer HTML for the gbrowse page.
config()
$config = $browser->config;
This method returns a Bio::Graphics::FeatureFile object corresponding to the current source.
mtime()
$time = $browser->mtime()
This method returns the modification time of the config file for the current source.
path()
$path = $browser->path()
This method returns the file path of the config file for the current source.
make_link()
$url = $browser->make_link($feature,$panel,$label)
Given a Legacy::SeqFeatureI object, turn it into a URL suitable for use in a hypertext link. For convenience, the Legacy::Graphics panel is also provided. If $label is provided, then its link overrides the type of the feature.
render_panels()
$panels = $browser->render_panels(%args);
Render an image and an image map according to the options in %args. In a Returns a two-element list. The first element is a URL that refers to the image which can be used as the SRC for an <IMG> tag. The second is a complete image map, including the <MAP> and </MAP> sections.
The arguments are a series of tag=>value pairs, where tags are:
Argument Value
segment A Bio::DB::GFF::Segment or
Legacy::Das::SegmentI object (required).
tracks An arrayref containing a series of track
labels to render (required). The order of the labels
determines the order of the tracks.
options A hashref containing options to apply to
each track (optional). Keys are the track labels
and the values are 0=auto, 1=force no bump,
2=force bump, 3=force label, 4=expanded bump.
feature_files A hashref containing a series of
Bio::Graphics::FeatureFile objects to be
rendered onto the display (optional). The keys
are labels assigned to the 3d party
features. These labels must appear in the
tracks arrayref in order for render_panels() to
determine the order in which to render them.
do_map This argument is a flag that controls whether or not
to generate the image map. It defaults to false.
do_centering_map This argument is a flag that controls whether or not
to add elements to the image map so that the user can
center the image by clicking on the scale. It defaults
to false, and has no effect unless do_map is also true.
title Add specified title to the top of the image.
noscale Suppress the scale
flip Flip coordinates left to right
hilite_callback Callback for performing hilighting
image_and_map This argument will cause render_panels to emulate
the legacy method image_and_map() and return a
GD::Image object and a 'boxes' array reference rather
than rendered html. This argument applies only to composite
(non-draggable) panel images.
Any arguments names that begin with an initial - (hyphen) are passed through to Bio::Graphics::Panel->new() directly
Any arguments names that begin with an initial - (hyphen) are passed through to Bio::Graphics::Panel->new() directly
drag_and_drop()
Return true if drag_and_drop tracks should be enabled on this datasource. Looks at the ``drag and drop'' option and also consults a series of user agents known to support drag_and_drop.generate_panels()
Generate the GD object and the imagemap and returns a hashref in the format
$results->{track_label} = {image=>$uri, map=>$map_data, width=>$w, height=>$h, file=>$img_path)
If the ``drag_n_drop'' argument is false, then returns a single track named ``__all__''.
Arguments: a key=>value list
'section' Section type to draw; one of ``overview'', ``region'' or ``detail''
'segment' A feature iterator that responds to next_seq() methods
'feature_files' A hash of Bio::Graphics::FeatureFile objects containing 3d party features
'options' An hashref of options, where 0=auto, 1=force no bump, 2=force bump, 3=force label
4=force fast bump, 5=force fast bump and label
'drag_n_drop' Force drag-and-drop behavior on or off
'limit' Place a limit on the number of features of each type to show.
'labels' List of named tracks, in the order in which they are to be shown
'tracks' List of named tracks, in the order in which they are to be shown (deprecated)
'label_scale' If true, prints chromosome name next to scale
'title' A title for the image
'noscale' Suppress scale entirely
'image_class' Optional image class for generating SVG output (by passing GD::SVG)
'cache_extra' Extra cache args needed to make this image unique
'scale_map_type' If equal to ``centering_map'' adds an imagemap to the ruler that recenters.
If equal to ``interval_map'' creates an imagemap that jumps to a small interval in map
'featurefile_select' callback for selecting features to be rendered from a featurefile onto a panel
any arguments that begin with an initial - (hyphen) are passed through to Panel->new
directly
add_feature_file
Internal use: render a feature file into a panelgenerate_image
($url,$path) = $browser->generate_image($gd)
Given a GD::Image object, this method calls its png() or gif() methods (depending on GD version), stores the output into the temporary directory given by the ``tmpimages'' option in the configuration file, and returns a two element list consisting of the URL to the image and the physical path of the image.
new_hits_on_overview()
$hashref = $browser->hits_on_overview($db,$hits,$options,$keyname);
This method is used to render a series of genomic positions (``hits'') into a graphical summary of where they hit on the genome in a segment-by-segment (e.g. chromosome) manner.
The first argument is a Bio::DB::GFF (or Bio::DasI) database.
The second argument is an array ref containing one of:
1) a set of array refs in the form [ref,start,stop,name], where
name is optional.
2) a Bio::DB::GFF::Feature object
3) a Legacy::SeqFeatureI object.
The third argument is the page settings hash from gbrowse.
The fourth option is the key to use for the ``hits'' track.
The returned HTML is stored in a hashref, where the keys are the reference sequence names and the values are HTML to be emitted.
error()
my $error = $browser->error(['new error']);
Retrieve or store an error message. Currently used to pass run-time errors involving uploaded/remote annotation files.
create_panel_args()
@args = $self->create_panel_args($section,$args);
Return arguments need to create a Bio::Graphics::Panel. $section is one of 'detail','overview', or 'region' $args is a hashref that contains the keys:
keystyle title image_class postgrid background
create_track_args()
@args = $self->create_track_args($label,$args);
Return arguments need to create a Legacy::Graphics::Track. $label is a config file stanza label for the track.
segment_coordinates()
($start,$stop,$flip) = $self->segment_coordinates($segment,$flip)
Method to correct for rare case in which start and stop are flipped.
create_cache_key()
$cache_key = $self->create_cache_key(@args)
Create a unique cache key for the given args.
get_cached_panel()
($image_uri,$map,$width,$height) = $self->get_cached_panel($cache_key)
Return cached image url, imagemap data, width and height of image.
($region_sizes,$region_labels,$region_default) = $config->region_sizes()
Return information about the region panel:
1. list of valid region sizes (@$region_sizes) 2. mapping of size to label (%$region_labels) 3. default size ($region_default)
AUTHOR
Lincoln Stein <[email protected]>.Copyright (c) 2001 Cold Spring Harbor Laboratory
This package and its accompanying libraries is free software; you can redistribute it and/or modify it under the terms of the GPL (either version 1, or at your option, any later version) or the Artistic License 2.0. Refer to LICENSE for the full license text. In addition, please see DISCLAIMER.txt for disclaimers of warranty.