c0e8fa6df3a0bd406c4188d49ee00f20aef203e5 max Mon Sep 7 12:07:18 2026 -0700 Substitute trackDb variables in hub track description pages A hub's description page comes straight off the hub's web server and has never been through variable substitution, so a $db or $parentTrack in it reached the reader as literal text. Native trackDb pages are fine, since hgTrackDb substitutes them when it loads trackDb, but there was no equivalent step for a hub. hgc's getTrackHtml and hgTrackUi's trackUi both call hVarSubstTrackDbHtml on a hub track's html. Only a short list of variables is recognized there and nothing is an error, because a hub page written before this existed can easily contain a dollar sign inside a shell example, and silently rewriting that would be worse than not substituting at all. Adds $parentTrack, the name of the container a track sits in, which is what a subtrack description page needs to link back to its superTrack or composite. Views are skipped, since a view has no page of its own, and the hub_<id>_ prefix is kept so the name works as hgTrackUi's g= parameter. Documents $track, $parentTrack and $hgsid in trackDb/README. refs #37599 diff --git src/hg/makeDb/trackDb/README src/hg/makeDb/trackDb/README index 7d7f8f1662e..8bbd24333bc 100644 --- src/hg/makeDb/trackDb/README +++ src/hg/makeDb/trackDb/README @@ -1,144 +1,155 @@ This directory contains the track database for the UCSC human genome browser. The program hgTrackDb converts the information here into a 'trackDb' table in the assembly's MySQL database. SEE ALSO: source tree file: src/product/README.trackDb for a general discussion of developing tracks. trackDb.ra documentation: http://genome.ucsc.edu/goldenPath/help/trackDb/trackDbDoc.html http://genome.ucsc.edu/admin/hgFindSpecHowTo.html for instructions on hgFindSpec. The bulk of the information about a track is contained in the trackDb.ra file. Tracks are separated from each other in this file by a blank line. Each line begins with an attribute name and is followed by attribute value separated by white space. The html text about a track is in separate files named xxx.html where xxx is a track name. The contents of the HTML is subject to variable substitution as described below. Note that the html file in lower-level directories can override the html in higher-level directories without requiring an entry in trackDb.ra. There may be subdirectories for each organism such as 'mouse', and underneath these directories for each database, such as 'mm10'. There are a trackDb.ra file and xxx.html files in these subdirectories. Track descriptions in the subdirectory will over-ride track descriptions in the parent directory. This allows you to customize a track for each version of the database. xxx.html files may include the contents of other files using this syntax: <!--#insert file="sharedText.html"--> where "sharedText.html" is a relative path, relative to the directory that contains the xxx.html file. This can also be made conditional on a database: <!-- #if (db==hg19) #insert file="human/hg19/specialNote.html" --> Variable substitution: The shortLabel and longLabel fields and the associated HTML files may have the following variables, which will be substituted: $ORGANISM - all upper case organism, like 'MOUSE' $Organism - initial capped organism, like 'Mouse' $organism - all lower case organism, like 'mouse' $db - database (like mm3, hg15, etc.) $date - freeze date of underlying assembly $blurb - If there is a blurb field in the .ra file this echos it. $matrix - content of the matrix and optional matrixHeader trackDb setting which will be converted to an HTML table. If there is no matrix setting, an empty string is substituted. $chainMinScore - value that gets substituted into this statement on the chain or chainNet html page: 'Chains scoring below a minimum score of "$chainMinScore" were discarded'. $chainLinearGap - value for the -linearGap matrix used with axtChain (e.g. loose, medium). Gets substituted into the chain or chainNet html page. $downloadsServer - the value of the hg.conf downloads.server variable, or hgdownload.soe.ucsc.edu if not set. + $track - the track's own name, as hgTrackUi's g= parameter needs it. For a + hub track that includes the hub_<id>_ prefix. + $parentTrack - the name of the container the track sits in, a superTrack or + a composite, in the same form as $track. Views are skipped, since + a view has no description page of its own. For a track that is + not in a container this is the same as $track. Useful for linking + a subtrack's description page back to its container, e.g. + <a href="hgTrackUi?db=$db&g=$parentTrack">. + $hgsid - the current session id. Substituted only where there is a cart, + that is by the CGIs; hgTrackDb leaves it empty, so it is of use + in hub description pages rather than in native trackDb. In addition, if there is an $otherDb field set in the .ra file, these variables are available: $o_ORGANISM - all upper case other organism, like 'MOUSE' $o_Organism - initial capped other organism, like 'Mouse' $o_organism - all lower case other organism, like 'mouse' $o_db - other database (like mm3, hg15, etc.) $o_date - freeze date of underlying other assembly Any other ra fields may be referenced as a variable. The reference can be in the form $name or ${name}. Without the braces, name is terminated by a character other than [0-9A-Za-Z_]. A literal $ is represented as $$. Here are some details on how to load various track types into the database tables: - type bedGraph [column] In this case, the data table is a bed type of table loaded with hgLoadBed. The [column] specified is a numeric column of data in the table to be used for the graphing value. The default column to graph would be column five, the 'score'. All graphing options as described in 'type wig' apply to this type of track. - type bigBed <fieldCount> <extraInfo> This uses a binary indexed file rather than a database table. It is, other than substituting "bigBed" for "bed" in the type line, the same as the "type bed". The database loading procedure for the table is: hgBbiDbLink hg18 itemRgbBbTest /gbdb/hg18/bbi/itemRgb.hg18.bb The file name given should be a full path name that can be accessed by the Apache WEB server. Or, the file name can also be a valid URL to the bb file. This loader is equivalent to: hgsql hg18 -e 'drop table if exists itemRgbBbTest; create table itemRgbBbTest (fileName varchar(255) not null); insert into itemRgbBbTest values ("/gbdb/hg18/bbi/itemRgb.hg18.bb");' - type bigWig [lower] [upper] This uses a binary indexed file rather than a database table. It is, other than substituting "bigWig" for "wig" in the type line, the same as the "type wig". The database loading procedure is: hgBbiDbLink hg19 myLocalBigWig /gbdb/hg19/bbi/myLocalBigWig.bw The file name given should be a full path name that can be accessed by the Apache WEB server. Or, the file name can also be a valid URL to the bw file. This loader is equivalent to: hgsql hg19 -e 'drop table if exists myLocalBigWig; \ create table myLocalBigWig (fileName varchar(255) not null); \ insert into myLocalBigWig values ("/gbdb/hg19/bbi/myLocalBigWig.bw");' - type pgSnp This type is used for the display of variants (for example, personal genome variants). It will display stacked boxes showing the proportion of reads supporting each allele when frequency is available (in case of 2 alleles only). Also the details page will use the UCSC genes to compute any amino acid changes. The track can be loaded using hgLoadBed and the -sqlTable option (see pgSnp.sql for the format). After editing a track definition here, run ./loadTracks which invokes hgTrackDb to bring it into the MySQL database. To update your personal copy (on hgwdev-userName) do make update to do it on genome-test do make alpha You can also restrict a track to alpha, beta, or public by using the release field.