2353ec21c6649e1de33b43bd1b3b304603ac71f1
mspeir
  Thu Oct 1 15:31:50 2026 -0700
Document how to set the order of the bars on a barChart track, refs #37619

Adds a "Setting the order of the bars" section to the barChart format page.
It explains that the order is a property of the data file rather than of the
display, that barChartBars, barChartCategoryUrl, barChartColors and the
barChartStatsUrl rows are all positional and have to move together, and then
gives three recipes: barChartReorder on a barChart file, the same wrapped in
bigBedToBed and bedToBigBed for a bigBarChart, and expMatrixToBarchartBed
--groupOrderFile for anyone who is still at the matrix stage and can get the
order right the first time.

The barChartBars entry in trackDbLibrary.shtml gains a line saying the labels
are positional, with a link to the new section.

Also corrects the bedToBigBed command in Example 4 to pass -sort.
expMatrixToBarchartBed writes its rows in item-name order, since it joins on
name, so bedToBigBed rejects the file as unsorted as soon as the two orders
disagree. The example has always worked on the three-row file we host, whose
rows happen to be in position order already, and fails on real data.

Checked the claims against the code rather than against the existing prose:
barChartTrack.c walks expScores and the category list in step at increasing x
with no sort anywhere, createCategs numbers the categories in label order,
facetedTableSelectOffsets hands back the stats row index as the expScores
offset, and getSampleValsFromFile matches samples to categories by name, which
is why the matrix and sample files need no changes. Every command and both
example orderings were run against the files already published under
goldenPath/help/examples/barChart.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

diff --git src/hg/htdocs/goldenPath/help/trackDb/trackDbLibrary.shtml src/hg/htdocs/goldenPath/help/trackDb/trackDbLibrary.shtml
index 77fa9a20c91..ca8b70036e3 100644
--- src/hg/htdocs/goldenPath/help/trackDb/trackDbLibrary.shtml
+++ src/hg/htdocs/goldenPath/help/trackDb/trackDbLibrary.shtml
@@ -6088,31 +6088,35 @@
 <DIV class="bigBarChart_intro">
 <H3>bigBarChart: Bar charts of variables displayed on genomic regions</H3>
     <P>
     The bigBarChart format stores values of a set of variables for each genomic region 
 in the file.  BigBarChart files are created using the program bedToBigBed with a special 
 AutoSQL file that defines the fields.  The resulting files are in an indexed binary format
 that supports efficient remote access, so the file can be hosted on your web accessible server
 and displayed at UCSC.
 For the complete bigBarChart format definitions please see the
     <A HREF="../barChart.html">bigBarChart help page</A>.</P>
 </DIV>
 
 <DIV class="barChartBars"><span class="types barChart bigBarChart"></span>
 <div class="format"><code>barChartBars &lt;label1 label2...&gt;</code></div>
     <P>This setting is a list of labels for the categorical variables (bars).
-    It is required for this track type.
+    It is required for this track type. The labels are positional: the first label
+    names the first value in the expScores field of the data file, the second names
+    the second, and so on. See
+    <A HREF="../barChart.html#barOrder" target="_blank">Setting the order of the bars</A>
+    for how to change the order the bars are drawn in.
     </P>
 </DIV>
 
 <DIV class="barChartUnit"><span class="types barChart bigBarChart"></span>
 <div class="format"><code>barChartUnit &lt;unit&gt;</code></div>
     <P>The unit label is attached to values in the display, charts and plots of the track.
     </P>
 </DIV>
 
 <DIV class="barChartLabel"><span class="types barChart bigBarChart"></span>
 <div class="format"><code>barChartLabel &lt;label&gt;</code></div>
     <P>This setting provides a label for the category selection list.</p>
     </P>
 </DIV>