Welcome to hub2gos documentation!

hub2gos

Transpiler to map a UCSC Trackhub configuration to a Gosling spec

Installation

Install the package directly from PyPI:

pip install hub2gos

Quickstart

To compile a UCSC trackhub into a Gosling specification from the command line, simply point the transpiler at your hub.txt file:

python -m hub2gos.cli path/to/hub.txt

hub2gos supports both the standard UCSC Trackhub mode and the useOneFile mode.

CLI Usage

usage: python -m hub2gos.cli [-h] [-o OUTPUT] [-c COORDS] [-a ASSEMBLY] [-v] hub_file

Convert UCSC TrackHub track information to a Gosling Spec

positional arguments:
  hub_file              Path to local hub.txt file. Supports both standard and useOneFile modes.

options:
  -h, --help            show this help message and exit
  -o, --output OUTPUT   Output JSON file path (prints to stdout if omitted)
  -c, --coords COORDS   Optional coordinates to set starting domain of tracks.
                        Must be in the format 'chr:start-end' (e.g., 'chr1:1000000-2000000')
  -a, --assembly ASSEMBLY
                        Optional genome assembly (e.g., 'hg38', 'mm10').
                        If not provided, will throw an error in standard mode.
                        This value is not used in useOneFile mode.
  -v, --verbose         Enable detailed logging output

Input Data Specifications & Compression Rules

When converting a UCSC Track Hub configuration using hub2gos, input data URLs must adhere strictly to the coordinate streaming capabilities of modern web browsers. In addition, some UCSC Track Hub file types are not compatible and must have an alternate file path under the gos_url property that will be used to read the data into Gosling instead. Otherwise the transpiler will use the bigDataUrl property instead.

This utility will return a Gosling Spec for the UCSC trackhub input, but does not validate that the supplied paths are streamable. There is a HTML page called quick_viewer.html on the top-level of this repository that can be used to validate the Gosling visualization itself by passing in the JSON spec.

Supported Formats & Compression Matrices

UCSC Track Type	Expected File Suffix(es)	gos_url file?	Tabix Index Required?	Work-in-progress?
BAM	.bam	No	Yes (.bam.bai)	Yes
BigBed	.bb, .bigbed	.bed.gz	Yes (BGZF-formatted .tbi)	No
BigInteract	.bi, .bigInteract	“beddb” HiGlass tileset	No	No
BigWig	.bw, .bigwig	No	No	No
HiC	.hic	“cooler” HiGlass tileset	No	No
VCF	.vcf.gz	No	Yes (BGZF-formatted .tbi)	Yes

⚠️ Performance Note on BAM Tracks: While natively supported by Gosling, rendering BAM files over a broad genomic coordinate range can degrade client-side performance. For better performance, consider converting BAM files to BigWig (for depth density) or BigBed/BED (for structural mutations) during your server pipeline staging.

Crucial Constraints

None of these contraints will prevent you from generating the Gosling spec JSON. They will however prevent you from streaming the data in the Gosling viewer.

1. Plaintext Text Files: Uncompressed tabular streams (e.g., raw .bed or .vcf text targets) are unsupported for chunked client-side streaming. Text tracking formats must be block-gzipped using bgzip before indexing. Documentation on bgzip

2. Alternative Compressors: High-ratio archival compressors such as bzip2 (.bz2) or xz (.xz) are completely unsupported. These engines do not produce block-level byte partitions, making selective genomic coordinate slicing over network requests impossible.

3. For any track type that recommends serving files on a HiGlass server, you can peruse the HiGlass documentation to learn how to set up a HiGlass server, aggregate files with Clodius, and ingest them into HiGlass.

CLI Reference

Command line interface to convert UCSC TrackHub trackDb files into Gosling JSON specifications.

hub2gos.cli.main()

Entrypoint for the CLI

API Reference

Takes parsed UCSC Trackhub file track stanzas and returns a vertical Gosling View containing all tracks and containers.

hub2gos.compiler.compile_track_stanzas(track_descriptors, coords=None)

