This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (
Help us improve Python packaging - Donate today!

Interface to UCSC genomic databases. Also allows things like up/downstream/k-nearest-neighbor queries and mirroring of tables to local sqlite databases

Project Description

A rendered version of the docs is available at:

A paper describing cruzdb is in Bioinformatics:

cruzdb overview

The UCSC Genomes Database is a great resource for annoations, regulation and variation and all kinds of data for a growing number of taxa. This library aims to make utilizing that data simple so that we can do sophisticated analyses without resorting to awk-ful, error-prone manipulations. As motivation, here’s an example of some of the capabilities:

>>> from cruzdb import Genome

>>> g = Genome(db="hg18")

>>> muc5b = g.refGene.filter_by(name2="MUC5B").first()
>>> muc5b

>>> muc5b.strand

# the first 4 introns
>>> muc5b.introns[:4]
[(1200999L, 1203486L), (1203543L, 1204010L), (1204082L, 1204420L), (1204682L, 1204836L)]

# the first 4 exons.
>>> muc5b.exons[:4]
[(1200870L, 1200999L), (1203486L, 1203543L), (1204010L, 1204082L), (1204420L, 1204682L)]

# note that some of these are not coding because they are < cdsStart
>>> muc5b.cdsStart

# the extent of the 5' utr.
>>> muc5b.utr5
(1200870L, 1200929L)

# we can get the (first 4) actual CDS's with:
>>> muc5b.cds[:4]
[(1200929L, 1200999L), (1203486L, 1203543L), (1204010L, 1204082L), (1204420L, 1204682L)]

# the cds sequence from the UCSC DAS server as a list with one entry per cds
>>> muc5b.cds_sequence #doctest: +ELLIPSIS
['atgggtgccccgagcgcgtgccggacgctggtgttggctctggcggccatgctcgtggtgccgcaggcag', ...]

>>> transcript = g.knownGene.filter_by(name="uc001aaa.2").first()
>>> transcript.is_coding

# convert a genome coordinate to a local coordinate.
>>> transcript.localize(transcript.txStart)

# or localize to the CDNA position.
>>> print transcript.localize(transcript.cdsStart, cdna=True)

Command-Line Interface

with cruzdb 0.5.4+ installed, given a file input.bed you can do:

python -m cruzdb hg18 input.bed refGene cpgIslandExt

to have the intervals annotated with the refGene and cpgIslandExt tables from versoin hg18.


… are so in. We can get one from a table as:

>>> df = g.dataframe('cpgIslandExt')
>>> df.columns #doctest: +ELLIPSIS
Index([chrom, chromStart, chromEnd, name, length, cpgNum, gcNum, perCpg, perGc, obsExp], dtype=object)

All of the above can be repeated using knownGene annotations by changing ‘refGene’ to ‘knownGene’. And, it can be done easily for a set of genes.


k-nearest neighbors, upstream, and downstream searches are available. Up and downstream searches use the strand of the query feature to determine the direction:

>>> nearest = g.knearest("refGene", "chr1", 9444, 9555, k=6)
>>> up_list = g.upstream("refGene", "chr1", 9444, 9555, k=6)
>>> down_list = g.downstream("refGene", "chr1", 9444, 9555, k=6)


The above uses the mysql interface from UCSC. It is now possible to mirror any tables from UCSC to a local sqlite database via:

# cleanup

>>> import os
>>> if os.path.exists("/tmp/u.db"): os.unlink('/tmp/u.db')
>>> g = Genome('hg18')
>>> gs = g.mirror(['chromInfo'], 'sqlite:////tmp/u.db')

and then use as:

>>> gs.chromInfo
<class 'cruzdb.sqlsoup.chromInfo'>


Most of the per-row features are implemented in cruzdb/ in the Feature class. If you want to add something to a feature (like the existing feature.utr5) add it here.

The tables are reflected using sqlalchemy and mapped in the __getattr__method of the Genome class in cruzdb/

So a call like:


calls the __getattr__ method with the table arg set to ‘knownGene’ that table is then reflected and an object with parent classes of Feature and sqlalchemy’s declarative_base is returned.



To start coding, it is probably polite to grab your own copy of some of the UCSC tables so as not to overload the UCSC server. You can run something like:

Genome('hg18').mirror(["refGene", "cpgIslandExt", "chromInfo", "knownGene", "kgXref"], "sqlite:////tmp/hg18.db")

Then the connection would be something like:

g = Genome("sqlite:////tmp/hg18.db")

If you have a feature you like to use/implement, open a ticket on github for discussion. Below are some ideas.

Release History

Release History

This version
History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


Download Files

Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
cruzdb-0.5.6.tar.gz (29.4 kB) Copy SHA256 Checksum SHA256 Source Jul 9, 2014

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting