1 of 4

Technical documentation

Setting up Xena for your institution

Please see our Viewing your own Data documentation:

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

One data column (with two subcolumns) display

Display in chart mode

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

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

Reverse sort on Column B

Display gene average in Column C

Display introns in Column C; Hide welcome banner

HTML Code showing how to build examples 1-7

Highlight Samples Examples

Below is HTML code showing how to generate URLs that:

1) highlight samples TCGA-C8-A131-01 or TCGA-BH-A0DL-01

2) highlight samples matching arbitrary criteria, such as samples in Column B with values > 10

HTML code for highlighting samples examples

HTML code showing sample filtering (to specify what samples to display in the view) examples

Base URL and URL construction

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.

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

filter: <string>

Like the search parameter, but filter the view to the matching samples. Equivalent to . 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.

Metadata Specification

metadata (.json file) specification

MAPs

MAPs are tsne, umap, pca embeddings in 2D or 3D, or spatial maps for spatical data.

map is a list in the .json metadata file

For each map

"label" free text. Display label of the map, should be easily readable by users

"dataSubType" a string. Describe the nature of the map, must be embedding, spatial . Note this is the dataSubType attribute for the map, not the dataSubType attribute for the file

"dimension" a list of strings. They are the column headers of the dimension columns in the data file. They are used to retrieve data from db.

If it is a spatial map, there might be microscopy image(s) associated with each map.

"unit" (optional, only relevant to spatial map) a string. The unit of map values, e.g. pixel, micrometer

"micrometer_per_unit" (optional, only relevant to spatial map) a floating point number. The physical size in micrometer (µm) of value =1 in spatial map. The parameter will be used in rendering scale bar is the spatial map. If not specified, scale will not be shown.

"spot_diameter" (optional, relevant to spatial map) a floating point number of the size of spot in map unit (not image unit). The parameter will be used to determine sphere size shown in spatial map. If not specified, the size of the sphere will be determined by the browser.

"image" (optional, only relevant to a spatial map with associated images) an array of images, each image has its own parameters. See below.

For each image

"label" free text. Display label of the image, should be easily readable

"path" file path to the image file

"offset" an array of integers. Image offset in pixel in x and y dimension. See below for conversion from spatial coordinate values in map to pixel position in this image.

"image_scalef": floating point number. A scaling factor that converts spatial coordinate values in the spatial map (e.g. pixel or micrometer) to the pixel unit in this image. It works together with the "offset" parameter to convert spatial coordinate values in the spatial map to the actual pixel positions in this image.

pixel_in_image_x = image_scalef * spatial_coordinate_x + offset_x
pixel_in_image_y = image_scalef * spatial_coordinate_y + offset_y

"transcript" (optional, only relevant to a spatial transcriptomics map) an array of transcript data, each has its own json parameters. See below.

Note. The transcript coordinate must be in the same unit and scale as the map. Therefore no scaling or offset are needed to convert transcript coordinate and map coordinate.

"label" free text. Display label of the transcript data, should be easily readable

"path" file path to the transcript datafile

"dimension" a list of strings. Must have the same number of dimensions as the map. They are the column headers of the dimension columns in the transcript file. They are used to retrieve data from db.

Map examples

Example, map without image

Example, spatial map with matching microscopy image

Example, spatial map with matching microscopy image and transcript data

SURVIVAL TIME UNIT

Surival time unit is displayed on the x-axis of the KM plot. You specify it in metadata file under the "units" attribute.

"units" free text , KM plot x-axis unit, e.g. years, months, days

example

CUSTOM CATEGORICAL PHENOTYPE

You customize the display of features in a phenotype file ("type": "clinicalMatrix") by adding a "clinicalFeature" file and accompanying .json file. To do this there are two steps

Add a "clinicalFeature" reference to the .json file that accompanies the phenotype file. Note the colon notation in example below.
Compose the clinicalFeaure file (tab delimitated) and its .json file.

Below is an example for adding "clinicalFeature" reference in the phenotype file .json metadata

Below is an example for clinical feature file. This file is tab-delimitated, with headers "feature", "attribute", "value". The attributes are "valueType", "state", and "stateOrder". The values for the attribute "valueType" can be "category" or "float".

Below is an example clinicalFeature file .json file (clinicalFeature.txt.json)

An example of setting binary 0/1 variables as categorical data in the phenotype file. Xena automatically assumes 0/1 is numerical data when it is loaded, so if you want this data to be displayed as categorical you need to indicate it in the clinicalFeature file.

