Linking in to Ensembl

URL structure

URLs for Ensembl views take the format:

http://www.ensembl.org/species/section/page?g=gene;t=transcript;r=seq_region:start-end

Location-based views

Any combination of the gene, transcript and genomic region may be specified. For example, the following all take the user to the genomic region surrounding the human gene BRCA1:

Feature-based views

Views based on a gene, transcript or variation need the parameter of that type in their URL - a location alone is insufficient:

Customising via links

Many of the customisation options available to users of the website in the Control Panel can be manipulated using specially constructed URLs. This allows configuration settings to be shared with colleagues, for example to highlight a particular data track. This includes:

  • Configuring options for a page
  • Configuring a panel/image (changing the way tracks are rendered)
  • Attaching external DAS or UCSC-style data without using the Control Panel

These are accomplished in a similar, systematic way. Extra parameters are appended to the URL for the relevant page:

context=key=value

Or when setting multiple values:

context=key1=value1,key2=value2,key2=value2

Or when setting multiple different types of parameter:

context1=key1=value1,key2=value2,key2=value2;context2=key3=value3

Global Page Settings

Global page settings are changed using the config key. For example, to turn off the top image on Location > Region in detail:

config=show_top_panel=no

Appending this to the URL for the Region in detail page, the final URL is:

http://www.ensembl.org/Homo_sapiens/Location/View?r=1:1000-2000;config=show_top_panel=no

To link directly to the Exon Intron markup panel (Transcript > Exons), to show full introns, only 60bp flanking sequence AND turn the display to be 60bp wide:

http://www.ensembl.org/Homo_sapiens/Transcript/Exons?t=ENST00000309255;config=flanking=60,seq_cols=60,fullseq=yes

Configuring Panels

To change configuration for an individual panel add a parameter referring to the panel:

  • Location > Region in detail: contigviewtop and contigviewbottom
  • Location > Region overview: cytoview

Options are again specificed in a comma separated list, where the left hand side of each "=" is the name of the track, and the right hand side is the name of the "renderer" to use - the latter depends on the type of track.

Track names

Track names are systematically named. The following example identifies a track with Ensembl transcripts from the core Ensembl database:

transcript_core_ensembl

Renderers

Renderers depend on the type of track:

  • Transcripts: transcript_label, transcript_nolabel, collapsed_label, collapsed_nolabel or off
  • Alignment features: normal, half_height, stack, unlimited, ungrouped or off

Example - configure a track

To collapse the Ensembl genes track down to a single line per gene AND turn off the top panel in Location > Region in detail:

http://www.ensembl.org/Homo_sapiens/Location/View?g=ENSG00000012048;contigviewbottom=transcript_core_ensembl=collapsed_nolabel;config=show_top_panel=no

Attaching External Data

To attach DAS or UCSC-style URL data, follow the procedure above for configuring the appropriate panel, using special track names to identify the data source. These special names are of the format:

type:source

Where type is either of das or url, and source is the location of the external data.

Renderers

Renderers depend on the type of track:

  • URL data: the same as for alignment tracks (see above), or for wiggle/graph data, either off or tiling.
  • DAS tracks: normal (use the DAS server's stylesheet), labels (force display of labels), nolabels (hide labels) and off.

Examples - attach external data

To attach an example data file by URL and display the features with the default renderer:

http://www.ensembl.org/Homo_sapiens/Location/View?g=ENSG00000130544;contigviewbottom=url:http://www.ensembl.org/info/website/upload/sample_files/example.bed

To attach an example data file by URL and display the features in a half_height style:

http://www.ensembl.org/Homo_sapiens/Location/View?g=ENSG00000130544;contigviewbottom=url:http://www.ensembl.org/info/website/upload/sample_files/example.bed=half_height

Note on bedGraph format If attaching a bedGraph file, please add the parameter 'format=bedGraph' to the URL, e.g.

http://www.ensembl.org/Homo_sapiens/Location/View?g=ENSG00000012048;contigviewbottom=url:http://www.abcd.edu/myprojects/data.bed=tiling;format=bedGraph

IMPORTANT: You must encode any = & or ; characters in your URL for the attachment to work correctly.


To attach the Ensembl transcripts DAS source and display the features according to the server's instructions (stylesheet):

http://www.ensembl.org/Mus_musculus/Location/View?g=ENSMUSG00000049878;r=4:120817978-120887689;contigviewbottom=das:http://das.sanger.ac.uk/das/ikmc_products=normal

To attach a DAS source from the DAS registry (in this case human SNPs from ASTD) and force the display of labels:

http://www.ensembl.org/Homo_sapiens/Location/View?g=ENSG00000012048;contigviewbottom=das:http://www.dasregistry.org/das/sources/DS_560=labels

To attach a text-based DAS source (one which will not be displayed on an image):

http://www.ensembl.org/Homo_sapiens/Gene/Summary?db=core;g=ENSG00000139618;r=13:32889611-32973347;t=ENST00000380152;das=http://www.genenames.org/das/HGNC/

Important Note

It is only possible to add a DAS track that is self-configuring. That is, it provides all of the information Ensembl needs to query it automatically via the sources or dsn command. This behaviour is by design. See setting up a DAS server for more details.

Due to a limitation of the website, it is currently only possible to attach a DAS source to a panel (i.e. a track on an image) and not to a page. Thus non-positional (text-based) DAS sources such as those annotating genes cannot be attached in this manner. For more information on the different types of DAS source, see how Ensembl uses DAS.