config.html

---
layout: page
title: Configuring Dalliance
---

There are many options you can configure when creating a Browser object.

<h5>chr/viewStart/viewEnd</h5>

These options configure the default view when the browser starts for the first time.

{%highlight javascript %}
    chr:          '22',
    viewStart:    30000000,
    viewEnd:      30030000
{%endhighlight%}

<h5>sources</h5>

An array of source or track configurations (see <a href="config-source.html">the source configuration guide</a>).

<h5>maxViewWidth</h5>

The maximum width of the visible region, configured in bases.  Default is 500000.

<h5>pageName</h5>

The id of an element on the page whose contents will be replaced with the Dalliance instance
when it starts up.

<h5>cookieKey</h5>

String used as a key for session persistance.  It should be unique amongst all Dalliance
instances served from a given domain.  Not relevant if <code>noPersist</code> is true.

<h5>coordSystem</h5>

This defines the reference genome coordinate system for the browser.  It's principally used when
querying the DAS registry to find relevant datasources.  It is also needed to correctly re-map data
between coordinate systems.  A typical configuration looks like:

{%highlight javascript %}
coordSystem: {
    speciesName: 'Danio rerio',
    taxon: 7955,
    auth: 'Zv',
    version: 9,
    ucscName: 'danRer7'
}
{%endhighlight%}

The <code>speciesName</code> field can be a human-readable label, and isn't used when querying the
registry.  <code>taxon</code> should be an integer identified from the <a href='http://www.ncbi.nlm.nih.gov/taxonomy'>NCBI Taxonomy</a>
<code>auth</code> and <code>version</code> should, as far as possible, match authority and version strings used
in the <a href='http://dasregistry.org/'>DAS Registry</a>.

The <code>ucscName</code> field is optional, but should be filled in with the UCSC genome browser name of the assembly
if it is defined.  This enables <a href='#hub'>track-hub support</a> to work properly.

<h5>setDocumentTitle</h5>

If true, attempt to change the title of the web browser window to reflect the species name being displayed.  Generally not
wanted for embedded browsers.

<h5>prefix</h5>

URL from which static browser resources should be downloaded (CSS, images, help
pages, and the Javascript "web worker" code).  By default, this
is <code>http://www.biodalliance.org/release-X.Y</code> code where X.Y represents the
current major and minor release numbers.  The <code>uiPrefix</code> option is a (deprecated)
synonym.

<h5>maxWorkers</h5>

The maximum number of web-workers to us when fetching data.  If set to 0, the web worker system
is disabled and all data fetching will be performed on the main UI thread.  Using workers generally
improves responsiveness but may increase resource usage.

<h5>noPersist</h5>

Fully disables Dalliance's built-in session management.  When the page is reloaded, everything will be
reset to the configuration passed to the Browser constructor.

<h5>noPersistView</h5>

Disable storing the current location in the session-management system.  All other options (notably,
current track configurations are preserved).  This is useful if you are embedding little feature-centric
browser instances into a larger application (e.g. a database with one page per gene).

<h5>noDefaultLabels</h5>

Do not add the standard "tier tab" labels.  Intended for very lightweight embedded browser instances/

<h5>tierBackgroundColors</h5>

Array of CSS color strings used as background colors.  Dalliance cycles through the available
colours in order.  In the special case of this property being set to <code>null</code>, tiers
will have transparent backgrounds.  This is only recommended if there's a specific reason
for letting the background show through.

<h5>maxHeight</h5>

Maximum height, in CSS pixels, that the Dalliance component can grow to (default 500).

<h5>fullScreen</h5>

Attempt to fit the Dalliance component to the containing window, making allowances for other content on the page.


<h5>rulerLocation</h5>

The default location of the vertical guideline. Valid values are <code>center</code>, <code>left</code>, <code>right</code>, or <code>none</code>.

<h5>reverseScrolling and reverseKeyScrolling</h5>

These control the <em>default</em> direction of scrolling using trackpads and keyboards
respectively (can also be configured in the settings panel).

<h3><a id='hub'>Configuring a track-hub</a></h3>

As of Dalliance 0.9, there is rudimentary support for <a href='http://genome.ucsc.edu/goldenPath/help/hgTrackHubHelp.html'>UCSC-style
track hubs</a>, so long as they're server over HTTP and support CORS.  These can be configured with:

{%highlight javascript%}
hubs: ['http://www.biodalliance.org/datasets/testhub/hub.txt', 
       'http://ftp.ebi.ac.uk/pub/databases/ensembl/encode/integration_data_jan2011/hub.txt']
{%endhighlight%}

...and will appear as extra tabs in the track-addition user interface.

<h3><a id='liftOver'>Configuring coordinate-system mappings</a></h3>

Dalliance can do on-the-fly coordinate system mapping.  The set of available mappings is configured by the <code>chains</code> property, which takes a map of mapping names to mapping definitions, e.g.:

{%highlight javascript %}
    chains: {
      hg18ToHg19: {uri: 'http://www.biodalliance.org/datasets/GRCh37/hg18ToHg19.bb',
                   type: 'bigbed',
                   coords: {
                        speciesName: 'Human',
                        taxon: 9606,
                        auth: 'NCBI',
                        version: 36
                   }
                  }
    }
{%endhighlight%}

You can use arbitrary strings as names for mappings.  When configuring a track in the <code>sources</code> array, you can specify which mapping to use, e.g.:

{%highlight javascript %}
sources: [
  {name: "My track",
   bwgURI: "http://some/old.data.bb",
   mapping: 'hg18ToHg19'}
]
{%endhighlight%}

Each mapping definition has the following properties:

<h5>uri</h5>

URI to access alignment data.

<h5>type (optional)</h5>

Currently supported values are "bigbed", which specifies a bigBed-encoded version of the chain file
format, produced by the <a href="https://github.com/dasmoth/hubbub">chain2bed</a> utility.  If <code>type</code> is not specified, alignment-DAS is assumed.  Alignment DAS support is deprecated as of
Dalliance 0.12.  Please contact Thomas Down for more details if you really need it.

<h5>credentials (optional)</h5>

Support credentials when accessing the alignment data.

<h5>coords (required)</h5>

The coordinate system that this mapping is <em>from</em> (it is assumed to be) <em>to</em> the default coordinate system of the browser.  This is important, because it controls what gets presented if the user is prompted to choose a coordinate system when the user manually adds data.  If possible, the <code>ucscName</code> of the coordinate system should also be specified -- if so, coordinate system mapping will be automatically supported when interacting with track-hubs which provide data for more than one genome assembly.

<h3><a id='uielements'>Fine-grained control over the default UI</a></h3>

<p>
Most of the UI can be disabled (it's also possible to run the Dalliance track component without <em>any</em> UI,
but that should probably be documented elsewhere).
<p>

<ul>
    <li>noLeapButtons</li>
    <li>noLocationField</li>
    <li>noZoomSlider</li>
    <li>noTitle</li>
    <li>noTrackAdder</li>
    <li>noTrackEditor</li>
    <li>noExport</li>
    <li>noOptions</li>
    <li>noHelp</li>
    <li>noClearHighlightsButton</li>
    <li>disableDefaultFeaturePopup</li>
    <li>noDefaultHubGroupShow</li>
</ul>