Below is an example of how you would do this for a feature called "your_featureName".

feature

attribute

value

More information about how to specify missing data as well as how Xena decides if a column is categorical or numerical, see our .

COLUMN DISPLAY NORMALIZATION

For genomic data matrix, the optional metadata parameter colNormalization sets the default display scale. If not specified, the browser automatically determines the scale.

colNormalization: ‘true’ | ‘log2(x)’ | ‘normal2’

true: display centered by column mean, x - column average, example usage is gene expression matrix that already log transformed.
log2(x): display in log2(x+1) scale, example usage is gene expression count matrix
normal2: display value of 2 in the background color (i.e. white), typically used for copy number data where the normal = 2

example

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

One data column (with two subcolumns) display

Display in chart mode

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

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

Reverse sort on Column B

Display gene average in Column C

Display introns in Column C; Hide welcome banner

HTML Code showing how to build examples 1-7

Highlight Samples Examples

Below is HTML code showing how to generate URLs that:

1) highlight samples TCGA-C8-A131-01 or TCGA-BH-A0DL-01

2) highlight samples matching arbitrary criteria, such as samples in Column B with values > 10

HTML code for highlighting samples examples

HTML code showing sample filtering (to specify what samples to display in the view) examples

Base URL and URL construction

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.

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

filter: <string>

<html>
<script>
	window.onload = function() {
        var browser = 'https://xenabrowser.net/';

        var hub1 = 'https://toil.xenahubs.net';
        var dataset1 = 'tcga_Kallisto_tpm';

		var hub2 = 'https://tcga.xenahubs.net';
		var dataset2 = 'TCGA.PANCAN.sampleMap/Gistic2_CopyNumber_Gistic2_all_data_by_genes';
		
		var hub3 = 'https://pancanatlas.xenahubs.net';
		var dataset3 = 'Survival_SupplementalTable_S1_20171025_xena_sp';

		var hub4 = 'https://pancanatlas.xenahubs.net';
		var dataset4 = 'broad.mit.edu_PANCAN_Genome_Wide_SNP_6_whitelisted.xena';

		var hub5 = 'https://gdc.xenahubs.net';
		var dataset5 = 'TCGA-BRCA.somaticmutation_wxs.tsv';

		var col1 = {name: dataset1, host: hub1, fields: 'TP53 FOXM1'};
		var col2 = {name: dataset2, host: hub2, fields: 'FOXM1'};
		var col3 = {name: dataset3, host: hub3, fields: 'cancer type abbreviation'};
		var col4 = {name: dataset4, host: hub4, fields: 'chr3:4000000-4100000'};
		var col5 = {
			name: dataset1,
			host: hub1,
			width: 400,
			columnLabel: 'top column label',
			fieldLabel: 'bottom column label',
			fields: 'ENST00000064780.6 ENST00000066544.7 ENST00000070846.10 ENST00000072516.7 ENST00000072644.5 ENST00000072869.8 ENST00000074304.9 ENST00000075120.11 ENST00000075322.10'
		};

		var col6 = {name: dataset1, host: hub1, fields: 'TP53'};
		var col6_geneAve = {name: dataset1, host: hub1, fields: 'TP53', geneAverage: true};

		var col7 = {name: dataset5, host: hub5, fields: 'TP53'};
		var col7_showIntron = {name: dataset5, host: hub5, fields: 'TP53', showIntrons: true};

		var col8 = {
			name: dataset1, 
			host: hub1, 
			fields: 'TP53 FOXM1', 
			sortDirection: 'reverse'
		};

		var heatmapChart = JSON.stringify({
			mode: 'chart'
		});

		var heatmapHideWelcome = JSON.stringify({
			showWelcome: false,
		});

		        var columns1 = JSON.stringify([col1]);
        var l1 = document.getElementById('link1');
        l1.href = browser + 'heatmap/?columns=' + encodeURIComponent(columns1);

        var columns2 = JSON.stringify([col1, col2]);
        var l2 = document.getElementById('link2');
        l2.href = browser + 'heatmap/?columns=' + encodeURIComponent(columns2) + '&heatmap=' + encodeURIComponent(heatmapChart);

        var columns3 = JSON.stringify([col3, col2, col4]);
        var l3 = document.getElementById('link3');
        l3.href = browser + 'heatmap/?columns=' + encodeURIComponent(columns3);

        var columns4 = JSON.stringify([col3, col5]);
        var l4 = document.getElementById('link4');
        l4.href = browser + 'heatmap/?columns=' + encodeURIComponent(columns4);

        var columns5 = JSON.stringify([col8]);
        var l5 = document.getElementById('link5');
        l5.href = browser + 'heatmap/?columns=' + encodeURIComponent(columns5);

        var columns6 = JSON.stringify([col6, col6_geneAve]);
        var l6 = document.getElementById('link6');
        l6.href = browser + 'heatmap/?columns=' + encodeURIComponent(columns6);

        var columns7 = JSON.stringify([col7, col7_showIntron]);
        var l7 = document.getElementById('link7');
        l7.href = browser + 'heatmap/?columns=' + encodeURIComponent(columns7) + '&heatmap=' + encodeURIComponent(heatmapHideWelcome);
    };
