bandhic.hiccups#

bandhic.hiccups(hic_file, chroms, resolutions, fdr=None, peak_width=None, window=None, thresholds=(0.02, 1.5, 1.75, 2.0), centroid_radius=None, max_loop_dist_bp=2000000, kr_neighborhood=5, matrix_size=512, norm='KR', out_path=None, n_jobs=-1)[source]#

Run the HiCCUPS loop-calling algorithm on Hi-C data using the BandHiC data structure.

This function provides a high-level interface to a BandHiC-based reimplementation of the HiCCUPS algorithm. It supports single- or multi-resolution loop detection across one or more chromosomes and internally applies multiprocessing to accelerate computation on large, high-resolution Hi-C matrices.

Parameters:

  • hic_file (str) – Path to the input Hi-C file. Supported formats include .hic, .cool, and .mcool.

  • chroms (str or list of str) – Chromosome name or list of chromosome names (e.g., "chr1" or ["chr1", "chr2"]).

  • resolutions (list of int) – List of bin resolutions (in base pairs) at which HiCCUPS will be executed.

  • fdr (list of float or float, optional) – Target false discovery rate (FDR) for loop detection at each resolution. If a single value is provided, it is applied to all resolutions.

  • peak_width (list of int or int, optional) – Peak half-width (in bins) for each resolution. Defaults follow Juicer recommendations if not specified.

  • window (list of int or int, optional) – Donut window size (in bins) for each resolution. Defaults follow Juicer recommendations if not specified.

  • thresholds (list of float, optional) – Threshold parameters [fdrsum, oe1, oe2, oe3] used for HiCCUPS filtering and cross-resolution merging.

  • centroid_radius (list of int or int, optional) – Radius (in base pairs) for clustering nearby loop pixels into centroids at each resolution.

  • max_loop_dist_bp (int, optional) – Maximum genomic distance (in base pairs) for loop search. Default is 2,000,000 bp.

  • kr_neighborhood (int, optional) – Radius (in bins) used to mask low-quality bins based on the KR normalization vector.

  • matrix_size (int, optional) – Reserved parameter for compatibility; not used in the current implementation.

  • norm (str, optional) – Normalization method to use (e.g., "KR", "VC"). Default is "KR".

  • out_path (str, optional) – Path to write the output loops in BEDPE format. If None, results are not written to disk.

  • n_jobs (int, optional) – Number of parallel worker processes to use. -1 uses all available CPUs.

Returns:

loops – List of detected chromatin loops after multi-resolution merging.

Return type:

list of Feature2D