U.S. flag

An official website of the United States government

NCBI Graphical Sequence Viewer Embedding API

Sequence Viewer Revision: 3.30 and newer

Contents


Introduction

The NCBI Graphical Sequence Viewer (SV) is a general purpose tool for viewing biological sequence data. It can be embedded in a wide variety of web pages and with a large number of options. This document serves as a launching point to understand how to embed the Sequence Viewer in any context. For purposes of standardization in this document, all links presented include the common refrain http://www.ncbi.nlm.nih.gov .

If you have questions or need help, please contact us.

Additional documentation can be found at http://www.ncbi.nlm.nih.gov/tools/sviewer/.

A tutorial with examples is available here and you can get a list of URL parameters here.

Including Sequence Viewer on a web page

The Sequence Viewer is implemented using an ExtJS JavaScript library.

  1. There is no need to declare or load ExtJS css files or js scripts. SV dynamically loads everything it needs from the www.ncbi.nlm.nih.com website. On the other hand if ExtJS scripts are declared/loaded before sviewer.js declaration, SV omits their loading to allow an embedding application to use a specific edition of the library. The following example demonstrate how to declare SV script:

    <script type=”text/javascript” src=”http://www.ncbi.nlm.nih.gov/projects/sviewer/js/sviewer.js”></script>

  2. If an embedding application does not create SV instances dynamically the following inlining of Sequence Viewer script (includes id="autoload”) allows the SV application to find appropriate SeqViewerApp declarations and create instances automatically (with data loading):

    <script type=”text/javascript” src=”http://www.ncbi.nlm.nih.gov/projects/sviewer/js/sviewer.js” id="autoload”></script>

    SeqViewerApp must be declared as <div> tag with class='SeqViewerApp' and one <a> tag where href attribute containing SViewer parameters. An example is:

    <div id='some-id' class='SeqViewerApp'> <a href='?embedded=true&id=…'><a> </div>

    You do not use this method if the Sequence Viewer div is initially hidden. Use the method from point 3 to instantiate Sequence Viewer dynamically.

  3. If an embedding application needs to create SV instances dynamically the following example demonstrates how to declare them and initiate SV instances creation and loading manually (SV script declaration from point 3):

    <div id=’sv1’></div> ... <script type='text/javascript'> SeqViewOnReady(function() { var app = new SeqView.App(‘sv1’); app.load(‘embedded=true&id=…’); } ); </script>

    In this case the application may not use class name (or any) for the div.

  4. Function SeqViewOnReady(callback, [scope]) is designed to prevent SV usage before SeqView class is initialized.

    Parameters:

    callback - user callback function scope - callback function scope (if necessary)

For a video tutorial please watch the following video:

Embed the NCBI Sequence Viewer into Your Pages Embed the NCBI Sequence Viewer into Your Pages

Including Sequence Viewer in an iFrame

How to obtain code of the Sequence Viewer for embedding

The suggested workflow is:

  1. Pick a molecule of interest, which illustrates the case. Use GDV or enter your accession at: https://www.ncbi.nlm.nih.gov/projects/sviewer/
  2. Find and zoom to the region of interest (it could be a gene or a specific mutation).
  3. Add markers (if desired) to annotate your region.
  4. Pick tracks of interest using the track configuration panel
  5. Change track display options if desired.
  6. Use the “Link to This View” option to show code.

link to this page dialog

The resulting code will contain parameters that capture the sequence molecule, location, and track and marker configuration of your view.

There are two types of embedding code. The first option, ‘Embed code for IFRAME’, can be used as is to embed the Sequence Viewer by itself as an IFRAME. The second option,‘Whole page example,’ can be used to embed the Sequence Viewer as a part of your page. This option has both the script in the HEAD element and DIV element with parameters.

How to include Sequence Viewer in a web page in an <iframe>

The NCBI Sequence Viewer can be embedded as an IFRAME. When configured, Sequence Viewer will automatically resize the enclosing iframe vertically to avoid scroll bars.

To use iframe embedding, add this to your page:

<iframe id="sviframe" src="/projects/sviewer/embedded_iframe.html?iframe=sviframe&id=nt_011515" width="900">

Please note :

  1. iframe id can be arbitrary, and it should be passed to the source URL as parameter 'iframe' (“sviframe” in the example above)
  2. iframe content page (“/projects/sviewer/embedded_iframe.html” in the example) should belong to the same domain as the main page (take the page and save it on your server)
  3. iframe should satisfy the minimal width requirement of 800 pixels to accommodate the pop-up interface elements of the Sequence Viewer

There can be issues using multiple libraries that reset style sheets. If you have any issues with the style sheets used in ExtJS/Sequence Viewer, i.e. Sequence Viewer doesn’t look right, try adding this directive:

<link rel="stylesheet" type="text/css" href="http://www.ncbi.nlm.nih.gov/projects/sviewer/css/sv-cleanup.css">

Sequence Viewer parameters

Parameters may be passed to Sequence Viewer by putting them in the included <a href=''> link tag within the Sequence Viewer <div> tag.

Base parameters:

The color used for highlighting can be changed per track using the track specific highlights_color parameter.

  1. embedded={false, true, minimal, panorama} – removes some components that are not needed in embedded mode (panorama view, some links) if 'minimal' value is passed then only a bare-bone image is shown with buttons-only tool bar and without panel header. If ‘panorama’ is passed then only the top panel, the Overview panel, is shown. Default is false. This is a required parameter for an embedded version of SV.
  2. id=<string> - GI of a sequence to show. Required parameter.1,2,3
  3. noviewheader={true,false} – removes header from a sequence view. This parameter only relevant when embedded=true. Default is false. Optional parameter.
  4. v=<view ranges> - sets a specified visible range to a graphical panel. If not specified the whole sequence is shown. (Example: v=1000:6000,100k:2m, 100K-2M, 100k..2M). Optional parameter.
  5. mk=<position or range>|<marker name>|<color in RGB hex> Use the mk parameter to set a marker at a position or on a range of positions. Multiple markers can be set by separating the each entry with a comma. Use an exclamation point ("!") after an entry to lock the marker. A locked marker is fixed in the graphical view. The name and color parameters are optional . Examples:

    mk=1000 puts an unlocked marker with default color and name at position 1000 mk=1000:2000 puts an unlocked marker with default color and name on the range 1000-2000 mk=1000:2000|TestMarker puts an unlocked marker with default color and the name "TestMarker" on the range 1000-2000 mk=1000:2000|TestMarker|00ff00 puts an unlocked marker with color 0x00ff00 and the name "TestMarker" on the range 1000-2000 mk=1000:2000|TestMarker|00ff00,3000:4000|TestMarker2|80ff10 puts an unlocked marker with color 0x00ff00 and the name "TestMarker" on the range 1000-2000 and another unlocked marker with color 0x80ff10 and the name "TestMarker2" on the range 3000-4000. mk=1000:2000|TestMarker|00ff00,3000:4000|TestMarker2|80ff10! - same as above with a lock on "TestMarker2". Note: Special characters in marker names must be escaped properly usually with a \ prepended.

  6. toolbar = <nspztcrhgmd> Specifies which options are present on the toolbar. This parameter is optional and if omitted, all options are shown. If any options are specified, all other options must be opted in.

    • n - Name button
    • s – Search field
    • p - Panning buttons
    • z - Zoom slider & buttons
    • t - Tools menu
    • c - Configure menu
    • r - Reload button
    • h - Help button
    • g - Gene render mode button (switches on "Show All" mode for gene tracks features)
    • m - Switch mode (Slim/Normal) button
    • d - Download menu
  7. origin=<sequence position> - Set the sequence origin. Optional parameter. (Example: origin=5000)

  8. flip=true - Flips the strand. Default is false. (Example: flip=true or flip=false) . Optional parameter.
  9. strand=true - Synonym for flip parameter. Optional parameter
  10. assm_context=GC Assembly accession – Defines the assembly accession used for retrieving track configuration for a given application context from track manager service. Optional parameter. It is required only when using SViewer inside a genome browser that uses track manager service to manager data tracks.
  11. app_context=Unique and preregistered genome browser application name – It differs from ‘appname’ below. ‘app_context’ is preregistered in track manager service. A combination of ‘app_context’ and ‘assm_context’ define a set of data tracks to be shown in the given application context. Optional parameter. It is required only when using SViewer inside a genome browser that uses track manager service to manager data tracks.
  12. appname=<string> - Defines the name of the client calling the application. This is an optional parameter used in storing a user’s configuration settings; we recommend that all developers supply an application name. The name chosen should be unique; this name will appear in a cookie set in the user’s browser to indicate storage of configuration information. We strongly recommend that callers avoid using generic phrases like “gene” or “viewer”, and prepend a namespace (i.e., “NcbiPortalGene” or “XYZViewer”). If there are questions about what name to use, please contact the sequence viewer team. (sviewer-service AT ncbi.nlm.nih.gov) Example:

    <div id="SeqViewer0" class="SeqViewerApp"> <a href="?id=89161185&embedded=true&appname=testemb&v=1:247249719 &tracks=[key:graph_track,annots:NA0000016.1|]"></a> </div>

  13. multipanel={true, false} – permits or prohibits the use of multiple graphical panels in one Sequence Viewer instance. If not specified, it is default to 'true' in standalone mode and to 'false' in embedded mode.

  14. slim=<true> - Constitutes the set of initial modes for graphical panels. Slim Mode displays tracks without title bars. Default is false. This is an optional parameter. (Example:slim=true, false, true or slim=1,0,1)
  15. a. nopdf= {true, false} - Disables PDF printing option. Default is false. (Example: nopdf=true or nopdf=false). This is an optional parameter.
    b. notrdata=true - Removes option Download Track Data from Download menu. Default is false.
  16. nosavetracks - Disables menu item "Save current tracks" in "My NCBI Track Collections" menu.
  17. highlights_color= is optional. When specified, it defines the color to be used for highlights in all tracks. Accepted formats:

    • A named color, such as "red", "blue", "salmon", etc. Supports HTML color names
    • HTML-format colors, such as "#f0f0dd", or "f0f0dd". These are accepted with or without the leading '#'. The color used for highlighting can also be changed per track using the track specific highlights_color parameter.

    Sample URL parameters: id=NC_000005.10&minheight=220&client=seqviewer&width=3999&view_width=970&from=68710561&len=1485030&assm_context= GCF_000001405.33&label=Default&color=Color&decor=Default&spacing=Normal&content=Details&tracks=[key:gene_model_track,name:Genes,display_name:Track1,id:STD14,category:Genes,annots:Unnamed,Options: MergeAll,SNPs:false,CDSProductFeats:false,highlights:GeneID\:5884, highlights_color:red , ShowLabelsForAllFeatures:false,NtRuler:true,AaRuler:false]key:gene_model_track,name:T577824,display_name: Track2,id:T577824,category:Genes,subcategory:NCBI,dbname:SADB,annots:NA000077605.1,highlights: GeneID\:100506658,Options:MergeAll,SNPs:false,CDSProductFeats:false,ShowLabelsForAllFeatures:false, NtRuler:true,AaRuler:false]& highlights_color=blue In the sample above the global highlights_color parameter changes the highlighting color for all tracks to blue, the track specific highlights_color parameter overrides the color for the first track to red:

    highlights color sample