</script>
<body>
    <a id=link1>Example 1</a> One data column (with two subcolumns) display
	<br><br>
	<a id=link2>Example 2</a> Display in chart mode
	<br><br>
	<a id=link3>Example 3</a> Three data column display, one clinical data column, two genomic data columns
	<br><br>
	<a id=link4>Example 4</a> Specify column width, top label, and bottom label on Column C
	<br><br>
	<a id=link5>Example 5</a> Reverse sort on Column B
	<br><br>
	<a id=link6>Example 6</a> Display gene average in Column C
	<br><br>
	<a id=link7>Example 7</a> Display introns in Column C; Hide welcome banner
</body>
</html>

<html>
<script>
	window.onload = function() {
		var browser = 'http://dev.xenabrowser.net/';
		var columns = JSON.stringify([
			{
				"width": 90,
				"columnLabel": "",
				"fieldLabel": "site id",
				"host": "https://xena.treehouse.gi.ucsc.edu",
				"name": "clinical_TumorCompendium_v11_PolyA_2020-04-09.tsv",
				"fields": "site_id"
			},
			{
				"width": 150,
				"columnLabel": "gene expression RNAseq",
				"fieldLabel": "ALK",
				"host": "https://xena.treehouse.gi.ucsc.edu",
				"name": "TumorCompendium_v11_PolyA_AllSamples_AllGenes_Kallisto_HugoLog2TPM_20230630.tsv",
				"fields": "ALK"
			}
		]);


		var heatmap1 = JSON.stringify({
			showWelcome: false,
			searchSampleList: ["THR30_0820_S01", "THR30_0861_S01"]
		});

		var l1 = document.getElementById('link1');
		l1.href = browser + 'heatmap/?columns=' + encodeURIComponent(columns) + '&heatmap=' + encodeURIComponent(heatmap1);

		var heatmap2 = JSON.stringify({
			showWelcome: false,
			search: "B:=TARGET"
		});

		var l2 = document.getElementById('link2');
		l2.href = browser + 'heatmap/?columns=' + encodeURIComponent(columns) + '&heatmap=' + encodeURIComponent(heatmap2);

		var heatmap3 = JSON.stringify({
			filter: "B:TARGET",
		});

		var l3 = document.getElementById('link3');
		l3.href = browser + 'heatmap/?columns=' + encodeURIComponent(columns) + '&heatmap=' + encodeURIComponent(heatmap3);

		var heatmap4 = JSON.stringify({
			showWelcome: false,
			filter: "B:TARGET OR B:TCGA",
		});

		var l4 = document.getElementById('link4');
		l4.href = browser + 'heatmap/?columns=' + encodeURIComponent(columns) + '&heatmap=' + encodeURIComponent(heatmap4);

		var heatmap5 = JSON.stringify({
			showWelcome: false,
			filter: "B: TARGET",
			searchSampleList: ["TARGET-40-0A4I6O-01A-01R"]
		});

		var l5 = document.getElementById('link5');
		l5.href = browser + 'heatmap/?columns=' + encodeURIComponent(columns) + '&heatmap=' + encodeURIComponent(heatmap5);

		var filterColumns = JSON.stringify([{
			"host": "https://xena.treehouse.gi.ucsc.edu",
			"name": "clinical_TumorCompendium_v11_PolyA_2020-04-09.tsv",
			"fields": "age_at_dx"
		}]);
		var heatmap6 = JSON.stringify({
			showWelcome: false,
			filter: "D:<5",
		});
		var l6 = document.getElementById('link6');
		l6.href = browser + 'heatmap/?columns=' + encodeURIComponent(columns) + '&filterColumns=' + encodeURIComponent(filterColumns) + '&heatmap=' + encodeURIComponent(heatmap6);
	};