Compiles a list of UCSC Trackhub track stanzas into a vertical Gosling View.

Parameters:

• track_descriptors (list) – A list of dictionaries, each representing a UCSC Trackhub track stanza.

• coords (str, optional) – A string representing the initial genomic coordinates for the view in the format (chromosome, start, end). Defaults to None.

Returns:

A vertical Gosling View containing all tracks and containers.

Return type:

gos.View

hub2gos.compiler.zoom_view_to_domain(view, position_str)

Zooms a Gosling view to a specified genomic domain with padding.

Parameters:

• view – A Gosling view object to be updated.

• position_str (str) – A string representing the genomic position in the format expected by parse_position_str.

Returns:

The updated Gosling view object with its xDomain set to the specified genomic coordinates plus padding.

Notes

Adds a base padding of 1500 base pairs to both sides of the specified genomic interval.

Handles Gosling Track configurations for different data types (BigWig, BED, BigInteract).

class hub2gos.components.BamSpec(data_url, color='steelblue', title='', ident='', visibility='full')

Bases: TrackSpec

This class is a work in progress and may not be fully functional.

Represents a Gosling Track specification for BAM (Binary Alignment/Map) files. An index file is required for this track type and is assumed to be located at the same URL with a .bai extension.

get_encoding(width, height, prefix='', is_child=False)

Gets the Gosling encoding for the Bam track.

Parameters:

• width (int) – The width of the track.

• height (int) – The height of the track.

• prefix (str, optional) – A prefix to be added to the track ID. Defaults to “”.

• is_child (bool, optional) – Whether the track is a child track in a composite view. Defaults to False.

Returns:

A Gosling Track object representing the track encoding.

Return type:

gos.Track

class hub2gos.components.BedSpec(data_url, color='steelblue', title='', ident='', visibility='full')

Bases: TrackSpec

Represents a Gosling Track specification for BED files. Since BigBed files are not directly supported in Gosling, this method uses a gzipped BED file for visualization. An index file is required for this track type and is assumed to be located at the same URL with a BGZF-formatted .tbi extension.

get_encoding(width, height, prefix='', is_child=False)

Gets the Gosling encoding for the BigBed track.

Parameters:

• width (int) – The width of the track.

• height (int) – The height of the track.

• prefix (str, optional) – A prefix to be added to the track ID. Defaults to “”.

• is_child (bool, optional) – Whether the track is a child track in a composite view. Defaults to False.

Returns:

A Gosling Track object representing the track encoding.

Return type:

gos.Track

class hub2gos.components.BigInteractSpec(data_url, color='steelblue', title='', ident='', visibility='full')

Bases: TrackSpec

Represents a Gosling Track specification for BigInteract (chromatin interaction) files. This class is designed to handle BigInteract data visualization using a BEDDB-formatted file, which is typically stored on a HiGlass server.

get_encoding(width, height, prefix='', is_child=False)

Gets the Gosling encoding for the BigInteract track. Since BigInteract files are only compatible with UCSC, this method uses a BEDDB-formatted file for visualization.

Parameters:

• width (int) – The width of the track.

• height (int) – The height of the track.

• prefix (str, optional) – A prefix to be added to the track ID. Defaults to “”.

• is_child (bool, optional) – Whether the track is a child track in a composite view. Defaults to False.

Returns:

A Gosling Track object representing the track encoding.

Return type:

gos.Track

class hub2gos.components.BigWigSpec(data_url, color='steelblue', title='', ident='', visibility='full')

Bases: TrackSpec

Represents a Gosling Track specification for BigWig files.

get_encoding(width, height, prefix='', is_child=False)

Gets the Gosling encoding for the BigWig track.

Parameters:

• width (int) – The width of the track.

• height (int) – The height of the track.

• prefix (str, optional) – A prefix to be added to the track ID. Defaults to “”.

• is_child (bool, optional) – Whether the track is a child track in a composite view. Defaults to False.

Returns:

A Gosling Track object representing the track encoding.

Return type:

gos.Track

