fa8084416354441c8c817069b7f92344f833d8dc
max
  Tue Sep 8 01:13:43 2026 -0700
hprc2annot: say in the pcLAI docs that uniform color is the expected case

Two of us in a row zoomed a pcLAI track to a few megabases, saw a single flat
color, and concluded the itemRgb was broken. It is not: pclai.bb for
GCA_046629565.1 holds 258 distinct RGB values, but 25,416 of its 25,438 windows
sit in one tight cluster in PCA space (PC1 ~0.40-0.44) and so map to one tight
cluster in color space, R 203-255 G 149-164 B 255, which is a couple of
perceptual steps wide. The color column is a byte-for-byte pass-through of the
HPRC source BED, verified against the S3 file.

Two things the page did not say. A haplotype with one ancestry throughout is
uniform across every chromosome and that is the correct render. And where a
haplotype does carry several ancestries, the blocks are tens of megabases long,
so any view narrower than a chromosome tends to land inside one block and look
uniform too.

Add an example so this is checkable rather than asserted: GCA_018466835.2
(HG02257) has four segment-level ancestry calls, and its chr17 crosses four
blocks with transitions near 10.0, 50.7 and 73.3 Mb. Name the three
chromosomes in that same assembly, chr2 chr13 chr18, that are single-ancestry
end to end, since chr2 is the one that started this.

refs #35415

diff --git src/hg/makeDb/trackDb/contrib/hprc2annot/pclai.html src/hg/makeDb/trackDb/contrib/hprc2annot/pclai.html
index 3d597d26f6a..0b71117dab3 100644
--- src/hg/makeDb/trackDb/contrib/hprc2annot/pclai.html
+++ src/hg/makeDb/trackDb/contrib/hprc2annot/pclai.html
@@ -13,30 +13,51 @@
 </p>
 
 <h2>Display Conventions</h2>
 <p>
 Each item is one genomic window. Items carry no visible label. Holding the mouse
 over an item shows the window identifier, the position of the window in the
 principal-component space that pcLAI uses to describe ancestry, the position of
 the longer ancestry segment the window belongs to, and a confidence score; the
 same values are on the details page. The item color is derived from the same
 principal-component position, so windows of similar inferred ancestry get similar
 colors and a run of shared ancestry appears as a block of consistent color.
 Because the color is continuous rather than a set of population labels, it is
 read by comparing regions with each other rather than against a fixed legend.
 </p>
 <p>
+The color follows the ancestry segment rather than the individual window, so
+neighboring windows inside one segment differ by only one or two color steps.
+Those small differences are not meaningful: the feature to read is the block, not
+the window. Two consequences are worth knowing before concluding that a display
+looks wrong. First, a haplotype with a single ancestry throughout gives one
+uniform color across every chromosome, which is the correct result for that
+sample rather than a rendering problem. Second, where a haplotype does carry
+several ancestries the blocks are tens of megabases long, so a view of only a few
+megabases usually falls inside one block and also looks uniform. Zooming out to a
+whole chromosome is what makes the block structure visible.
+</p>
+<p>
+Assembly <tt>GCA_018466835.2</tt> (sample HG02257) is a useful example of a
+haplotype with several ancestry segments. Its <tt>chr17</tt> crosses four blocks,
+with transitions near 10.0 Mb, 50.7 Mb and 73.3 Mb, and <tt>chr5</tt> crosses
+four more across its 184 Mb; <tt>chr20</tt> and <tt>chr22</tt> each cross three.
+In that same assembly <tt>chr2</tt>, <tt>chr13</tt> and <tt>chr18</tt> carry a
+single ancestry from end to end and are uniform in color, so picking one of those
+chromosomes gives no sense of what the track shows.
+</p>
+<p>
 The track is best viewed in pack mode. In dense mode the windows are collapsed
 onto one row, which hides the per-window values.
 </p>
 
 <h2>Methods</h2>
 <p>
 Conventional local ancestry inference gives every segment of a genome one of a
 fixed set of population labels. Point cloud local ancestry inference instead
 places each segment at a point in a continuous coordinate space, so a genome
 becomes a cloud of points, one per haplotype segment. The coordinate space can be
 any continuous description of ancestry; here it is the first two principal
 components of a reference panel of genomes with known population of origin.
 Ancestry that falls between the reference populations, which a label-based method
 has to round to the nearest label, therefore stays visible as an intermediate
 position. The files carry both the coordinate of each individual window and the