> For the complete documentation index, see [llms.txt](https://ucsc-xena.gitbook.io/project/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ucsc-xena.gitbook.io/project/technical-documentation/deep-linking-into-xena.md). # Deep Linking Into Xena Xena has the ability to draw visualizations based on parameters passed through URL. You will need to URL encode the parameters. The list of supported parameters below is not exhaustive. If you do not see your functionality supported below please [contact us](/project/contact-us.md)**.** ## **Examples** **Display Column Setup Examples** [Example 1](https://xenabrowser.net/heatmap/?columns=%5B%7B%22name%22%3A%22tcga_Kallisto_tpm%22%2C%22host%22%3A%22https%3A%2F%2Ftoil.xenahubs.net%22%2C%22fields%22%3A%22TP53%20FOXM1%22%7D%5D) One data column (with two subcolumns) display [Example 2](https://xenabrowser.net/heatmap/?columns=%5B%7B%22name%22%3A%22tcga_Kallisto_tpm%22%2C%22host%22%3A%22https%3A%2F%2Ftoil.xenahubs.net%22%2C%22fields%22%3A%22TP53%20FOXM1%22%7D%2C%7B%22name%22%3A%22TCGA.PANCAN.sampleMap%2FGistic2_CopyNumber_Gistic2_all_data_by_genes%22%2C%22host%22%3A%22https%3A%2F%2Ftcga.xenahubs.net%22%2C%22fields%22%3A%22FOXM1%22%7D%5D\&heatmap=%7B%22mode%22%3A%22chart%22%7D) Display in chart mode [Example 3](https://xenabrowser.net/heatmap/?columns=%5B%7B%22name%22%3A%22Survival_SupplementalTable_S1_20171025_xena_sp%22%2C%22host%22%3A%22https%3A%2F%2Fpancanatlas.xenahubs.net%22%2C%22fields%22%3A%22cancer%20type%20abbreviation%22%7D%2C%7B%22name%22%3A%22TCGA.PANCAN.sampleMap%2FGistic2_CopyNumber_Gistic2_all_data_by_genes%22%2C%22host%22%3A%22https%3A%2F%2Ftcga.xenahubs.net%22%2C%22fields%22%3A%22FOXM1%22%7D%2C%7B%22name%22%3A%22broad.mit.edu_PANCAN_Genome_Wide_SNP_6_whitelisted.xena%22%2C%22host%22%3A%22https%3A%2F%2Fpancanatlas.xenahubs.net%22%2C%22fields%22%3A%22chr3%3A4000000-4100000%22%7D%5D) Three data column display, one clinical data column, two genomic data columns [Example 4](https://xenabrowser.net/heatmap/?columns=%5B%7B%22name%22%3A%22Survival_SupplementalTable_S1_20171025_xena_sp%22%2C%22host%22%3A%22https%3A%2F%2Fpancanatlas.xenahubs.net%22%2C%22fields%22%3A%22cancer%20type%20abbreviation%22%7D%2C%7B%22name%22%3A%22tcga_Kallisto_tpm%22%2C%22host%22%3A%22https%3A%2F%2Ftoil.xenahubs.net%22%2C%22width%22%3A400%2C%22columnLabel%22%3A%22top%20column%20label%22%2C%22fieldLabel%22%3A%22bottom%20column%20label%22%2C%22fields%22%3A%22ENST00000064780.6%20ENST00000066544.7%20ENST00000070846.10%20ENST00000072516.7%20ENST00000072644.5%20ENST00000072869.8%20ENST00000074304.9%20ENST00000075120.11%20ENST00000075322.10%22%7D%5D) Specify column width, top label, and bottom label on Column C [Example 5](https://xenabrowser.net/heatmap/?columns=%5B%7B%22name%22%3A%22tcga_Kallisto_tpm%22%2C%22host%22%3A%22https%3A%2F%2Ftoil.xenahubs.net%22%2C%22fields%22%3A%22TP53%20FOXM1%22%2C%22sortDirection%22%3A%22reverse%22%7D%5D) Reverse sort on Column B [Example 6](https://xenabrowser.net/heatmap/?columns=%5B%7B%22name%22%3A%22tcga_Kallisto_tpm%22%2C%22host%22%3A%22https%3A%2F%2Ftoil.xenahubs.net%22%2C%22fields%22%3A%22TP53%22%7D%2C%7B%22name%22%3A%22tcga_Kallisto_tpm%22%2C%22host%22%3A%22https%3A%2F%2Ftoil.xenahubs.net%22%2C%22fields%22%3A%22TP53%22%2C%22geneAverage%22%3Atrue%7D%5D) Display gene average in Column C [Example 7](https://xenabrowser.net/heatmap/?columns=%5B%7B%22name%22%3A%22TCGA-BRCA.somaticmutation_wxs.tsv%22%2C%22host%22%3A%22https%3A%2F%2Fgdc.xenahubs.net%22%2C%22fields%22%3A%22TP53%22%7D%2C%7B%22name%22%3A%22TCGA-BRCA.somaticmutation_wxs.tsv%22%2C%22host%22%3A%22https%3A%2F%2Fgdc.xenahubs.net%22%2C%22fields%22%3A%22TP53%22%2C%22showIntrons%22%3Atrue%7D%5D\&heatmap=%7B%22showWelcome%22%3Afalse%7D) Display introns in Column C; Hide welcome banner #### HTML Code showing how to build examples 1-7 ```html Example 1 One data column (with two subcolumns) display

Example 2 Display in chart mode

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

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

Example 5 Reverse sort on Column B

Example 6 Display gene average in Column C

Example 7 Display introns in Column C; Hide welcome banner ``` **Highlight Samples Examples** Below is HTML code showing how to generate URLs that: 1\) highlight samples TCGA-C8-A131-01 or TCGA-BH-A0DL-01 2\) highlight samples matching arbitrary criteria, such as samples in Column B with values > 10 #### HTML code for highlighting samples examples ```html Sample highlight example 1: highlight samples of specific sample IDs, such as TCGA-C8-A131-01 or TCGA-BH-A0DL-01
Sample highlight example 2: highlight samples matching arbitary criteria, such as samples in Column B with values > 10 ``` **HTML code showing sample filtering (to specify what samples to display in the view) examples** ```html Sample highlight Example 1: highlight samples of specific sample IDs, such as THR30_0820_S01 or THR30_0861_S01

Sample highlight Example 2: highlight samples matching an arbitary criteria, such as TARGET samples

Sample filtering Example 1: specify (filter to) what samples to show in a view using a predicate, such as TARGET samples

Sample filtering Example 2: specify samples in a view using a predicate that includes a boolean term, such as TARGET and TCGA samples (use boolean OR)

Sample filtering and highlight at the same time: specify samples in a view using a predicate (e.g. just show TARGET samples), as well as highlight specific samples by IDs, such as TARGET-40-0A4I6O-01A-01R

Sample filtering using data in a hidden filter column: useful when you want to filter samples using data not displayed on the screen. You can use HIDDEN FILTER COLUMN. For exmaple, filter the samples to < 5 years old, but you don't want to actually display the age column on the screen. ``` ### Base URL and URL construction ``` var page = ‘https://xenabrowser.net/heatmap/’; var url = page + ‘?columns=’ + encodeURIComponent(columns_parameter) + \ ‘&heatmap=’ + encodeURIComponent(heatmap_parameter); ``` ## ***columns*** **parameter** The *columns* parameter is a JSON-encoded array of objects, specifying the columns to display. ### **Properties** To specify a single column you need to, at a minimum, specify the dataset ID, the hub where the data resides, and the fields that you want to display. ``` var column = {name: dataset1, host: hub1, fields: 'foo bar'}; var columns_parameter = JSON.stringify([column]); var url = page + ‘?columns=’ + encodeURIComponent(columns_parameter); ``` #### *Fields* for genomic columns Fields can be a gene, probe, or chromosome position. All fields need to be of the same type (i.e. all genes or all probes). You can only enter one chromosome position per column. #### *Fields* for phenotypic columns Field should be the field ID as it appears exactly in the dataset ### **Optional properties** *width: \* Width in pixels *columnLabel: \* Text for top column label *fieldLabel: \* Text for bottom column label *geneAverage: \* Display the gene average instead of the individual probes for a gene. You can use this only when a single gene is specified for a dataset that has probes on a gene *normalize: ‘none’ | ‘mean’ | ‘log2’ | ‘normal2’* How the data should be dynamically normalized on the fly. 'mean' is x-mean (subtract mean), applied per (sub)column. 'log2' is log2(x+1). 'normal2' is (x-2). *showIntrons: \* Show introns for mutation and segmented copy number columns *sortDirection: 'reverse'* Reverse sort the samples *sortVisible: \* Sort column on the zoomed region ## ***filterColumns*** **parameter** Same as the *columns* parameter, but these columns will not be displayed. They are available for sample filtering. See the *filter* property of the *heatmap* parameter, below. ## ***heatmap*** **parameter** The *heatmap* parameter is a JSON-encoded object specifying global display options ### **Properties** *mode: 'chart'* Display in chart mode rather than visual spreadsheet mode. *showWelcome: \* Show the welcome banner. *searchSampleList: \[\, ...]* Highlight the specified samples in the view. *search: \* Equivalent to typing this text into the 'Find' feature in Xena. In this example it is highlighting the samples that for column B have a value of 'TARGET'. [More examples of possible search terms.](/project/overview-of-features/filter-and-subgrouping.md) *filter: \* Like the *search* parameter, but filter the view to the matching samples. Equivalent to [selecting 'Filter' from the 'Find' UI](/project/overview-of-features/filter-and-subgrouping.md#general-functionality). Columns that are only needed for filtering (not visualization) can be added to the *filterColumns* parameter, and appear semantically after *columns*. For example, if *columns* has length two they are labeled 'B' and 'C', and the first column in *filterColumns* will be 'D'. Both *search* and *filter* can be specified in the same url, in which case the samples will be filtered, and any remaining samples matching *search* will be highlighted. Note that the *search* expression should only reference *columns*, not *filterColumns*, since the latter are not available for visualization. ``` var heatmap_paramter = JSON.stringify({ showWelcome: false, search: "B:=TARGET" }); var url = page + ‘?columns=’ + encodeURIComponent(columns_parameter) + \ ‘?heatmap=’ + encodeURIComponent(heatmap_paramter); ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://ucsc-xena.gitbook.io/project/technical-documentation/deep-linking-into-xena.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.