Advanced parameters:

  1. rid=<rid> - Option to load BLAST results stored as an RID. Optional parameter .4,5
  2. tracks=[<track1_descr>,<track2_descr>] - Specify tracks that should be rendered. Optional parameter. See Appendix A for examples.

Events sent by SV instance:

An application that uses SV can subscribe to events that SV will send in case of a user interaction with SV. Here is the list of supported events:

'panorama_image_loaded' - fired when panorama image is loaded to application ' 'graphical_image_loaded' - fired when graphical image is loaded to view 'marker_created' - fired when marker is created in view 'marker_deleted' - fired when marker is deleted in view 'feature_clicked' - fired when feature is clicked in view 'origin_changed' - fired when origin is changed for application 'strand_changed' - fired when strand is changed 'visible_range_changed' - fired when visible range is changed (for example, zoom or shift) 'configuration_changed' - fired when configuration is changed (for example, tracks are added)

The subscription object for any events is SViewer application (object SeqView.App). Every event has a reference to its source provided. Events related to particular view are provided with view object, others are provided with application object. Here is an example of use:

function initSviewerApp(sviewer){ sviewer.on({ 'visible_range_changed': function(view) { // event processing }, 'graphical_image_loaded': function(view) { // event processing }); }

Also SViewer application provides some number of access functions.

getApps() - returns the list of all applications on the current HTML page getTracks() - provides loaded tracks for particular application getConfiguration() - provides the configuration object for particular application

Example:

var app = SeqView.App.findAppByDivId(‘YOUR_SV_DIV_ID’); app.on({ visible_range_changed: function(view) { console.log(view.m_VisFromSeq + ' - ' + view.m_VisLenSeq); }, marker_created: function(marker) { … }, marker_deleted: function(marker) { … }, graphical_image_loaded: function(view) { … }, feature_clicked: function(view, feat) { … }, scope: this });

Examples:

<div style="padding:10px;"> <div id="sv1" class="SeqViewerApp" > <a href="?embedded=true&id=NC_003284&from=13598210&to=13599776"> </a> </div> </div>

Example1

<div style="padding:10px;"> <div id="sv1" class="SeqViewerApp" > <a href= "?embedded=minimal&id=NC_003284&from=13598210&to=13599776&mk=13598700:13598925|Marker1|008000"></a> </div> </div>

Example2

Example web pages:

  1. Embedding Sequence Viewer into a standalone web page. http://www.ncbi.nlm.nih.gov/projects/sviewer/embedded.html
  2. Embedding Sequence Viewer and collecting its events. The example includes controlled SeqView.App launch (via SeqViewOnReady function): http://www.ncbi.nlm.nih.gov/projects/sviewer/event_demo.html

Cross-domain embedding

Previously we recommended to set up redirecting scripts on the embedder's site. Now, as we support Internet standard CORS it is no longer needed.

Web tracks upload/embedding

There is a new ability allowing to add multiple user data items and assign them names through parameters to Sequence Viewer.

Before this only one item of each type (URL, Blast RID, or inline ASN.1 text) could be used, and track names were assigned automatically based on the data itself.

New parameter, 'tn' (short for Track Name) is introduced for this purpose. This parameter can be present several times and corresponds to the data item (url, rid, or data parameter) in the order of occurrence. E.g., if you have an RID and data file and would like to display them and assign these track names, the following syntax should be used:

http://www.ncbi.nlm.nih.gov/projects/sviewer/?id=NC_000001.10&url=https://ftp.ncbi.nlm.nih.gov/toolbox/gbench/samples/UCSCGenes_exon20.short.bed&url=https://ftp.ncbi.nlm.nih.gov/toolbox/gbench/samples/UCSCGenes_exon20.bed&tn=Some%20USCS%20genes&tn=Some%20other%20genes&v=660932:2480277

The same syntax works for embedding Sequence Viewer in your own pages:

<div id="some-id" <class="SeqViewerApp"> <a href="?embedded=true&id=NC_000001.10&url=https://ftp.ncbi.nlm.nih.gov/toolbox/gbench/samples/UCSCGenes_exon20.short.bed&url=https://ftp.ncbi.nlm.nih.gov/toolbox/gbench/samples/UCSCGenes_exon20.bed&tn=Some%20USCS%20genes&tn=Some%20other%20genes&v=660932:2480277"></a> </div>

The files used for 'url' parameter should be accessible through public HTTP or FTP.

If you'd like to name only the second data item, you ought to include empty track name parameter for the first item:

http://www.ncbi.nlm.nih.gov/projects/sviewer/?id=NC_000001.10&url=https://ftp.ncbi.nlm.nih.gov/toolbox/gbench/samples/UCSCGenes_exon20.short.bed&url=https://ftp.ncbi.nlm.nih.gov/toolbox/gbench/samples/UCSCGenes_exon20.bed&tn=&tn=Some%20other%20genes&v=660932:2480277

Same thing can be done with other data types, such as Blast RID:

http://www.ncbi.nlm.nih.gov/projects/sviewer/?id=NC_000001.10&url=https://ftp.ncbi.nlm.nih.gov/toolbox/gbench/samples/UCSCGenes_exon20.bed&rid=G9TDMFBP016&tn=Some%20external%20genes&tn=Some%20alignments&v=1570103:1594554

Unfortunately, Blast RID is valid for very short time - around 2 days, so to provide more permanent view for your data you can use Genome Workbench to read the data from RID, and export it as ASN.1 file:

http://www.ncbi.nlm.nih.gov/projects/sviewer/?id=NC_000001.10&url=https://ftp.ncbi.nlm.nih.gov/toolbox/gbench/samples/UCSCGenes_exon20.bed&url=https://ftp.ncbi.nlm.nih.gov/toolbox/gbench/samples/RID_G9TDMFBP016.asn&tn=Some%20external%20genes&tn=Some%20alignments&v=1570103:1594554

Sequence Viewer now supports two parameters with the same syntax but different behavior: url and url_reload

Parameter url uploads the target file once and uses it for visualization. If underlying data changes you have to change the file name as well, otherwise Sequence Viewer will keep showing the old data (until some potentially long timeout period expires). You file name naming scheme may need some versioning.

Parameter url_reload always tries to re-upload the file to check the content, which can introduce a processing delay. If you use this parameter you don't have to create a file name versioning but this mode will be slower as it needs to download the file every time.

SRA tracks embedding

An SRA track can be referenced in three different ways, by either using an SRR accession (e.g. SRR505885), or a NCBI Internal file path (e.g. /netmnt/traces04/sra2/SRR/001282/SRR1313308), or a URL (e.g. http://ftp-trace.ncbi.nlm.nih.gov/sra/sra-instant/reads/ByRun/sra/SRR/SRR131/SRR1313308/SRR1313308.sra).

The Sequence viewer accepts a comma-delimited list of SRR accessions in a srz parameter. A comma-delimited list of file paths and/or URLs is accepted in bam_path parameter (despite its name, this parameter accepts both BAM and SRA formatted files).

For defining SRA tracks via the "tracks" parameter, two of its settings are used: "dbname" and "annots". "dbname" must be set to "SRA" if an SRR accession is going to be used and to "cSRA" for file paths or URLs (SRA or BAM formatted). "annots" holds a SRR accession or file path/URL (please note that all colons including the one in "http://" prefix must be escaped with a backslash).

srz - sets the SRR (SR Run) to use as a datasource for a track, expands to proper track description, e.g. srz=ERR276220 expands into tracks=[key:alignment_track,name:ERR276220,display_name:ERR276220,dbname:SRA,category:Alignments,setting_group:cSRA,annots:ERR276220]

bam_path - BAM file's url or path (NCBI Internal) to BAM file

Examples

Explicit srz parameter for SRR

Same SRR expressed as track with dbname = SRA

Explicit bam_path for external BAM file

Same BAM file expressed as track with dbname = cSRA

seqgraphic.cgi call with dbname=SRA

seqgraphic.cgi call with dbname=cSRA

Alignment tracks from AlignDb

To use internal NCBI AlignDb as data source for alignment track following parameters are required:

key:alignment_track - to specify the track type as alignment,

annots:AlignDb - to specify the data source - AlignDb. Capitalization is important and should be exactly as in this example,

batch - batch number to get the data from.

Example

Assembly to assembly alignment

Remote (HTTP-based) BAM files

The HTTP and HTTPS protocols are supported for all remote file types. Note: BAM files hosted on the FTP protocol are not supported. To request streaming support for additional file types (e.g. tabixVCF), click the "Support Center" link located at the lower right of the Sequence Viewer page.

Minimal set of parameters to display a BAM alignment track:

key values
key alignment_track
dbname cSRA
annots path to the remote BAM file (index files is expected to reside at the same path)

Optional parameters:

Key Value Description
layout Adaptive (default)|Packed|Full Adaptive - let sviewer decide when to switch between coverage graph, pileup graph and reads
Packed - show only coverage or pileup graphs
Full - Show reads as lons many reads as possible
display_name string Use defined track name
ShowAlnStat false (default)|true Set to always show read's pileup graph
GraphHeight number Graph's height

Examples

Rattus norvegicus strain mixed chromosome 1, Rnor_6.0

Homo sapiens chromosome X, GRCh38.p7 Primary Assembly

Remote (HTTP-hosted) BAM files visualization demo

BigBED and BigWIG files

The FTP protocol is supported for bigBED and bigWIG files.

Embedding for BigBED and BigWIG tracks is done the same way as with any other files. User needs to specify corresponding dbname and annots parameters:

Key Value Description
dbname BigWig|BigBed bigWig or bigBed for corresponding type of data
annot string Location of the file on the web, http or ftp protocol

Examples

annots usage example: http\://hgdownload.soe.ucsc.edu/hubs/gtexAnalysis/hg38/gtexAwgAseDensity.bw

SV Demo

Appendix A: Tracks Parameters

The ‘tracks’ parameters are for advanced developers.

‘Tracks’ parameter syntax:

The ‘tracks’ parameter is used to configure track content, track order, and track display in the rendered image. The track display includes track rendering options and other track-specific settings. The syntax for “tracks” parameter is:

tracks=[track1 ][track2][…]

  1. The settings for one track are grouped together using a pair of square brackets ‘[‘ and ‘]’.
  2. The order of tracks in the list determines the final track order in the rendered image.

There can be a special track definition in tracks parameter (must be the first track) - [amend]. If present, track definitions in the URL will be merged with discovered/TMS tracks. If absent, only tracks in the URL will be shown. Compare predefined default tracks, the track given in the URL, and both predefined and URL tracks.

The format of settings for each track grouped in one pair of ‘[‘ and ‘]’ is:

key :track_key [, subkey :feature_subtype] [, name :track_name] [, display_name :track_title] [, annots :annot1[|annot2]] [, shown :true/false] [, comments :comment1|loc1[|comment2|loc2]] [, highlights :label1|...|[labelN]|[GeneID\:id1]|...|[GeneID\:idM]] [, highlights_color :color] [, filter :A>aaa and B<bbb and (C eq ccc or D<=ddd)] [, sort_by :sorting criteria] [, track_setting_key :value]* *HighlightMode:value] [, The track settings consist of a set of key:value pairs. Any unmatched pair (only key or value) will be ignored. A key:value pair is formed using ‘:’, and multiple key:value pairs are separated by ‘,’.

[ Note ] Since these five special characters ([],|:) are used as delimiters in ‘tracks’ parameter, if any of the five special characters are used in user-provided name, title or comment, they have to be escaped using a backslash (‘\’).

  1. key is required. It is one of the predefined track type keys. The same key can be used in multiple track instances. Track keys are case-sensitive. The existing track keys are:

    • sequence_track
    • six_frames_translation
    • SNP_track
    • HapMapRR_track
    • SNP_Bins_track
    • segment_map_track
    • graph_track
    • graph_overlay
    • gene_model_track
    • alignment_track
    • feature_track
    • dbvar_track
    • user_data_track
    • trace_track
  2. subkey is required only when key is a feature_track. It is the storage key for a given feature subtype, such as STS, repeat_region, misc_feature and Protein. For a complete list of feature subtype storage keys, please refer to Appendix A.

  3. name is optional. However, if two or more track instances use the same track key (and subkey combination), then track name (any unique arbitrary track name) is necessary to uniquely represent a track instance.
  4. display_name is optional. It is used for display purpose, such as track title in the rendered image and track name in track configurator. If display_name is not provided, a default display name will be generated based on information retrieved from data. The defined order of precedence is annotation title, annotation name, and file name for uploaded data.
  5. annots is optional. It lists all the annotations needed to be shown in the given track type. If there is more than one annotation, the annotations are separated using '|'. If it is absent, all annotations related to the track type will be loaded. The order of annotations in the list determines the subtrack (each for one annotation) order in the rendered image. If the annotation is unnamed, then the annotation name should be “Unnamed”.
  6. comments is optional. Comments are used for highlighting one or more specific locations in a track. A comment has to come with a pair of comment text and location separated using ‘|’, such as comments:comment1|position1. The sequence location is an integer. ‘,’ separated locations are not acceptable. Multiple comments are supported that are also separated using ‘|’, such as comments:comment1|pos1| comment2|pos2. Figure 2 shows an example with multiple comments specified.

    image13 Figure 2. Example screenshots for ‘tracks’ parameter with ‘comments’ specified. The ‘tracks’ parameter used in the example is:

    tracks=[key:gene_model_track,comments:comment 1|28000|comment 2|48000] [key:feature_track,subkey:STS,comments:histogram comment 1|20000|histogram comment 2|35000|histogram comment 3|44000]

  7. highlights is optional and not all track types support this setting. When specified, it highlights one or more objects:

    • represented using the exactly same labels as the ones shown on screen (case-insensitive)
    • gene(s), having the GeneID(s), listed in the highlights parameter

    If multiple objects need to be highlighted their labels and/or GeneIDs should be separated using '|', such as highlights:label1|label2. The colon after the GeneID identifier needs to be prefixed with '\', such as highlights:GeneID\:100506658. The highlighted objects will be promoted to the top row in the corresponding track to make it more prominent, will be rendered as the normal size even in zoomed-out mode that other objects are shown in a reduced size, and will be shown with label enabled if the label fits.

    The currently supported tracks types include: gene_model_track, feature_track, dbvar_track, and segment_map_track. Figure 3 shows an example with multiple highlighted objects specified:

    image14 Figure 3. Example screenshots for ‘tracks’ parameter with ‘highlighs’ specified. The ‘tracks’ parameter used in the example is:

    tracks=[key:sequence_track] [key:SNP_track] [key:gene_model_track,annots:Unnamed][key:dbvar_track,name:dbvar_track1,annots:NA000001999.1,Rendering:Default,highlights:nsv492962|nssv579665]

  8. highlights_color is optional. When specified, it defines the color to be used for highlights in the curent track. Accepted formats:

    • A named color, such as "red", "blue", "salmon", etc. Supports HTML color names
    • HTML-format colors, such as "#f0f0dd", or "f0f0dd". These are accepted with or without the leading '#'. The color used for highlighting can be changed for all tracks using the global highlights_color parameter.
  9. filter is optional and not all track types support this setting. When specified, it only shows the objects that get passed through the filter. The filter string is similar to many other query languages. For example, if A, B, C, D and E are identifiers, it is ok to have A > aaa and B < bbb and (C eq ccc or D >=ddd) or E between 2 and 10. Currently, the supported operators include: and, or, xor, sub, not, like, between, in, eq, >, <, >=, and <=.
  10. sort_by is optional and not all track types support this setting. When specified, it sorts the objects into several sub-tracks/sub-groups according to a predefined sorting criteria within a given track.
  11. track_setting_key :value pairs are track-specific. The currently exposed track-specific settings include:

    key: six_frames_translation

    key_name value comment
    ShowOption Default: All Forward Show forward direction translations (+1, +2, +3)
    Reverse Show reverse direction translations (-1, -2, -3)
    LTR Show translations from left to right (sense strand) regardless of sequence orientation
    All Show all six-frame translations
    Orfthreshold Default: 20 0 Highlight all ORFs
    20 Highlight ORFs equal or longer than 20 codons
    100 Highlight ORFs equal or longer than 100 codons
    250 Highlight ORFs equal or longer than 250 codons
    100000000 Do not highlight ORFs
    HighlightCodons
    Default: true
    true Highligh start and stop codons
    false Don’t highligh start and stop codons

    key:alignment_track

    key_name value comment
    Color
    Default: Show Differences
    Column Quality score
    – DNA
    DNA: Score residues based on how well a particular residue agrees with the others in a column.
    Frequency-Based Difference DNA/Protein: Score residues based on their frequency in the column
    Show Differences DNA/Protein: Score residues based on match/mismatch to a master/anchor row
    Nucleic Acid Colors DNA: Assign color based on residue (A - Red, G - Blue, C - Yellow, T - Green)
    Column Quality score - Protein Protein: Score residues based on how well a particular residue agrees with the others in a column.
    Rasmol Amino Acid Colors Protein: Used by the application RasMol to group amino acids with similar properties
    Shapely Amino Acid Colors Protein: Used by the application RasMol to group amino acids with similar shapes using a standard color table
    BLOSUM45 Protein: Matrix made by matblas from blosum45.iij BLOSUM Clustered Scoring Matrix in 1/3 Bit Units
    BLOSUM62 Protein: Matrix made by matblas from blosum62.iij BLOSUM Clustered Scoring Matrix in 1/2 Bit Units
    BLOSUM80 Protein: Matrix made by matblas from blosum80.iij BLOSUM Clustered Scoring Matrix in 1/2 Bit Units
    Protein Quality Scoring with Coloring Protein: Color residues where the quality scoring is above (or below) a given threshold
    Hydropathy Scale Protein: Side chain hydropathy, corrected for solvation
    Membrane preference Protein: Membrane-buried preference parameters
    Signal sequence Protein: Signal sequence helical potential
    Size Protein: Amino acid size
    false Disable alignment score coloration
    AlignedSeqFeats
    Default: false
    true Show features projected from the aligned sequences
    false Don’t show features projected from the aligned sequences
    Label
    Default: true
    true Show labels for alignments
    false Hide labels for alignments
    ShowAligns
    Default: true
    true Show alignments always
    false Hide alignments when alignment statistics are shown
    ShowSecondPass
    Default: true
    true Show second-pass aligments
    false Hide second-pass aligments
    Layout Default:
    Adaptive1000
    Adaptive200 Show the individual alignments if less than 200 alignments. Otherwise smear the alignments.
    Adaptive1000 Show the individual alignments if less than 1000 alignments. Otherwise smear the alignments.
    Adaptive5000 Show the individual alignments if less than 5000 alignments. Otherwise smear the alignments.
    Adaptive20000 Show the individual alignments if less than 20000 alignments. Otherwise smear the alignments.
    Adaptive100000 Show the individual alignments if less than 100000 alignments. Otherwise smear the alignments.
    Adaptive250000 Show the individual alignments if less than 250000 alignments. Otherwise smear the alignments.
    Expanded by position Show one alignment per row sorted by alignments' start location
    Smear Smear all alignments into a smear bar
    StatDisplay
    Default: -1
    -1 Don't show alignment statistics
    8 Show A, T, G, C, and gaps percentage as table
    9 Show A, T, G, C, and gaps percentage as bar graph
    10 Show A, T, G, C, and gaps count as table
    11 Show A, T, G, C, and gaps count as bar graph
    12 Show matches, mismatches, and gaps percentage as table
    13 Show matches, mismatches, and gaps percentage as bar graph
    14 Show matches, mismatches, and gaps count as table
    15 Show matches, mismatches, and gaps count as bar graph
    UnalignedTailsMode
    Default:glyph
    glyph Show length of unaligned tails
    hide Hide tails
    sequence Show sequence of unaligned tails
    Sort_by
    Default:
    strand Alignment strand
    haplotype Haplotype (if available)
    reciprocity Reciprocity score (if available)
    GraphHeight Numeric value This parameter is applicable to coverage or pile-up graph of BAM/CSRA alignments
    GraphColor Color name or HTML color code This parameter is applicable to coverage or pile-up graph of BAM/CSRA alignments

    key:gene_model_track

    key_name values comment
    Options
    Default:MergePairs
    GeneOnly Only the 'green' gene bar is shown
    MergeAll Merge all transcripts and CDSs into a single line, no gene bar shown.
    MergePairs Merge the display of the transcript and its coding region as appropritate. Coding reginos are represented by different color. No gene bar is shown.
    ShowAllButGenes Show all transcripts and CDSs separately but with no gene bar.
    ShowAll Show all transcripts and CDSs separately with gene bar.
    SingleLine No gene bar, but merge exon/CDS features and only show on a single line.
    HideNonCoding
    Default: false
    true Show only transcripts or gene loci with associated CDS
    false Show both coding and non-coding features
    HideModels
    Default: false
    true Do not show predicted RefSeq models from Gnomon
    false Show model and curated RefSeq variants
    CCDSOnly
    Default: false
    true Show only CCDS variants
    false Show CCDS and non-CCDS variants
    SelectOnly
    Default: false
    true Show only RefSeq Select or MANE Select variants
    false Do not limit to RefSeq Select or MANE Select variants
    SNPs
    Default: false
    true Show SNP features projected from RNA and coding region features
    false Don’t show SNP features projected from RNA and coding region features
    CDSProductFeats
    Default: false
    true Show product features projected from protein sequence
    false Don’t show product features projected from protein sequence
    ShowLabelsForAllFe atures
    Default: false
    true For top labeling, show labels for all features inside one gene model. This affects the top label mode only.
    false For top labeling, show labels for the first gene, RNA and coding region only in one gene model. This affects the top label mode only.

    key:SNP_track

    key_name value comment
    Layout
    Default: Adaptive
    Adaptive Show labels if less than 15 variants; Show density bar if greater than 50 variants
    Density Always show the density bar of variants
    Features Show all variants rendered individually
    Labels Always show the labels of variants

    key:feature_track

    key_name value comment
    Layout
    Default: Adaptive
    Packed Track is displayed, with all features collapsed on a single line.
    Adaptive show the individual features if less than 50 features. Otherwise, show histogram.
    Layered Always show the individual features and layer the features in a compact form
    LinkedFeat
    Default:Packed
    Default All features, both parent and all child features
    Packed Show parent on one line and all children merged below it.
    ParentHidden Show only the children, not parent
    Hidden Show the parent features, not the children
    OnParent Render all child features on the parent feature
    Sort_by Supported sort_by includes: concordancy, apply to clone features only
    sort_reads
    Default: false
    false do not sort intron features track by number of spliced reads
    true sort intron features track by number of spliced reads, with features with most spliced reads at the top
    sort_strands
    Default: false
    false do not sort intron features track by strand
    true features on the forward strand are sorted separately from features on the reverse strand
    read_range, intron features track only min|max
    Default: inf|inf
    min - number or 'inf'=0, Minimum threshold, the values below this threshold will be hidden from view

    max - number or 'inf'=infinity, Maximum threshold, the values above this threshold will be hidden from view

    key:aggregate_feature_track

    key_name value comment
    subkey biological_region

    Shows the following set of features:

    • miscellaneous features
    • recombination features
    • sequence secondary structures
    • mobile genetic elements
    • protein binding sites
    • origin of replications
    • repeat regions
    • stem loops
    • regulatory features
    aggregate_features A track combining all possible features

    The aggregate_feature_track supports all parameters, supported by the feature track.

    key:dbvar_track

    key_name value comment
    Rendering
    Default: Packed
    Default All features, both parent and all child features
    Packed Show parent on one line and all children merged below it.
    ParentHidden Show only the supporting variants (children) not the variant region (parent)
    Hidden Show the variant region (parent) not the supporting variants (children)",
    SingleLine Track is displayed, with all features collapsed on a single line.
    Histogram Track is displayed, with all features displayed as a histogram.
    Filter Supported filters include: variant_quality=low/high, pilot=1/2, len=size, clinical_assertion= likely_unknown/benign/likely_benign/pathogenic/likely_pathogenic/not_tested/oth er,sampleset_type=case/control
    Sort_by Supported sort_by:
    • Variant_quality
    • pilot
    • clinical_assertion
    • sampleset_type
    • validation_status

    key:graph_track

    key_name value comment
    color It can be color name such as 'red', 'dark blue', or RGB color such as '255 0 0', or HTML color code such as '#FF0000'
    Default: blue
    neg_color Color for negative values
    Default: deep red
    height Graph height in pixels. Default value is 30 pixels for histogram and line graph, and 10 pixels for smear bar
    style Graph rendering styles:
    • histogram
    • line graph
    • smear bar

    Default: histogram
    num bins Integer from 2 to 10 Smear bar is a heat map of data values from min value colored as light blue to the max value colored as dark blue.
    The coloring can be controlled by num_bins parameter. Num_bins parameter allows to partition the data into the number of equal bins
    scale What scale to use:
    • linear
    • log 2
    • log 10
    • loge

    Default: linear
    stored_scale Scale of stored data:
    • linear
    • log2
    • log10
    • loge
    ocolor Color to use for outliers
    Default: red
    uid User ID. Any alphanumeric value that uniquely identifies the track.
    Default: none
    opacity Color opacity in a percentage value (100 completely visible)
    Default: 100
    range min|max|auto min - real number or 'inf', Minimum threshold, the values below this threshold will be clipped

    max - real number or 'inf', Maximum threshold, the values above this threshold will be clipped

    auto - optional flag indicating that value range should be calculated automatically

    key:graph_overlay

    The graph_overlay key allows multiple graph tracks with the same data dimensions to be overlaid in a single track. The tracks to overlay are indicated by the ‘subtracks’ parameter.

    key_name value comment
    subtracks List of tracks to be included in graph overlay. The values represent track_ids - strings separated by ‘|’. For example: track1| track2| track3. Track_ids are references to the other tracks and can be either annot name, id parameter or uid parameter.
    Default: Packed
    BG Background color. It can be color name such as 'red', 'dark blue', or RGB such as '255,0,0', or HTML color code as '#FF0000'
    Default: white
    height Graph height in pixels
    Default: 30
    scale What scale to use
    • linear
    • log2
    • log10
    • loge

    Default: linear
    stored_scale Scale of stored data
    • linear
    • log2
    • log10
    • loge

    Default: linear
    ocolor Color to use for outliners
    Default: red
    range min|max|auto min - real number or 'inf', Minimum threshold, the values below this threshold will be clipped

    max - real number or 'inf', Maximum threshold, the values above this threshold will be clipped

    auto - optional flag indicating that value range should be calculated automatically

    Example: http://www.ncbi.nlm.nih.gov/projects/sviewer/?id=NC_000001.10&v=151955200-151956000&tracks=[key:graph_track,annots:NA000011424.1,opacity:50,color:navy,shown:false][key:graph_track,annots:NA000011426.1,opacity:50,color:tomato,shown:false][key:graph_track,annots:NA000011432.1,color:deeppink,opacity:50,shown:false][key:graph_overlay,subtracks:NA000011424.1|NA000011426.1|NA000011432.1,height:120,display_name:overlay%20example]

    In the example above graph overlay track [key:graph_overlay,subtracks:NA000011424.1|NA000011426.1|NA000011432.1,height:120,display_name:overlay example] refers to three subtracks by their annot names.

    Alternatively, each track can be assigned a user id (uid) and the graph overlay can refer to uid instead [key:graph_overlay,subtracks:tr2|tr1|tr3,height:120,display_name:overlay example] http://www.ncbi.nlm.nih.gov/projects/sviewer/?id=NC_000001.10&v=151955200-151956000&tracks=%5bkey:graph_track,annots:NA000011424.1,uid:tr1,opacity:50,color:navy,shown:false%5d%5bkey:graph_track,name:aaa,annots:NA000011426.1,uid:tr2,opacity:50,color:tomato,shown:false%5d%5bkey:graph_track,annots:NA000011432.1,uid:tr3,color:deeppink,opacity:50,shown:false%5d%5bkey:graph_overlay,subtracks:tr2|tr1|tr3,height:120,display_name:overlay%20example

    key:trace_track

    The trace_track key allows to visualize traces data in NCBI Sequence Viewer.

    key_name value comment
    style curve | intensity Trace graph style
    show_conf_graph true | false Confidence graph visibility
    height 70 Track height
    colorA red Trace chromatogram for base A
    colorC green Trace chromatogram for base C
    colorG blue Trace chromatogram for base G
    colorT purple Trace chromatogram for base T
    colorConfMin dark green Confidence graph's minimum
    colorConfMax light green Confidence graph's maximum

  12. HighlightMode - defines how genes will be highlighted in overview mode:

    Value Description Sample output
    0 Disabled (default) highlights color sample
    1 Highlight the top most important genes highlights color sample
    2 Display the labels of the top most important genes highlights color sample

  13. label - label position relative to the feature

    Values (same as in dialog Tools|Preferences|Label Placement):

    • Default
    • Top label
    • Side label
    • No label

    An ordinal number (base 0) of the value must be given, not the string.

  14. color - greyscale or colored

    Values (same as in dialog Tools|Preferences|Coloration):

    • Color
    • Greyscale

    An ordinal number (base 0) of the value must be given, not the string.

  15. decor - feature drawing style

    Values (same as in dialog Tools|Preferences|Shapes):

    • Default
    • Arrows
    • CircleAnchor
    • Fancy
    • SquareAnchor

    An ordinal number (base 0) of the value must be given, not the string.

  16. spacing - sets vertical spacing between the features

    Values (same as in dialog Tools|Preferences|Spacing):

    • Normal
    • Compact
    • Oversize
    • Overview

    An ordinal number (base 0) of the value must be given, not the string.

Key:user_data_track

Unlike other types of track, user_data_track is a track key to represent a user-uploaded data track that is stored in a NetCache key. By default, all user-uploaded data tracks will be added to bottom of the view. If a user wants to change that default track order without knowing the data track details such as real track key and annotation name, he/she can specify a ‘tracks’ string that contains ‘ user_data_track ’ along with a ‘ data_key ’ in a specific track order. The track order for the user data track will be honored just like other tracks. In addition to ‘ data_key ’ parameter, several other generic parameters are also supported which include: shown , category , and subcategory

key_name value comment
data_key A NetCache key

‘tracks’ parameter examples:

  1. show sequence track, SNP track, gene model track and alignment tracks “track” parameter:

    tracks=[key:sequence_track][key:SNP_track] [key:gene_model_track,annots:Unnamed,Options:ShowAll,SNPs:true] [key:alignment_track]

    Full SV link: http://www.ncbi.nlm.nih.gov/projects/sviewer/?id=nc_000001&tracks=%5Bkey:sequence_track%5D%5Bkey:SNP_track%5D%5Bkey:gene_model_track,annots:Unnamed,Options:ShowAll,SNPs:true%5D%5Bkey:alignment_track%5D&v=180m..181m

  2. show sequence track, SNP track, gene model track and two dbvar tracks with named annotation accessions “track” parameter:

    tracks=[key:sequence_track][key:SNP_track] [key:gene_model_track,annots:Unnamed] [key:dbvar_track,name:dbvar_track1,annots:NA000001999.1|NA000002000.1,Rendering:Default] [key:dbvar_track,dbvar_track2,annots:NA000002001.1,Rendering:SingleLine]

    Full SV link: http://www.ncbi.nlm.nih.gov/projects/sviewer/?id=nc_000001.9&tracks=%5bkey:sequence_track%5d%5bkey:SNP_track%5d%5bkey:gene_model_track,annots:Unnamed%5d%5bkey:dbvar_track,name:dbvar_track1,annots:NA000001999.1%7CNA000002000.1,Rendering:Default%5d%5bkey:dbvar_track,name:dbvar_track2,annots:NA000002001.1,Rendering:SingleLine%5d

  3. show tracks with comments specified “track” parameter:

    tracks=[key:gene_model_track,comments:comment%201|28000|comment%202|48000] [key:alignment_track] \ [key:feature_track,subkey:STS,comments:histogram%20comment%201|20000|histogram%20comment%202|35000|histogram%20comment%203|44000]

    Full SV link: http://www.ncbi.nlm.nih.gov/projects/sviewer/?id=NG_000007&tracks=%5Bkey:gene_model_track,comments:comment%201%7C28000%7Ccomment%202%7C48000%5D%5Bkey:alignment_track%5D%5Bkey:feature_track,subkey:STS,comments:histogram%20comment%201%7C20000%7Chistogram%20comment%202%7C35000%7Chistogram%20comment%203%7C44000

  4. tracks settings with ‘highlights’ specified “track” parameter:

    tracks=[key:sequence_track] [key:SNP_track] [key:gene_model_track,annots:Unnamed] [key:dbvar_track,name:dbvar_track1,annots:NA000001999.1,Rendering:Default,highlights:nsv492962|nssv579665]

    Full SV link: http://www.ncbi.nlm.nih.gov/projects/sviewer/?id=nc_000001.9&tracks=%5Bkey:sequence_track%5D%5Bkey:SNP_track%5D%5Bkey:gene_model_track,annots:Unnamed%5D%5Bkey:dbvar_track,name:dbvar_track1,annots:NA000001999.1,Rendering:Default,highlights:nsv492962%7Cnssv579665%5D

  5. tracks settings with ‘filter’ specified “track” parameter:

    tracks=[key:sequence_track] [key:feature_track,subkey:STS,name:all,display_name:All STSs] [key:feature_track,subkey:STS,filter:len between 260 and 650,name:filtered,display_name:filtered STSs]

    Full SV link: http://www.ncbi.nlm.nih.gov/projects/sviewer/?id=ng_000007&v=6000..10000&tracks=[key:sequence_track][key:feature_track,subkey:STS,name:all,display_name:All STSs][key:feature_track,subkey:STS,filter:len between 260 and 650,name:filtered,display_name:filtered STSs]

  6. tracks settings with ‘sort_by specified “track” parameter:

    tracks=[key:feature_track,name:clone,display_name:Clone%20library\:%20CH242%20Assembly\:%20CCF_000003025.5,subkey:clone,category:Clone,subcategory:CLONES,annots:NA000004255.1,Rendering:Default,sort_by:concordancy]

    Full SV link: http://www.ncbi.nlm.nih.gov/projects/sviewer/?id=nc_010447.4&tracks=[key:feature_track,name:clone,display_name:Clone%20library\:%20CH242%20Assembly\:%20CCF_000003025.5,subkey:clone,category:Clone,subcategory:CLONES,annots:NA000004255.1,Rendering:Default,sort_by:concordancy]&v=632680:3072449

Appendix B: Feature Subtype Storage Keys

Index Subtype Storage Key
1 Gene
2 Org
3 CDS
4 Prot
5 PreProtein
6 Mat-Peptide AA
7 Sig-Peptide AA
8 Transit-Peptide AA
9 precursor_RNA
10 mRNA
11 tRNA
12 rRNA
13 snRNA
14 scRNA
15 sno_RNA
16 misc_RNA
17 ncRNA
18 tmRNA
19 Pub
20 Seq
21 import
22 allele
23 attenuator
24 C_region
25 CAAT_signal
26 Imp_CDS
27 conflict
28 D-loop
29 D_segment
30 enhancer
31 exon
32 GC_signal
33 iDNA
34 intron
35 J_segment
36 LTR
37 mat_peptide
38 misc_binding
39 misc_difference
40 misc_feature
41 misc_recomb
42 misc_RNA
43 misc_signal
44 misc_structure
45 modified_base
46 mutation
47 N_region
48 old_sequence
49 polyA_signal
50 polyA_site
51 precursor_RNA
52 prim_transcript
53 primer_bind
54 promoter
55 protein_bind
56 RBS
57 repeat_region
58 repeat_unit
59 rep_origin
60 S_region
61 satellite
62 sig_peptide
63 source
64 stem_loop
65 STS
66 TATA_signal
67 terminator
68 transit_peptide
69 unsure
70 V_region
71 V_segment
72 variation
73 virion
74 3'clip
75 3'UTR
76 5'clip
77 5'UTR
78 -10_signal
79 -35_signal
80 gap
81 operon
82 oriT
83 site_ref
84 mobile_element
85 region
86 comment
87 bond
88 site
89 rsite
90 user
91 txinit
92 num
93 psec_str
94 non_std_residue
95 het
96 biosrc
97 clone
98 variation


  1. http://www.ncbi.nlm.nih.gov/Sitemap/sequenceIDs.html
  2. http://www.ncbi.nlm.nih.gov/books/NBK1058/
  3. http://eutils.ncbi.nlm.nih.gov/corehtml/query/static/elink_help.html
  4. http://blast.ncbi.nlm.nih.gov/Blast.cgi?CMD=Web&PAGE_TYPE=BlastDocs
  5. http://www.ncbi.nlm.nih.gov/Class/MLACourse/Modules/BLAST/rid.html

Appendix C: Objects/Features tooltips preprocessing

This feature allows to modify links before they are shown in an Objects/Feature tooltip. It is based on an ability to set a callback function for preprocessing an array of objects describing links coming with the tooltip information.

setTooltipPreprocessor(callback) - the callback function receives the following two parameters:

  1. Array of link objects:

linksList: [{ name: string, type: string, // 'Extra', 'Basic', 'Download' html: string, // may be added by a preprocessor function links: [{ label: string, link: string // url }, ...] },...]

  1. Some extra information about the feature/object:

obj_info: { acc: string, //sequence id (accession.ver) title: string, // feature/object title start_pos: int, // start position end_pos: int // end position }

If the preprocessing function added html property to a linksList object Sequence Viewer uses it instead of the array links . Removing an object from a linksList removes it from the tooltip.

Example (removes each 3rd link from the list):

var app = SeqView.App.findAppByDivId(‘YOUR\_SV\_DIV\_ID’);
app.setTooltipPreprocessor(function(linksList, obj\_info) {
for (var i = linksList.length - 1; i >= 0; i--) {
if (i % 3 == 0) linksList.splice(i, 1);
}
Support Center

Last updated: 2023-06-02T21:39:21Z