Deep Linking Into Xena

How to programmatically specify Xena Browser views

Xena has the ability to draw visualizations based on parameters passed through URL. You will need to URL encode the parameters.

The list of supported parameters below is not exhaustive. If you do not see your functionality supported below please contact us.

Examples

Display Column Setup Examples

Example 1 One data column (with two subcolumns) display

Example 2 Display in chart mode

Example 3 Three data column display, one clinical data column, two genomic data columns

Example 4 Specify column width, top label, and bottom label on Column C

Example 5 Reverse sort on Column B

Example 6 Display gene average in Column C

Example 7 Display introns in Column C; Hide welcome banner

4KB

linktest.html

Highlight Samples Examples

Example 8: highlight TCGA-C8-A131-01 or TCGA-BH-A0DL-01 samples

Example 9: highlight samples matching arbitrary criteria, such as samples in Column B with values > 10

1KB

samplehighlight2.html

Sample Filtering (specify what samples to display in the view) Examples

4KB

sample_highlight_filter.html

Base URL and URL construction

var page = ‘https://xenabrowser.net/heatmap/’;
var url = page + ‘?columns=’ + encodeURIComponent(columns_parameter) + \
    ‘&heatmap=’ + encodeURIComponent(heatmap_parameter);

columns parameter

The columns parameter is a JSON-encoded array of objects, specifying the columns to display.

Properties

To specify a single column you need to, at a minimum, specify the dataset ID, the hub where the data resides, and the fields that you want to display.

var column = {name: dataset1, host: hub1, fields: 'foo bar'};
var columns_parameter = JSON.stringify([column]);
var url = page + ‘?columns=’ + encodeURIComponent(columns_parameter);

Fields for genomic columns

Fields can be a gene, probe, or chromosome position. All fields need to be of the same type (i.e. all genes or all probes). You can only enter one chromosome position per column.

Fields for phenotypic columns

Field should be the field ID as it appears exactly in the dataset

Optional properties

width: <number>

Width in pixels

columnLabel: <string>

Text for top column label

fieldLabel: <string>

Text for bottom column label

geneAverage: <boolean>

Display the gene average instead of the individual probes for a gene. You can use this only when a single gene is specified for a dataset that has probes on a gene

normalize: ‘none’ | ‘mean’ | ‘log2’ | ‘normal2’

How the data should be dynamically normalized on the fly. 'mean' is x-mean (subtract mean), applied per (sub)column. 'log2' is log2(x+1). 'normal2' is (x-2).

showIntrons: <boolean>

Show introns for mutation and segmented copy number columns

sortDirection: 'reverse'

Reverse sort the samples

sortVisible: <boolean>

Sort column on the zoomed region

filterColumns parameter

Same as the columns parameter, but these columns will not be displayed. They are available for sample filtering. See the filter property of the heatmap parameter, below.

heatmap parameter

The heatmap parameter is a JSON-encoded object specifying global display options

Properties

mode: 'chart'

Display in chart mode rather than visual spreadsheet mode.

showWelcome: <boolean>

Show the welcome banner.

searchSampleList: [<string>, ...]

Highlight the specified samples in the view.

search: <string>

Equivalent to typing this text into the 'Find' feature in Xena. In this example it is highlighting the samples that for column B have a value of 'TARGET'. More examples of possible search terms.

filter: <string>

Like the search parameter, but filter the view to the matching samples. Equivalent to selecting 'Filter' from the 'Find' UI. Columns that are only needed for filtering (not visualization) can be added to the filterColumns parameter, and appear semantically after columns. For example, if columns has length two they are labeled 'B' and 'C', and the first column in filterColumns will be 'D'.

Both search and filter can be specified in the same url, in which case the samples will be filtered, and any remaining samples matching search will be highlighted. Note that the search expression should only reference columns, not filterColumns, since the latter are not available for visualization.

var heatmap_paramter = JSON.stringify({
      showWelcome: false,
      search: "B:=TARGET"
});
var url = page + ‘?columns=’ + encodeURIComponent(columns_parameter) + \
      ‘?heatmap=’ + encodeURIComponent(heatmap_paramter);