</script>
<body>
	<a id=link1>Sample highlight Example 1:</a> highlight samples of specific sample IDs, such as THR30_0820_S01 or THR30_0861_S01
	<br><br>
	<a id=link2>Sample highlight Example 2:</a> highlight samples matching an arbitary criteria, such as TARGET samples
	<br><br>
	<a id=link3>Sample filtering Example 1:</a> specify (filter to) what samples to show in a view using a predicate, such as TARGET samples
	<br><br>
	<a id=link4>Sample filtering Example 2:</a> specify samples in a view using a predicate that includes a boolean term, such as TARGET and TCGA samples (use boolean OR)
	<br><br>
	<a id=link5>Sample filtering and highlight at the same time:</a> specify samples in a view using a predicate (e.g. just show TARGET samples), as well as highlight specific samples by IDs, such as TARGET-40-0A4I6O-01A-01R
	<br><br>
	<a id=link6>Sample filtering using data in a hidden filter column:</a> useful when you want to filter samples using data not displayed on the screen. You can use <i>HIDDEN FILTER COLUMN</i>. For exmaple, filter the samples to < 5 years old, but you don't want to actually display the age column on the screen.  
</body>
</html>

<html>
<script>
	window.onload = function() {
        var browser = 'https://xenabrowser.net/';

        var hub1 = 'https://toil.xenahubs.net';
        var dataset1 = 'tcga_Kallisto_tpm';

		var hub2 = 'https://tcga.xenahubs.net';
		var dataset2 = 'TCGA.PANCAN.sampleMap/Gistic2_CopyNumber_Gistic2_all_data_by_genes';
		
		var hub3 = 'https://pancanatlas.xenahubs.net';
		var dataset3 = 'Survival_SupplementalTable_S1_20171025_xena_sp';

		var hub4 = 'https://pancanatlas.xenahubs.net';
		var dataset4 = 'broad.mit.edu_PANCAN_Genome_Wide_SNP_6_whitelisted.xena';

		var hub5 = 'https://gdc.xenahubs.net';
		var dataset5 = 'TCGA-BRCA.somaticmutation_wxs.tsv';

		var col1 = {name: dataset1, host: hub1, fields: 'TP53 FOXM1'};
		var col2 = {name: dataset2, host: hub2, fields: 'FOXM1'};
		var col3 = {name: dataset3, host: hub3, fields: 'cancer type abbreviation'};
		var col4 = {name: dataset4, host: hub4, fields: 'chr3:4000000-4100000'};
		var col5 = {
			name: dataset1,
			host: hub1,
			width: 400,
			columnLabel: 'top column label',
			fieldLabel: 'bottom column label',
			fields: 'ENST00000064780.6 ENST00000066544.7 ENST00000070846.10 ENST00000072516.7 ENST00000072644.5 ENST00000072869.8 ENST00000074304.9 ENST00000075120.11 ENST00000075322.10'
		};

		var col6 = {name: dataset1, host: hub1, fields: 'TP53'};
		var col6_geneAve = {name: dataset1, host: hub1, fields: 'TP53', geneAverage: true};

		var col7 = {name: dataset5, host: hub5, fields: 'TP53'};
		var col7_showIntron = {name: dataset5, host: hub5, fields: 'TP53', showIntrons: true};

		var col8 = {
			name: dataset1, 
			host: hub1, 
			fields: 'TP53 FOXM1', 
			sortDirection: 'reverse'
		};

		var heatmapChart = JSON.stringify({
			mode: 'chart'
		});

		var heatmapHideWelcome = JSON.stringify({
			showWelcome: false,
		});

		        var columns1 = JSON.stringify([col1]);
        var l1 = document.getElementById('link1');
        l1.href = browser + 'heatmap/?columns=' + encodeURIComponent(columns1);

        var columns2 = JSON.stringify([col1, col2]);
        var l2 = document.getElementById('link2');
        l2.href = browser + 'heatmap/?columns=' + encodeURIComponent(columns2) + '&heatmap=' + encodeURIComponent(heatmapChart);

        var columns3 = JSON.stringify([col3, col2, col4]);
        var l3 = document.getElementById('link3');
        l3.href = browser + 'heatmap/?columns=' + encodeURIComponent(columns3);

        var columns4 = JSON.stringify([col3, col5]);
        var l4 = document.getElementById('link4');
        l4.href = browser + 'heatmap/?columns=' + encodeURIComponent(columns4);

        var columns5 = JSON.stringify([col8]);
        var l5 = document.getElementById('link5');
        l5.href = browser + 'heatmap/?columns=' + encodeURIComponent(columns5);

        var columns6 = JSON.stringify([col6, col6_geneAve]);
        var l6 = document.getElementById('link6');
        l6.href = browser + 'heatmap/?columns=' + encodeURIComponent(columns6);

        var columns7 = JSON.stringify([col7, col7_showIntron]);
        var l7 = document.getElementById('link7');
        l7.href = browser + 'heatmap/?columns=' + encodeURIComponent(columns7) + '&heatmap=' + encodeURIComponent(heatmapHideWelcome);
    };
