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

Sparse binary format for genomic interaction matrices

Project Description

A cool place to store your Hi-C

Cooler is a support library for a sparse, compressed, binary persistent storage format, called cool, used to store genomic interaction data, such as Hi-C contact matrices.

The cool file format is a reference implementation of a genomic matrix data model using HDF5 as the container format.

The cooler package aims to provide the following functionality:

  • Build contact matrices at any resolution from a list of contacts.
  • Query a contact matrix.
  • Export and visualize the data.
  • Perform efficient out-of-core operations, such as aggregation and contact matrix normalization (a.k.a. balancing).
  • Provide a clean and well-documented Python API to facilitate working with potentially larger-than-memory data.

To get started:

  • Read the documentation.
  • See the Jupyter Notebook walkthrough.
  • cool files from published Hi-C data sets are available at ftp://cooler.csail.mit.edu/coolers.

Related projects:

Installation

Requirements:

  • Python 2.7/3.4+
  • libhdf5 and Python packages numpy, scipy, pandas, h5py. We highly recommend using the conda package manager to install scientific packages like these. To get it, you can either install the full Anaconda Python distribution or just the standalone conda package manager.

Install from PyPI using pip.

$ pip install cooler

See the docs for more information.

Command line interface

The cooler package includes command line tools for creating, querying and manipulating cool files.

$ cooler makebins $CHROMSIZES_FILE $BINSIZE > bins.10kb.bed
$ cooler cload bins.10kb.bed $CONTACTS_FILE out.cool
$ cooler balance -p 10 out.cool
$ cooler dump -b -t pixels --header --join -r chr3:10,000,000-12,000,000 -r2 chr17 out.cool | head
chrom1  start1  end1    chrom2  start2  end2    count   balanced
chr3    10000000        10010000        chr17   0       10000   1       0.810766
chr3    10000000        10010000        chr17   520000  530000  1       1.2055
chr3    10000000        10010000        chr17   640000  650000  1       0.587372
chr3    10000000        10010000        chr17   900000  910000  1       1.02558
chr3    10000000        10010000        chr17   1030000 1040000 1       0.718195
chr3    10000000        10010000        chr17   1320000 1330000 1       0.803212
chr3    10000000        10010000        chr17   1500000 1510000 1       0.925146
chr3    10000000        10010000        chr17   1750000 1760000 1       0.950326
chr3    10000000        10010000        chr17   1800000 1810000 1       0.745982

See also:

Python API

The cooler library provides a thin wrapper over the excellent h5py Python interface to HDF5. It supports creation of cooler files and the following types of range queries on the data:

  • Tabular selections are retrieved as Pandas DataFrames and Series.
  • Matrix selections are retrieved as NumPy arrays or SciPy sparse matrices.
  • Metadata is retrieved as a json-serializable Python dictionary.
  • Range queries can be supplied using either integer bin indexes or genomic coordinate intervals.
>>> import cooler
>>> import matplotlib.pyplot as plt
>>> c = cooler.Cooler('bigDataset.cool')
>>> resolution = c.info['bin-size']
>>> mat = c.matrix(balance=True).fetch('chr5:10,000,000-15,000,000')
>>> plt.matshow(np.log10(mat), cmap='YlOrRd')
>>> import multiprocessing as mp
>>> import h5py
>>> pool = mp.Pool(8)
>>> f = h5py.File('bigDataset.cool', 'r')
>>> weights, stats = cooler.ice.iterative_correction(f, map=pool.map, ignore_diags=3, min_nnz=10)

See also:

Schema

The cool format implements a simple data model that stores a genomic matrix in a sparse representation, crucial for developing robust tools for use on increasingly high resolution Hi-C data sets, including streaming and out-of-core algorithms.

The data tables in a cool file are stored in a columnar representation as HDF5 groups of 1D array datasets of equal length. The contact matrix itself is stored as a single table containing only the nonzero upper triangle pixels.

Contributing

Pull requests are welcome. The current requirements for testing are nose and mock.

For development, clone and install in “editable” (i.e. development) mode with the -e option. This way you can also pull changes on the fly.

$ git clone https://github.com/mirnylab/cooler.git
$ cd cooler
$ pip install -e .

License

BSD (New)

Release History

Release History

This version
History Node

0.7.4

History Node

0.7.3

History Node

0.7.2

History Node

0.7.1

History Node

0.7.0

History Node

0.6.6

History Node

0.6.5

History Node

0.6.4

History Node

0.6.3

History Node

0.6.2

History Node

0.6.1

History Node

0.6.0

History Node

0.5.3

History Node

0.5.2

History Node

0.5.1

History Node

0.5.0

History Node

0.4.1

History Node

0.4.0

History Node

0.3.0

History Node

0.2.1

History Node

0.2

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
cooler-0.7.4-py2.py3-none-any.whl (78.0 kB) Copy SHA256 Checksum SHA256 3.5 Wheel May 25, 2017
cooler-0.7.4.tar.gz (51.4 MB) Copy SHA256 Checksum SHA256 Source May 25, 2017

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