Cooler API

API to operate on .cool files. Compared to the generic API, this API provides:

• more control over how files are opened

• direct access to HDF5 group and datasets

• lower overhead

• support for creating .cool files

• support for opening collections of Coolers (e.g. .mcool and .scool files)

Single-resolution Cooler (.cool)

class File

Constructors

File(const File &other) = delete;

File(File &&other) noexcept = default;

[[nodiscard]] explicit File(std::string_view uri, std::size_t cache_size_bytes = DEFAULT_HDF5_CACHE_SIZE * 4, bool validate = true);

[[nodiscard]] explicit File(RootGroup entrypoint, std::size_t cache_size_bytes = DEFAULT_HDF5_CACHE_SIZE * 4, bool validate = true);

Factory functions

[[nodiscard]] static File open_random_access(RootGroup entrypoint, std::size_t cache_size_bytes = DEFAULT_HDF5_CACHE_SIZE * 4, bool validate = true);

[[nodiscard]] static File open_read_once(RootGroup entrypoint, std::size_t cache_size_bytes = DEFAULT_HDF5_CACHE_SIZE * 4, bool validate = true);

template<typename PixelT = DefaultPixelT>
[[nodiscard]] static File create(RootGroup entrypoint, const Reference &chroms, std::uint32_t bin_size, Attributes attributes = Attributes::init<PixelT>(0), std::size_t cache_size_bytes = DEFAULT_HDF5_CACHE_SIZE * 4, std::uint32_t compression_lvl = DEFAULT_COMPRESSION_LEVEL);

template<typename PixelT = DefaultPixelT>
[[nodiscard]] static File create(std::string_view uri, const Reference &chroms, std::uint32_t bin_size, bool overwrite_if_exists = false, Attributes attributes = Attributes::init<PixelT>(0), std::size_t cache_size_bytes = DEFAULT_HDF5_CACHE_SIZE * 4, std::uint32_t compression_lvl = DEFAULT_COMPRESSION_LEVEL);

Open/close methods

[[nodiscard]] static File open_random_access(std::string_view uri, std::size_t cache_size_bytes = DEFAULT_HDF5_CACHE_SIZE * 4, bool validate = true);

[[nodiscard]] static File open_read_once(std::string_view uri, std::size_t cache_size_bytes = DEFAULT_HDF5_CACHE_SIZE * 4, bool validate = true);

void close();

Note that Files are automatically closed upon destruction.

Operators

File &operator=(const File &other) = delete;

File &operator=(File &&other) noexcept = default;

[[nodiscard]] explicit operator bool() const noexcept;

Return whether the File is in a valid state and other member functions can be safely called.

Accessors

[[nodiscard]] std::string uri() const;

[[nodiscard]] std::string hdf5_path() const;

[[nodiscard]] std::string path() const;

[[nodiscard]] auto chromosomes() const noexcept -> const Reference&;

[[nodiscard]] auto bins() const noexcept -> const BinTable&;

[[nodiscard]] auto bins_ptr() const noexcept -> std::shared_ptr<const BinTable>;

[[nodiscard]] std::uint32_t resolution() const noexcept;

[[nodiscard]] std::uint64_t nbins() const;

[[nodiscard]] std::uint64_t nchroms() const;

[[nodiscard]] std::uint64_t nnz() const;

[[nodiscard]] auto attributes() const noexcept -> const Attributes&;

[[nodiscard]] auto group(std::string_view group_name) -> Group&;

[[nodiscard]] auto dataset(std::string_view dataset_name) -> Dataset&;

[[nodiscard]] auto group(std::string_view group_name) const -> const Group&;

[[nodiscard]] auto dataset(std::string_view dataset_name) const -> const Dataset&;

[[nodiscard]] const NumericVariant &pixel_variant() const noexcept;

template<typename T>
[[nodiscard]] bool has_pixel_of_type() const noexcept;

[[nodiscard]] bool has_signed_pixels() const noexcept;

[[nodiscard]] bool has_unsigned_pixels() const noexcept;

[[nodiscard]] bool has_integral_pixels() const noexcept;

[[nodiscard]] bool has_float_pixels() const noexcept;

Iteration