</script>
<body>
    <a id=link1>Example 1</a> One data column (with two subcolumns) display
	<br><br>
	<a id=link2>Example 2</a> Display in chart mode
	<br><br>
	<a id=link3>Example 3</a> Three data column display, one clinical data column, two genomic data columns
	<br><br>
	<a id=link4>Example 4</a> Specify column width, top label, and bottom label on Column C
	<br><br>
	<a id=link5>Example 5</a> Reverse sort on Column B
	<br><br>
	<a id=link6>Example 6</a> Display gene average in Column C
	<br><br>
	<a id=link7>Example 7</a> Display introns in Column C; Hide welcome banner
</body>
</html>

<html>
<script>
	window.onload = function() {
		var browser = 'http://dev.xenabrowser.net/';
		var columns = JSON.stringify([
			{
				"width": 90,
				"columnLabel": "",
				"fieldLabel": "site id",
				"host": "https://xena.treehouse.gi.ucsc.edu",
				"name": "clinical_TumorCompendium_v11_PolyA_2020-04-09.tsv",
				"fields": "site_id"
			},
			{
				"width": 150,
				"columnLabel": "gene expression RNAseq",
				"fieldLabel": "ALK",
				"host": "https://xena.treehouse.gi.ucsc.edu",
				"name": "TumorCompendium_v11_PolyA_AllSamples_AllGenes_Kallisto_HugoLog2TPM_20230630.tsv",
				"fields": "ALK"
			}
		]);


		var heatmap1 = JSON.stringify({
			showWelcome: false,
			searchSampleList: ["THR30_0820_S01", "THR30_0861_S01"]
		});

		var l1 = document.getElementById('link1');
		l1.href = browser + 'heatmap/?columns=' + encodeURIComponent(columns) + '&heatmap=' + encodeURIComponent(heatmap1);

		var heatmap2 = JSON.stringify({
			showWelcome: false,
			search: "B:=TARGET"
		});

		var l2 = document.getElementById('link2');
		l2.href = browser + 'heatmap/?columns=' + encodeURIComponent(columns) + '&heatmap=' + encodeURIComponent(heatmap2);

		var heatmap3 = JSON.stringify({
			filter: "B:TARGET",
		});

		var l3 = document.getElementById('link3');
		l3.href = browser + 'heatmap/?columns=' + encodeURIComponent(columns) + '&heatmap=' + encodeURIComponent(heatmap3);

		var heatmap4 = JSON.stringify({
			showWelcome: false,
			filter: "B:TARGET OR B:TCGA",
		});

		var l4 = document.getElementById('link4');
		l4.href = browser + 'heatmap/?columns=' + encodeURIComponent(columns) + '&heatmap=' + encodeURIComponent(heatmap4);

		var heatmap5 = JSON.stringify({
			showWelcome: false,
			filter: "B: TARGET",
			searchSampleList: ["TARGET-40-0A4I6O-01A-01R"]
		});

		var l5 = document.getElementById('link5');
		l5.href = browser + 'heatmap/?columns=' + encodeURIComponent(columns) + '&heatmap=' + encodeURIComponent(heatmap5);

		var filterColumns = JSON.stringify([{
			"host": "https://xena.treehouse.gi.ucsc.edu",
			"name": "clinical_TumorCompendium_v11_PolyA_2020-04-09.tsv",
			"fields": "age_at_dx"
		}]);
		var heatmap6 = JSON.stringify({
			showWelcome: false,
			filter: "D:<5",
		});
		var l6 = document.getElementById('link6');
		l6.href = browser + 'heatmap/?columns=' + encodeURIComponent(columns) + '&filterColumns=' + encodeURIComponent(filterColumns) + '&heatmap=' + encodeURIComponent(heatmap6);
	};
