Features¶
FinaleToolkit computes the established cell-free DNA fragmentomic features
below. Each one is available both as a finaletoolkit subcommand and as a
Python function. See the CLI Reference and
API Reference for exact signatures.
Fragment length¶
Fragment-length distributions and per-interval summary statistics across cfDNA fragments.
- Commands:
frag-length-bins,frag-length-intervals
Fragment coverage¶
The number of fragments mapped to a region, reported either raw or normalized by the sample’s total coverage.
- Commands:
coverage
Windowed Protection Score (WPS)¶
WPS (Snyder et al. 2016) quantifies nucleosome protection. For a window (typically 120 bp) centered on a position, it counts the fragments that fully span the window and subtracts the fragments that have an endpoint inside it. The score tracks nucleosome positioning and features such as transcription start sites and DNase I hypersensitive sites.
- Commands:
wps,adjust-wps
DELFI¶
DELFI (Cristiano et al. 2019) detects fragmentation abnormalities in cfDNA. The score is the ratio of GC-corrected short fragment counts to GC-corrected long fragment counts. In the original study it was used to categorize cancer and the associated tissue of origin.
- Commands:
delfi
Bins. To replicate the original study, use the 100kb hg19 HiC A/B
compartment bins the DELFI scripts load:
hic_compartments_100kb_ebv_2014.txt
from HiC_AB_Compartments
(Fortin & Hansen 2015). That file is space-delimited with an uncommented
header, so convert it to a tab-delimited BED with a # header first:
$ curl -sL https://raw.githubusercontent.com/Jfortin1/HiC_AB_Compartments/master/data/hic_compartments_100kb_ebv_2014.txt \
| awk 'BEGIN{OFS="\t"} NR==1{$1="#"$1} {$1=$1; print}' > hic_100kb.bed
Any BED of uniform bins also works. For example, 100kb autosomal bins for
hg38 (requires bedtools), which also writes the autosome-only
CHROM_SIZES file to pass to delfi:
$ curl -s https://hgdownload.soe.ucsc.edu/goldenPath/hg38/bigZips/hg38.chrom.sizes \
| awk '$1 ~ /^chr([1-9]|1[0-9]|2[0-2])$/' | sort -k1.4,1n > hg38.autosomes.chrom.sizes
$ bedtools makewindows -g hg38.autosomes.chrom.sizes -w 100000 \
| awk '$3 - $2 == 100000' > hg38_100kb_bins.bed
$ finaletoolkit delfi sample.bam hg38.autosomes.chrom.sizes hg38.2bit hg38_100kb_bins.bed \
-g hg38 --no-remove-nocov -o delfi.tsv
The final awk drops the shorter last bin of each chromosome (delfi
would otherwise drop it with a warning).
Merging. When bins are merged (the default), every bin must be the same
size and --merge-size (default 5Mb) must be a multiple of it; a shorter
last bin on a contig, as bedtools makewindows produces, is dropped with a
warning. Merging happens within each chromosome arm, counting from the
telomere: p-arms from their first bin, q-arms from their last. Partial
windows at the centromere end are dropped. Without a gap file (-g), arms
are unknown and each contig is merged as a whole, from its first bin.
Bins that overlap any gap annotation are removed before merging, including
small contig, scaffold, and clone gaps, not just centromeres and telomeres.
(The blacklist, -b, removes fragments, not bins.) How merging treats
those holes depends on --strict-merge-size:
By count (default). Each window holds
merge size / bin sizeconsecutive remaining bins (50 x 100kb by default), as in the original DELFI scripts. Every window aggregates the same number of bins, but a window spans more than--merge-sizewhere bins were removed (e.g. a “5Mb” window covering 5.2Mb of genome).By span (
--strict-merge-size,strict_window_size=True). Each window covers exactly--merge-sizeof genome and aggregates whichever bins remain inside it, so windows with removed bins have lower summed counts (short,long,num_frags) than full ones. Ratios and GC are averaged per bin, so their scale is unaffected, though they rest on fewer bins. Windows with no remaining bins are omitted. This departs from the original method.
Coordinates. Both half-open BED bins (stop - start = 100000) and
end-inclusive bins (stop - start = 99999, as in the HiC file above) are
accepted, and the bin size is inferred accordingly. FinaleToolkit reads bin
coordinates as written (0-based, half-open). The original R scripts read the
HiC file as 1-based and closed, so each bin there covers 1 bp earlier and
1 bp more than it does here (chr1 700000 799999 is [699999, 799999)
in R and [700000, 799999) in FinaleToolkit). The effect on fragment
counts is negligible, but results will not match the R output to the
fragment.
No-coverage bins. --remove-nocov (on by default) drops the two bins the
original scripts found to have no coverage. They are identified by row
position (the 8,780th and 13,665th bins left after gap and arm filtering),
exactly as in the original scripts, so the option is only meaningful with the
HiC bins above, the hg19 gap file (-g hg19), and all autosomes in
CHROM_SIZES. With any other bins file, reference, or subset of
chromosomes it removes two arbitrary bins; pass --no-remove-nocov.
End and breakpoint motifs¶
Frequencies of k-mer motifs at fragment ends (the cleavage sites) and at breakpoints. Because these sequences arise from how cfDNA is cut, they can reflect condition-specific cleavage activity.
- Commands:
end-motifs,interval-end-motifs,breakpoint-motifs,interval-breakpoint-motifs
Motif Diversity Score (MDS)¶
MDS (Jiang et al. 2020) is the normalized Shannon entropy of the end-motif
k-mer distribution, summarizing end-motif diversity in a single number. The
regional Motif Diversity Score (rMDS) computes that same entropy per genomic
region (Bandaru et al. 2026). Because the underlying plug-in entropy
estimator is biased downward in regions with few fragments, regional-mds
accepts an optional --miller-madow flag that applies a Miller-Madow bias
correction, making rMDS values comparable across regions of differing depth.
It is off by default, so existing output is unchanged unless requested.
- Commands:
mds(whole sample),regional-mds(per region, optionally bias-corrected with--miller-madow)
Cleavage profile¶
Cleavage proportion (Zhou et al. 2022). At each nucleotide, it is the fraction of the overlapping fragment ends that fall on that position. The authors report a relationship to DNA methylation, particularly at CpG sites.
- Commands:
cleavage-profile
Intersect policy¶
When a feature pulls fragments over an interval [start, stop), the
intersect_policy argument (CLI: -p/--intersect-policy) decides which
fragments count:
midpoint(default)Include a fragment only if its midpoint falls inside the interval. Avoids double-counting fragments that straddle a boundary.
anyInclude a fragment if it overlaps the interval at all, even by one base pair.
Use midpoint for binned, genome-wide features; use any when you care
about every fragment that touches a region.