template<typename N>
[[nodiscard]] typename PixelSelector::iterator<N> begin(std::string_view weight_name = "NONE") const;

template<typename N>
[[nodiscard]] typename PixelSelector::iterator<N> end(std::string_view weight_name = "NONE") const;

template<typename N>
[[nodiscard]] typename PixelSelector::iterator<N> cbegin(std::string_view weight_name = "NONE") const;

template<typename N>
[[nodiscard]] typename PixelSelector::iterator<N> cend(std::string_view weight_name = "NONE") const;

Fetch methods (1D queries)

[[nodiscard]] PixelSelector fetch(const balancing::Method &normalization = balancing::Method::NONE()) const;

[[nodiscard]] PixelSelector fetch(std::shared_ptr<const balancing::Weights> weights) const;

[[nodiscard]] PixelSelector fetch(std::string_view range, std::shared_ptr<const balancing::Weights> weights, QUERY_TYPE query_type = QUERY_TYPE::UCSC) const;

[[nodiscard]] PixelSelector fetch(std::string_view chrom_name, std::uint32_t start, std::uint32_t end, std::shared_ptr<const balancing::Weights> weights) const;

[[nodiscard]] PixelSelector fetch(std::string_view range, const balancing::Method &normalization = balancing::Method::NONE(), QUERY_TYPE query_type = QUERY_TYPE::UCSC) const;

[[nodiscard]] PixelSelector fetch(std::string_view chrom_name, std::uint32_t start, std::uint32_t end, const balancing::Method &normalization = balancing::Method::NONE()) const;

[[nodiscard]] PixelSelector fetch(std::uint64_t first_bin, std::uint64_t last_bin, std::shared_ptr<const balancing::Weights> weights = nullptr) const;

Fetch methods (2D queries)

[[nodiscard]] PixelSelector fetch(std::string_view range1, std::string_view range2, std::shared_ptr<const balancing::Weights> weights, QUERY_TYPE query_type = QUERY_TYPE::UCSC) const;

[[nodiscard]] PixelSelector fetch(std::string_view chrom1_name, std::uint32_t start1, std::uint32_t end1, std::string_view chrom2_name, std::uint32_t start2, std::uint32_t end2, std::shared_ptr<const balancing::Weights> weights) const;

[[nodiscard]] PixelSelector fetch(std::string_view range1, std::string_view range2, const balancing::Method &normalization = balancing::Method::NONE(), QUERY_TYPE query_type = QUERY_TYPE::UCSC) const;

[[nodiscard]] PixelSelector fetch(std::string_view chrom1_name, std::uint32_t start1, std::uint32_t end1, std::string_view chrom2_name, std::uint32_t start2, std::uint32_t end2, const balancing::Method &normalization = balancing::Method::NONE()) const;

[[nodiscard]] PixelSelector fetch(std::uint64_t first_bin1, std::uint64_t last_bin1, std::uint64_t first_bin2, std::uint64_t last_bin2, std::shared_ptr<const balancing::Weights> weights = nullptr) const;

Write pixels

template<typename PixelIt, typename = std::enable_if_t<is_iterable_v<PixelIt>>>
void append_pixels(PixelIt first_pixel, PixelIt last_pixel, bool validate = false);

Normalization

[[nodiscard]] bool has_normalization(std::string_view normalization) const;

std::shared_ptr<const balancing::Weights> read_normalization(std::string_view normalization, bool rescale = false) const;

std::shared_ptr<const balancing::Weights> normalization(std::string_view normalization, balancing::Weights::Type type, bool rescale = false) const;

[[nodiscard]] bool has_normalization(const balancing::Method &normalization) const;

std::shared_ptr<const balancing::Weights> normalization(const balancing::Method &normalization, bool rescale = false) const;

std::shared_ptr<const balancing::Weights> normalization(const balancing::Method &normalization, balancing::Weights::Type type, bool rescale = false) const;

[[nodiscard]] std::vector<balancing::Method> avail_normalizations() const;

bool purge_weights(std::string_view name = "");

template<typename It>
static void write_weights(std::string_view uri, std::string_view name, It first_weight, It last_weight, bool overwrite_if_exists = false, bool divisive = false);

template<typename It>
void write_weights(std::string_view name, It first_weight, It last_weight, bool overwrite_if_exists = false, bool divisive = false);

Others

void flush();

void validate_bins(bool full = false) const;

Multi-resolution Cooler (.mcool)

class MultiResFile

Constructors

explicit MultiResFile(const std::filesystem::path &path, unsigned int mode = HighFive::File::ReadOnly);

Factory functions

[[nodiscard]] static MultiResFile create(const std::filesystem::path &path, const Reference &chroms, bool force_overwrite = false);

template<typename ResolutionIt>
[[nodiscard]] static MultiResFile create(const std::filesystem::path &path, const File &base, ResolutionIt first_res, ResolutionIt last_res, bool force_overwrite = false);

Open/close methods

[[nodiscard]] File open(std::uint32_t resolution) const;

Operators

[[nodiscard]] explicit operator bool() const noexcept;

Accessors

[[nodiscard]] std::string path() const;

[[nodiscard]] auto chromosomes() const noexcept -> const Reference&;

[[nodiscard]] constexpr const std::vector<std::uint32_t> &resolutions() const noexcept;

[[nodiscard]] constexpr const MultiResAttributes &attributes() const noexcept;

Modifiers

File copy_resolution(const cooler::File &clr);

template<typename N = DefaultPixelT>
File create_resolution(std::uint32_t resolution, Attributes attributes = Attributes::init<N>(0));

RootGroup init_resolution(std::uint32_t resolution);

Others

[[nodiscard]] static std::uint32_t compute_base_resolution(const std::vector<std::uint32_t> &resolutions, std::uint32_t target_res);

static void coarsen(const File &clr1, File &clr2, std::vector<ThinPixel<std::int32_t>> &buffer);

Single-cell Cooler (.scool)

class SingleCellFile

Constructors

explicit SingleCellFile(const std::filesystem::path &path, unsigned int mode = HighFive::File::ReadOnly);

Factory functions

[[nodiscard]] static SingleCellFile create(const std::filesystem::path &path, const Reference &chroms, std::uint32_t bin_size, bool force_overwrite = false);

Open/close functions

[[nodiscard]] File open(std::string_view cell) const;

Operators

[[nodiscard]] explicit operator bool() const noexcept;

Accessors

[[nodiscard]] std::string path() const;

[[nodiscard]] auto chromosomes() const noexcept -> const Reference&;

[[nodiscard]] auto bins() const noexcept -> const BinTable&;

[[nodiscard]] std::uint32_t resolution() const noexcept;

[[nodiscard]] constexpr const phmap::btree_set<std::string> &cells() const noexcept;

[[nodiscard]] constexpr const SingleCellAttributes &attributes() const noexcept;

Modifiers

template<typename N>
File create_cell(std::string_view cell, Attributes attrs = Attributes::init<N>(0));

Others

template<typename N>
File aggregate(std::string_view uri, bool overwrite_if_exists = false, std::size_t chunk_size = 500'000, std::size_t update_frequency = 10'000'000) const;

Pixel selector

class PixelSelector

Operators

[[nodiscard]] bool operator==(const PixelSelector &other) const noexcept;

[[nodiscard]] bool operator!=(const PixelSelector &other) const noexcept;

Iteration

template<typename N>
[[nodiscard]] auto begin() const -> iterator<N>;

template<typename N>
[[nodiscard]] auto end() const -> iterator<N>;

template<typename N>
[[nodiscard]] auto cbegin() const -> iterator<N>;

template<typename N>
[[nodiscard]] auto cend() const -> iterator<N>;

Fetch at once

template<typename N>
[[nodiscard]] std::vector<Pixel<N>> read_all() const;

template<typename N>
[[nodiscard]] Eigen::SparseMatrix<N> read_sparse() const;

template<typename N>
[[nodiscard]] Eigen::Matrix<N, Eigen::Dynamic, Eigen::Dynamic> read_dense() const;

Accessors

[[nodiscard]] const PixelCoordinates &coord1() const noexcept;

[[nodiscard]] const PixelCoordinates &coord2() const noexcept;

[[nodiscard]] const BinTable &bins() const noexcept;

[[nodiscard]] std::shared_ptr<const BinTable> bins_ptr() const noexcept;