+
Composite tracks are a standard way to collect a number of related tracks within -the browser and interact with them in a unified interface. For example, our Conservation tracks -are often organized as composites as are each of our "All GENCODE" tracks (see -here). -The standard user interface works for intermediate numbers of subtracks (around 20-200), -but becomes unusable when that scales up into the thousands. Faceted composites provide -an alternate user interface for composite tracks that is designed fork these situations. +
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 (see here). +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, etc.), and where only a few of them may be of interest for 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 TL;DR version of this is that a faceted composite is like any other composite,
-but don't add views or subgroups. All tracks in a mix of types live under the same
-composite parent. The 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 have
+but cannot include views or subgroups. All subtracks in a mix of types live under the same
+parent: the composite track itself. The 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 have
names that match "<parent_name>_<primaryKey>".
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 @@ -65,31 +69,31 @@ parent myComposite type bigBed bigDataUrl https://url/to/ex2.bb shortLabel ex2 peaks longLabel ex2 Blood data peaksmetadata.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 entries: 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.
@@ -294,28 +298,28 @@
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 block. 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.