af11383bd34a7d4feffe8f602f4dd73958a11d26 brianlee Thu Apr 28 16:29:03 2022 -0700 Adding barChart examples about recent barChart settings announced from trackDbLibrary diff --git src/hg/htdocs/goldenPath/help/barChart.html src/hg/htdocs/goldenPath/help/barChart.html index 732ddb0..f334c64 100755 --- src/hg/htdocs/goldenPath/help/barChart.html +++ src/hg/htdocs/goldenPath/help/barChart.html @@ -352,30 +352,126 @@ barChartUnit RPKM bigDataUrl http://genome.ucsc.edu/goldenPath/help/examples/barChart/hg38.gtexTranscripts.bb barChartMatrixUrl http://genome.ucsc.edu/goldenPath/help/examples/barChart/exampleMatrix.txt barChartSampleUrl http://genome.ucsc.edu/goldenPath/help/examples/barChart/exampleSampleData.txt </code></pre> Please note, the fields in your barChartBars line must match the terms in your categories file (exampleBarChartSamples.txt) in order for the boxplot display to show up on the details page for tracks. Below is an example image indicating the benefit of using these files in a hub, note the "View all data points for..." link that allows extracting data from the matrix file (exampleBarChartMatrix.txt) specific for this named item. <div class="text-center"> <img src="../../images/exampleBoxPlot.png" alt="Example boxPlot image" height="500" width="700"> </div> </ol> +<h6 id="example5">Example #5</h6> +<p> +To help Track Hub Developers adjust the display of tracks we add two settings +<a href="trackDb/trackDbHub.html#barChartBarMinWidth" target="_blank">barChartBarMinWidth</a> and +<a href="trackDb/trackDbHub.html#barChartBarMinPadding" target="_blank">barChartBarMinPadding</a>. +The first sets the minimum pixel width of the bars in the chart to a number of pixels, +for example <code>barChartBarMinWidth 10</code>. The second sets the minimum pixel width between +bars to a number of pixels, for example <code>barChartBarMinPadding 5</code>.</p> +<p> +Here are two example tracks using these settings on the same source data that can be loaded by +going to the My Data, Custom Tracks page and pasting the below text to see how the display +differs.</p> +<pre> +browser position chr14:95,081,796-95,436,280 +track type=bigBarChart barChartBarMinPadding=5 name="ex barChartBarMinPadding" description="A bigBarChart file with barChartBarMinPadding" barChartBars="adiposeSubcut breastMamTissue colonTransverse muscleSkeletal wholeBlood" visibility=pack bigDataUrl=http://genome.ucsc.edu/goldenPath/help/examples/barChart/hg38.gtexTranscripts.bb +track type=bigBarChart barChartBarMinWidth=20 name="ex barChartBarMinWidth" description="A bigBarChart file with barChartBarMinWidth" barChartBars="adiposeSubcut breastMamTissue colonTransverse muscleSkeletal wholeBlood" visibility=pack bigDataUrl=http://genome.ucsc.edu/goldenPath/help/examples/barChart/hg38.gtexTranscripts.bb +</pre> +<div class="text-center"> + <img src="../../images/barChartPadWidth_1.png" alt="Example1 of barChartBarMinPadding and barChartBarMinWidth" + width="700"> +</div> +<p> Both tracks have the same data, however, in the bottom track the <code>barChartBarMinWidth 20</code> +setting triggers wider widths, and the top track has larger padding between bars from the setting +<code>barChartBarMinPadding 5</code>. As described in the settings entries for +<a href="trackDb/trackDbHub.html#barChartBarMinWidth" target="_blank">barChartBarMinWidth</a> and +<a href="trackDb/trackDbHub.html#barChartBarMinPadding" target="_blank">barChartBarMinPadding</a> +there is a dynamic calculation dependent on the current window size, the width of the item, and the +number of bars for the item. So that when zooming in the appearance of the barCharts with these +settings can be different, at different scales. For instance, in the first image, you can see how +much impact barChartBarMinWidth has on the second track, as well as the barChartBarMinPadding in the top +track. But as zoomed in, with the below image, the impact of both of these settings is less noticeable.</p> +<div class="text-center"> + <img src="../../images/barChartPadWidth_2.png" alt="Example2 of barChartBarMinPadding and barChartBarMinWidth" + width="700"> +</div> +<h6 id="example6">Example #6</h6> +<p> +To help with the selection and exploration of large data sets the new settings +<a href="trackDb/trackDbHub.html#barChartFacets" target="_blank">barChartFacets</a>, +<a href="trackDb/trackDbHub.html#barChartStatsUrl" target="_blank">barChartStatsUrl</a>, +and <a href="trackDb/trackDbHub.html#barChartMerge" target="_blank">barChartMerge</a> +were introduced where on the details page checkboxes enable slicing data down to smaller +collections based on metadata.</p> +<p>The setting <code>barChartFacets <column1,column2,...columnN></code> turns on the +faceted selection on the track details and configure page which is useful for +selecting which bars out of a large number to display by clicking designated checkboxes. +The setting <code>barChartStatsUrl <url></code> associates a table in tab-separated values +with the barChart, with one line per bar. And the setting <code>barChartMerge on</code> +enables a merge button inside of the faceted selections. It is particularly useful when +there are many bars and many facets to condense a related group, such as tissue source.</p> +<p> +Below is an example track using these settings on source data for a +<a href="../cgi-bin/hgTracks?db=hg38&hideTracks=1&tabulaSapiensTissueCellType=pack&tabulaSapiens=show" +target="_blank">Tabula Sapiens single cell RNA data from many tissues</a> track. This excerpt +of settings from that track allows experimenting to see these settings in action, and to be +loaded by going to the My Data, Custom Tracks page.</p> +<pre> +track type=bigBarChart name="ex Tabula Sapiens" description="A bigBarChart using Tabula Sapiens data to illustrate new Details pages" visibility=pack barChartCategoryUrl=http://hgdownload.soe.ucsc.edu/gbdb/hg38/bbi/tabulaSapiens/bw_edit_tissue_cell_type.categories barChartFacets=tissue,cell_class,cell_type barChartStatsUrl=http://hgdownload.soe.ucsc.edu/gbdb/hg38/bbi/tabulaSapiens/bw_edit_tissue_cell_type.facets barChartMerge=on bigDataUrl=http://hgdownload.soe.ucsc.edu/gbdb/hg38/bbi/tabulaSapiens/tissue_cell_type.bb +</pre> +<p> +Once loaded, click into an item to see the details page, in this case for the gene ACE2 +at the default position in hg38. On the details page, rather than a static bar chart +image, there is a dynamic interactive selection screen with checkbox facets to narrow down +the display. Click the first two "merge" buttons next to +"tissue" and "cell_class."</p> +<div class="text-center"> + <img src="../../images/barChartFacets1.png" alt="Example1 of Facets on barCharts" width="700"> +</div> +<p> +With those two merged selections, then click on the "Macrophage" option to see just +this one cell type selection.</p> +<div class="text-center"> + <img src="../../images/barChartFacets2.png" alt="Example2git l of Facets on barCharts" width="700"> +</div> +<p> +By then clicking the "unmerge" button next to "tissue" the single bar +chart will expand with tissue clusters.</p> +<div class="text-center"> + <img src="../../images/barChartFacets3.png" alt="Example3 of Facets on barCharts" width="700"> +</div> +<p> +In these ways the new barChartFacets, barChartStatsUrl, and barChartMerge settings allow users +to explore the barChart data on the individual details page more closely. One can use the facets +to further select certain types and also click the columns (val/count/cluster) to arrange +by numerical value or alphabetical name.</p> +<p> +Also, if you click the "Return to Genome Browser" link, you will see only these +selection bars are displayed.</p> +<div class="text-center"> + <img src="../../images/barChartFacets4.png" alt="Example4 of Facets on barCharts" width="700"> +</div> +<p> +In this image after making the selections browsing ACE2 the "zoom out" button has +been clicked to also view nearby genes where the expression of these tissue selections for the +gene PIR is quite noticeably different.</p> + <h2>Sharing your data with others</h2> <p> If you would like to share your barChart/bigBarChart data track with a colleague, learn how to create a URL by looking at Example 6 on <a href="customTrack.html#EXAMPLE6">this page</a>.</p> <h2>Extracting data from the bigBarChart format</h2> <p> Because bigBarChart files are an extension of bigBed files, which are indexed binary files, it can be difficult to extract data from them. UCSC has developed the following programs to assist in working with bigBed formats, available from the <a href="http://hgdownload.soe.ucsc.edu/admin/exe/">binary utilities directory</a>.</p> <ul> <li> <code>bigBedToBed</code> — converts a bigBed file to ASCII BED format.</li> <li>