class hub2gos.components.HiCSpec(data_url, color='steelblue', title='', ident='', visibility='full')

Bases: TrackSpec

Represents a Gosling Track specification for HiC (chromatin interaction) files. This class is designed to handle HiC data visualization using a cooler-formatted file, which is typically stored on a HiGlass server.

get_encoding(width, height, prefix='', is_child=False)

Gets the Gosling encoding for the HiC track. Since HiC files are only compatible with UCSC, this method uses a cooler-formatted file for visualization.

Parameters:

• width (int) – The width of the track.

• height (int) – The height of the track.

• prefix (str, optional) – A prefix to be added to the track ID. Defaults to “”.

• is_child (bool, optional) – Whether the track is a child track in a composite view. Defaults to False.

Returns:

A Gosling Track object representing the track encoding.

Return type:

gos.Track

class hub2gos.components.TrackSpec(data_url, color='steelblue', title='', ident='', visibility='full')

Bases: ABC

Abstract base class for Gosling Track specifications. Subclasses should implement the get_encoding method to define how the track is rendered.

abstractmethod get_encoding(width, height, prefix='', is_child=False)

Abstract method to be implemented by subclasses to return the Gosling encoding for the track.

Parameters:

• width (int) – The width of the track.

• height (int) – The height of the track.

• prefix (str) – A prefix to be added to the track ID.

• is_child (bool) – Whether the track is a child track in a composite view.

Returns:

A Gosling Track object representing the track encoding.

Return type:

gos.Track

render(prefix='')

Renders the track encoding if the visibility is not set to “hide”.

Parameters:

prefix (str) – A prefix to be added to the track ID.

Returns:

The Gosling Track object if visibility is not “hide”, otherwise

Return type:

gos.Track or None

class hub2gos.components.VcfSpec(data_url, color='steelblue', title='', ident='', visibility='full')

Bases: TrackSpec

This class is a work in progress and may not be fully functional.

Represents a Gosling Track specification for VCF (Variant Call Format) files. The file must be gzipped An index file is required for this track type and is assumed to be located at the same URL with a BGZF-formatted .tbi extension.

get_encoding(width, height, prefix='', is_child=False)

Gets the Gosling encoding for the VCF track.

Parameters:

• width (int) – The width of the track.

• height (int) – The height of the track.

• prefix (str, optional) – A prefix to be added to the track ID. Defaults to “”.

• is_child (bool, optional) – Whether the track is a child track in a composite view. Defaults to False.

Returns:

A Gosling Track object representing the track encoding.

Return type:

gos.Track

Handles Gosling specialty View configurations (i.e. grouping multiple tracks into a single view).

class hub2gos.containers.MultiWigSpec(title='', ident='', visibility='full')

Bases: ViewSpec

Represents a Gosling View specification that can contain multiple wiggle tracks.

render(prefix='')

Renders the Gosling view specification for the MultiWigSpec.

Parameters:

prefix (str) – A prefix to be added to the view’s identifier.

Returns:

A Gosling overlay object representing the view, or None if the view is hidden.

class hub2gos.containers.ViewSpec(title='', ident='', visibility='full')

Bases: object

Represents a Gosling View specification that can contain multiple tracks.

add_member(track)

Adds a TrackSpec member to the view.

Takes an existing UCSC Trackhub track stanza and returns the appropriate Gosling Track or View Spec subclass instance.

class hub2gos.factory.TrackSpecFactory

Bases: object

Factory class to create Gosling TrackSpec instances based on UCSC Trackhub track stanzas.

static create_track(stanza)

Create a Gosling TrackSpec instance based on the provided UCSC Trackhub track stanza.

Return type:

getattr

class hub2gos.factory.ViewSpecFactory

Bases: object

Factory class to create Gosling ViewSpec instances based on UCSC Trackhub view stanzas.

static create_view(stanza)

Create a Gosling ViewSpec instance based on the provided UCSC Trackhub view stanza.

Return type:

getattr

Parse a UCSC Trackhub file and return a list of track stanzas as dictionaries.

