6b0035d19769346baffe193ef9419c269d46f8d8 max Wed Sep 9 06:09:41 2026 -0700 hprc2annot: pcLAI column 10 is the ancestry centroid, not a segment coordinate Reading the pcLAI authors' own format description (github.com/AI-sandbox/hprc-pclai, README "Output format (BED)") while building the same annotation as a native hg38 track showed that column 10 of the source BED had been described wrongly here. It is not the PCA coordinate of a longer ancestry segment the window belongs to; the authors call it the centroid, the discretized pcLAI ancestry of the window written as the PCA centroid of its ancestry cluster. That is why it only ever takes four values -- four clusters, not four long shared segments. The old reading also implied a segmentation step the method does not have: pcLAI predicts one coordinate per window, and the blocks visible in the display are runs of windows with similar predictions. Field renamed pcaSegment -> centroid in pclai.as with the description corrected, and the mouseOver, the detailsScript exportFields and the description page follow. The README also settles that windows are a fixed 1000 SNPs rather than a fixed number of bases, and that thickStart is specified to equal chromStart, so the occasional thickStart == chromStart-1 the converter works around is a bug in their files rather than something we misread. A field name and its description live inside each bigBed, so editing pclai.as does nothing to a built collection. hprc2annotRewriteAs.sh re-emits a built bigBed with the current .as -- no re-download, no column change, item count checked across the round trip, and safe to re-run, unlike hprc2annotFixBed.sh. All 460 pclai.bb were rewritten with it. Worth knowing: those files had been built from an older pclai.as than the tree and nothing had noticed, so this is the tool to run after any .as description edit. genark: the "...Url" inside a detailsScript value must not be rebased the way bigDataUrl is. hgc resolves a relative detailsScript Url against the track's own bigDataUrl when it builds the details page, and bigDataUrl has already been rebased, so the prefix landed twice: the pcLAI scatterplot had been asking for contrib/hprc2annot/contrib/hprc2annot/pclaiRefPanel.json and quietly getting nothing on every GenArk hub. In this layout the panel file is symlinked beside the .bb, so relative-to-the-.bb is the bare file name; rebaseBeside() does that and is idempotent, so addContrib can be re-run. refs #35415 diff --git src/hg/makeDb/trackDb/contrib/hprc2annot/pclai.html src/hg/makeDb/trackDb/contrib/hprc2annot/pclai.html index 0b71117dab3..6f85f98f1b8 100644 --- src/hg/makeDb/trackDb/contrib/hprc2annot/pclai.html +++ src/hg/makeDb/trackDb/contrib/hprc2annot/pclai.html @@ -1,92 +1,97 @@ <h2>Description</h2> <p> This track shows pangenome local ancestry inference (pcLAI) for this Human Pangenome Reference Consortium (HPRC) Release 2 assembly, in the assembly's own coordinates. Every person's genome is a mosaic inherited from ancestors of different populations, and "local ancestry" describes, region by region along a chromosome, where a stretch of DNA came from. Rather than picking one population label per region, pcLAI places each region on a continuous scale, so ancestry that sits between two reference populations is not forced into one of them. This -track divides each haplotype into windows of about a hundred thousand bases and -reports the ancestry inferred for each one, letting users see how ancestry varies +track divides each haplotype into windows of 1000 SNPs, roughly a hundred thousand +bases, and reports the ancestry inferred for each one, letting users see how ancestry varies along a single individual's genome. </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. +principal-component space that pcLAI uses to describe ancestry, the ancestry the +window is assigned to if that continuous position is discretized, and a confidence +score; the same values are on the details page, together with a scatterplot +showing where the window sits relative to the reference haplotypes that define the +space. The item color is derived from the 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 +Neighboring windows inside one block of shared ancestry 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, +haplotype with several ancestry blocks. 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. +becomes a cloud of points, one per window. The coordinate space can be any +continuous description of ancestry; here it is the first two principal components +of a reference PCA embedding built from 3122 1000 Genomes haplotypes of 21 +populations of known 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 -coordinate of the longer ancestry segment that window belongs to. See the +position. Each haplotype is split into windows of 1000 SNPs and a coordinate is +predicted for each, with a confidence score; windows of very low confidence are +dropped before the files are published. The files also carry a discretized version +of each prediction, written as the PCA centroid of the ancestry cluster the window +falls in, which across the whole release takes only four values. See the reference below for the method. This track uses the assembly-coordinate (<tt>asm_coord</tt>) output, that is, ancestry placed on each HPRC assembly's own sequence; companion outputs projected onto GRCh38 and CHM13 coordinates are distributed separately. </p> <p> The annotation files were obtained from the HPRC Release 2 data collection on the public <tt>s3://human-pangenomics</tt> bucket, indexed at <a href="https://github.com/human-pangenomics/hprc_intermediate_assembly/tree/main/data_tables/annotation/pclai" target="_blank">the hprc_intermediate_assembly data tables</a>. The per-assembly BED file was converted to a UCSC bigBed file, with the window -identifier and the two sets of coordinates split out of the source item name into -their own fields. The steps are described in the -<a href="https://github.com/ucscGenomeBrowser/kent/blob/master/src/hg/makeDb/doc/contrib/hprc2annot.txt" target="_blank">makeDoc</a>, +identifier and the predicted coordinate split out of the source item name into +their own fields and the source's centroid column named. The steps are described in the +<a href="https://github.com/ucscGenomeBrowser/kent/blob/master/src/hg/makeDb/doc/contrib/hprc2annot/hprc2annot.txt" target="_blank">makeDoc</a>, the build scripts are in the <a href="https://github.com/ucscGenomeBrowser/kent/tree/master/src/hg/makeDb/scripts/hprc2annot" target="_blank">kent source tree</a>, and the track configuration is in <a href="https://github.com/ucscGenomeBrowser/kent/tree/master/src/hg/makeDb/trackDb/contrib/hprc2annot" target="_blank">trackDb/contrib/hprc2annot</a>. Every window in the source files is carried through to the bigBed. </p> <h2>Data Access</h2> <p> For automated analysis, the annotation is stored in a bigBed-format file (<tt>pclai.bb</tt>) that can be read with the UCSC tool <tt>bigBedToBed</tt>. The original files are available from the HPRC S3 bucket linked above. </p> <h2>Credits</h2>