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 constexpr operator bool() const noexcept;
[[nodiscard]] constexpr bool operator!() 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(),
bool load_index = false
) const;
[[nodiscard]] PixelSelector fetch(
std::shared_ptr<const balancing::Weights> weights,
bool load_index = false
) 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;
[[nodiscard]] std::shared_ptr<const balancing::Weights> normalization_ptr(
std::string_view normalization_,
bool rescale = false
) const;
[[nodiscard]] std::shared_ptr<const balancing::Weights> normalization_ptr(
std::string_view normalization_,
balancing::Weights::Type type,
bool rescale = false
) const;
[[nodiscard]] const balancing::Weights &normalization(
std::string_view normalization_,
bool rescale = false
) const;
[[nodiscard]] 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;
[[nodiscard]] std::shared_ptr<const balancing::Weights> normalization_ptr(
const balancing::Method &normalization_,
bool rescale = false
) const;
[[nodiscard]] std::shared_ptr<const balancing::Weights> normalization_ptr(
const balancing::Method &normalization_,
balancing::Weights::Type type,
bool rescale = false
) const;
[[nodiscard]] const balancing::Weights &normalization(
const balancing::Method &normalization_,
bool rescale = false
) const;
[[nodiscard]] 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,
HighFiveAccessMode 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
);
template<typename N = std::int32_t>
static void coarsen(
const File &clr1,
File &clr2,
std::vector<ThinPixel<N>> &buffer
);

Single-cell Cooler (.scool)

class SingleCellFile

Constructors

explicit SingleCellFile(
const std::filesystem::path &path,
HighFiveAccessMode 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]] auto bins_ptr() const noexcept -> std::shared_ptr<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;

Accessors

[[nodiscard]] const PixelCoordinates &coord1() const noexcept;
[[nodiscard]] const PixelCoordinates &coord2() const noexcept;
[[nodiscard]] std::uint64_t size(bool upper_triangular = true) const;
[[nodiscard]] const BinTable &bins() const noexcept;
[[nodiscard]] std::shared_ptr<const BinTable> bins_ptr() const noexcept;