Legacy...Browser(3pm)

📦
version 2.56 · 5 versions
, in ubuntu questing

💖 Legacy...Browser(3pm) — User Contributed Perl Documentation 💖

🌸 NAME 🌸

Legacy::Graphics::Browser-- Old version, deprecated

Old version, deprecated, bestie. It's giving vintage. Still iconic, still here, still doing the most.

✨ METHODS ✨

The remainder of this document describes the methods available to the programmer. Periodt.

💅 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, so like, you don't have to lift a finger. Slay.

🎀 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". It's giving URL-to-label glow-up, no cap.

🌸 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. Lowkey essential.

🦋 dir() 🦋

$conf_dir = dir()

Returns the directory path that this config is attached to. Simple. Clean. Iconic.

✨ 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". The way that 03.fly.conf becomes fly is honestly main character energy.

💜 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. So don't try it unless you want that warning energy. 💀

🌈 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'));

Obsessed with this idiom, honestly.

💖 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]. It's giving fallback chain realness.

🫶 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". Plugins could never be boring, fr fr.

🔥 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". Royalty behavior.

🌟 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. No notes.

🧚 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. The way that it's basically the same but different? Love that for us.

🍓 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. Shortcut queen.

💀 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. Human-readable? We love to see it.

⏰ remember_settings_time ⏰

$time = $browser->remember_settings_time

Return the relative time (in CGI "expires" format) to maintain information about the current page settings, including plugin configuration.

⏳ remember_source_time ⏳

$time = $browser->remember_source_time

Return the relative time (in CGI "expires" format) to maintain information on which source the user is viewing.

🌍 language([$new_language]) 🌍

$language = $browser->language([$new_language])

Get/set an associated Legacy::Graphics::Browser::I18n language translation object. Multilingual icon behavior.

🗣️ tr($english) 🗣️

$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($section_name) 📑

$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. Track labels are the moment.

🌟 default_labels() 🌟

@default_labels = $browser->default_labels

This method returns the labels for each track that is turned on by default. Defaults are valid.

🧬 label2type($label,$lowres) 🧬

@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). Semantic zooming? We stan.

🔁 type2label($type) 🔁

$label = $browser->type2label($type);

Given a feature type, this method translates it into a track label. Reverse uno card energy.

🧵 feature2label($feature [,$length]) 🧵

$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($label) 📚

$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');. Cite your sources, bestie.

📏 width() 📏

$width = $browser->width

This is a shortcut method that returns the width of the display in pixels. Pixels are giving measurements.

$header = $browser->header;

This is a shortcut method that returns the header HTML for the gbrowse page.

$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.

$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. Link me up, bestie.

🖼️ render_panels(%args) 🖼️

$panels = $browser->render_panels(%args);

Render an image and an image map according to the options in %args. 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:

  • 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()

Returns true if drag_and_drop tracks should be enabled on this datasource. Bestie, it peeks at the "drag and drop" option and also consults a whole little roster of user agents that are known to support drag_and_drop. She does her research. 💅

🦋 generate_panels()

Generates the GD object and the imagemap, then hands you back a hashref shaped like this:

$results->{track_label} = {image=>$uri, map=>$map_data, width=>$w, height=>$h, file=>$img_path)

If the "drag_n_drop" argument is false, then it returns a single track named "__all__". Just the one. Lowkey minimal of it.

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 panel

💖 generate_image

  ($url,$path) = $browser->generate_image($gd)

Given a GD::Image object, this method calls its png() or gif() methods (depending on GD version — she adapts, she's flexible 😌), 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 (we call them "hits") into a graphical summary of where they hit on the genome, in a segment-by-segment (e.g. chromosome) manner. It's giving map-of-the-whole-vibe. 🗺️

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. Periodt. 💅

🫶 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. Not me handling your drama for you bestie 😭

⭐ 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 the rare case in which start and stop are flipped. She fixes it. Iconic behavior honestly. 🔥

🍓 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)

👀 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 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.

and that's a wrap bestie!! 🎀 this whole page dropped as part of perl v5.40.0 on 2024-10-20, filed under Legacy...Browser(3pm) in the User Contributed Perl Documentation. go forth and render, queen 💅✨

📦 where this page comes from