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::optional<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::optional<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(bool include_ALL = false) 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;
[[nodiscard]] const balancing::Weights &normalization(
const balancing::Method &norm,
const Chromosome &chrom
) const;
[[nodiscard]] const balancing::Weights &normalization(
std::string_view norm,
const Chromosome &chrom
) const;
[[nodiscard]] const balancing::Weights &normalization(
const balancing::Method &norm
) const;
[[nodiscard]] const balancing::Weights &normalization(
std::string_view norm
) const;
[[nodiscard]] std::shared_ptr<const balancing::Weights> normalization_ptr(
const balancing::Method &norm,
const Chromosome &chrom
) const;
[[nodiscard]] std::shared_ptr<const balancing::Weights> normalization_ptr(
std::string_view norm,
const Chromosome &chrom
) const;
[[nodiscard]] std::shared_ptr<const balancing::Weights> normalization_ptr(
const balancing::Method &norm
) const;
[[nodiscard]] std::shared_ptr<const balancing::Weights> normalization_ptr(
std::string_view norm
) const;

Fetch methods (1D queries)

[[nodiscard]] PixelSelectorAll fetch(
const balancing::Method &norm = balancing::Method::NONE(),
std::optional<std::uint64_t> diagonal_band_width = {}
) const;
[[nodiscard]] PixelSelector fetch(
std::string_view range,
const balancing::Method &norm = balancing::Method::NONE(),
QUERY_TYPE query_type = QUERY_TYPE::UCSC,
std::optional<std::uint64_t> diagonal_band_width = {}
) const;
[[nodiscard]] PixelSelector fetch(
std::string_view chrom_name,
std::uint32_t start,
std::uint32_t end,
const balancing::Method &norm = balancing::Method::NONE(),
std::optional<std::uint64_t> diagonal_band_width = {}
) const;
[[nodiscard]] PixelSelector fetch(
std::uint64_t first_bin,
std::uint64_t last_bin,
const balancing::Method &norm = balancing::Method::NONE(),
std::optional<std::uint64_t> diagonal_band_width = {}
) const;

Fetch methods (2D queries)

[[nodiscard]] PixelSelector fetch(
std::string_view range1,
std::string_view range2,
const balancing::Method &norm = balancing::Method::NONE(),
QUERY_TYPE query_type = QUERY_TYPE::UCSC,
std::optional<std::uint64_t> diagonal_band_width = {}
) 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 &norm = balancing::Method::NONE(),
std::optional<std::uint64_t> diagonal_band_width = {}
) const;
[[nodiscard]] PixelSelector fetch(
std::uint64_t first_bin1,
std::uint64_t last_bin1,
std::uint64_t first_bin2,
std::uint64_t last_bin2,
const balancing::Method &norm = balancing::Method::NONE(),
std::optional<std::uint64_t> diagonal_band_width = {}
) 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;

Accessors

[[nodiscard]] const PixelCoordinates &coord1() const noexcept;
[[nodiscard]] const PixelCoordinates &coord2() const noexcept;
[[nodiscard]] std::uint64_t size(bool upper_triangular = true) const;
[[nodiscard]] MatrixType matrix_type() const noexcept;
[[nodiscard]] const 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]] std::shared_ptr<const BinTable> bins_ptr() 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;