DELFI

See also

DELFI bins in the Features guide: which bins file to use, how to convert the original HiC bins into a usable BED, how to make bins for other genomes, and when to disable remove_nocov.

finaletoolkit.frag.delfi(input_file, chrom_sizes, bins_file, reference_file, blacklist_file=None, gap_file=None, output_file=None, no_gc_correct=False, gc_correct=None, remove_nocov=True, merge_bins=True, window_size=5000000, strict_window_size=False, quality_threshold=30, workers=1, verbose=False)[source]

Compute DELFI features, replicating Cristiano et al. (2019).

Parameters:
  • input_file (str) – BAM/CRAM/fragment file of paired-end reads.

  • chrom_sizes (str) – .chrom.sizes file (autosomes only to match the original scripts).

  • bins_file (str) – BED of bins. To match the original methodology, use the 100kb hg19 HiC compartment bins, hic_compartments_100kb_ebv_2014.txt from HiC_AB_Compartments, converted to tab-delimited with a # header (see DELFI bins for the command). Coordinates are read as written (0-based, half-open), whereas the original R scripts read that file as 1-based, so bins here sit 1 bp later than in the original.

  • reference_file (str) – Reference genome (.2bit or FASTA; FASTA required for CRAM input).

  • blacklist_file (str, optional) – BED of regions to ignore.

  • gap_file (str or GenomeGaps, optional) – Telomere/centromere annotations: a BED4 file, a genome name ("hg19"/"b37"/"human_g1k_v37"/"hg38"/"GRCh38"), or a GenomeGaps.

  • output_file (str, optional) – Output BED/.bed.gz/.tsv/.csv path, or "-" for stdout.

  • no_gc_correct (bool, optional) – Skip GC correction (default False).

  • gc_correct (bool, optional) – Deprecated; overrides no_gc_correct when set.

  • remove_nocov (bool, optional) – Remove the two hg19 no-coverage windows of Cristiano et al. (default True). They are removed by row position, so this is only correct with the HiC bins above, hg19 gaps, and all autosomes; disable it otherwise (see DELFI bins).

  • merge_bins (bool, optional) – Merge bins into window_size windows (default True). Requires uniform bins in bins_file (half-open or end-inclusive); short bins at contig ends are dropped with a warning.

  • window_size (int, optional) – Merge window size in bp (default 5,000,000). Must be a multiple of the bin size; only used when merge_bins is True.

  • strict_window_size (bool, optional) – Merge into windows exactly window_size bp wide instead of window_size // bin_size consecutive remaining bins (default False, matching the original DELFI scripts). See delfi_merge_bins().

  • quality_threshold (int, optional) – Minimum mapping quality (default 30).

  • workers (int, optional) – Worker-process count (default 1).

  • verbose (int or bool, optional) – Print progress/timing.

Returns:

DELFI results with the original author’s column names.

Return type:

pandas.DataFrame

finaletoolkit.frag.delfi_gc_correct(windows, alpha=0.75, it=8, verbose=False)[source]

GC-correct DELFI window features with a LOESS fit per feature.

For each of short, long, num_frags and ratio, a degree-2 LOESS curve is fit over GC content and subtracted (re-centered on the feature median), producing {feature}_corrected columns.

Parameters:
  • windows (pandas.DataFrame) – DELFI windows; must contain a gc column and the feature columns.

  • alpha (float, optional) – LOESS smoothing fraction (default 0.75).

  • it (int, optional) – Retained for signature compatibility (unused).

  • verbose (bool, optional) – Print timing.

Returns:

A copy of windows with {feature}_corrected columns added.

Return type:

pandas.DataFrame

finaletoolkit.frag.delfi_merge_bins(hundred_kb_bins, gc_corrected=True, verbose=False, *, window_size=5000000, bin_size=None, strict_window_size=False)[source]

Merge uniform DELFI bins into non-overlapping windows per arm.

By default each window holds window_size // bin_size consecutive bins (50 x 100kb = 5Mb by default). As in the original DELFI scripts, bins are grouped by count, so a window may span more than window_size bp where bins were removed (e.g. for overlapping a gap). With strict_window_size=True, windows instead span exactly window_size bp and hold however many bins remain inside them.

p-arms are aggregated 5’->3’; q-arms are aggregated 3’->5’ and then reversed. Partial windows at arm ends are dropped. Without gap annotations (arm equal to contig), each contig is aggregated 5’->3’ as a whole.

Parameters:
  • hundred_kb_bins (pandas.DataFrame) – Uniform bins with contig and arm columns and DELFI feature columns. When gc_corrected is True the *_corrected columns must be present.

  • gc_corrected (bool, optional) – Whether the input carries GC-corrected columns to aggregate (default True). Unlike the original implementation this flag is honored, so merging works with GC correction disabled.

  • verbose (bool, optional) – Unused; kept for signature compatibility.

  • window_size (int, optional) – Merged window size in bp (default 5,000,000). Must be a multiple of the bin size.

  • bin_size (int, optional) – Size of the input bins in bp. If omitted, it is inferred from the start/stop columns, accepting half-open or end-inclusive coordinates; short bins at contig ends are dropped with a warning.

  • strict_window_size (bool, optional) – Merge into windows exactly window_size bp wide instead of a fixed number of bins (default False, matching the original DELFI scripts). Windows where bins were removed then aggregate fewer bins, so their summed counts are lower; windows with no remaining bins are omitted. Bins are assigned to windows by their start coordinate.

Returns:

The merged bins, with the same columns as the input (minus any index column).

Return type:

pandas.DataFrame

Raises:

ValueError – If the bins are not uniform or the bin size does not evenly divide window_size.