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.sizesfile (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.txtfrom 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 (
.2bitor 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 aGenomeGaps.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_correctwhen 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_sizewindows (defaultTrue). Requires uniform bins inbins_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_binsisTrue.strict_window_size (bool, optional) – Merge into windows exactly
window_sizebp wide instead ofwindow_size // bin_sizeconsecutive remaining bins (defaultFalse, matching the original DELFI scripts). Seedelfi_merge_bins().quality_threshold (int, optional) – Minimum mapping quality (default 30).
workers (int, optional) – Worker-process count (default 1).
- Returns:
DELFI results with the original author’s column names.
- Return type:
- 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_fragsandratio, a degree-2 LOESS curve is fit over GC content and subtracted (re-centered on the feature median), producing{feature}_correctedcolumns.- Parameters:
windows (pandas.DataFrame) – DELFI windows; must contain a
gccolumn 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
windowswith{feature}_correctedcolumns added.- Return type:
- 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_sizeconsecutive bins (50 x 100kb = 5Mb by default). As in the original DELFI scripts, bins are grouped by count, so a window may span more thanwindow_sizebp where bins were removed (e.g. for overlapping a gap). Withstrict_window_size=True, windows instead span exactlywindow_sizebp 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 (
armequal tocontig), each contig is aggregated 5’->3’ as a whole.- Parameters:
hundred_kb_bins (pandas.DataFrame) – Uniform bins with
contigandarmcolumns and DELFI feature columns. Whengc_correctedisTruethe*_correctedcolumns 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/stopcolumns, 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_sizebp wide instead of a fixed number of bins (defaultFalse, 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
indexcolumn).- Return type:
- Raises:
ValueError – If the bins are not uniform or the bin size does not evenly divide
window_size.