Basic Step-by-Step Tutorial

Advanced Step-by-Step Tutorial

Video Tutorials

Overview of Xena (2 min)

Beginner Tutorial (17 min)

Advanced Tutorial (55 min)

Recording of tutorial given for NCI in May 2021. Includes closed captioning.

https://cbiit.webex.com/cbiit/lsr.php?RCID=acf4ea46dd9e41338662f0ba1ac59754

Workshop Cheatsheet/Handout

How do I ...

How do I ... guides are useful if you have a specific question.

Request a workshop

Workshops are a great way to teach a group of people how to use Xena. They can be 1-hour, 1/2-day, or 1-day in length. Currently we are only giving workshops remotely via Zoom or a similar technology. We give workshops both within the USA and internationally. Please contact us for more information: genome-cancer@soe.ucsc.edu

Description

This tutorial is made for those who have never used Xena but who have completed Section 1 of the Basic Tutorial. We will cover how to make box plots and bar charts using our Charts and Statistics View and how to add another column of data, in particular phenotype data, to the view.

Prerequisites

This tutorial assumes you have done Basic Tutorial: Section 1. Basic Tutorial: Section 2 is recommended but not required. This tutorial begins where the Basic Tutorial: Section 2 ends. A live link to the end of Basic Tutorial: Section 2 is at the beginning of this tutorial.

Estimated time needed

Part A: 5 min

Part B: 15 min

Learning goals

Part A

• Create a box plot using the Charts and Statistics View

Part B

• Add another column of data to the view

• Add phenotype data to the view

• Create a bar chart using the Charts and Statistics View

Tutorial

In the Basic Tutorial: Section 1 we found that patient's samples that have aberrations in EGFR have higher expression. These aberrations could be mutations or copy number amplifications.

In the Basic Tutorial: Section 2 we created two subgroups: patient's samples that have aberrations in EGFR and those without. We ran a Kaplan Meier survival analysis and found that there was no difference in survival between these two groups.

Now we are going to use the subgroups created in the Basic Tutorial: Section 2 to see if there is a statistical difference in gene expression between the two subgroups. We will also look at whether samples from male or female patients have more aberrations.

Part A

We found that patient's samples that have aberrations in EGFR have higher gene expression. Now we are going to investigate if this difference in gene expression statistically significant.

Ending Screenshot

We can now see that patient's samples with EGFR aberrations have statistically higher gene expression.

Steps

1. Click the 3-dot column menu at the top of the gene expression column (don't worry if you start with another column - you will be selecting the correct columns in the steps ahead).

2. Click 'Compare subgroups', since we want to compare the group of samples who have aberrations in EGFR to the group of samples that do not.

3. Click the dropdown for 'Show data from' and choose 'column C: EGFR - gene expression RNAseq - HTSeq - FPKM-UQ'.

4. Click the dropdown for 'Subgroup samples by' and choose 'column B: (mis OR infra) OR C:>0.5 - Subgroup'.

5. Click 'Done'.

Video of steps

Part B

We will now investigate how EGFR aberrations compare between samples from men and women.

Ending Screenshot

We can now see that EGFR aberrations are more common in samples from females.

Steps

1. Click the 'x' in the upper right corner to exit Chart View.

2. Hover between columns B and C until 'Click to insert a column' becomes visible. Click on it.

3. Choose 'Phenotypic', click in the search bar, and choose 'Advanced'.

4. Type 'gender' into the search bar, select 'gender.demographic' from the dropdown menu, and click 'Done'.

5. Click the column menu at the top of column C and choose 'Chart & Statistics'. Note that this is just another way to enter Chart View.

6. Click 'Compare subgroups', since we want to compare the group of samples who have aberrations in EGFR to the group of samples that do not.

7. 'column C: gender.demographic' should already be selected for 'Show data from'. If not, select it.

8. 'column B: (mis OR infra) OR C:>0.5 - Subgroup' should already be selected for 'Subgroup samples by'. If not, select it.

9. Click 'Done'.

Video of steps 1-4

Video of steps 5-9

Test your knowledge

Description

This tutorial is made for those who have basic knowledge of how to use Xena. We will cover how to view whole chromosome and how to use the advanced dataset menu to access datasets such as exon expression.

Prerequisites

This tutorial assumes basic knowledge of how to build and read a Visual Spreadsheet. To get this, go through Basic Tutorial: Section 1.

Estimated time needed

10 min‌

Learning goals

Create a visual spreadsheet that with a chromosome-wide column and data from the advanced dataset menu.

Tutorial

We will look at the ERG-TMPRSS2 gene fusion in patients from the TCGA Prostate Cancer study.

ERG is an oncogene that expressed at low levels in normal prostate tissue. Some patient's prostate cancer samples have higher expression of ERG. These samples tend to have an intra-chromosomal deletion that fuses ERG to TMPRSS2. TMPRSS2 is expressed at high levels in normal prostate tissue. This allows ERG to use the TMPRSS2 promoter to increase ERG expression.

​Ending Screenshot​

We can now see that there are many patient's samples with relatively high expression of ERG (column B). This relatively high expression is not uniform across the exons of ERG, but instead is in the exons closer to the 3' end of the gene (column C). Looking at column D, we can see that these samples also have an intra-chromosomal deletion of part of chromosome 21. If we hover over the genes at either end of the deletion, we can see that the end points fall within ERG and TMPRSS2.

Steps

1. Start at https://xenabrowser.net/

2. Type 'TCGA Prostate Cancer (PRAD)', select this study from the drop down menu, and click 'To first variable'.

3. Type 'ERG', select the checkbox for Gene Expression and click 'To second variable'.

4. Type 'ERG', click 'Show Advanced', select the checkbox for 'IlluminaHiSeq' under 'exon expression RNAseq', and click 'Done'.

5. Click the text 'Click to insert a column' after column C. Type 'chr21', select the checkbox for Copy Number and click 'Done'.

6. Click on the filter menu and select 'Remove samples with nulls'

7. Click on the handle in the lower right corner of column E, copy number for chromosome 21. Move it to the right to make the column bigger.

8. Click and drag within column E, copy number for chromosome 21 to zoom into the intra-chromosomal deletion.

Video of steps 1-4

‌Video of steps 5-8

Test your knowledge

Description

This tutorial is made for those who have never used Xena. We will cover how to create a Visual Spreadsheet with gene expression, mutation, and copy number variation data.

Prerequisites

This tutorial assumes basic knowledge of

• gene expression, copy number variation, and mutational genomic sequencing data

• how a change in copy number variation or mutations can lead to a change in gene expression

• The Cancer Genome Atlas (TCGA)

These resources can help you gain basic knowledge of these concepts:

Estimated time needed

Part A: 5 min

Part B: 10 min

Learning goals

Part A

• Create a Visual Spreadsheet

• Compare data across columns

Part B

• Move columns

• Resize columns

• Zoom in and out

Tutorial

We are going to look at EGFR aberrations in patients with lung adenocarcinomas using TCGA data. We will be looking at mutations and copy number aberrations and how they change gene expression.

Part A

Our goal is to build a Visual Spreadsheet and understand the relationship between the columns of data.

Link to Ending Screenshot

Steps

1. Start at our home page http://xena.ucsc.edu/ and click on 'Launch Xena'. You are now in our Visual Spreadsheet Wizard.

2. Type 'GDC TCGA Lung Adenocarcinoma (LUAD)', select this study from the drop down menu, and click 'To first variable'.

3. Type 'EGFR', select the checkboxes for Gene Expression, Copy Number, and Somatic Mutation, and click 'To second variable'.

Video of steps:

Biological interpretation

We can see that samples from TCGA patients that have high expression of EGFR (red, column B) tend to either have amplifications of EGFR (red, column C) or mutations in EGFR (blue tick marks, column D).

Part B

We will now move the columns to change the sort order and resize columns. We will zoom in to the whole Visual Spreadsheet and also within a column.

Steps

1. Move columns. Click column C, copy number variation, and drag it to the left so that it becomes the first column after the samples column (i.e. column B). Note that the samples are now sorted by the values in this column.

2. Resize columns. Click the handle in the lower right corner of column D, mutation. Move it to the right to make the column bigger.

3. Zoom in on a column. Click and drag within column D. Release to zoom.

4. Zoom out on a column. Click the red zoom out text at the top of column D.

5. Zoom in on samples. Click and drag vertically in any column in the Visual Spreadsheet to zoom in on these samples.

6. Zoom out on samples. To zoom out click either 'Zoom out' or 'Clear zoom' at the top of the Visual Spreadsheet.

Video of step 1

Video of step 2

Video of steps 3-6

Test your knowledge

Steps:

1. Add a column of data. Enter your gene or list of genes, select 'Gene Expression' and click done.

2. From the column menu at the top of the new column you created, select 'Chart & Statistics'

3. Choose 'Compare Subgroups'

4. Click the dropdown for 'Show data from' and choose your gene expression column.

5. Click the dropdown for 'Subgroup samples by' and choose the cancer type column.

6. Choose if you would like a box plot or violin plot and click 'Done'.

TCGA matched normal vs. GTEx normal

There are two main sources of normal expression data in Xena. The first is matched normal tissue samples from TCGA patients. These patient's samples are called "solid tissue normals" and are taken from tissue near the tumor. Normal samples from TCGA patients are typically limited in number but some cancer types may have enough for a robust statistical comparison. It is important to note that their proximity to tumor means it may have tumor microenvironment signal. The second source of normal expression is GTEx. GTEx has expression data from normal tissue of individuals who do not have cancer. There are typically many more samples in GTEx then in TCGA solid tissue normals. However, experimental sample processing are different from TCGA, which may lead to batch effects.

Using the TCGA TARGET GTEx study

You can use the TCGA TARGET GTEx study for both types of 'normal' samples. Data from the study is from the UCSC RNA-seq Compendium, where TCGA, TARGET, and GTEx samples are re-analyzed by the same RNA-seq pipeline. This pipeline involved re-aligning the reads to hg38 genome and calling gene expression using RSEM and Kallisto methods. Because all samples are processed using a uniform bioinformatic pipeline, batch effects due to different computational processing is eliminated. Note that the samples from this study have only undergone per-sample normalization.

To compare tumor vs normal, you will need to filter down to just the samples you want to compare and then compare gene expression between your groups of samples.

There are four gene expression datasets in this study. Two are normalized using with-in sample methods. The 'RSEM norm__count' dataset is normalized by the upper quartile method, the 'RSEM expected__count (DESeq2 standardized)' dataset is by DESeq2 normalization. Therefore, these two gene expression datasets should be used.

Running a Differential Gene Expression Analysis

If you are looking to compare just a few genes, you can use our chart view to run your analysis. If you are looking to run a genome-wide differential gene expression analysis, you can use our DEA feature. Note that we only allow users to run our Differential Gene Expression Analysis on less than 2,000 samples total. Thus, you will need to filter to run this analysis on this dataset.

Tutorial

To make a KM plot, click on the column menu at the top of a column and choose 'Kaplan Meier Plot'.

Example

More information about KM plots can be found in our Overview of Kaplan Meier Plots.

Description

This tutorial is made for those who have basic knowledge of how to use Xena. We will cover how to view tumor and normal samples from healthy and diseased individuals together, and how to compare gene expression for one or more genes between tumor and normal samples.

We will be using both GTEx samples as our normal samples as well as TCGA matched normal samples. More information on GTEx normal samples can be found here:

Prerequisites

This tutorial assumes basic knowledge of how to build and read a Visual Spreadsheet. To get this, go through Basic Tutorial: Section 1.

Estimated time needed

Part A: 10 min

Part B: 5 min

Learning goals

Part A

• Build a visual spreadsheet with the columns primary site, sample type, study, and gene expression for the TCGA TARGET GTEx study.

• Filter to just colon samples.

Part B

• Create a box plot using the Charts and Statistics View

Tutorial

We will compare MYC gene expression between patient's samples in TCGA colon adenocarcinoma tumor samples and individuals normal colon tissue in GTEx.

Part A

Our goal is to build a visual spreadsheet with the columns 'primary site', 'sample site', 'study', and gene expression for MYC for the TCGA TARGET GTEx study. We will then filter to samples in the colon.

Ending Screenshot

We can now see that normal samples tend to have lower MYC gene expression.

Steps

1. Start at our home page http://xena.ucsc.edu/ and click on 'Launch Xena'. You are now in our Visual Spreadsheet Wizard.

2. Type 'TCGA TARGET GTEx', select this study from the drop down menu, and click 'To first variable'.

3. Type 'MYC', select the checkbox for Gene Expression and click 'To second variable'.

4. Choose 'Phenotypic' and select the checkboxes for 'sample type', 'study' and 'Primary site', and click 'Done'.

5. Type 'colon' in the samples search bar and choose 'Keep samples'.

Video of steps 1-4

Video of step 5

Part B

Our goal is to see if the difference in gene expression, where normal samples tend to have lower MYC gene expression, is statistically significant.

Ending Screenshot

We can now see that patient's tumor samples, both recurrent, primary, and metastatic, have higher expression compared to normal tissue, both patient's matched normal tissue from TCGA and unmatched individual's normal tissue from GTEx.

Steps

1. Click the column menu for column B (MYC gene expression) and choose 'Charts & Stats'

2. Click 'Compare subgroups', click the dropdown for 'Show data from' and choose 'column B: MYC - gene expression RNAseq - RSEM norm_count' if it is not already selected

3. Click the dropdown for 'Subgroup samples by' and choose 'column C: Sample Type'.

4. Leave the chart type as 'box plot', and click 'Done'.

Video of steps 1-4

Test your knowledge

Description

This tutorial is made for those who have basic knowledge of how to use Xena. We will cover how to load your own data into a Xena hub on your computer. We will then view the data in the Xena Browser

We will be viewing RNAseq and clinical data from the Chinese Glioma Genome Atlas (CGGA).

Prerequisites

To format the datasets you will need access to a spreadsheet application, such as Microsoft Excel.

To load the data into a Local Xena Hub you will need a computer where you have installation privileges.

To visualize the data, you will need basic knowledge of how to build and read a Visual Spreadsheet, how to filter samples, how to create a box plot in Chart View, and how to run a Kaplan Meier Analysis. To get this go through the Basic Tutorials, starting with Basic Tutorial: Section 1.

Estimated time needed

Part A: 10 min

Part B: 15 min

Part C: 10 min

Learning goals

Part A

• Download data from CGGA

• Use Microsoft Excel or another spreadsheet application to make small formatting adjustments. These adjustments are only to enable Kaplan Meier analyses. Data can be visualized as is.

Part B

• Download and install a Local Xena Hub

• Load data into the Xena Hub on your computer

Part C

• Make a visual spreadsheet from the data in the Xena Hub on your computer

• Create a box plot

• Run a Kaplan Meier Analysis

Tutorial

Part A

We will start with downloading the files from the CGGA. These files already conform to our data file requirements. This is because they are matrices that have sample IDs along one axis and probe, gene, or clinical data names along the other. Additionally, the files are tab-delimited.

For more information see:

While we can load the files exactly as is, we will perform a small format adjustment so that we can create a Kaplan Meier plot. Our Kaplan Meier analyses need two columns of clinical data to create a plot: the event/censor column and the time to that event/censor. These columns need to be specially named so that our Kaplan Meier analysis recognizes them. For Overall Survival, the column names need to be 'OS' and 'OS.time'.

For more information on other supported columns for our Kaplan Meier analysis see:

Genomic and Clinical data to load into Xena

Steps to format the file

1. Go to http://www.cgga.org.cn/download.jsp and scroll to the DataSet ID mRNAseq_693.

2. Click to download the 'Clinical Data' and 'Expression Data from STAR+RSEM'. Unzip the files. The resulting files should be named 'CGGA.mRNAseq_693.RSEM-genes.20200506.txt' and 'CGGA.mRNAseq_693_clinical.20200506.txt'.

3. Open CGGA.mRNAseq_693_clinical.20200506.txt

   in a spreadsheet application like Microsoft Excel. If the spreadsheet application asks, these files are tab-delimited.

4. Rename the column header 'OS' to be 'OS.time'.

5. Rename the column header 'Censor (alive=0; dead=1)' to be 'OS'.

6. Save and close the file.

Part B

Steps

If this is your first time viewing your own data

1. Click 'VIEW MY DATA' at the top of the screen. You should see a screen similar to this:

2. Click 'Open UCSC Xena' to set your computer up to automatically open the Xena Hub when you come to this page in the future.

3. Click on 'download & run a Local Xena Hub' to download the correct installer for your computer.

4. Double-click the installer to install the Xena Hub on your computer. Follow onscreen instructions, which vary by operating system.

Please see our FAQ/Troubleshooting Guide or contact us if you encounter any problems.

If you already have viewed your own data

1. Click 'VIEW MY DATA' at the top of the screen. You should see a screen similar to this:

2. Wait for 30 seconds. If you allowed your browser to open the Xena Hub every time you come to this screen, then it will open the Xena Hub and this dialog box will close. If you did not, you will need to go to your Applications Folder and open UCSC Xena yourself

Whether you have viewed your own data before or not, you should arrive at a screen like this:

Steps to load the data files

1. Click the 'Load Data' button.

2. Click 'Select Data File', choose 'CGGA.mRNAseq_693_clinical.20200506.txt', and click 'Next'.

3. Choose 'Phenotypic Data' and click 'Next'.

4. Choose 'The first column is sample IDs' and click 'Next'

5. Choose 'These are the first data on these samples.', change the study name to 'CGGA', and click 'Import'.

6. Choose 'Load more data'

7. Click 'Select Data File', choose

   'CGGA.mRNAseq_693.RSEM-genes.20200506.txt', and click 'Next'.

8. Choose 'Genomic Data' and click 'Next'.

9. Confirm selection of 'The first row is sample IDs' and click 'Next'

10. Choose 'I have loaded other data on these samples and want to connect to it.', select 'CGGA' from the drop down, and click 'Import'.

Video of steps 1-6

Video of steps 7-10

Part C

We will look at the chromosome 1p-19q co-deletion in Chinese glioma patients and compare this to IDH1 expression.

Ending Screenshot for Visual Spreadsheet (end of step 5)

Ending Screenshot for Box plot (end of step 11)

Ending Screenshot for Kaplan Meier Analysis (end of step 13)

Steps

1. Click on 'Visualization' in the top menu bar.

2. Type 'CGGA', choose 'CGGA' as the study and click 'To first variable'.

3. Enter the gene 'IDH1', choose 'CGGA.mRNAseq_693.RSEM-genes.20200506.txt', and click 'To second variable'

4. Choose 'Phenotypic', click '1p19q_codeletion_status', and click 'Done'

5. The dataset authors annotated samples without a 1p/19q co-deletion status with 'NA'. To remove these samples, type 'NA' in the samples search bar and choose 'Remove Samples' from the filter actions menu drop down.

6. Compare IDH1 expression between samples with a 1p/19q co-deletion and those that do not. To do this, click on the column menu for column B (IDH1 expression) and choose 'Charts & Stats'.

7. Choose 'Compare Subgroups'.

8. Click the dropdown for 'Show data from' and choose 'column B: IDH1 - CGGA.mRNAseq_693.RSEM-genes.20200506.txt'.

9. Click the dropdown for 'Subgroup samples by' and choose 'column C: 1p19q_codeletion_status - CGGA.mRNAseq_693_clinical.20200506.txt'.

10. Click 'Done'.

11. Close the chart using the 'x' in the upper left corner.

12. Run a Kaplan Meier analysis comparing patients with high IDH1 expression to those with low IDH1 expression. To do this, click on the column menu for column B (IDH1 expression) and choose 'KM plot'

Video of steps 2-4

Video of steps 5-10

Video of steps 11-12

To make more than 2 sample subgroups, enter multiple search terms, such as 'C:>15' into the search box. Separate each search term with a ';'.

This can be used for a number of situations:

• To divide a single numerical column into more than 2 subgroups (e.g. geneA high, geneA mid, and geneA low)

• To make subgroups over the expression of two genes such that you get 4 subgroups (e.g. geneA high + geneB high, geneA low + geneB high, geneA high + geneB low, geneA low + geneB low)

• To make subgroups over the expression of a gene and a categorical column (e.g. geneA high + Estrogen Receptor positive, geneA low + Estrogen Receptor positive, geneA high + Estrogen Receptor negative, geneA low + Estrogen Receptor negative)

• To make subgroups over two categorical columns (e.g. Estrogen Receptor positive + HER2 positive, Estrogen Receptor negative + HER2 positive, Estrogen Receptor positive + HER2 negative, Estrogen Receptor negative + HER2 negative)

See below for an example of each.

Examples

Dividing a single numerical column into more than 2 subgroups (e.g. geneA high, geneA mid, and geneA low)

In the screenshot below you can see that column D that ranges from 7.3 to 12. If you wanted to have 3 groups: 7.3 - 9, 9 - 10, and 10 - 12, you would enter:

C:>9 ; C:>10

into the search bar and then choose 'New subgroup column' from the filter/subgroup drop down menu.

Ending Screenshot

Making subgroups over the expression of two genes such that you get 4 subgroups (e.g. geneA high + geneB high, geneA low + geneB high, geneA high + geneB low, geneA low + geneB low)

Click here to see our separate help page for this scenario

Making subgroups over the expression of a gene and a categorical column (e.g. geneA high + Estrogen Receptor positive, geneA low + Estrogen Receptor positive, geneA high + Estrogen Receptor negative, geneA low + Estrogen Receptor negative)

In the screenshot below you can see that column E (ERBB2 gene expression) that ranges from 10 to 16. If you wanted to have 4 groups: ERBB2 > 13 + Estrogen Receptor positive, ERBB2 <= 13 + Estrogen Receptor positive, ERBB2 > 13 + Estrogen Receptor negative, ERBB2 <= 13 + Estrogen Receptor negative), you would enter:

E:>13 ; C:Negative

into the search bar and then choose 'New subgroup column' from the filter/subgroup drop down menu.

Ending screenshot

Making subgroups over two categorical columns (e.g. Estrogen Receptor positive + HER2 positive, Estrogen Receptor negative + HER2 positive, Estrogen Receptor positive + HER2 negative, Estrogen Receptor negative + HER2 negative)

In the screenshot below, if you wanted to have 4 groups: Estrogen Receptor positive + HER2 positive, Estrogen Receptor negative + HER2 positive, Estrogen Receptor positive + HER2 negative, Estrogen Receptor negative + HER2 negative you would enter:

C:Negative ; D:Negative

into the search bar and then choose 'New subgroup column' from the filter/subgroup drop down menu.

Ending bookmark

Sometimes not all samples in a dataset have data. This can happen for a variety of reasons, such as a particular patient's sample did not undergo one or more analyses. In this case, we use gray, or 'null' to show that there is no data.

To remove null data use the 'Remove samples with nulls' shortcut in the filter menu.

Example

Use the find samples feature (highlighted below) to make subgroups:

First, search for all the patient's samples you want in one of your subgroups. Next, click the Filter + Subgroup menu and choose 'New subgroup column'.

This will create a new subgroup column. All the patient's samples that matched your search term will be in one subgroup labeled as 'true' and all the samples that did not match your search term will in the other subgroup labeled as 'false'.

Example

In this example we are creating two subgroups in the TCGA Lung Adenocarcinoma study: patient's samples with aberrations in EGFR and those without. These aberrations could be mutations or copy number amplifications.

Steps

1. Type '(mis OR infra) OR C:>0.5' into the samples search bar. This will select samples that either have a missense or inframe deletion '(mis OR infra)', or where copy number variation (column C) is greater than 0.5. Note that I arbitrarily choose a cutoff of 0.5.

2. Click the filter menu and select 'New column subgroup'. This will create a new column that has samples that met our search term marked as 'true' (ie. those that have an EGFR aberration) and those that did not meet our search term as 'false' (ie. those that do not have an EGFR aberration).

The Visual Spreadsheet allows you to add an arbitrary number of columns of any data type (mutation, copy number, expression, protein, phenotype, methylation, etc) on any number of patient's samples into a spreadsheet-like view. We line up all columns so that each row is the same sample, allowing you to easily see trends in the data. Data is always sorted left to right and sub-sorted on columns thereafter.

Get started by going to the and following the wizard to enter your data of interest.

Making a Visual Spreadsheet

The wizard on the screen will guide you to choose a study to view and TWO columns of data to view on those samples. Note that if you do not choose at least two columns, the wizard will not exit and let you interact with the data.

Selecting a cohort

You can select a cohort either by choosing 'Help me select a cohort' and searching our cohorts for you cancer type, etc. or by choosing 'I know the study I want to use' and searching for the partial or full name of the cohort you are interested in.

