The UCSC Genome Browser includes a large and ever-expanding collection of data tracks, particularly on its core assemblies. To make this collection easier to navigate, we provide several types of container tracks - tracks whose purpose is to hold other tracks, similar to how a folder holds files. Composite tracks are one such container, allowing related tracks to be grouped and managed through a unified interface. For example, our Conservation tracks are often organized as composites as are each of our "All GENCODE" tracks (e.g., this one). But while the standard user interface for a composite works well for intermediate numbers of subtracks (around 20-200), it becomes much more difficult to use when that number scales up into the thousands. Faceted composites use an alternate interface for composite tracks that is designed for these situations.
The faceted composite display is particularly useful for data sets where each subtrack has many potential values to be filtered on (e.g., cell type, protocol, date, experiment scores), and where only a few of them may be of interest to any particular user. Because the focus is on simply helping users identify which subtracks are relevant to them, the subtrack configuration options are reduced to "is this subtrack displayed or not". Users can then alter the display of individual subtracks using the right-click Configure menu from the main hgTracks browser display.
The short version of this is that a faceted composite is like any other composite,
but cannot include views or subgroups. All subtracks, which may be a mix of data types,
live under the same parent: the composite track itself. A mandatory metadata file (which must be
web-accessible) describes the facet data for the tracks. The composite's trackDb settings
must include a "primaryKey" setting that names one of the fields in the metadata file. Child
tracks must then have names that match "<parent_name>_<primaryKey value>".
Brief example:
TrackDb entries
track myComposite compositeTrack faceted metaDataUrl https://url/to/metadata.tsv primaryKey name shortLabel Blood tests longLabel Blood tests track myComposite_ex1 parent myComposite type bigBed bigDataUrl https://url/to/ex1.bb shortLabel ex1 peaks longLabel ex1 Blood data peaks track myComposite_ex2 parent myComposite type bigBed bigDataUrl https://url/to/ex2.bb shortLabel ex2 peaks longLabel ex2 Blood data peaks
metadata.tsv
name collection_date cell_type lab ex1 2026-01-01 erythrocyte Richter ex2 2026-01-03 erythrocyte Helsing
This section walks through building a faceted composite from the ground up, starting with the bare minimum structure and adding features piece by piece. By the end, you should have all of the trackDb settings needed to assemble a fully faceted composite track for your own data.
Like any composite track, a faceted composite is built from two kinds of trackDb stanzas: a single parent stanza that declares the composite as a whole, and a collection of child stanzas (also called subtracks) that each carry the underlying data. The parent is what users see in the track list on the browser gateway; opening it brings up the faceted interface that lets users choose which children to display.
The parent track
At its simplest, a faceted composite parent looks like this:
track myComposite compositeTrack faceted shortLabel Blood tests longLabel Blood tests across cell types
The line compositeTrack faceted is what tells the browser to use
the faceted user interface rather than the traditional composite matrix.
The shortLabel and longLabel are the names shown
in the track list and on the configuration page.
The child tracks
Each child stanza names its parent with a parent line and
points at its own data file. A minimal pair of children for the example
above might be:
track myComposite_ex1 parent myComposite type bigBed bigDataUrl https://url/to/ex1.bb shortLabel ex1 peaks longLabel ex1 Blood data peaks track myComposite_ex2 parent myComposite type bigBed bigDataUrl https://url/to/ex2.bb shortLabel ex2 peaks longLabel ex2 Blood data peaks
Two things worth noting. First, unlike a traditional composite, a faceted
composite happily mixes data types - the children don't all need to be
bigBed, or all bigWig. Second, each child track name follows the convention
<parent_name>_<identifier>, where the identifier
matches the first field from a row in the metadata file introduced below. That naming
convention is how the browser ties each subtrack to its metadata, so the
match must be exact, capitalization included. For example, the track
"myComposite_ex2" in the example above would be paired with an entry in the
metadata file for the "ex2" identifier.
With just the settings above, the composite will load and display, but it won't yet have any facets or filters. The remaining sections below cover the trackDb settings that turn this plain composite into a fully faceted one. Our trackDb documentation gives the full reference for each setting; what follows is some additional exposition.
view and subGroups
These settings are not used in faceted composites. Instead, the UI for a faceted
composite is governed by the dataTypes and metaDataUrl
settings. Most composite track needs can be addressed without using the
dataTypes setting at all, so we are going to ignore it to start with.
After considering an example where the dataTypes setting
is not in use, we will then discuss where it might be helpful and what associated
changes are required.
In most situations, the desired user interface for a faceted composite track presents a table where each row is a separate subtrack from the composite. The user has full flexibility to decide which subtracks they want to see. Clicking on individual rows adds them to the list of displayed subtracks; clicking again deselects that track, removing it from the display. Facet filters are provided to help narrow down the list interactively, as the list of subtracks is often too long to easily scroll all the way through.
metaDataUrl
In order to set up the facets, the track needs to include a description
of which facets exist and what the associated values for each track are. This
data comes from a separate web-accessible TSV (tab-separated value) file named
in the metaDataUrl setting of the track. Here is a new
example with more metadata than the previous one:
accession tissue protocol treatment _date __count SRR11111 blood Omni-ATAC-seq control 2026-01-01 12 SRR11112 blood Omni-ATAC-seq IFNg6h 2026-01-01 31 SRR11113 spleen Omni-ATAC-seq control 2026-08-21 8 SRR11114 spleen Omni-ATAC-seq IFNg6h 2026-08-22 17
These lines would be saved into a file called something like "myTrackMetadata.tsv" that would then be attached to your faceted composite by adding
metaDataUrl https://url/to/myTrackMetadata.tsv
to the trackDb settings for the faceted composite track. A particular note about two field names in this example file. The "date" field begins with one underscore, and the "count" field begins with two underscores. These prefixes modify the facet interface for the track. By default, each field apart from the primaryKey field will have an associated facet created for it on the page, and a search box will be provided in the table. When a field name begins with one underscore, however, no facet will be created (a search box will still be provided in the table header). When a field name begins with two underscores, there will be no facet for it and no search box in the table header.
primaryKey
The primaryKey setting is required and works together with the metadataUrl
setting. The metadataUrl setting describes where to find the metadata file; the
primaryKey setting dictates which field in that file will be used to identify the
subtracks. The column named as the primaryKey column does not have to be the first,
but it is often convenient to organize the metadata file that way.
The values in that column are expected to be unique - no two rows should
share the same value. The above metadataUrl setting would be combined with a setting
reading
primaryKey accession
to indicate that subtrack names are pulled from values in the "accession" column, and that subtracks would be named <parent_name>_SRR11111, <parent_name>_SRR11112, <parent_name>_SRR11113, and so on. The corresponding trackDb stanzas for the parent and child tracks would then look something like this:
track SRRComposite compositeTrack faceted metaDataUrl https://url/to/myTrackMetadata.tsv primaryKey accession shortLabel Omni-ATAC-seq longLabel Omni-ATAC-seq Results track SRRComposite_SRR11111 parent SRRComposite type bigBed bigDataUrl https://url/to/SRR11111_data.bb shortLabel SRR11111 peaks longLabel SRR11111 blood control peaks track SRRComposite_SRR11112 parent SRRComposite type bigBed bigDataUrl https://url/to/SRR11112_data.bb shortLabel SRR11112 peaks longLabel SRR11112 blood IFNg6h peaks track SRRComposite_SRR11113 parent SRRComposite type bigBed bigDataUrl https://url/to/SRR11113_data.bb shortLabel SRR11113 peaks longLabel SRR11113 spleen control peaks track SRRComposite_SRR11114 parent SRRComposite type bigBed bigDataUrl https://url/to/SRR11114_data.bb shortLabel SRR11114 peaks longLabel SRR11114 spleen IFNg6h peaks
dataTypes
In the above examples, the assumption is that there is one track for each accession.
In some situations, however, there may be multiple tracks associated with each
accession in a formulaic way. For example, each accession could have a raw counts
bigWig track, a scaled counts bigWig track, and a peak calls bigBed track.
One way to address this is to create synthetic accessions, like SRR11111_counts,
SRR11111_scaled, and SRR_11111_peaks, and treat them all as completely independent.
This works, but fails to capture the relationship between the three tracks.
Instead of having three entries in the table that all share the same metadata
(one for each track), you can use the dataTypes setting to describe
which data types (raw counts, scaled counts, and peaks) are available for each
sample accession. The dataTypes setting is used once on the parent track, and
comes with the expectation that the same set of data types will be available for
every accession.
When this setting is used, an additional selector is placed near the top of the
page to permit users to identify which data types they want to display. The
selected data types will be turned on for every selected sample in the table,
so the interface is a bit less flexible than the plain one-row-per-track table.
In this alternate setup, however, the one-row-per-sample arrangement can save
significant space both in the configuration UI and in the metadata TSV file.
An important note: the rules for subtrack names change when
the dataTypes setting is active. Without dataTypes, subtrack names
are expected to match <parent track name>_<primary key value>. An example
of that can be seen in the quick start near the top of the page. When
dataTypes are used, however, then subtrack names are expected to match
<parent track name>_<primary key value>_<data type>. For example,
if the data types "signal" and "peaks" are in use for the composite presented
above instead of just peaks, then the set of tracks might look like this:
track SRRComposite compositeTrack faceted metaDataUrl https://url/to/myTrackMetadata.tsv primaryKey accession shortLabel Omni-ATAC-seq longLabel Omni-ATAC-seq Results dataTypes signal peaks track SRRComposite_SRR11111_peaks parent SRRComposite type bigBed bigDataUrl https://url/to/SRR11111_data.bb shortLabel SRR11111 peaks longLabel SRR11111 blood control peaks track SRRComposite_SRR11111_signal parent SRRComposite type bigWig 0 100 bigDataUrl https://url/to/SRR11111_data.bw shortLabel SRR11111 signal longLabel SRR11111 blood control signal track SRRComposite_SRR11112_peaks parent SRRComposite type bigBed bigDataUrl https://url/to/SRR11112_data.bb shortLabel SRR11112 peaks longLabel SRR11112 blood IFNg6h peaks track SRRComposite_SRR11112_signal parent SRRComposite type bigWig 0 100 bigDataUrl https://url/to/SRR11112_data.bw shortLabel SRR11112 signal longLabel SRR11112 blood IFNg6h signal track SRRComposite_SRR11113_peaks parent SRRComposite type bigBed bigDataUrl https://url/to/SRR11113_data.bb shortLabel SRR11113 peaks longLabel SRR11113 spleen control peaks track SRRComposite_SRR11113_signal parent SRRComposite type bigWig 0 100 bigDataUrl https://url/to/SRR11113_data.bw shortLabel SRR11113 signal longLabel SRR11113 spleen control signal track SRRComposite_SRR11114_peaks parent SRRComposite type bigBed bigDataUrl https://url/to/SRR11114_data.bb shortLabel SRR11114 peaks longLabel SRR11114 spleen IFNg6h peaks track SRRComposite_SRR11114_signal parent SRRComposite type bigWig 0 100 bigDataUrl https://url/to/SRR11114_data.bw shortLabel SRR11114 signal longLabel SRR11114 spleen IFNg6h signal
metadata.tsv
accession tissue protocol treatment _date __count SRR11111 blood Omni-ATAC-seq control 2026-01-01 12 SRR11112 blood Omni-ATAC-seq IFNg6h 2026-01-01 31 SRR11113 spleen Omni-ATAC-seq control 2026-08-21 8 SRR11114 spleen Omni-ATAC-seq IFNg6h 2026-08-22 17
One other note: sometimes you may wish to have more descriptive text than just "peaks"
or "signal" for the selector, but the better labels aren't compatible with being used
as part of a track name (maybe because they include spaces). This can be handled
by specifying each data type as <name>|"<label>". The "name"
value will be used to generate track names, while the label will be used for display.
If the signal and peaks tracks represent methylated regions, then the following dataTypes
setting might be appropriate:
dataTypes signal|"Methylation signal (scaled)" peaks|"Highly methylated regions"
subtrackUrls
It can also be useful to have certain fields provide links out to external resources,
particularly when accessions are in use. The subtrackUrls setting describes
which fields are to be used to generate links out and what the format of those URLs should be.
Bringing back this example metadata file:
accession tissue protocol treatment _date __count SRR11111 blood Omni-ATAC-seq control 2026-01-01 12 SRR11112 blood Omni-ATAC-seq IFNg6h 2026-01-01 31 SRR11113 spleen Omni-ATAC-seq control 2024-08-21 8 SRR11114 spleen Omni-ATAC-seq IFNg6h 2026-08-22 17
It might be helpful to provide links out from the accession column to SRA, and the protocol column to a description page of the protocol. This could be achieved by adding the following subtrackUrls setting to the composite's trackDb stanza:
subtrackUrls accession=https://www.ncbi.nlm.nih.gov/sra/$$ protocol=https://www.protocols.io/view/$$
For each of these URLs, $$ will be replaced with the relevant value from that field (whether one of the SRR strings for the accession field, or "Omni-ATAC-seq" for the protocol field).
Similar to the dataTypes discussion, there is also a final note here about situations where
you want to use one value in the URL while having another value displayed in the column. And
just as in that case, the solution is to use <value>|"<label>" in that
field in the metadata TSV file. The above example wouldn't quite work right because the actual
URL for the protocol is "https://www.protocols.io/view/omni-atac-seq-improved-atac-seq-protocol-14egn94jyl5d".
Clearly, however, we don't want to use "omni-atac-seq-improved-atac-seq-protocol-14egn94jyl5d"
in the display for people reading through the table. By setting up the rows like this instead,
we maintain a clean display while providing links to the right protocol:
accession tissue protocol treatment _date __count SRR11111 blood omni-atac-seq-improved-atac-seq-protocol-14egn94jyl5d|"Omni-ATAC-seq" control 2026-01-01 12 SRR11112 blood omni-atac-seq-improved-atac-seq-protocol-14egn94jyl5d|"Omni-ATAC-seq" IFNg6h 2026-01-01 31 SRR11113 spleen omni-atac-seq-improved-atac-seq-protocol-14egn94jyl5d|"Omni-ATAC-seq" control 2024-08-21 8 SRR11114 spleen omni-atac-seq-improved-atac-seq-protocol-14egn94jyl5d|"Omni-ATAC-seq" IFNg6h 2026-08-22 17
The most likely place to encounter problems when building a faceted composite is a mismatch between the metadata TSV file and the subtrack names in the trackDb stanza. Check carefully to ensure that the values in the primaryKey column match the names of the subtracks, including capitalization. The hubCheck tool has not yet been updated to automate these checks, but that work is in progress.
Other important considerations: