Hi-C API

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

• more control over how files are opened

• access to .hic-specific metadata

• control over the interaction block cache

Common

enum class MatrixType

enumerator observed

enumerator oe

enumerator expected

enum class MatrixUnit

enumerator BP

enumerator FRAG

enum class QUERY_TYPE

enumerator BED

enumerator UCSC

File handle

class File

Constructors

explicit File(std::string url_, std::uint32_t resolution_, MatrixType type_ = MatrixType::observed, MatrixUnit unit_ = MatrixUnit::BP, std::uint64_t block_cache_capacity = 0);

Open/close methods

File &open(std::string url_, std::uint32_t resolution_, MatrixType type_ = MatrixType::observed, MatrixUnit unit_ = MatrixUnit::BP, std::uint64_t block_cache_capacity = 0);

File &open(std::uint32_t resolution_, MatrixType type_ = MatrixType::observed, MatrixUnit unit_ = MatrixUnit::BP, std::uint64_t block_cache_capacity = 0);

Accessors

[[nodiscard]] bool has_resolution(std::uint32_t resolution) const;

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

[[nodiscard]] const std::string &name() const noexcept;

[[nodiscard]] std::int32_t version() const noexcept;

[[nodiscard]] const Reference &chromosomes() const noexcept;

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

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

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

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

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

[[nodiscard]] const std::string &assembly() const noexcept;

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

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

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

Fetch methods (1D queries)

[[nodiscard]] PixelSelectorAll fetch(balancing::Method norm = balancing::Method::NONE()) const;

[[nodiscard]] PixelSelector fetch(std::string_view range, balancing::Method norm = 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, balancing::Method norm = balancing::Method::NONE()) const;

[[nodiscard]] PixelSelector fetch(std::uint64_t first_bin, std::uint64_t last_bin, balancing::Method norm = balancing::Method::NONE()) const;

Fetch methods (2D queries)

[[nodiscard]] PixelSelector fetch(std::string_view range1, std::string_view range2, balancing::Method norm = 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, balancing::Method norm = 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, balancing::Method norm = balancing::Method::NONE()) const;

Caching

[[nodiscard]] std::size_t num_cached_footers() const noexcept;

void purge_footer_cache();

[[nodiscard]] double block_cache_hit_rate() const noexcept;

void reset_cache_stats() const noexcept;

void clear_cache() noexcept;

void optimize_cache_size(std::size_t upper_bound = (std::numeric_limits<std::size_t>::max)());

void optimize_cache_size_for_iteration(std::size_t upper_bound = (std::numeric_limits<std::size_t>::max)());

void optimize_cache_size_for_random_access(std::size_t upper_bound = (std::numeric_limits<std::size_t>::max)());

[[nodiscard]] std::size_t cache_capacity() const noexcept;

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(bool sorted = true) const -> iterator<N>;

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

template<typename N>
[[nodiscard]] auto cbegin(bool sorted = true) 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]] MatrixType matrix_type() const noexcept;

[[nodiscard]] balancing::Method normalization() const noexcept;

[[nodiscard]] MatrixUnit unit() const noexcept;

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

[[nodiscard]] const Chromosome &chrom1() const noexcept;

[[nodiscard]] const Chromosome &chrom2() const noexcept;

[[nodiscard]] const balancing::Weights &weights1() const noexcept;

[[nodiscard]] const balancing::Weights &weights2() const noexcept;

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

[[nodiscard]] const internal::HiCFooterMetadata &metadata() const noexcept;

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

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

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

Caching

[[nodiscard]] std::size_t estimate_optimal_cache_size(std::size_t num_samples = 500) const;

void clear_cache() const;