Adding a Gene or Position

Enter a HUGO gene name or a dataset-specific probe names (e.g. a CpG island). You can enter one gene or multiple genes. Separate multiple genes with a space, comma, tab, or new line.

To display a genomic region, enter the genomic region, choose your dataset and click 'done'. We recongize chromosomes (e.g. chr1), arms of chromosomes (e.g. chr19q), and chromosomes coordinates (e.g. chr1:100-4,000).

Selecting a Dataset

After entering a gene or probe name, you will need to select one or more datasets.

Basic Datasets

We have pre-selected default datasets for most cohorts. These datasets are selected based because they are the most used datasets. Typically there is a default mutation, copy number, and expression dataset.

Advanced Datasets

Xena also has more datasets than those listed in the Basic Menu. Depending on the cohort, these can include DNA methylation, exon expression, thresholded CNV data and more. To access them, click on 'Show Advanced' below:

More information on basic datasets

Video of making a Visual Spreadsheet

After you made a Visual Spreadsheet

Overview

Patient samples are on the y-axis and your columns of data are on the x-axis. We line up all columns so that each row is the same sample, allowing you to easily see trends in the data. Data is always sorted left to right and sub-sorted on columns thereafter.

If you entered a single gene

If you entered a single gene, that gene will be listed at the top of the column. If there are multiple probes mapped to that gene in the dataset you selected they will be displayed as subcolumns ordered left to right in the direction of transcription.

If you selected a positional dataset, such as segmented copy number variation or mutation we will display the gene model will be displayed at the top of the column. The gene model is a composite of all transcripts of the gene. Boxes show different exons with UTR regions being short and CDS regions being tall. We display 2Kb upstream to show the promoter region. Use the column menu to toggle to show intronic regions.

If you entered multiple genes

If you entered multiple genes, each gene will be listed as a subcolumn for that dataset. If there are multiple probes mapped to that gene in the dataset (i.e. if you entered a single gene then you would see the probes as subcolumns), then the probes are averaged for a single value per gene.

Note that if you entered more than one gene and selected a mutation dataset, we will only show the first gene. If you wish to see multiple mutation columns, please enter each gene individually and click 'done'

If you entered a chromosome or chromosome position

When displaying a chromosome range, genes will be shown at the top of the column, with dark blue genes being on the forward strand and red genes being on the reverse strand. Hovering over a gene will display the gene name in the tooltip. Note that introns are always shown in this mode.

Data values

Individual values vary by dataset. The legend at the bottom of the dataset will tell you the units for your particular dataset, including any normalization that was performed. If a sample does not have data for a column, it will show as gray and be labeled as 'null'.

If the entire column is gray this means we did not recognize the gene, probe, or position. If you believe this to be in error, please try an alternate name.

More information about a dataset can be found in the dataset details page. To get there, click on the column menu and choose 'About'.

Sample sorting

The Xena Browser uses the y-axis for samples and the x-axis/columns for genomic/phenotypic features. Data from a single sample is always on the same horizontal line across all columns, allowing you to see screen-wide trends. The Xena Browser orders samples left to right first by the first columns, then the second, etc. If there are multiple genes, identifiers, probes within in a column, samples is ordered from left to right by 1st sub-column, then 2nd sub-column, and so on.

Numerical data are ordered in descending order (e.g. 3.5, 1.2, ...). Categorical data (e.g. stage, tumor type, etc) are ordered by categories. CNV data is sorted by the average of the entire column. Positional mutation data is ordered by genomic coordinates (from 5'->3') and then by the predicted impact of the mutation. Both CNV and positional mutation data has the option to instead sort by the zoomed region. Click the column menu at the top of the column and choose 'Sort by zoom region avg'.

To reverse the ordering, click the column menu at the top of the column and chose 'Reverse sort'

Move a column/change the sample sorting

As the sample sort order is controlled by the left most columns, it can be useful to explore the data by moving a different column to the left.

To move a column click on the column header and drag a column to the right or left.

Zooming

Click and drag any where in any column to zoom in in either direction. Zoom out to all samples by clicking the 'Clear Zoom' at the top. Zoom out to the whole column by clicking the red 'x' at the top of a column.

Tooltip

Resize a column

You can change the size of a column by clicking on the bottom right corner of a column and dragging to a new size.

Add another column

You can add another column of data by clicking on 'Click to add column' either on the right edge of the visual spreadsheet or by hovering between columns until 'Click to insert column' displays'.

This page details how to create subgroups based on the expression of 2 genes so that you create the following 4 subgroups:

• geneA expression is high AND geneB expression is high

• geneA expression is high AND geneB expression is low

• geneA expression is low AND geneB expression is low

• geneA expression is low AND geneB expression is high

To do this enter a search terms for each gene, such as 'C:>15' or 'D:<0.6' into the search box and separate each search term with a ';'.

Example

You can see in the search bar the expression used to make column A using the example genes of CD44 and CD24.

Also note that you can use this feature on columns besides gene expression, such as copy number variation, etc. You can also use it on categorical features, for instance to compare expression of a gene and the patient's gender (male or female). Simply add the gender column to the Visual Spreadsheet and enter 'female' for one of the search terms above.

To view multiple types of cancer patients side-by-side you will need to start with a Pan-Cancer dataset and then filter down to just the cancer types you want to see.

The contains the latest data from the PanCan Atlas project, including many hand curated datasets. It also contains some legacy TCGA data across all cancer types, including GISTIC 2 CNV estimates and miRNAseq estimates.

Generalized Steps

1. Add the phenotype column cancer type abbreviation that details the cancer type.

2. Search for the cancer type you are interested in, making sure that it is listed in the phenotype column. Separate each cancer type by 'OR'. Example: 'lgg OR gbm'. Click the Filter + subgroup menu next to the search bar and select 'Keep Samples'.

Example

Below is an example for viewing breast and ovarian cancer together for the TCGA PanCan Atlas

When you are in the Xena Visual Spreadsheet, hovering the mouse over any data on the screen will trigger a tooltip to show up at the top of the view.

To freeze the tooltip, you need to "Alt-click", i.e. hold on the ALT key on your computer and at the same time click the left mouse button.

To unfreeze the tooltip, click on the close (X) icon.

This can be helpful if you want to click on the link to take you to the UCSC Genome Browser, where you can view more information about those genomic coordinates.

When there are no overlapping segments, Xena displays the value and color of the copy number segment as indicated in the column legend at the bottom of the column.

When there are overlapping segments, Xena follows these steps:

1. Compute overlaps by slicing segments that overlap with other segments. For example if there was one segment from chr1:10000-20000 and a second segment from chr1:10050-10100, then resulting segments from this step would be chr1:10000-10050, chr1:10050-10100, and chr1:10100-20000.

2. For each segment defined in step 1, determine which segments in the original data overlap with this segment.

3. Divide data segments into those that are greater than copy number neutral (i.e. are amplifications) and those that are less than copy number neutral (i.e. are deletions). Average the segments for each of these two groups.

4. Find the colors corresponding to the two averages from step 3. Then pick a color that is in between those two colors on the color wheel. An example would be that if the amplifications are red and deletions are blue, the resulting color from a strong amplification and a strong deletion would be purple. Note that copy number neutral in this example would be white.

To change the color threshold, click on the column menu at the top and choose 'Display'. From there click 'custom', enter your new thresholds, and click 'Done'.

To change the color, click on the column menu at the top and choose 'Display'. From there choose a new set of colors from the drop down.

You've run your analysis and are ready to publish your paper - congratulations! Cite the paper below to thank Xena and keep our project funded.

Goldman, M.J., Craft, B., Hastie, M. et al. Visualizing and interpreting cancer genomics data via the Xena platform. Nat Biotechnol (2020). https://doi.org/10.1038/s41587-020-0546-8

You can also read our paper for free at bioRxiv: https://www.biorxiv.org/content/10.1101/326470v6

Samples that have mutation data are white with a dot or line for the mutation for where the mutation falls in relation to the gene model at the top of the column. Mutation data is colored by the functional impact:

• Red - Deleterious

• Blue - Missense

• Orange - Splice site mutation

• Green - Silent

• Gray - Unknown

Samples for which there is no mutation data are gray with no dot or line, and are marked as 'null'.

More details for 'Somatic mutation (SNP and INDEL)' datasets

Red --> Nonsense_Mutation, frameshift_variant, stop_gained, splice_acceptor_variant, splice_acceptor_variant&intron_variant, splice_donor_variant, splice_donor_variant&intron_variant, Splice_Site, Frame_Shift_Del, Frame_Shift_Ins

Blue --> splice_region_variant, splice_region_variant&intron_variant, missense, non_coding_exon_variant, missense_variant, Missense_Mutation, exon_variant, RNA, Indel, start_lost, start_gained, De_novo_Start_OutOfFrame, Translation_Start_Site, De_novo_Start_InFrame, stop_lost, Nonstop_Mutation, initiator_codon_variant, 5_prime_UTR_premature_start_codon_gain_variant, disruptive_inframe_deletion, inframe_deletion, inframe_insertion, In_Frame_Del, In_Frame_Ins

Green --> synonymous_variant, 5_prime_UTR_variant, 3_prime_UTR_variant, 5'Flank, 3'Flank, 3'UTR, 5'UTR, Silent, stop_retained_variant

Orange --> others, SV, upstreamgenevariant, downstream_gene_variant, intron_variant, intergenic_region

Note that we are case insensitive when we color for these terms.

For the gene-level mutation datasets (Somatic gene-level non-silent mutation):

Red (=1) --> indicates that a non-silent somatic mutation (nonsense, missense, frame-shif indels, splice site mutations, stop codon readthroughs, change of start codon, inframe indels) was identified in the protein coding region of a gene, or any mutation identified in a non-coding gene

White (=0) --> indicates that none of the above mutation calls were made in this gene for the specific sample

Pink (=0.5) --> some samples have two aliquots. In the event that in one aliquot a mutation was called and in the other no mutation was called, we assign a value of 0.5.

Description

This tutorial is made for those who have never used Xena but who have completed Section 1 of the Basic Tutorial. We will cover how to filter to just the samples you are interested in, how to create subgroups, and how to run a Kaplan Meier survival analysis.

Prerequisites

This tutorial assumes completion of the Basic Tutorial: Section 1. This tutorial begins where the Basic Tutorial: Section 1 ends.

Estimated time needed

Part A: 7 min

Part B: 15 min

Part C: 5 min

Learning goals

Part A

• Search for samples of interest

• Remove samples with no data

Part B

• Make subgroups

• Rename subgroups

Part C

• Run a Kaplan Meier survival analysis

• Use a custom time endpoint

Tutorial

In the Basic Tutorial Section 1 we found that we found that samples from patients that have aberrations in EGFR have relatively higher expression. These aberrations could be mutations or copy number amplifications.

Now we are going to look at whether those patient with aberrations in their samples also have a worse survival prognosis.

Part A

Our goal is to remove patient's samples with no data (i.e. null) from the view. This will make the view look cleaner and remove irrelevant samples from our Kaplan Meier survival analysis.

Ending Screenshot

Steps

1. Type 'null' into the samples search bar. This will highlight samples that have 'null' values in any column on the screen. Null means that there is no data for that sample for that column.

2. Click the filter menu and select 'Remove samples'.

3. Delete the search term.

Video of steps

Shortcut for Part A

Instead of typing 'null' and removing those samples from the view, you can also use the 'Remove samples with nulls' shortcut in the filter menu.

Part B

Our goal is to create two subgroups, those patient's with samples with aberrations in EGFR and those patient's samples without aberrations in EGFR. We will then name the subgroups.

Ending Screenshot

Steps

1. Type '(mis OR inframe) OR B:>0.5' into the samples search bar. This will select samples that either have a missense or inframe deletion '(mis OR inframe)', or where copy number variation (column B) is greater than 0.5. Note that I arbitrarily choose a cutoff of 0.5.

1. Click the filter menu and select 'New subgroup column'. This will create a new column that has samples that met our search term marked as 'true' (ie. those that have an EGFR aberration) and those that did not meet our search term as 'false' (ie. those that do not have an EGFR aberration).

2. Click the column menu for the column we just created (column B) and chose 'Display'.

3. Rename the display so that samples that are 'true' are instead labeled as 'EGFR Aberrations' and the samples that are 'false' are instead labeled as 'No EGFR Aberrations'. Click 'Done'

4. Delete the search term. This will remove the black tick marks for matching samples.