</script>
<body>
	<a id=link1>Sample highlight Example 1:</a> highlight samples of specific sample IDs, such as THR30_0820_S01 or THR30_0861_S01
	<br><br>
	<a id=link2>Sample highlight Example 2:</a> highlight samples matching an arbitary criteria, such as TARGET samples
	<br><br>
	<a id=link3>Sample filtering Example 1:</a> specify (filter to) what samples to show in a view using a predicate, such as TARGET samples
	<br><br>
	<a id=link4>Sample filtering Example 2:</a> specify samples in a view using a predicate that includes a boolean term, such as TARGET and TCGA samples (use boolean OR)
	<br><br>
	<a id=link5>Sample filtering and highlight at the same time:</a> specify samples in a view using a predicate (e.g. just show TARGET samples), as well as highlight specific samples by IDs, such as TARGET-40-0A4I6O-01A-01R
	<br><br>
	<a id=link6>Sample filtering using data in a hidden filter column:</a> useful when you want to filter samples using data not displayed on the screen. You can use <i>HIDDEN FILTER COLUMN</i>. For exmaple, filter the samples to < 5 years old, but you don't want to actually display the age column on the screen.  
</body>
</html>

Metadata Specification

metadata (.json file) specification

MAPs

MAPs are tsne, umap, pca embeddings in 2D or 3D, or spatial maps for spatical data.

map is a list in the .json metadata file

For each map

"label" free text. Display label of the map, should be easily readable by users

"dataSubType" a string. Describe the nature of the map, must be embedding, spatial . Note this is the dataSubType attribute for the map, not the dataSubType attribute for the file

"dimension" a list of strings. They are the column headers of the dimension columns in the data file. They are used to retrieve data from db.

If it is a spatial map, there might be microscopy image(s) associated with each map.

"unit" (optional, only relevant to spatial map) a string. The unit of map values, e.g. pixel, micrometer

"image" (optional, only relevant to a spatial map with associated images) an array of images, each image has its own parameters. See below.

For each image

"label" free text. Display label of the image, should be easily readable

"path" file path to the image file

"offset" an array of integers. Image offset in pixel in x and y dimension. See below for conversion from spatial coordinate values in map to pixel position in this image.

pixel_in_image_x = image_scalef * spatial_coordinate_x + offset_x
pixel_in_image_y = image_scalef * spatial_coordinate_y + offset_y

"transcript" (optional, only relevant to a spatial transcriptomics map) an array of transcript data, each has its own json parameters. See below.

Note. The transcript coordinate must be in the same unit and scale as the map. Therefore no scaling or offset are needed to convert transcript coordinate and map coordinate.

"label" free text. Display label of the transcript data, should be easily readable

"path" file path to the transcript datafile

Map examples

Example, map without image

Example, spatial map with matching microscopy image

Example, spatial map with matching microscopy image and transcript data

SURVIVAL TIME UNIT

Surival time unit is displayed on the x-axis of the KM plot. You specify it in metadata file under the "units" attribute.

"units" free text , KM plot x-axis unit, e.g. years, months, days

example

CUSTOM CATEGORICAL PHENOTYPE

You customize the display of features in a phenotype file ("type": "clinicalMatrix") by adding a "clinicalFeature" file and accompanying .json file. To do this there are two steps

Add a "clinicalFeature" reference to the .json file that accompanies the phenotype file. Note the colon notation in example below.
Compose the clinicalFeaure file (tab delimitated) and its .json file.

Below is an example for adding "clinicalFeature" reference in the phenotype file .json metadata

Below is an example clinicalFeature file .json file (clinicalFeature.txt.json)

An example of setting binary 0/1 variables as categorical data in the phenotype file. Xena automatically assumes 0/1 is numerical data when it is loaded, so if you want this data to be displayed as categorical you need to indicate it in the clinicalFeature file.

Below is an example of how you would do this for a feature called "your_featureName".

feature

attribute

value

More information about how to specify missing data as well as how Xena decides if a column is categorical or numerical, see our .

COLUMN DISPLAY NORMALIZATION

For genomic data matrix, the optional metadata parameter colNormalization sets the default display scale. If not specified, the browser automatically determines the scale.

