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 Pixel
s 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 Pixel
s overlapping queries.
Common#
File handle#
-
class File#
This class implements a generic file handle capable of transparently operating on .cool and .hic files.
Constructors
-
File(std::string uri, std::uint32_t resolution = 0, 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. Matrixtype
andunit
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.
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() 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]] std::vector<balancing::Method> avail_normalizations() 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
-
[[nodiscard]] constexpr auto get() const noexcept -> const FileVar&;#
-
[[nodiscard]] constexpr auto get() noexcept -> FileVar&;#
Methods to get the underlying
hic::File
orcooler::File
file handle or astd::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);
-
File(std::string uri, std::uint32_t resolution = 0, hic::MatrixType type = hic::MatrixType::observed, hic::MatrixUnit unit = hic::MatrixUnit::BP);#
Pixel selector#
-
class PixelSelector#
This class implements a generic, lightweight pixel selector object.
PixelSelector
objects are constructed and returned byFile::fetch()
methods. Users are not supposed to constructPixelSelector
objects themselves.Iteration
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]] Eigen::Matrix<N, Eigen::Dynamic, Eigen::Dynamic> read_dense() const;#
Read and return all
Pixel
s at once using astd::vector
.Accessors
-
[[nodiscard]] const PixelCoordinates &coord1() const;#
-
[[nodiscard]] const PixelCoordinates &coord2() const;#
Return the genomic coordinates used to construct the
PixelSelector
.Return the
BinTable
used to mapPixel
s to genomicBin
s.Advanced
-
template<typename PixelSelectorT>
[[nodiscard]] constexpr const PixelSelectorT &get() const noexcept;#
-
template<typename PixelSelectorT>
[[nodiscard]] constexpr PixelSelectorT &get() noexcept;#
-
[[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);
-
template<typename N>