Video of steps 1

Video of steps 2-4

Part C

Now that we have our subgroups we will run a Kaplan Meier survival analysis. Note that TCGA survival data is in days, hence the x-axis will be in days.

Ending Screenshot

We can now see that there is no difference in survival between patients with EGFR aberrations and those without.

Steps

1. Click the column menu at the top of column B.

2. Choose 'Kaplan Meier Plot'.

3. Click 'Custom survival time cutoff' at the bottom of the Kaplan Meier plot.

4. Enter 3650, as this is 10 years.

Video of steps

Test your knowledge

Description

This tutorial is made for those who have basic knowledge of how to use Xena. We will cover how to use the pick samples feature, how to view multiple genes in a single column, how to enter and view a signature, and how to run a differential expression analysis.

Prerequisites

This tutorial assumes basic knowledge of how to build and read a Visual Spreadsheet. To get this, go through Basic Tutorial: Section 1. It also assumes basic knowledge of filtering. To get this, go through Basic Tutorial: Section 2.

Estimated time needed

Part A: 10 min

Part B: 5 min

Part C: 15 min

Learning goals

Part A

• Create a visual spreadsheet with single column with multiple genes.

• Filter to only Primary Tumor samples using the Pick Samples mode.

• Remove nulls using the option in the filter menu

Part B

• Enter and view a gene expression signature

Part C

• Run a differential expression analysis.

Tutorial

We will investigate the PAM50 molecular subtypes in breast cancer. PAM50 is a 50-gene signature that classifies breast cancer into five molecular intrinsic subtypes: Luminal A, Luminal B, HER2-enriched, Basal-like, and Normal-like.

Part A

We will make a visual spreadsheet where we can explore the relationship between the PAM50 subtype call and the 50 genes that make up the PAM50 subtype call.

Ending Screenshot

Steps

1. Start at https://xenabrowser.net/

2. Type 'TCGA Breast Cancer (BRCA)', select this study from the drop down menu, and click 'To first variable'.

3. Choose 'Phenotypic', select 'sample_type' from the dropdown menu, and click 'To second variable'.

4. Choose 'Phenotypic', click on 'advanced', type 'pam' into the search bar, select 'PAM50Call_RNAseq' from the dropdown menu, and click 'Done'. This will exit the wizard.

5. Click on 'Click to insert a column' after column C. Copy and paste the 50 genes, choose 'Gene Expression', and click 'Done'.

6. Click the handle in the lower right corner of column D, mutation. Move it to the right to make the column bigger.

Video of steps 1-4

Video of steps 5-6

Steps continued

1. Click on the picker icon next to the filter menu to enter pick samples mode.

2. Click on the Primary Tumor samples.

3. Click the filter menu and select 'Keep samples'.

4. Exit pick samples mode by clicking on the picker icon again.

5. Click the filter menu and select 'Remove samples with nulls'.

Video of steps 1-5

Part B

We will now look at the TFAC30 gene signature and see how it relates to the PAM50 subtype calls. This gene expression signature over 30 genes predicts pathologic complete response (pCR) to preoperative weekly paclitaxel and fluorouracil-doxorubicin-cyclophosphamide (T/FAC) chemotherapy.

Ending Screenshot

Steps

1. Click on 'Click to insert a column' after column D. Copy and paste the signature below, choose 'Gene Expression', and click 'Done'. Note you need to include the '=' as this tells Xena that you want the signature rather than to see all the genes individually.

We can now see that patient's samples that are labeled as 'Her2' and 'Basal' are predicted to be more likely to achieve pCR on TFAC chemotherapy.

Video of step 1

Part C

We will run a differential expression analysis comparing Basal samples to Luminal A and Luminal B samples.

Steps

1. Click the column menu for the PAM50 subtype call (column C) and chose 'Differential Expression'. This will open a new tab where we will run the analysis.

2. Choose the first subgroup to be 'Basal' and the second subgroup to be 'LumA' and 'LumB'. Hold the shift key while clicking to select multiple groups.

3. Click 'Submit'.

Video of steps 1-3

Categorical features

Our search is 'contains' search, meaning the term you enter can be at the beginning, end or in the middle of a matched term. Our search is case-independent. An example is

IIA

will match 'Stage IIIA' and 'Stage IIA'. To specify a specific string, use quotes

"Stage IIA"

Numerical and Continuous features

You can specify a certain column and mathematical expression such as

A:>2

which will find all values greater than 2 in the first column. We support the following operators

• = (equal)

• >= (less than or equal)

• >= (greater than or equal)

• < (less than)

• > (greater than)

• != (not equal)

Mutation data

You can search any annotation on a mutation, such as the functional impact, protein position, or gene name itself

To find all samples with mutations with the protein change, enter:

V600E

To find all samples where the functional impact has the text 'frame' or 'nonsense' in it:

frame OR nonsense

To find all samples that have a mutation, search the gene annotation:

TP53

To find all samples that do not have a mutation, use the negation of the gene annotation:

!=TP53

No data or 'null'

To find all samples that do not have data in one or more columns, use:

null

and choose 'Remove samples'. To find all samples that do not have data for just one column, use:

B:null

Sample IDs

Enter a sample ID to find a sample of interest. An example:

TCGA-DB-A4XH

If you are searching for multiple sample IDs, you will need to separate each by an 'OR'. You can copy and paste a list of sample IDs into the search bar as long as they are separated by a space, tab, or return (new line).

TCGA-DB-A4XH OR TCGA-2F-A9KO-01 OR TCGA-02-0001

Search a specific column

To make it easy to search a specific column, we use shorthand to annotate the first column as 'A:', the second as 'B:', etc. An example is

A:YES

This will search ONLY the first column for the word 'YES'. Note that we will retain your original search if you move the columns around.

Boolean operators: OR, AND, and !=

You can enter multiple search terms and we will match all of them with an implicit 'AND'. We also support 'OR'.

Use parentheses to group search terms. For example:

"Stage II" (B:Negative OR C:Negative)

will search for samples that match 'Stage II' in any column and are 'Negative' for either the second or third column.

You can also use '!=' to negate a term such as:

!=null

which will match all samples that have data across all columns.

Kaplan Meier Survival Analyses are a way of comparing the survival of groups of patients. More information on what a Kaplan Meier analysis is can be found in this article

Generating a plot

To generate a KM plot, click on the column menu at the top of a column and choose 'Kaplan Meier Plot'.

Features

Sample groups

For numerical or continuous features, you will have the option of having 2 groups of samples, 3 groups of samples, or viewing the upper vs lower quartile. For 2 groups, we divide the samples on the median. For 3 groups, we divide samples into the upper third, middle third, and lower third.

When viewing the upper vs lower quartile, note that we only include samples that are greater than (not greater than or equal to) the upper quartile, and the same for the lower quartile.

Note that all are used to calculate the median and other dividing values, whether or not they have survival data. To see which samples have survival data, add the column 'OS' from the phenotype data.

If more than one sample has the same value, we put the samples in a group together, even if this means the groups end up being unequal in size.

For categorical features, we only show the first 10 categories.

For mutation features, we divide samples into those with any mutation and those without. To make different groups (e.g. samples with nonsense mutations vs those without), create your own subgroups and run a KM plot on the new column

We remove samples with 'null' data for all plots.

Type of survival

We default to Overall Survival. Users can select different end points if they are available. An example of this is in the TCGA PanCancer Study.

Survival time cutoff

We default to the last time any individual in the plot was known to be alive. You can change this to be 1-year or 5-year survival by changing the time cutoff at the bottom of the screen. The statistics will automatically recalculate. TCGA data uses days as their measurement of time.

PDF

You can generate a high quality PDF by clicking the PDF icon.

Download

You can download the data used to generate the KM plot using the download icon. It will download the Event and Time to Event columns, in addition to the sample ID, patient ID, groups, and underlying data.

Statistics used

When there are multiple curves or lines in a KM plot, Xena Browser compares the different Kaplan–Meier curves using the log-rank test. The Browser reports the test statistics (𝜒 2) and p-value (𝜒 2 distribution). Data is retrieved in real-time from Xena Hub(s) to a user's web browser and the test is performed in the browser to maintain your data privacy.

The statistics the Xena Browser reports are equivalent to R's survival package, survdiff, with rho=0 (default in R).

Exceptions

If all patients in a particular group (i.e. line) are censored before any event happens for the whole population (including all the groups), we exclude this group from the statistical analysis and perform the log-rank test on the remaining groups. We do this because we have no way to know the number of people at risk for this particular group at any of event times, and therefore can not compute any statistics for this group. R handles this exception in the same way. Although this group is removed from the statistical analysis, we still display the group in the KM plot.

Duplicate samples

Note that we do not automatically remove duplicate patients (for instance if there is a tumor and a normal sample from the same patient). You can determine if there are duplicate patients by looking for the "!" icon next to the p value. Learn how to remove duplicate samples.

More information on how to load your own survival data into Xena

1. First, make sure that the gene or genes that you want to compare across your groups are on screen.

2. Click on the charts icon in the top right and choose 'Compare subgroups'.

3. Click the dropdown for 'Show data from' and choose your gene expression column.

4. Click the dropdown for 'Subgroup samples by' and choose your subgroup column.

5. Choose if you would like a box plot or violin plot and click 'Done'.

Example

Below we look at patient's samples that have aberrations in EGFR in the TCGA Lung Adenocarcinoma study. We will investigate if patient's samples that have aberrations in EGFR (mutations or copy number amplifications) have higher expression.

Ending Screenshot

Steps

1. Click the graph icon in the upper right corner to enter Chart View.

2. Click 'Compare subgroups', since we want to compare the group of samples who have aberrations in EGFR to the group of samples that do not.

3. Click the dropdown for 'Show data from' and choose 'column C: EGFR - gene expression RNAseq - HTSeq - FPKM-UQ'.

4. Click the dropdown for 'Subgroup samples by' and choose 'column B: (mis OR infra) OR C:>0.5 - Subgroup'.

5. Click 'Done'.

Video of steps

Generalized Steps

1. Add the phenotype column that details the cancer type

2. Search for the cancer type you are interested in, making sure that it is listed in the phenotype column. Click the Filter + subgroup menu next to the search bar and select 'Keep Samples'.

For TCGA Pan-Cancer (PANCAN)

For the TCGA PanCan (PANCAN), you will want to add the phenotype column:

cancer type abbreviation

For TCGA TARGET GTEx

For the TCGA TARGET GTEx, you will want to add the phenotype columns:

main category

study

primary_site

If your plot has an '!' icon next to the p-value this means that some patients are in your plot twice. This can happen when A) a patient has both a tumor and normal sample or when a patient has a metastasis that is part of the dataset and/or B) a tumor sample was split into multiple aliquots and then run through the same analysis twice.

This page will guide you on how to remove duplicates due to A. If there are duplicates due to B you will need to download the data, decide how to resolve any inconsistencies between the multiple aliquots and load it into your own Xena Hub.

Example of error icon

Ending Screenshot

Removing duplicates

1. Add the data column of 'sample type' from the Phenotype data

2. Filter to only samples that are 'Primary tumor' by typing 'primary' into the filter search box. Next, click the filter icon next to the filter search box and chose 'Filter'. This will filter out all samples that are not primary tumor.

3. Run your KM analysis by clicking the caret menu at the top of the column and choosing 'Kaplan-Meier plot' It will now only have primary tumor samples in it.

Example

Removing duplicate samples from TCGA Lower Grade Glioma KM analysis

Ending Screenshot

Workshop cheatsheet/handout

FOXM1a, FOXM1b, FOXM1c transcript expression in tumor vs. normal samples

PDL1 and PD1 expression across 39 cancer types in TCGA and TARGET

MGMT gene expression ~ promoter DNA methylation in GBM

ERG-TMPRSS2 fusion in prostate cancer

KM plot of breast cancer PAM50 subtypes

Genetic separation of lower grade gliomas: one characterized by loss of chromosomes 1p & 19q, the other by TP53 & ATRX mutations

Copy number for EGFR, PTEN, chromosome 1, 7, 10, 19 in TCGA brain tumors

Mutation pile-ups in intron enhancers in ICGC lymphoma

Xena mutation views supports examination of both coding and non-coding mutations from whole genome analysis. We support viewing mutations from both gene- or coordinate- centric perspective. In the gene-centric view, you can dynamically toggle to show or hide introns from the view. This figure shows the frequent intron mutations in 321 samples from the ICGC lymphoma cohorts. These 'pile-ups' would be not be visible if viewing mutations only in the exome. These intron mutations overlap with known enhancers regions (Mathelier 2015).‌