colNormalization: ‘true’ | ‘log2(x)’ | ‘normal2’

true: display centered by column mean, x - column average, example usage is gene expression matrix that already log transformed.
log2(x): display in log2(x+1) scale, example usage is gene expression count matrix
normal2: display value of 2 in the background color (i.e. white), typically used for copy number data where the normal = 2

example

Technical documentation

Setting up Xena for your institution

Deep Linking Into Xena

hashtagExamples

hashtagHTML Code showing how to build examples 1-7

hashtagHTML code for highlighting samples examples

hashtagBase URL and URL construction

hashtagcolumns parameter

hashtagProperties

hashtagFields for genomic columns

hashtagFields for phenotypic columns

hashtagOptional properties

hashtagfilterColumns parameter

hashtagheatmap parameter

hashtagProperties

Metadata Specification

hashtagMAPs

hashtag"image" (optional, only relevant to a spatial map with associated images) an array of images, each image has its own parameters. See below.

hashtag"transcript" (optional, only relevant to a spatial transcriptomics map) an array of transcript data, each has its own json parameters. See below.

hashtagMap examples

hashtagSURVIVAL TIME UNIT

hashtagCUSTOM CATEGORICAL PHENOTYPE

hashtagAn example of setting binary 0/1 variables as categorical data in the phenotype file. Xena automatically assumes 0/1 is numerical data when it is loaded, so if you want this data to be displayed as categorical you need to indicate it in the clinicalFeature file.

hashtagCOLUMN DISPLAY NORMALIZATION

Setting up Xena for your institution

Deep Linking Into Xena

hashtagExamples

hashtagHTML Code showing how to build examples 1-7

hashtagHTML code for highlighting samples examples

hashtagBase URL and URL construction

hashtagcolumns parameter

hashtagProperties

hashtagFields for genomic columns

hashtagFields for phenotypic columns

hashtagOptional properties

hashtagfilterColumns parameter

hashtagheatmap parameter

hashtagProperties

Metadata Specification

hashtagMAPs

hashtag"image" (optional, only relevant to a spatial map with associated images) an array of images, each image has its own parameters. See below.

hashtag"transcript" (optional, only relevant to a spatial transcriptomics map) an array of transcript data, each has its own json parameters. See below.

hashtagMap examples

hashtagSURVIVAL TIME UNIT

hashtagCUSTOM CATEGORICAL PHENOTYPE

hashtagAn example of setting binary 0/1 variables as categorical data in the phenotype file. Xena automatically assumes 0/1 is numerical data when it is loaded, so if you want this data to be displayed as categorical you need to indicate it in the clinicalFeature file.

hashtagCOLUMN DISPLAY NORMALIZATION

Technical documentation

Examples

HTML Code showing how to build examples 1-7

HTML code for highlighting samples examples

Base URL and URL construction

columns parameter

Properties

Fields for genomic columns

Fields for phenotypic columns

Optional properties

filterColumns parameter

heatmap parameter

Properties

MAPs

"image" (optional, only relevant to a spatial map with associated images) an array of images, each image has its own parameters. See below.

"transcript" (optional, only relevant to a spatial transcriptomics map) an array of transcript data, each has its own json parameters. See below.

Map examples

SURVIVAL TIME UNIT

CUSTOM CATEGORICAL PHENOTYPE

An example of setting binary 0/1 variables as categorical data in the phenotype file. Xena automatically assumes 0/1 is numerical data when it is loaded, so if you want this data to be displayed as categorical you need to indicate it in the clinicalFeature file.

COLUMN DISPLAY NORMALIZATION

Examples

HTML Code showing how to build examples 1-7

HTML code for highlighting samples examples

Base URL and URL construction

columns parameter

Properties

Fields for genomic columns

Fields for phenotypic columns

Optional properties

filterColumns parameter

heatmap parameter

Properties

MAPs

"image" (optional, only relevant to a spatial map with associated images) an array of images, each image has its own parameters. See below.

"transcript" (optional, only relevant to a spatial transcriptomics map) an array of transcript data, each has its own json parameters. See below.

Map examples

SURVIVAL TIME UNIT

CUSTOM CATEGORICAL PHENOTYPE

An example of setting binary 0/1 variables as categorical data in the phenotype file. Xena automatically assumes 0/1 is numerical data when it is loaded, so if you want this data to be displayed as categorical you need to indicate it in the clinicalFeature file.

COLUMN DISPLAY NORMALIZATION