5dc1d6e658ab009f27314e192340275a6bb70237
max
  Tue Jun 2 16:20:48 2026 -0700
Add colorFields trackDb setting for bigBed/bigGenePred color scheme switching

Adds a new trackDb statement `colorFields` that renders a "Color by:" dropdown
in the track controls page, letting users switch among multiple pre-computed
color schemes stored as extra bigBed fields containing R,G,B strings.

The `default="label"` key renames the standard itemRgb option in the dropdown.
Other entries name extra bigBed fields whose R,G,B values override itemRgb when
selected. When a non-default scheme is active, a "(Coloring by: label)" suffix
appears in the track long label.

Changes:
- hui.c/hui.h: new colorFieldsCfgUi() rendered inside bedScoreCfgUi() for bigBed
- bigBedTrack.c: colorFieldIdx lookup + per-item filterColor override + longLabel suffix
- tagTypes.tab: register colorFields for bigBed and bigGenePred
- trackDbLibrary.shtml, trackDbDoc.html, trackDbHub.v3.html, changes.html: documentation

refs #26253

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

diff --git src/hg/htdocs/goldenPath/help/trackDb/trackDbLibrary.shtml src/hg/htdocs/goldenPath/help/trackDb/trackDbLibrary.shtml
index 1dac1d8f38d..7946fe831a2 100644
--- src/hg/htdocs/goldenPath/help/trackDb/trackDbLibrary.shtml
+++ src/hg/htdocs/goldenPath/help/trackDb/trackDbLibrary.shtml
@@ -2139,30 +2139,69 @@
     into a table, this field appears as an integer with the RGB values
     in specific bits of the integer. To observe this field, specify the type as,
      <code>type bigBed 9</code>, or, <code>type bigBed 9+</code>, for additional
     <A HREF="../../../FAQ/FAQformat.html#format1" target="_blank">non-standard columns</A>, 
     in the trackDb stanza for the bigBed file.</P>
     <P>Note that the display of color is affected by the <code>maxItems</code> option.
     When the track is zoomed to the point that the number of items to display
     exceeds <code>maxItems</code>, the track is forced into dense mode and the items
     are drawn from the bigBed summary in the default track color rather than using
     the <code>itemRgb column</code>.
   </P>
     <P><B>Example:</B></P>
     <pre>   itemRgb on</pre>
 </DIV>
 
+<DIV class="colorFields"><span class="types bigBed bigGenePred"></span>
+    <div class="format">
+        <code>colorFields default="&lt;label&gt;" &lt;fieldName1&gt;="&lt;label1&gt;" &lt;fieldName2&gt;="&lt;label2&gt;" ...</code>
+    </div>
+    <P>
+    Enables a <b>Color by:</b> dropdown in the track controls that lets the user switch
+    among multiple pre-computed color schemes without leaving the track display.
+    </P>
+    <P>
+    Each entry is a <code>fieldName="Human Label"</code> pair.  The field name must be an
+    extra bigBed field (defined in the track's <code>.as</code> file) that contains a
+    pre-computed <code>R,G,B</code> color string — the same format as the standard
+    <A onclick="jumpTo(this)" href="#itemRgb">itemRgb</A> field.  The label in double
+    quotes is shown in the dropdown; if omitted, a label is derived automatically by
+    stripping a leading <code>colorBy</code> prefix and replacing underscores with spaces.
+    </P>
+    <P>
+    The special name <code>default</code> (with an optional label) represents the track's
+    existing <code>itemRgb</code> field (column 9) and is placed first in the dropdown.
+    When no <code>default=</code> entry is given, an unlabeled &quot;Default&quot; option
+    is added automatically.
+    </P>
+    <P>
+    Item coloring must be active for <code>colorFields</code> to work. It is active by
+    default on bigBed tracks with more than 9 fields; it is suppressed only if the track has
+    an explicit <code>color</code> setting or <code>itemRgb off</code>. The currently
+    selected scheme is stored in the cart variable <code>&lt;trackName&gt;.colorField</code>.
+    When a non-default scheme is active, the track long label gains a
+    <em>(Coloring by: &lt;label&gt;)</em> suffix.
+    </P>
+    <P><B>Example:</B></P>
+    <pre>
+    colorFields default="Kozak strength" colorByEvidence="Evidence type" colorByHlaClass="HLA class"
+    </pre>
+    <P>This creates a three-option dropdown. <code>colorByEvidence</code> and
+    <code>colorByHlaClass</code> must be extra fields in the bigBed whose values are
+    <code>R,G,B</code> strings.</P>
+</DIV>
+
 <DIV class="maxItems"><span class="types bed bigBed broadPeak psl"></span>
 <div class="format"><code>maxItems &lt;integer&gt;</code></div>
     <P>Maximum number of items to display individually in full or pack or squish mode.  When the maximum is
     exceeded, the track switches to coverage mode.
     Default: 1000. For <code>type bigBed</code> tracks, this setting can never 
     be larger than the hg.conf setting bigBedMaxItems, which by default is 100,000 at UCSC.
     </P>
     <P>bigBedMaxItems is configured globally for a Genome Browser server and sets an upper limit
     on how many features can be loaded at most from a bigBed file, to avoid a
     single track making a Genome Browser view unusable at high zoom levels so
     it the upper limit for all maxItems settings of any tracks shown on a
     Genome Browser.  If you have feedback on these values,
     please do not hesitate to contact us.</P>
     <P><B>Example:</B>
     </P>