Stemness scores across TCGA cancer types

To run a differential gene expression analysis, click on the 3 dot column menu at the top of a categorical column (not a numerical column) and choose 'Differential Expression'.

This will take you to new page where you will define the sample subgroups you would like to compare (note that you can select multiple categories for a single subgroup).

After you have your subgroups, scroll to the bottom and click 'submit'.

This will start the analysis, which make take a while to run depending on the size of the dataset. As the results are completed, the web page will update. Scroll to see more results. Once the analysis is finished it will say 'Done' at the top of the page.

More details

The Advanced Visualization parameters only apply to the PCA or t-SNE plot. They do not apply to any other analyses.

Running it on your own data

We disable running our differential gene expression analysis on your own data since we send the data in the analysis to various websites, which may not be secure. There are 3 options to run our analysis on your own data:

Adding in new samples

We apologize but we don't provide a simple way to do this because of the batch effects that would be present when combining most data across studies. You will need to download the data you wish to combine from TCGA, combine it yourself outside of Xena, and then load it into your own Xena hub.

Adding in more data on TCGA patient's samples, such as new subtype calls

1. Load your data into your own Xena hub, making sure to select the cohort that you want to view your data side-by-side with when loading it.

Genomic Signatures

Note that if you want to view a genomic signature on our gene expression data, you can do so using our

Use the search box at the top of the screen to first pick/find your samples of interest. Then filter to keep or removes these samples, create a new subgroup column, or zoom.

The bar highlighted above allows you to search all data on the screen for your search term. Note that it will not search data that is not on the screen. Samples that match your criteria are marked with a black bar in the Visual Spreadsheet.

Searching for samples

You can search for samples by either typing in the search bar or by clicking on the dropper icon to enter the pick samples mode. The pick samples mode will allow you to click on a column to select samples. The search term for your picked samples will appear in the search bar. To exit the pick samples mode, click on the dropper icon again.

Note the pick samples mode tends to work best if the column you are selecting from is the first column.

Example of pick samples mode

Filter + Subgroup menu

Once you have your sample(s) of interest, click on the filter + subgroup menu and choose to:

Keep samples: Keep only the samples which match your criteria.

Remove samples: Remove the samples which match your criteria.

Clear sample filter: Remove ALL filters currently applied.

Remove Samples with nulls: Removes samples that have no data for one or more columns. Equivalent to typing 'null' in the search bar and choosing 'Remove samples'.

Zoom: Zoom to the samples that meet your criteria. Shift-click to zoom out.

Search bar history

Once you have either filtered, created a subgroup column, or zoomed to samples, your search term will be added to the search history. Access the search history by clicking the downward facing arrow at the upper right of the search bar.

Changing subgroup labels

Once the subgroup column is created, users can change the labels from "true" or "false" to, for example, "wild type" or "EGFR mutant" by adjusting the column display settings. To access these select the three dot menu at the top of the column and choose 'Display'

Chart View will generate bar plots, box plots, violin plots, scatter plots, and distribution graphs using any of the columns in a Visual Spreadsheet. Statistics, such as and , and will be calculated automatically.

Enter Chart View

To get to the chart view click on the icon indicated below by the red box or use the column menu and select 'Chart & Statistics'.

Build a chart

Once you enter Chart View, it will ask you a series of questions about what type of graph you are trying to make.

Compare subgroups will allow you to compare groups of patient's samples, either those that you have made or via a categorical feature, such as sample type. It will build the appropriate graph depending on whether you have selected a continuous numerical or categorical column. This option will let you make box plots, violin plots, and bar charts.

See a distribution will let you see a histogram distribution of the data in a single column. The column can have sub-columns, either multiple probes or multiple genes, which will instead create a plot with multiple box plots.

Make a scatterplot will make a scatterplot from two continuous numerical columns. The second column can have multiple sub-columns, either multiple probes or multiple genes, which will create overlapping scatterplots

If an option is grayed out, this means that you do not have enough or the right type of data on the screen. Return to the Visual Spreadsheet and add more data.

After building a chart

We show statistics in the upper right corner of the screen for most graphs. If we detect it will take some time run the statistics we may instead show a button with 'run stats', so that you can decide if you would like to run the statistical test.

Advanced options available under the graph will allow you to change the scales of the axes. If you are viewing a scatterplot it will also allow you to color the points by a column of data.

Return to the Visual Spreadsheet

To return to the Visual Spreadsheet, click either the icon in the upper left, or the 'x' close button.

We support a wide variety of data types including:

• SNPs and small INDELs

• Large structural variants

• Segmented copy number, gene-level copy number

• Gene-, Transcript-, Exon-, Protein-, LncRNA-, and miRNA-expression

• DNA methylation (genes and probes)

• Phenotype, clinical data

• Signature scores, classifications, derived parameters

The type of data in each study vary considerably and depend on what analyses that particular study performed

If you need a particular type of data, please see choosing a study/cohort to help you find the study with that type of data

This help page is for the Genomic Data Commons (GDC) data we host from GDC Data Release 41.0 - August 28, 2024. We display all GDC open access genomic data and its accompanying phenotype/clinical data. Explore the GDC data on Xena.

In addition to the data from the GDC, we added two new phenotype/clinical fields to all GDC cohorts: age_at_earliest_diagnosis.diagnoses.xena_derived and age_at_earliest_diagnosis_in_years.diagnoses.xena_derived. This was done because some GDC cohorts had multiple diagnoses, each with their own age_at_diagnosis.diagnoses. When there were multiple ages the Xena Visual Spreadsheet would display these fields as a category. In order to have a field that could always be displayed as a continuous feature, we created the age_at_earliest_diagnosis.diagnoses.xena_derived field that has the smallest value when there were multiple entries. age_at_earliest_diagnosis_in_years.diagnoses.xena_derived was created similarly, but also dividing the number of days by 365.

For this release, we worked to not have samples that have no genomic data and only have phenotype/clinical data. This should make visualizing data in our Visual Spreadsheet easier.

You can still view data from the older GDC Data Release v18.0 release - August 28, 2019. This data will be available until October 2025. After October 2025 the data from this release will only be available for download.

CPTAC-3

For the CPTAC-3 cohort, we noted that occasionally samples were pooled into the same aliquot before sequencing was performed. Xena's visualizations are based on the sample-level, thus for these pooled aliquots there are several samples with duplicate data. An example of this is noted for case C3N-03011, where samples C3N-03011-04, C3N-03011-02, and C3N-03011-01 were all pooled into the aliquot CPT0226250007 before sequencing was performed.

Overview

Get started viewing your own data:

1. Install a Local Xena Hub on your computer

2. Start the Local Xena Hub

3. Load the data you want to view

4. View the data

We support most types of genomic and/or phenotypic/clinical/annotation data. Genomic data needs to be values called on genes, transcripts, exons, probes or some other identifier. Phenotypic/clinical/annotation data can be almost anything, including patient data (e.g. age, set, etc), clinical data (survival data for a KM plot), and other data such as gene fusion calls, regulon activity, immune scores, and more. Samples can be bulk tissue, cell lines, cells, and more. We do not visualize raw data such as FASTQs or BAMs.

Data can be your own or from another source, like GEO or a publication.

We support tab-delimited (.tsv and .txt) and Microsoft Excel files (.xlsx and .xls). Data on a Local Xena Hub can only be viewed or accessed by the same computer on which it is running, keeping private data secure.

The Local Xena Hub must be installed and running in order to load data, as well as any time you want to view data. The Local Xena Hub will remember previously loaded data.

Installing a Local Xena Hub

Click on VIEW MY DATA. You will be prompted to download and install a local Xena Hub.

Double click on the download to begin the installation of the Xena Hub. Follow the wizard to finish the install.

System requirements for Xena Hub

• Mac: OSX 10.7 and above

• Windows: 64-bit

• Linux: ability to run a .jar file

Starting/running a Local Xena Hub

After installing a local Xena Hub, go back to VIEW MY DATA to auto-start the Hub. If it does not automatically start, refresh the page or double click on the Xena Hub application on your computer. The Xena Hub application should be in your Applications folder for Mac and Windows. Note that it will take up to one minute to start up.

Loading data into a Local Xena Hub

Most people load data into their Local Xena Hub through our website wizard, which leads you through the loading process step by step. Note that you will want to make sure your data is properly formatted ahead of time.

You can also load data via the command line.

Viewing data from a Local Xena Hub

Click on VISUALIZATION. If your study is not already selected as step 1 of the wizard, then select it from the drop down and click 'Done'. Note that if you did not enter a study name your data will be under 'My Study'.

Gene names and identifiers for genomic data

When you loaded your genomic data we asked what type of genes, transcripts or probes you used. If you selected one of the options from the drop down menu then you can enter HUGO gene names or the identifiers in your file. If you did not select one of the options then you will need to enter the identifiers as they appear in your file.

Help! I don't see my study listed

You Local Xena Hub must be running to view any data that you have loaded into it. Please ensure it is running on your computer. You can also check which studies are on your hub and what data is in them by going to the My Computer Hub page.

Data security

How does Xena ensure the security of my data?

Xena does not utilize a central rendering service, or require hubs to be publicly accessible on the internet like, for example, the UCSC Genome Browser does. Data flows in one direction, from hubs to the user agent. If the user installs a Xena Hub on their laptop, the hub is as secure as the laptop. If the user installs a Xena Hub on a local network, behind a firewall, the hub is as secure as the local network.

The Xena Browser accesses data from a local Xena Hub on the same computer by requesting data from http://127.0.0.1. The local Xena Hub will make the data within it available at this address. The local Xena Hub will only answer requests made form the user's own computer.

Users will need to use a web browser that supports this if they wish to use a Xena Hub on the loopback interface. At the time of writing, this includes Chrome, and Firefox, but not Safari.

Is there any data that is considered to not be secure?

A very limited set of metadata is considered to be not secure in the Xena architecture model. This includes cohort names and samples names. This metadata is visible to other hubs in the following scenarios. When the user selects a cohort, all hubs are queried for samples on that cohort. When the user selects a data field, the hub holding that field is queried with the field ID (e.g. gene, probe, transcript, phenotype) and all cohort sample IDs. This means, for example, that two hubs holding data on the same cohort will see the union of sample IDs from that cohort. While data queries are not made available publicly, a malicious person could gain entry to a Xena Hub and comb through logs for these queries. For these reasons, these metadata fields should not contain private information.

To run a GSEA analysis, click on the 3 dot column menu at the top of a categorical column (not a numerical column) and choose 'GSEA'.

This will take you to new page where you will define the sample subgroups you would like to compare (note that you can select multiple categories for a single subgroup).

After you have your subgroups, choose a gene set library, scroll to the bottom and click 'submit'.

This will start the analysis, which make take a while to run depending on the size of the dataset. As the results are completed, the web page will update. Scroll to see more results. Once the analysis is finished it will say 'Done' at the top of the page.

More details

The gene expression dataset chosen for a specific study/cohort is the same gene expression dataset as the one in the Basic Datasets menu.

The Advanced Visualization parameters apply to the PCA or t-SNE plot, as well as the blitzGSEA analysis itself.

Note that the GSEA analysis runs blitzGSEA, a faster implementation of a traditional GSEA analysis.

Running it on your own data

We disable running our GSEA analysis on your own data since we send the data in the analysis to various websites, which may not be secure. Currently we only offer a docker image as a method for running this pipeline on your own data. Please contact us if you need help setting this up.

Why can't I interact with the browser? I can see one column of data but I can't do anything.

The Visual Spreadsheet wizard asks that you add at least TWO columns of data before interacting with the browser. This is because Xena was designed to allow you to find correlations within the data and you need more than one type of data on the screen to find a trend.

Add another column of data and click Done. You can always delete this column after you have completed the wizard if it is not needed.

Help! My gene is showing up as gray.

In general, we recognize genes from the HUGO gene name space. If you gene name isn't recognized, try looking at Gene Card and see if other names listed there are recognized.

Genomic signatures, sometimes expressed as a weighted sum of genes, are an algebra over genes, such as "ESR1 + 0.5*ERBB2 - GRB7". Once a signature is entered, the value for each gene name for each sample are substituted and the algebraic expression is evaluated.

Entering a signature

1. Open the Add column menu

2. Enter '=' and then your signature into the gene entry box

