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.
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.

