v0.5.0rc2

NOTE: THIS RELEASE BREAKS BACKWARDS COMPATIBILITY!

This release addresses two major issues:

• Integration with bioframe viewframes defined as of bioframe v0.3.
• Synchronization of the CLI and Python API

Additionally, the documentation has been greatly improved and now includes detailed tutorials that show how to use the cooltools API in conjunction with other Open2C libraries. These tutorials are automatically re-built from notebooks copied from https://github.com/open2c/open2c_examples repository.

API changes

• More clear separation of top-level user-facing functions and low-level API.

  • Most standard analyses can be performed using just the user-facing functions which are imported into the top-level namespace. Some of them are new or heavily modified from earlier versions.

    • cooltools.expected_cis and cooltools.expected_trans for average by-diagonal contact frequency in intra-chromosomal data and in inter-chromosomal data, respectively

    • cooltools.eigs_cis and cooltools.eigs_trans for eigenvectors (compartment profiles) of cis and trans data, repectively

    • cooltools.digitize and cooltools.saddle can be used together for creation of 2D summary tables of Hi-C interactions in relation to a digitized genomic track, such as eigenvectors

    • cooltools.insulation for insulation score and annotation of insulating boundaries

    • cooltools.directionality for directionality index

    • cooltools.pileup for average signal at 1D or 2D genomic features, including APA

    • cooltools.coverage for calculation of per-bin sequencing depth

    • cooltools.sample for random downsampling of cooler files

    • For non-standard analyses that require custom algorithms, a lower level API is available under cooltools.api

• Most functions now take an optional view_df argument. A pandas dataframe defining a genomic view (https://bioframe.readthedocs.io/en/latest/guide-technical-notes.html) can be provided to limit the analyses to regions included in the view. If not provided, the analysis is performed on whole chromosomes according to what’s stored in the cooler.

• All functions apart from coverage now take a clr_weight_name argument to specify how the desired balancing weight column is named. Providing a None value allows one to use unbalanced data (except the eigs_cis, eigs_trans methods, since eigendecomposition is only defined for balanced Hi-C data).

• The output of expected-cis function has changed: it now contains region1 and region2 columns (with identical values in case of within-region expected). Additionally, it now allows smoothing of the result to avoid noisy values at long distances (enabled by default and result saved in additional columns of the dataframe)

• The new cooltools.insulation method includes a thresholding step to detect strong boundaries, using either the Li or the Otsu method (from skimage.thresholding), or a fixed float value. The result of thresholding for each window size is stored as a boolean in a new column is_boundary_{window}.

• New subpackage sandbox for experimental codes that are either candidates for merging into cooltools or candidates for removal. No documentation and tests are expected, proceed at your own risk.

• New subpackage lib for auxiliary modules

CLI changes

• CLI tools are renamed with prefixes dropped (e.g. diamond-insulation is now insulation), to align with names of user-facing API functions.
• The CLI tool for expected has been split in two for intra- and inter-chromosomal data (expected-cis and expected-trans, repectively).
• Similarly, the compartment profile calculation is now separate for cis and trans (eigs-cis and eigs-trans).
• New CLI tool cooltools pileup for creation of average features based on Hi-C data. It takes a .bed- or .bedpe-style file to create average on-diagonal or off-diagonal pileups, respectively.

Maintenance

Support for Python 3.6 dropped