3. Select 'gene expression' as the dataset

4. Click 'Done'

Example: TFAC30 Gene Signature

Hess et.al. identified 30 genes whose gene expression profile is predictive of complete pathologic response to chemotherapy treatment in breast cancer.

Gene signature

=E2F3 + MELK + RRM2 + BTG3 - CTNND2 - GAMT - METRN - ERBB4 - ZNF552 - CA12 - KDM4B - NKAIN1 - SCUBE2 - KIAA1467 - MAPT - FLJ10916 - BECN1 - RAMP1 - GFRA1 - IGFBP4 - FGFR1OP - MDM2 - KIF3A - AMFR - MED13L - BBS4

Here we can see that the predicted chemo response signature is high in the basal subtype and low in luminal subtype. Additionally, the signature is high for ER negative samples and low for ER positive samples.

Bookmark: https://xenabrowser.net/?bookmark=2401ccb792e256d7397008b24af20565

Hess KR, et. al. Pharmacogenomic predictor of sensitivity to preoperative chemotherapy with paclitaxel and fluorouracil, doxorubicin, and cyclophosphamide in breast cancer. J Clin Oncol. 2006 Sep 10;24(26):4236-44. Epub 2006 Aug 8.

Signatures datasets

We also have a number of signature datasets under the TCGA Pan-Cancer study from the PanCan Atlas project:

• gene programs

• HRD score, genome-wide DNA damage footprint

• Immune Signature Scores (Denise Wolf et al)

• Stemness score (DNA methylation based)

• Stemness score (RNA based)

To use these signatures, go to the dataset pages (links above) to see what the names of the specific signatures are (under Identifiers). Then in the visualization enter the name of the specific signature as a gene, click 'Advanced', choose the appropriate dataset, and click 'Done'

Creating a bookmark

To bookmark a view, click on 'Bookmark' in the top navigation bar. From here you can either click 'Bookmark' to create a bookmark URL or click 'Export' to export a file that can then be imported back to the browser.

When you click 'Bookmark' you will then need to click 'Copy Bookmark' to copy the bookmark URL to your copy buffer. Large views may take a second or two to generate a URL.

More information: Bookmark vs. Export/Import

The 'Bookmark' option will store all the data in view on our servers and provide you a link. This is the easiest way to share a view. Note that if you have any private data in view, this option will be disabled to preserve your privacy. Please also note that if you lose the link there is no way to get it back.

If you chose Export, it will give you a file with everything Xena needs to recreate your view. You can then save this file and import it back into Xena. While this option can be a bit cumbersome, it will allow you to share private data. Note that these files are still only guaranteed for 3 months, though they may last for longer.

Recent Bookmarks

The 'Recent Bookmarks' option will temporarily show the 15 most recent bookmarks you have created. This can be useful if you're constructing many bookmarks. Note that this menu is frequently reset so do not use this as permanent storage for a bookmark.

FAQ

How do I make a bookmark with private data in view?

When you create a bookmark link, we save the data in view on our servers. To protect user data privacy, we have disabled this option when private data is in view. Please use the Export/Import option instead.

About

Xena's Transcript View shows transcript-specific expression or isoform percentage for 'tumor' TCGA data and 'normal' GTEX data. It allows you to compare the distribution of these values for two groups of patient samples.

This tool was created by Akhil Kamath as part of Google Summer of Code 2017. Akhil was advised by Angela Brooks and Brian Craft. Thank you Akhil for all your work!

Usage

Enter the HUGO name of your gene of interest and click 'OK'. Choose your two studies of interest from the two drop down menus. Each row in the visualization shows the transcript, transcript structure and density plots showing range of expression of that transcript.

Change the units from TMP (Transcripts Per Million) to isoform percentage using the drop-down near the top. To zoom on a row, click on it. To zoom out, click on the row again.

Data behind the view

All RNAseq data was generated by the Toil pipeline recompute done by the UCSC Computational Core using the RSEM package. All transcripts are from Gencode V23 comprehensive annotation.

Exon numbering

For this visualization, we numbered the exons using an in-house automated method which may not line up with exon numbering in the literature. This method is subject to change and should not be relied on to denote any exon going forward.

Regions that are intronic in all transcripts are removed. The remaining exonic regions are numbered 1..N. Different exons within a given region are labeled starting with ‘a’ for the left-most exon (in transcript direction).

For example, exon 3 is the unique exon in the third exonic region. Exons 4a and 4b are two different exons in the fourth exonic region.

Another way to say this is: different exons across all transcripts which overlap transitively will be assigned the same integer. So if one transcript has exons 4a and 4c, there must be exons in other transcripts that overlap them, and each other.

UCSC TumorMap is a separate project developed by the Stuart Lab at UCSC. We link to them to help users gain another perspective on the data they are seeing in Xena. From their Overview page:

TumorMap is a tool that enables grouping samples based on their omic signatures in a visually accessible way. Similar to dimensionality reduction methods, Tumor Map method takes a high-dimensional omics space and produces a two dimensional visualization. Unlike most dimensionality reduction methods, the TumorMap method is able to combine multiple types of omics data (e.g. mRNA expression and methylation data types in a single map). Furthermore, TumorMap is an interactive tool that allows navigating through a tumor landscape that represents a heterogeneous multi-dimensional and multi-platform omic space of oncogenic signatures.

In the TumorMap, each node is a sample and clusters of samples indicate groups with similar oncogenic signatures and genomic alteration events. The samples in a map may be colored by various molecular, clinical, diagnostic, prognostic, and phenotypic annotations (e.g. tumor type, molecular subtype, etc.) to visualize associations with the data type used in clustering.

The four ways to download data

1. Download data in a single column of a Visual Spreadsheet In a Visual Spreadsheet, click on the column Hamburger menu, then "Download" to download just the data from the column.

2. Download data in an entire Visual Spreadsheet In a Visual Spreadsheet, clicking on the download icon in the upper right corner of the spreadsheet.

3. Bulk download a whole dataset file Click top banner "Data Sets" to navigate to the dataset of your interest, where a download url link is in the page. You can also reach the dataset page by clicking on the column Hamburger menu, then "About". Click on the download url to download the entire dataset. Or use "wget", "curl" to download from command line.

4. Via our APIs:

• Python

• R

How do I open the download files?

Our files are tab-delimited or '.tsv'. We recommend opening them in your favorite spreadsheet program, such as Microsoft Excel, which will automatically convert the tabs into new columns. Please note that if you have many thousands of samples, Microsoft Excel will likely have difficulty opening the file. In this case, the command line may work better for you.

The Cancer Genome Atlas (TCGA), a collaboration between the National Cancer Institute (NCI) and National Human Genome Research Institute (NHGRI), has generated comprehensive, multi-dimensional maps of the key genomic changes in 33 types of cancer. The TCGA dataset, describing tumor tissue and matched normal tissues from more than 11,000 patients, is publicly available and has been used widely by the research community. The data have contributed to more than a thousand studies of cancer by independent researchers and to the TCGA research network publications.

TCGA is our most used data resource. We host several versions of the TCGA data.

• TCGA Pan-Cancer Atlas As its concluding project, The Cancer Genome Atlas (TCGA) Research Network completes the most comprehensive cross-cancer analysis to date: The Pan-Cancer Atlas. Xena displays the curated genomics and clinical data generated by the Pan-Cancer Atlas consortium working groups.

