Generic API

hictk generic API allows users to transparently operate on .hic .cool files. There is virtually no runtime overhead when using the File and PixelSelector classes. However iterating over Pixels using this API is slightly slower than using the format-specific APIs.

Refer to examples in the Quickstart (API) section for how to use the generic API without incurring into any overhead when iterating over Pixels overlapping queries.

Common

enum class QUERY_TYPE
enumerator BED
enumerator UCSC

File handle

class File

This class implements a generic file handle capable of transparently operating on .cool and .hic files.

Constructors

File(cooler::File clr);
File(hic::File hf);
File(
std::string_view uri,
std::optional<std::uint32_t> resolution = {},
hic::MatrixType type = hic::MatrixType::observed,
hic::MatrixUnit unit = hic::MatrixUnit::BP
);

Constructors for File class. resolution is a mandatory argument when opening .hic files. Matrix type and unit are ignored when operating on .cool files.

Accessors

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

Returns the URI of the open file. Always returns the file path when file is .hic.

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

Returns the path to the open file.

[[nodiscard]] constexpr bool is_hic() const noexcept;
[[nodiscard]] constexpr bool is_cooler() const noexcept;

Test whether the open file is in .hic or .cool format.

[[nodiscard]] auto chromosomes() const -> const Reference&;
[[nodiscard]] auto bins() const -> const BinTable&;
[[nodiscard]] std::shared_ptr<const BinTable> bins_ptr() const;

Accessors to the chromosomes and bin table of the open file.

[[nodiscard]] std::uint32_t resolution() const;
[[nodiscard]] std::uint64_t nbins() const;
[[nodiscard]] std::uint64_t nchroms(bool include_ALL = false) const;

Accessors for common attributes. Calling any of these accessors does not involve any computation.

[[nodiscard]] bool has_normalization(std::string_view normalization) const;
[[nodiscard]] const balancing::Weights &normalization(
std::string_view normalization_
) const;
[[nodiscard]] std::shared_ptr<const balancing::Weights> normalization_ptr(
std::string_view normalization_
) const;

Accessors for normalization methods/vectors.

Fetch methods (1D queries)

[[nodiscard]] PixelSelector fetch(
const balancing::Method &normalization = balancing::Method::NONE()
) 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;

Return a PixelSelector object that can be used to fetch pixels overlapping 1D (symmetric) queries.

Example usage:

hictk::File f{"myfile.hic", 1'000};

// Fetch all pixels
const auto sel1 = f.fetch();

// Fetch all pixels (normalized with VC);
const auto sel2 = f.fetch(balancing::Method::VC());

// Fetch pixels overlapping chr1
const auto sel3 = f.fetch("chr1");

// Fetch pixels overlapping a region of interest
const auto sel4 = f.fetch("chr1:10,000,000-20,000,000");
const auto sel5 = f.fetch("chr1", 10'000'000, 20'000'000");

// Fetch pixels using a BED query
const auto sel6 = f.fetch("chr1\t10000000\t20000000",
                          balancing::Method::NONE(),
                          QUERY_TYPE::BED);

Fetch methods (2D queries)

[[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;

Return a PixelSelector object that can be used to fetch pixels overlapping 2D (asymmetric) queries.

Example usage:

hictk::File f{"myfile.hic", 1'000};

// Fetch pixels overlapping chr1:chr2
const auto sel1 = f.fetch("chr1", "chr2");

// Fetch pixels overlapping a region of interest
const auto sel2 = f.fetch("chr1:10,000,000-20,000,000",
                          "chr2:10,000,000-20,000,000");
const auto sel3 = f.fetch("chr1", 10'000'000, 20'000'000,
                          "chr2", 10'000'000, 20'000'000);

Advanced

template<typename FileT>
[[nodiscard]] constexpr const FileT &get() const;
template<typename FileT>
[[nodiscard]] constexpr FileT &get();
[[nodiscard]] constexpr auto get() const noexcept -> const FileVar&;
[[nodiscard]] constexpr auto get() noexcept -> FileVar&;

Methods to get the underlying hic::File or cooler::File file handle or a std::variant of thereof.

Example usage:

hictk::File f{"myfile.hic", 1'000};

assert(f.get<hic::File>().path() == "myfile.hic");
assert(f.get<cooler::File>().path() == "myfile.hic");  // Throws an exception

const auto fvar = f.get();
std::visit([](const auto& f) {
  assert(f.path() == "myfile.hic");
}, fvar);

Pixel selector

class PixelSelector

This class implements a generic, lightweight pixel selector object.

PixelSelector objects are constructed and returned by File::fetch() methods. Users are not supposed to construct PixelSelector objects themselves.

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>;

Return an InputIterator to traverse pixels overlapping the genomic coordinates used to create the PixelSelector.

Specifying sorted = false will improve throughput for queries over .hic files.

When operating on .cool files, pixels are always returned sorted by genomic coordinates.

Example usage:

hictk::File f{"myfile.hic", 1'000};
const auto sel = f.fetch();

std::for_each(sel.begin<std::int32_t>(), sel.end<std::int32_t>(),
              [&](const auto& pixel) { fmt::print("{}\n", pixel); });

// STDOUT
// 0  0 12
// 0  2 7
// 0  4 1
// ...

Fetch at once

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

Read and return all Pixels at once using a std::vector.

Accessors

[[nodiscard]] const PixelCoordinates &coord1() const noexcept;
[[nodiscard]] const PixelCoordinates &coord2() const noexcept;
[[nodiscard]] std::uint64_t size(bool upper_triangular = true) const;

Return the genomic coordinates used to construct the PixelSelector.

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

Return the BinTable used to map Pixels to genomic Bins.

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

Return the balancing weights associated with the PixelSelector instance.

Advanced

template<typename PixelSelectorT>
[[nodiscard]] constexpr const PixelSelectorT &get(
) const;
template<typename PixelSelectorT>
[[nodiscard]] constexpr PixelSelectorT &get(
);
[[nodiscard]] constexpr auto get() const noexcept -> const PixelSelectorVar&;
[[nodiscard]] constexpr auto get() noexcept -> PixelSelectorVar&;

Example usage:

hictk::File f{"myfile.hic", 1'000};

const auto sel = f.fetch();

assert(f.get<hic::PixelSelector>().matrix_type() == hic::MatrixType::observed");
f.get<cooler::PixelSelector>();  // Throws an exception

const auto selvar = sel.get();
std::visit([](const auto& s) { assert(s.bins().resolution() == 1'000); }, selvar);