Can accept UCSC useOneFile mode trackhub files or the more common multi-file trackhub format.

hub2gos.parser.fetch_trackdb_path(genomes_txt, assembly)

Extract the trackDb path for a specified genome assembly from UCSC genomes.txt format.

Parameters:

• genomes_txt (str) – The contents of a UCSC genomes.txt file as a string.

• assembly (str) – The genome assembly identifier to search for (e.g., ‘hg38’, ‘mm10’).

Returns:

The trackDb path for the specified assembly.

Return type:

str

Raises:

ValueError – If the assembly is not found or trackDb entry is missing.

hub2gos.parser.load_hub(hub_path, assembly=None)

Orchestrates loading and parsing a UCSC Trackhub from a local or remote source.

Parameters:

• hub_path (str) – Path or URL to a hub.txt file.

• assembly (str, optional) – Genome assembly (required for standard multi-file mode).

Returns:

List of parsed track stanza dictionaries ready for compilation.

Return type:

list[dict]

Raises:

• ValueError – If assembly is missing in standard mode or parsing fails.

• FileNotFoundError – If required files are not found.

hub2gos.parser.parse_hub_from_file(hub_txt)

Parse hub.txt file in useOneFile mode into hub metadata and track stanzas.

Parameters:

hub_txt (str) – The contents of a hub.txt file in useOneFile mode.

Returns:

(hub_dict, track_stanzas_list)

• hub_dict: Dictionary with hub metadata (hub, shortLabel, longLabel, email, useOneFile, genome)

• track_stanzas_list: List of track dictionaries

Return type:

tuple

Notes

In useOneFile mode, the hub.txt file contains both hub metadata and track definitions. Track stanzas begin with ‘track <name>’ and are separated by blank lines.

hub2gos.parser.parse_tracks_from_trackdb(trackdb_txt, trackdb_url)

Parse track stanzas from a UCSC trackDb.txt file.

Parameters:

• trackdb_txt (str) – The contents of a UCSC trackDb.txt file.

• trackdb_url (str) – The base URL of the trackDb.txt file (used to resolve relative URLs).

Returns:

A list of dictionaries, each representing a track with keys like ‘track’, ‘type’,

’bigDataUrl’, ‘shortLabel’, ‘longLabel’, ‘color’, ‘visibility’, etc.

Return type:

list

Example track dict:

{

“name”: “P1HC_ATAC_1”, “type”: “bigWig”, “bigDataUrl”: “https://example.com/P1HC_ATAC_1.bigwig”, “shortLabel”: “ATAC-seq 1st replicate”, “longLabel”: “ATAC-seq 1st replicate”, “color”: “rgb(31,119,180)”, “visibility”: “dense”,

}

hub2gos.parser.validate_hub_contents(hub_json)

Validate the contents of a UCSC Trackhub hub.txt file and its track stanzas.

Parameters:

hub_json (dict) – Dictionary containing hub metadata.

Returns:

True if the hub contents are valid, False otherwise.

Return type:

bool

hub2gos.parser.validate_track_contents(track_stanzas)

Validate the contents of track stanzas parsed from a UCSC Trackhub.

Parameters:

track_stanzas (list) – List of dictionaries, each representing a track stanza.

Returns:

True if all track stanzas are valid, False otherwise.

Return type:

bool

Functions that don’t really fit in any other module, but are used in multiple places.

hub2gos.utils.find_node_by_id(spec, id)

Recursively search a Gosling specification for a specific ‘id’. Returns the node if found, otherwise returns None.

Return type:

dict | None

hub2gos.utils.parse_position_str(position_str)

Parses a position string in the format ‘chromosome:start-end’ and returns its components.

Parameters:

position_str (str) – The position string to parse.

Returns:

A tuple containing (assembly, chromosome, start, end) if parsing is successful,

otherwise (None, None, None) on failure.

Return type:

tuple

hub2gos.utils.replace_node_by_id(node, target_id, replacement)

Recursively search a Gosling specification for a specific ‘id’ and replace that node.

Return type:

dict | list