• TCGA data from Genomic Data Commons TCGA data uniformly re-analyzed at GDC using the latest Human Genome Assembly hg38. We download all open-access tier data from GDC, compile individual files into datasets organized by cohorts (33 individual tumor cohorts as well as a Pancan cohort. Xena displays the compiled datasets.

• TCGA data in the UCSC RNA-seq Recompute Compendium TCGA data has been co-analyzed with GTEx data using the UCSC bioinformatic pipeline (TOIL RNA-seq) and can be used to compare tumor vs normal gene and transcript expression from the matching tissue of origin. Xena hosts gene and transcript expression results of the UCSC RNA-seq recompute compendium.

• Legacy TCGA data Data generated and published by TCGA Research Network before the Pan-Cancer Atlas publications. Xena displays the level-3 data.

This paper helps clarify the differences between the Legacy TCGA data and the TCGA data on the GDC:

The Xena Gene Sets Viewer https://xenagoweb.xenahubs.net/xena compares gene expression, somatic mutation, and copy number variation profile of cancer related gene sets across cancer cohorts. It queries genomics data hosted on public Xena Hubs, in a similar way as other tools in the Xena Visualization suite. And then it generates gene set visualizations of those data.

Source code:

• Xena Gene Set Viewer

• Xena Analysis Server

Overview

The Gene Set Viewer allows comparison of individual gene sets or pathways and their genes across two cancer tumor sample cohorts as well as comparison within the same sub cohorts.

As an overview, Figure 1 shows two cohorts, the left (olive background, TCGA Ovarian Cancer) and the right (tan background , TCGA Prostate Cancer). Figure 1A shows the selection for the analysis, Gene Set, view limit, and filter (differential versus similar). Figure 1B shows the view comparing the Mean Gene Set Score in the center and individual samples on the right. 1C shows the individual samples, with the hover result showing the sample and score in 1E. 1D provides a link directly into Xena for the given gene set. 1F provides a sharable URL link. 1G provides a login for use in uploading.

Figure 8 shows analysis of a GMT file using the BPA method [citation: thanks to Verena Friedl]. This is only available to logged in users and they may only see their own analysis and are limited to 100 pathways. Logins are any valid google login. Several public pathway sets are available including those curated from the Gene Ontology Consortium (thanks to Laurent-Philippe Albou) as well as those from the Hallmark [cite] and Pancan [cite] analyses.

Analysis

Gene Expression

• BPA GENE EXPRESSION

• PARADIGM IPL

• REGULON ACTIVITY (only avaiable for the LUAD Cohort)

Mutation / CNV

• CNV ∩ MUTATION

• COPY NUMBER

• MUTATION

Sources for the somatic mutation and copy number variation data

• https://xenabrowser.net/datapages/?hub=https://tcga.xenahubs.net:443

• https://xenabrowser.net/datapages/?cohort=Cancer Cell Line Encyclopedia (Breast)

We use the MuPIT 3D protein viewer from Rachel Karchin's lab at John Hopkins to provide this visualization to our users. From their Help Page:

MuPIT interactive is an online tool that allows you to map sequence variants from their genomic position onto protein structures. Viewing a variant on protein structure can be useful in interpreting its potential biological consequences. After mapping, the variants are displayed on an interactive 3d structure. The user may turn variants on and off, and display annotations on the protein structure.

Access this tool by going to our Visualization tab and following the wizard to select samples. Next, enter your gene of interest, click 'somatic mutation' and then click 'Done'. You may need to choose another variable such as 'gene expression'.

Once you have the mutation data you're interested in, click the menu at the top of the column and chose 'MuPIT View'. This will send your mutation data to MuPIT and open their viewer in a new tab.

MuPIT Help: http://mupit.icm.jhu.edu/MuPIT_Interactive/Help.html

Example

Live bookmark of above image

On the left of the figure is Xena mutation column view of ERBB2 somatic mutations from the TCGA breast cancer cohort. Users click on the MuPIT link from the caret menu at the top of the column. It will send all the mutations' genomic positions as well as their recurrence p-values to the MuPIT display. On the right side of the figure, MuPIT displays mutations in various size of bright green spheres. Large spheres for recurrent mutations. Size of the mutation spheres are determined by recurrence p values. The MuPIT display shows these ERBB2 somatic mutations cluster around the ERBB2 active site (ATP binding site in blue and proton acceptor site in teal).

TCGA, TARGET, and GTEx RNA-seq data are uniformly re-aligned to hg38 genome, and re-processed using RSEM and Kallisto methods with gencode v23 annotations to generate expression estimates for ~60,000 genes and ~200,000 transcripts, including many LncRNAs. Xena hosts and displays gene and transcript expression results of this analysis.

International Cancer Genome Consortium (ICGC) goal is to obtain a comprehensive description of genomic, transcriptomic and epigenomic changes in 50 different tumor types and/or subtypes which are of clinical and societal importance across the globe. It includes TCGA data (U.S.A.) plus data contributed by groups from other countries in the International Cancer Genome Consortium. The resource has publically-accessible non-coding somatic mutation data from non-TCGA samples.

The Pan-Cancer Analysis of Whole Genomes (PCAWG) study is an international collaboration to identify common patterns of mutation in more than 2,600 cancer whole genomes from the International Cancer Genome Consortium. Building upon previous work which examined cancer coding regions, this project explored the nature and consequences of somatic and germline variations in both coding and non-coding regions, with specific emphasis on cis-regulatory sites, non-coding RNAs, and large-scale structural alterations.

The NCI's Genomic Data Commons (GDC) provides the cancer research community with a unified data repository that enables data sharing across cancer genomic studies in support of precision medicine.

The GDC supports several cancer genome programs at the NCI Center for Cancer Genomics (), including The Cancer Genome Atlas () and Therapeutically Applicable Research to Generate Effective Treatments (), and many more.

Xena displays gene expression data from the metastatic cancer study published in

Cancer Cell Line Encyclopedia. Detailed genetic and pharmacologic characterization of a large panel (~1100) of human cancer cell lines.

Pediatric data

We have a number of sources of pediatric data

The goal of the Treehouse Childhood Cancer Initiative (Treehouse) is to evaluate the utility of comparative gene expression analysis for difficult-to-treat pediatric cancer patients. Approaching 2000 pediatric tumor data, Treehouse has now assembled a large collection of pediatric cancer RNA-Seq, which, added to adult data, results in a compendium of over 11,000 adult and pediatric tumor-derived gene expression data. Pediatric cancer expression data are from public repository samples and from clinical samples at partner institutions, including UC San Francisco, Stanford, Children’s Hospital of Orange County and British Columbia Cancer Agency. In line with UC Santa Cruz Genomics Institute’s commitment to sharing data and to furthering research everywhere, we have made this data available for all to download and use.

Interested in a dataset we don't have?

In addition to the data itself, we require some metadata about your file. When you use our website to load your data we fill in this metadata for you. When you use the command line, you will need to provide this data in an additional file.

Metadata file requirements

The metadata file is a .json file and follows. The metadata .json file needs to be in the same directory as the data file. The metadata file and the data file need to have the same base name, including any file extensions (e.g. my_first_dataset and my_first_dataset.json OR my_second_dataset.txt and my_second_dataset.txt.json).

There are two required fields: type and cohort.

Type

Type can be:

• 'genomicMatrix' -> where samples are columns and genomic regions are rows. Note that for loading on the command line we do not support the other orientation

• 'clinicalMatrix' -> where samples are rows and phenotypic columns are rows. Note that for loading on the command line we do not support the other orientation

• 'mutationVector' ->

• ‘genomicSegment’->

Example:

Cohort

Cohort is used to know if there are other data on the samples that you are loaded. You can either specify a pre-existing cohort or create your own. Cohort names are displayed on the dataset pages and the cohort drop down menu on the Heatmaps page.

For existing cohorts, you need to enter the cohort name EXACTLY as it appears as the existing cohort name. Note that our cohort names are case sensitive.

Example

Reference

If you are loading a mutation or segmented copy number file you will also need to specify the reference genome. You do not need to specify this for other file types

Example

Probemap

If you are loading a file that has probes, transcripts, or exons and you would like to query your data by gene, you will need to provide a mapping file. You do not need to specify this for other file types.

If you do not see a probemap that will work for you, please let us know.

To reference a probemap you need three files:

1. Include the probemap reference in your data file .json

2. Have the probemap file in the same directory as your data file and data file .json

3. Also have a .json file for the probemap so that we know how to load it

Example data file .json

Example probemap

Example probemap .json file (required to be in the same folder as the probemap)

More information about the metadata

Commands to load data

Put both your .tsv and .json files in your_home_directory/xena/files. Then run the jar, passing in the file name, like so:

→ loads all files

OR

→ loads just file1.tsv

Note that you will need to substitute the name of the .jar. file As of the time of writing (September 20, 2018), the name of the .jar file was cavm-0.22.0-standalone.jar. On linux this will be in the directory where you opened the archive. On Windows or MacOS, use your operating system’s file search capability to search for cavm*jar. On Windows you will need to use the full path to your home directory, instead of “~”.

Note you do not need to load the .json files. Xena will automatically look for these and load them.

Commands to delete data

→ delete just file1.tsv

→ delete file1.tsv and file2.tsv

Help

You can always type:

for help.

There are 2 basic data formats and 2 advanced data formats. Each of these formats has one or more biological data types that it supports.

General Specifications for all data formats

We support most types of genomic and phenotype/clinical/sample annotations. For genomic data we support calls made on the raw data including but not limited to expression calls, mutation calls, etc. This is what TCGA calls ‘Level 3’ data and is typically a value on gene, transcript, probe, etc. We do not support FASTQ, BAMs, or other ‘raw’ files. Please contact us if you have any questions.

We support tab-delimited and Microsoft Excel files (.xlsx and .xls). Tab-delimited files generally have a file name ending in .tsv or .txt, though we do not require this. Note that we load tab-delimited files much faster than Excel files. You can export a Microsoft Excel file as a tab-delimited file using the 'Save as ...' function.

Please do not have any duplicate genes/probes/identifiers or samples. We will allow you to load with duplicates but will only display the first one encountered in the file.

We assume you use a '.' to indicate a decimal place as opposed to a ',' .

Here is a with example data in addition to the examples below.

Basic Genomic data: numbers in a rectangle/matrix/spreadsheet

These are numeric data called on genomic regions (e.g. exon expression or gene-level copy number). This data is in a rectangle where samples are columns and rows are the genomic regions (e.g. HUGO gene symbol, transcript ID, probe ID, etc). We also support samples as rows and genomic regions as the columns (i.e. the opposite orientation). For supported genomic regions, please see .

Supported data types

• RNA-seq expression (exon, transcript, gene, etc)

• Array-based expression (probe, gene, etc)

• Gene-level mutation

• Gene-level copy number

• DNA methylation

• RPPA

• and more ...

An example of a genomic matrix file (in this case, expression):

Basic Phenotypic data: categories or non-genomic in a rectangle/matrix/spreadsheet

These are data on a sample or patient that is categorical in nature (e.g. Tumor Stage or 'wild type' or 'mutant' for a gene) or is numerical but non-genomic (e.g. age or a genomic signature). Samples can be columns and rows can be phenotype/clinical/sample orientation or vice versa. We support both orientations.

Supported data types

• phenotype/patient/clinical data (age, weight, if there was blood drawn, etc)

• sample/aliquot data (where it was sequenced, tumor weight, etc)

• derived data (regulon activity for a gene, etc)

• genomic signatures (EMT signature score, stemness score, etc)

• other (whether a sample has an ERG-TMPRSS2 fusion, whether a sample has WGS data available, etc)

Categorial vs numerical data

We support both numerical and categorical data. For numerical data please use a blank field for any samples which may be missing data. For categorical data you can use a blank field or "NA" for any samples which may be missing data.

To have it be treated as a numerical field please use a blank field.

An example of a phenotype matrix file:

Advanced Segmented data

For segmented data, we require the following 5 columns: sample, chr, start, end, and value. Note that your column headers must be these names exactly!

Please use 'NA' to indicate no data.

Supported data types

• copy number

We currently accept hg38, hg19, hg18 coordinates.

Example segmented copy number data with required columns:

Advanced Positional data

For positional data, we require 6 columns: sample, chr, start, end, reference, alt. Note that your column headers must be these names exactly!

Supported data types

• mutation data

We currently accept hg38, hg19, hg18 coordinates.

Example mutation data with the six required columns, plus the gene column:

Advanced Other data

Institutional Xena Hubs allow you to share data, visualizations, and analyses with a specific group of people. Xena Hubs can be set up on any server or in the cloud. You control who has access to the Xena Hub by controlling who has access to the server on which it is hosted.

To make your data publicly available, simply make the server open to the web.

Download

First, download the ucsc_xena_xxx.tar.gz file to your server, here:

The file to download is the one called "Tar archive, no updater or JRE - recommended for linux server developments". Uncompress and extract the .jar file (cavm-xxx-standalone.jar). The current version is 0.25.0.

Start the hub

The hub can be started with "java -jar cavm-xxx-standalone.jar". Passing option --help will display usage information.

Note that you need to use Java 8 to run the hub.

There are several options you will want to set.

To bind an external interface (instead of loopback), use "--host 0.0.0.0".

The connection between your hub and the Xena Browser is through https, use "--certfile" and "--keyfile" options to set them.

There are three paths that can be configured: the database file, the log file, and the root directory for data files to be served. These are set by --database, --logfile, and --root. If you don't set these, they will default to paths under ${HOME}/xena.

Example start script for an open-access hub

Copy the content below to a file "start_script"

Link server.jar to cavm-x.xx.x-standalone.jar

Make "start_script" executable

Run "./start_script"

Your hub is now running on "https://computer-external-ip:7223".

Getting a security certificate for an open-access hub

When a Xena Hub starts, it opens two consecutive ports, for http and https connections, e.g. 7222 and 7223. HTTP is always the lower number, and HTTPS is always the higher number. This means your hub has two urls

Connecting via HTTP to the hub is no longer supported by modern web browsers, thus you will need to connect via HTTPS. To do this you will need an HTTPS certificate and private key. Paths to the cert and key are set with --certfile and --keyfile. This might seem redundant for a hub behind a firewall, but the web app has no influence over the security policies of the web browser. HTTPS certificates can be acquired from free public Certificate Authorities, or via NIH InCommon.

Make your data ready

Load data through command line

Once the hub is running, and input files have been placed in the --root directory, a file can be loaded by running the jar a second time, with the -l option, like

Delete data through command line

If your hub is run on the default 7222 port, you can load data with

If your hub is running on a different port, you load data with

Please contact us at genome-cancer@soe.ucsc.edu for more assistance.

If your hub is run on the default 7222 port, you can delete data with

If your hub is running on a different port, you delete data with

Viewing data from the hub

You can now go to the visualization and add a cohort or study listed in your hub.

If you don't have a security certificate yet

If you don't have a security certificate yet but you would like to verify that the hub is working you can use ssh tunneling. An example of how to do this for AWS is below, where it is assumed that the xena hub is running on port 7222 for http and 7223 for https. In this scenario, you start the hub without using --certfile and --keyfile options.

Assuming that you typically ssh into EC2 on AWS like this,

you will now set up an ssh tunnel to port 8000 on your computer. To do this we add the -L option:

Now on your computer, http://localhost:8000 is the same as the http://aws-ip:7222. Chrome Browser does not allow a connection to http://aws-ip:7222, but it will allow a connection to http://localhost:8000.

An example apache configuration on AWS VM

in /etc/httpd/conf/httpd.conf

A landing page for my hub

How do I add a 'Launch Xena' button like the TOIL landing page

<button class="hubButton" data-cohort="TCGA TARGET GTEx">Launch Xena</button>

To add a clickable button in the hub landing page, make sure the button has classname 'hubButton'. You also need to specify the cohort to view, defined by the data parameter 'data-cohort'. Once users click the button, the visualization wizard will be launched to the specified cohort. You can change the button label.

A landing page for my cohort

How do I add a "Launch" button like the TCGA TARGET GTEx landing page

<button class="cohortButton" data-bookmark="bc7f3f46b042bcf5c099439c2816ff01">Example: compare FOXM1 expression</button>

The button must has a classname 'cohortButton'. If you have the data parameter 'data-bookmark', clicking the button will take the user to the bookmark view. If you don't have the 'data-bookmark' parameter, clicking the button will take the user to the visualization wizard with an empty spreadsheet. You can change the button label. You can as many button as you want.

You can use the python API, , to programmatically access data in the public Xena Data Hubs.

Installation

Usage

Example

Help

More Information

We will automatically detect and map your probes/transcripts/identifiers to HUGO gene names. For instance, we will map Affy probe IDs to HUGO gene names so that you can enter a HUGO gene name when creating a column in the Visual Spreadsheet and we will pull up the corresponding Affy probes.

Supported probes and other identifiers

• Affy U133 array (hg19) e.g. 1007_s_at

• Affy HumanExon1.0ST (hg18) e.g. 2315101

• Affy Human Gene 1.0 ST array (hg19) e.g. 7896736

• Affy Human SNP6 array (hg18) e.g. CN_473963

• Agilent Human gene expression 4X44K array (hg18) e.g. A_23_P100001

• Agilent SurePrint G3 Human CGH array 2x400K (hg18) e.g. A_16_P01651995

• Agilent Human 1A array (hg18) e.g. A_23_P149050

• Exon: GENCODE 19 e.g. ENSE00000327880.1

• Infinium HumanMethylation27 array GDC version (hg38) e.g. cg00000292

• Infinium HumanMethylation27 array TCGA legacy version (hg18) e.g. cg26211698

• Infinium HumanMethylation450 array TCGA legacy version (hg19) e.g. cg13332474

• Infinium HumanMethylation450 array GDC version (hg38) e.g. cg00000029

Supported genes and transcripts

• HUGO: human gene symbol (hg18) e.g. TP53

• HUGO: human gene symbol (hg19) e.g. TP53

• HUGO: human gene symbol (hg38) e.g. TP53

• Gene: Ensembl human genes (hg19) e.g. ENSG00000223972

• Gene: Ensembl human genes (hg38) e.g. ENSG00000223972

• Gene: GENCODE 19 e.g. ENSG00000223972.4

• Gene: GENCODE 22 comprehensive e.g. ENSG00000223972.5

• Gene: GENCODE 23 comprehensive e.g. ENSG00000223972.5

• Gene: GENCODE 23 basic e.g. ENSG00000223972.5

• Gene: UCSC Known genes (hg18) e.g. uc001aaa.1

• Gene: UCSC Known Genes (hg19) e.g. uc001aaa.1

• Transcript: GENCODE 19 comprehensive e.g. ENST00000456328.2

• Transcript: GENCODE 23 comprehensive e.g. ENST00000456328.2

• Transcript: GENCODE 23 basic e.g. ENST00000456328.2

• Transcript: RefSeq (hg19) e.g. NM_000014

• miRNA miRBase v13 stem-loop (hg18) e.g. hsa-mir-1977

• miRNA miRBase v20 stem-loop (hg19) e.g. hsa-mir-1302-2

Contact us if you don't see your gene or probe names in this list and we may be able to add it for you.

FAQ

FAQ: Xena didn't map the right probes

If it looks like we picked the wrong set of probes, please click 'Advanced' next to the 'Import' button on the last screen of the wizard to load data. You can then pick the appropriate probes.

What are the Source Repositories Xena pulls from?

• GDC data portal (https://portal.gdc.cancer.gov/repository) for the GDC Hub data

• GDC legacy archive (https://portal.gdc.cancer.gov/legacy-archive) for the TCGA Hub data

• ICGC data portal (https://dcc.icgc.org/) for the ICGC Hub data

• Pan Cancer Atlas publications’ data site (https://gdc.cancer.gov/node/905/) for the Pan-Cancer Atlas Hub data

• TCGA ATAC-seq publication’s data site (https://gdc.cancer.gov/about-data/publications/ATACseq-AWG) for the ATAC-seq Hub data

• Nature biotechnology publication (https://doi.org/10.1038/nbt.3772) for the UCSC Toil RNAseq Recompute Hub data

• Various journal publications for UCSC Public Hub data

For TCGA, which gene expression RNAseq dataset should I use for my analysis?

TCGA Pan-Cancer Atlas gene expression

For comparison across multiple or all TCGA cohorts. Dataset was generated by the TCGA PanCan Atlas project and has been normalized for batch effects. Please see the PanCan Atlas paper in Cell for more information. https://xenabrowser.net/datapages/?dataset=EB%2B%2BAdjustPANCAN_IlluminaHiSeq_RNASeqV2.geneExp.xena&host=https%3A%2F%2Fpancanatlas.xenahubs.net

GDC STAR gene expression

Generated by the GDC, this data can be used to compare across TCGA cohorts as well. May not have as many batch effects removed as the PanCan Atlas work.

Toil RSEM gene expression

The goal of the Toil recompute was to process ~20,000 RNA-seq samples to create a consistent meta-analysis of four datasets free of computational batch effects. This is best used to compare TCGA cohorts to TARGET or GTEx cohorts

TCGA Gene expression RNAseq (IlluminaHiSeq)

For comparison within a single TCGA cohort, you can use the "gene expression RNAseq" data. Values in this dataset is log2(x+1) where x is the RSEM value.

TCGA Gene expression RNAseq (IlluminaHiSeq pancan normalized)

For questions regarding the gene expression of a particular cohort in relation to other types tumors, you can use the pancan normalized version of the "gene expression RNAseq" data. Values in this dataset are generated at UCSC by first combining "gene expression RNAseq" values (above) of all TCGA cohorts and then mean normalizing all values per gene. This data was then divided into the 30-40 cancer types after normalization so that this data is available for each cancer type. Since there are 30-40 cancer types with RNAseq data, the TCGA pancan data can serve as a proxy of background distribution of gene expression.

TCGA Gene expression RNAseq (IlluminaHiSeq percentile)

For comparing with data outside TCGA, you can use the percentile version if your non-TCGA RNAseq data is normalized by percentile ranking. Values in this dataset are generated at UCSC by rank RSEM values per sample. The values are percentile ranks ranges from 0 to 100, lower values represent lower expression. You can also combine the TCGA RNAseq data with your RNAseq data, perform normalization across the combined dataset using whatever method you choose, then analyze the combined dataset further.

What is the difference between RPPA data and RPPA_RBN data?

The TCGA RPPA data are generated at MD Anderson. RPPA data is values generated using method described at http://bioinformatics.mdanderson.org/main/TCPA:Overview. We download the RPPA values from TCGA DCC.

The RPPA_RBN data is normalized value generated using the RBN (replicate-base normalization) method developed by MDACC. For more information: http://bioinformatics.mdanderson.org/main/TCPA:Overview. We downloaded the RBN values from synapse at https://www.synapse.org/#!Synapse:syn1750330.

Can I combine data from the methylation 450k and 27k datasets?

The methylation 450k dataset has 90% of the probes from the 27k dataset. However, we have discovered the range of data for each dataset to be slightly different. As such, we recommend applying some sort of normalization. We recommend looking in the literature to see what methods people have used.

What is the difference between GISTIC 2 and GISTIC 2 thresholded datasets?

Many copy number estimation algorithms estimate copy number variation on a continuous scale even though it is measuring something discrete (i.e. the number of copies of piece of chromosome or a gene in the cell). The GISTIC 2 thresholded data attempts to assign discrete numbers to these fragments by thresholding the data. The estimated values -2,-1,0,1,2, represent homozygous deletion, single copy deletion, diploid normal copy, low-level copy number amplification, or high-level copy number amplification respectively. More information can be found in the GISTIC 2 paper and at the Broad Institute, which is the group that processed this data.

Where is the transcript-level expression data?

As of March 2019, our transcript-level data is in the TCGA Pan-Cancer cohort. From here choose 'Advanced' and select any of the transcript-level expression datasets. Enter your transcript of interest as a Ensembl identifier (not a gene).

How do I calculate fold change (FC)?

The following instructions assume that your data has been log transformed. All the RNAseq data in Xena public data hubs have already been log transformed, either by us or by the data providers. You can always confirm this by viewing the dataset details page (start at our Explore Data pages and drill down until you get to the details page for the dataset).

Log transformed means that the output values from the gene expression caller/program have been put through the following transformation:

log2(x+theta) = y

Where x is the TPM, RSEM, etc value, "theta" is a very small value (1, 0.01, etc) added to x since you can not take the log of zero, "log2" is log base 2, and y is the transformed value.

When comparing these log transformed values, we use the quotient rule of logarithms:

log(A/B) = log(A) - log(B)

So, within our downloads (either from our bulk downloads or just a slice of the data that has not been mean normalized), say you have 2 samples with expression for a gene. In our downloads, one sample is 4 and one sample is 1. This means, because our values are log transformed,

log(A) = 4

log(B) = 1

Therefore:

log(A/B) = 4 - 1

log(A/B) = 3

This gives you a 3-fold change.

Please note that in this case we are reporting the log(fold change). Biologists often use the log(fold change) because without taking the log, down regulated genes would have values between 0 and 1, whereas up regulated genes would have any value between 1 and infinity. This distribution makes graphing and further statistical analysis difficult. Taking the log typically makes the resulting values more normally distributed, which is better for further analysis.

Can I get access to the raw TOIL data?

Yes! We host it on AWS. Note that due to how large the files are, you will need to pay the egress fees to download the files. To get started, first look through the manifests for TCGA: s3://cgl-rnaseq-recompute-toil/tcga-manifest , TARGET: s3://cgl-rnaseq-recompute-toil/target-manifest , and GTEx s3://cgl-rnaseq-recompute-toil/gtex-manifest and decide which files you want. Then using your AWS account, download the files. Contact us if you run into any issues.

Example command to get the manifest

aws s3 cp s3://cgl-rnaseq-recompute-toil/tcga-manifest . --request-pay

Now you can take look of the manifest to see the TCGA files

Example command to download a single TCGA file

aws s3 cp s3://cgl-rnaseq-recompute-toil/tcga/0106d51d-d581-4be7-91f3-b2f0c84468d1.tar.gz . --request-pay

As Xena does not generate any of the data it displays, there is no Xena Data Use Agreement. If you use data from Xena, please cite us.

Please check with the original data providers (e.g. the GDC) for any data use restrictions. You can see more about our data providers by clicking on the Hub page.

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

{
    "type": "clinicalMatrix",
    "cohort": "name of the cohort",
    "label": "display label of the file",
    "dataSubType": "the section the dataset is displayed under in Xena Datapages, describe what data is in the life",
    "map": [
      {
        "label": "display label of the map",
        "dataSubType": "embedding",
        "dimension": ["UMAP_1","UMAP_2","UMAP_3"] 
      }
    ]
}

Example, spatial map with matching microscopy image

{
    "type": "clinicalMatrix",
    "cohort": "name of the cohort",
    "label": "display label of the file",
    "dataSubType": "the section the dataset is displayed under in Xena Datapages, describe what data is in the life",
    "map": [
    {
        "label": "display label of the map",
        "dataSubType": "spatial",
        "dimension": ["X","Y"],
        "unit": "pixel",
        "spot_diameter": 178.37655999999998,
        "micrometer_per_unit": 0.3083364764966877,
        "image": [
            {
            "label": "display label of the image",
            "path": "image file path",
            "size": [24240, 24240],
            "offset": [0,0],
            "image_scalef": 1,
            },
            {
            "label": "display label of the image",
            "path": "image file path",
            "size": [2000, 2000],
            "offset": [0,0],
            "image_scalef": 0.08250825
            }]
      }]
}

Example, spatial map with matching microscopy image and transcript data

{
    "type": "clinicalMatrix",
    "dataSubtype": "phenotype",
    "label": "display label of the file",
    "cohort": "name of the cohort",
    "bioentity":"cell",
    "map":[
        {
            "label":"mIF H&E coregistered",
            "type":"spatial",
            "dimension":["CenterX", "CenterY"],
            "unit":"pixel",
            "micrometer_per_unit":0.120280945,
            "spot_diameter":84,
            "image":[
                {
                    "label":"morphology 2D image, coregistered H&E",
                    "path":"/CosMx/img",
                    "offset": [0, 0],
                    "image_scalef": 1
                }
            ],
            "transcript":[
                {
                    "label":"CosMx transcript data",
                    "path":"transcripts.tsv",
                    "dimension":["x","y"]
		}
            ]
        }
    ]
}

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

{
    "cohort": "TCGA Breast Cancer (BRCA)", 
    "dataSubType": "phenotype", 
    "label": "Curated survival data", 
    "type": "clinicalMatrix", 
    "units": {
        "OS": "days",
        "DSS": "days",
        "DFI": "days",
        "PFI": "days"
    }
}

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

1. Add a "clinicalFeature" reference to the .json file that accompanies the phenotype file. Note the colon notation in example below.

2. Compose the clinicalFeaure file (tab delimitated) and its .json file.

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

{
    "cohort": "TCGA Breast Cancer (BRCA)",
    "label": "label of you dataset", 
    "type": "clinicalMatrix",
    ":clinialFeature": "clinicalFeature.txt"
}

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

feature    attribute    value
alcohol_history    valueType    category
alcohol_history    state    no
alcohol_history    state    yes
alcohol_history_intensity    stateOrder    "no","yes"

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

{    
    "type":"clinicalFeature"
}

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

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

• for segmented copy number data, if you don't specify colNormalization, display defaults to normal=0, display value of 0 in background color (i.e. white)

example

{
     "cohort": "TCGA Acute Myeloid Leukemia (LAML)",
     "dataSubType": "gene expression RNAseq",
     "label": "IlluminaHiSeq",
     "colNormalization": true,
     "type": "genomicMatrix",
     "unit": "log2(norm_count+1)"
}