Skip to content
Universal Transcript Archive: comprehensive genome-transcript alignments; multiple transcript sources, versions, and alignment methods; available as a docker image
Python Perl TSQL Makefile Shell PLpgSQL Other
Branch: master
Clone or download
Latest commit ea866a5 Jul 21, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
archive moved old scripts from sbin/ to archive/ Oct 24, 2016
bin Improvements for creating the NCBI schema on uta (#210) Nov 4, 2017
dev more python3 updates Jul 12, 2019
doc mostly doc changes prior before moving to minion Jul 5, 2017
etc update for loading with localhost (rather than socket) Jul 6, 2017
loading more python3 updates Jul 12, 2019
misc add_ensembl_data_v2 (#214) Jan 18, 2019
sql Improvements for creating the NCBI schema on uta (#210) Nov 4, 2017
tests added core-187 demo script; fixed minor issue in ensembl-fetch Aug 28, 2015
uta more python3 updates Jul 12, 2019
.gitignore added code to build ncbi.geneinfo table Jul 7, 2017
.travis.yml more attempts to fix travis builds Sep 23, 2016
LICENSE.txt updated authors; other minor changes May 14, 2015
Makefile manually edited 0.2.0a1.clog Aug 18, 2015
README.rst added health check to README May 30, 2017
setup.cfg standardized doc/ layout Aug 17, 2015 Improvements for creating the NCBI schema on uta (#210) Nov 4, 2017


uta -- Universal Transcript Archive

bringing smiles to transcript users since 2013

build_status docker_badge Health Check


The UTA (Universal Transcript Archive) stores transcripts aligned to sequence references (typically genome reference assemblies). It supports aligning the same transcript to multiple references using multiple alignment methods. Specifically, it facilitates the following:

  • querying for multiple transcript sources through a single interface
  • interpretating variants reported in literature against obsolete transcript records
  • identifying regions where transcript and reference genome sequence assemblies disagree
  • comparing transcripts across from distinct sources
  • comparing transcript alignments generated by multiple methods
  • identifying ambiguities in transcript alignments

UTA is used by the hgvs package to map variants between genomic, transcript, and protein coordinates.

This code repository is primarily used for generating the UTA database. The primary interface for the database itself is via direct PostgreSQL access. (A REST interface is planned, but not yet available.)

Accessing the Public UTA Instance

Invitae provides a public instance of UTA. The connection parameters are:

param value
port 5432 (default)
database uta
login anonymous
password anonymous

For example:

$ PGPASSWORD=anonymous psql -h -U anonymous -d uta

Or, in Python:

> import psycopg2, psycopg2.extras
> conn = psycopg2.connect(" dbname=uta user=anonymous password=anonymous")
> cur = conn.cursor(cursor_factory=psycopg2.extras.DictCursor)
> cur.execute("select * from uta_20140210.tx_def_summary_v where hgnc='BRCA1'")
> row = cur.fetchone()
> dict(row)
'hgnc': 'BRCA1',
'tx_ac': 'ENST00000586385',
'cds_md5': '5d405c70b9b79add38d28e5011a6ddc0',
'es_fingerprint': '95d60b8d62f5c23cbeff3499eedf5e89',
'cds_start_i': 144,
'cds_end_i': 666,
'starts_i': [0, 148, 226, 267, 351, 406, 480, 541],
'ends_i': [148, 226, 267, 351, 406, 480, 541, 781],
'lengths': [148, 78, 41, 84, 55, 74, 61, 240],

Installing UTA Locally

Installing with Docker (preferred)

docker enables the distribution of lightweight, isolated packages that run on essentially any platform. When you use this approach, you will end up with a local UTA installation that runs as a local postgresql process. The only requirement is docker itself -- you will not need to install postgresql or any of its dependencies.

  1. Install docker.

  2. Fetch the uta docker image from docker hub.

    $ docker pull biocommons/uta:uta_20150827

    This process will likely take 1-3 minutes.

  3. Run the image

    $ docker run -dit --name uta_20150827 -p 50827:5432 biocommons/uta:uta_20150827

    The first time you run this image, it will initialize a postgresql database cluster, then download a database dump and install it. -d starts the container in daemon (background) mode. To see progress:

    $ docker logs -f uta_20150827

    You will see messages from several processes running in parallel. Near the end, you'll see:

    == You may now connect to uta.  No password is required.

    Hit Ctrl-C to stop watching logs. (The container will still be running.)

  4. Test your installation

    With the test commands below, you should see a table dump with at least 4 lines showing schema_version, create date, license, and uta (code) version used to build the instance.


    On Linux, where docker runs natively, -p 50827:5432 option to the docker run command causes localhost:50827 to be mapped to the container port 5432. The following command connects to the UTA instance:

    $ psql -h localhost -p 50827 -U anonymous -d uta -c 'select * from uta_20150827.meta'

    With DockerToolbox (Mac and Windows)

    On Mac and Windows, docker runs in a virtual machine using DockerToolbox. The -p 50827:5432 option to the docker run maps VM port 50827 (not that of the host OS). In order to connect to UTA, you must use the IP address of the VM, like this:

    $ psql -h $(docker-machine ip default) -p 50827 -U anonymous -d uta -c 'select * from uta_20150827.meta'

Installing from database dumps

Users should prefer the public UTA instance ( or the docker installation wherever possible. When those options are not available, users may wish to create a local postgresql database from database dumps. Users choosing this method of installation should be experienced with PostgreSQL administration.

The public site and docker images are built from exactly the same dumps as provided below. Building a database from these should result in a local database that is essentially identical to those options.


Due to the heterogeneity of operating systems and PostgreSQL installations, installing from database dumps is unsupported.

The following commands will likely need modification appropriate for the installation environment.

  1. Download an appropriate database dump from

  2. Create a user and database.

    You may choose any username and database name you like. uta and uta_admin are likely to ease installation.

    $ createuser -U postgres uta_admin
    $ createdb -U postgres -O uta_admin uta
  3. Restore the database.

    $ gzip -cdq uta_20150827.pgd.gz | psql -U uta_admin -1 -v ON_ERROR_STOP=1 -d uta -Eae


See the hgvs docs for information how to configure hgvs to use this instance.

Development and Testing

To develop UTA, follow these steps.

  1. Setup a virtual environment.

With virtualenvwrapper:

mkvirtualenv uta-ve

Or, with virtualenv:

virtualenv uta-ve
source uta-ve/bin/activate
  1. Clone UTA.:

    hg clone ssh://
    cd uta
    make develop
  2. Restore a database or load a new one

    UTA currently expects to have an existing database available. When the loaders are available, instructions will appear here. For now, creating an instance of TranscriptDB without arguments will cause it to connect to a populated Invitae database.

You can’t perform that action at this time.