4d43b746e730f4cf9df40e70d715e75b33ed6fca
mspeir
  Tue Sep 22 14:43:59 2026 -0700
Explain the bigPsl o-prefixed field names on the help page, refs #37155

The autoSql field comments now name the PSL field each o-prefixed field
corresponds to, but nothing on the page said what the o fields are or why
they are named after chromosomes when the aligned sequence is usually a
transcript or protein.  Add a paragraph under the schema block.

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

diff --git src/hg/htdocs/goldenPath/help/bigPsl.html src/hg/htdocs/goldenPath/help/bigPsl.html
index a4f82cb4f12..0ac1143a608 100755
--- src/hg/htdocs/goldenPath/help/bigPsl.html
+++ src/hg/htdocs/goldenPath/help/bigPsl.html
@@ -54,30 +54,36 @@
     uint    oChromSize; 	"Size of other sequence (PSL qSize)"
     int[blockCount] oChromStarts;"Start positions in other sequence; relative to oChromStart or oChromStart+oChromSize depending on strand (PSL qStarts)"
 
     lstring  oSequence;  	"Sequence on other side of alignment (or empty)"
     string   oCDS;       	"CDS in NCBI format"
 
     uint    chromSize;		"Size of reference sequence (PSL tSize)"
   
     uint match;        		"Number of bases matched."
     uint misMatch; 		"Number of bases that don't match "
     uint repMatch; 		"Number of bases that match but are part of repeats "
     uint nCount;   		"Number of 'N' bases "
     uint seqType;   		"0=empty, 1=nucleotide, 2=amino_acid"
     ) </code></pre>
 <p>
+The fields that begin with <code>o</code> hold what a PSL file calls the query; the corresponding
+PSL field name is given in parentheses above. Despite the <code>Chrom</code> in their names, the
+aligned sequence need not be a chromosome, and usually is not one: it is typically a transcript, a
+protein, or another query sequence. Alignments between two genomes are normally stored as
+<a href="chain.html">chain</a> and <a href="net.html">net</a> files rather than as bigPsl.</p>
+<p>
 The value of the <code>oStrand</code> field indicates whether or not the stored psl data should be
 reverse-complemented before it is outputted or displayed. This is necessary because the bigPsl file 
 stores reference coordinates on the positive strand, as required by the BED format. The 
 <code>strand</code> field indicates whether the positions in <code>oChromStarts</code> are listed 
 from the chromosome beginning (+) or end (-).</p>
 
 <p><b>Additional fields:</b>
 Since a bigPsl file is a bigBed file, additional fields can be added as bigBed fields. The
 additional bigBed fields are defined after the seqType field of the bigPsl.as file. 
 See <a href="bigBed.html#Ex3">Example 3</a> of the bigBed Track Format page for an example
 on how to create a bigBed file with extra (custom) fields. The additional fields can be used for
 custom
 <a href="https://genome-blog.gi.ucsc.edu/blog/2022/06/28/track-hub-settings/">mouseOvers</a>,
 feature filters, and coloring options. Contact us at
 <A HREF="mailto:&#103;&#101;&#110;&#111;&#109;&#101;&#45;ww&#119;&#64;&#115;&#111;&#101;.