0c6f2bdc5a264553fee007f88d1c150df961b018
max
  Fri Jun 21 03:27:49 2024 -0700
rmsk docs change, refs #33994

diff --git src/hg/makeDb/trackDb/rmsk.html src/hg/makeDb/trackDb/rmsk.html
index 299c9fa..4ce3adf 100644
--- src/hg/makeDb/trackDb/rmsk.html
+++ src/hg/makeDb/trackDb/rmsk.html
@@ -9,30 +9,43 @@
 query sequence (represented by this track), as well as a modified version
 of the query sequence in which all the annotated repeats have been masked
 (generally available on the
 <a href="http://hgdownload.soe.ucsc.edu/downloads.html"
 target=_blank>Downloads</a> page). RepeatMasker uses the
 <a href="https://www.girinst.org/repbase/update/index.html"
 target=_blank>Repbase Update</a> library of repeats from the
 <a href="https://www.girinst.org/" target=_blank>Genetic 
 Information Research Institute</a> (GIRI).
 Repbase Update is described in Jurka (2000) in the References section below.
 Some newer assemblies have been made with Dfam, not Repbase. You can
 find the details for how we make our database data here in our &quot;makeDb/doc/&quot;
 <a href="https://genome-source.gi.ucsc.edu/gitlist/kent.git/tree/master/src/hg/makeDb/doc/"
 target="_blank">directory</a>.</p>
 
+<p>
+When analyzing the data tables of this track, keep in mind that Repbase is not the same 
+as the Repeatmasker sequence database and that the repeat names in the
+Repeatmasker output are not the same as the sequence names in the Repeatmasker
+database.  Concretely, you can find a name such as "L1PA4" in the Repeatmasker
+output and this track, but there is not necessarily a single sequence "L1PA4"
+in the Repeatmasker database. This is because Repeatmasker creates annotations
+by joining matches to partial pieces of the database together so there is no
+1:1 relationship between its sequence database and the annotations. To learn
+more, you can read the Repeatmasker paper, its source code or reach out to the
+Repeatmasker authors, your local expert on transposable elements or us.
+</p>
+
 <h2>Display Conventions and Configuration</h2>
 
 <p>
 In full display mode, this track displays up to ten different classes of repeats:
 <ul>
 <li>Short interspersed nuclear elements (SINE), which include ALUs</li>
 <li>Long interspersed nuclear elements (LINE)</li>
 <li>Long terminal repeat elements (LTR), which include retroposons</li>
 <li>DNA repeat elements (DNA)</li>
 <li>Simple repeats (micro-satellites)</li>
 <li>Low complexity repeats</li>
 <li>Satellite repeats</li>
 <li>RNA repeats (including RNA, tRNA, rRNA, snRNA, scRNA, srpRNA)</li>
 <li>Other repeats, which includes class RC (Rolling Circle)</li>
 <li>Unknown</li>