CLI Reference

Tip

Every subcommand also prints its own options and a worked example with finaletoolkit <command> --help. Flags are consistent across commands: -o/--output, -r/--reference, -q/--min-mapq, --min-length / --max-length, -t/--threads, -v/--verbose, and -k/--kmer-length.

finaletoolkit

A package and standalone program to extract fragmentation features of cell-free DNA from paired-end sequencing data. Run a subcommand with –help to see its options and an example invocation. For file outputs, pass “-o -” to write to standard output instead of a file.

finaletoolkit [OPTIONS] COMMAND [ARGS]...

Options

-v, --version

Show the version and exit.

adjust-wps

Adjust raw WPS with a median filter and a Savitsky-Golay filter.

INPUT bigWig file of raw WPS results.
REGIONS BED file of intervals WPS was calculated over.
CHROM_SIZES .chrom.sizes file of chromosome names and sizes.
finaletoolkit adjust-wps [OPTIONS] INPUT REGIONS CHROM_SIZES

Options

-o, --output <PATH>

bigWig file of adjusted WPS results over the input intervals. Pass ‘-’ to write to standard output (stdout).

Default:

'-'

-i, --interval-size <BP>

Size in bp of each interval in the interval file.

Default:

5000

-m, --median-window-size <BP>

Size of the median/mean filter window used to adjust WPS scores.

Default:

1000

--savgol-window-size <BP>

Size of the Savitsky-Golay filter window.

Default:

21

--savgol-poly-deg <DEG>

Degree of the Savitsky-Golay filter polynomial.

Default:

2

--savgol, --no-savgol

Apply Savitsky-Golay filtering to the adjusted WPS. On by default.

--mean

Use a mean filter instead of a median filter.

--subtract-edges

Subtract the mean of each interval’s edges (see –edge-size) before filtering.

--edge-size <BP>

Edge width subtracted from each interval end when –subtract-edges is set.

Default:

500

-t, --threads <N>

Number of worker processes to use.

Default:

1

-v, --verbose

Increase verbosity (repeatable, e.g. -vv) for detailed output.

Example: finaletoolkit adjust-wps wps.bw intervals.bed hg38.chrom.sizes -o adjusted.bw

agg-bw

Aggregate a bigWig signal over constant-length BED intervals.

INPUT bigWig file of signal over the input intervals.
REGIONS BED file of intervals the signal was calculated over.
finaletoolkit agg-bw [OPTIONS] INPUT REGIONS

Options

-o, --output <PATH>

Wiggle file of the aggregate signal over the input intervals. Pass ‘-’ to write to standard output (stdout).

Default:

'-'

-m, --median-window-size <BP>

Median filter window used to aggregate scores. Set to 120 when aggregating WPS signals.

Default:

1

--mean

Use the mean instead of the sum.

-v, --verbose

Increase verbosity (repeatable, e.g. -vv) for detailed output.

Example: finaletoolkit agg-bw wps.bw intervals.bed -m 120 -o agg.wig

breakpoint-motifs

Frequency of k-mer breakpoint motifs.

INPUT BAM/CRAM/Fragment file of fragment data.
REFERENCE .2bit or FASTA reference genome file.
finaletoolkit breakpoint-motifs [OPTIONS] INPUT REFERENCE

Options

-k, --kmer-length <K>

Length of the k-mer motif.

Default:

6

--min-length <BP>

Minimum fragment length to include.

Default:

50

--max-length <BP>

Maximum fragment length to include.

--strand <strand>

Fragment strand(s) for breakpoint motifs: ‘both’, ‘forward’ (5’ ends of the positive strand only), or ‘reverse’ (negative strand only).

Default:

'both'

Options:

both | forward | reverse

-o, --output <PATH>

TSV of k-mer frequencies. Pass ‘-’ to write to standard output (stdout).

Default:

'-'

-q, --min-mapq <MAPQ>

Minimum mapping quality (MAPQ) for a fragment to be included.

Default:

20

-t, --threads <N>

Number of worker processes to use.

Default:

1

-v, --verbose

Increase verbosity (repeatable, e.g. -vv) for detailed output.

Example: finaletoolkit breakpoint-motifs sample.bam hg38.2bit -k 6 -o bp.tsv

cleavage-profile

Cleavage proportion over BED intervals from a BAM/CRAM/Fragment file.

INPUT BAM/CRAM/Fragment file of fragment data.
REGIONS BED file of intervals to compute cleavage proportion over.
CHROM_SIZES .chrom.sizes file of chromosome names and sizes.
finaletoolkit cleavage-profile [OPTIONS] INPUT REGIONS CHROM_SIZES

Options

-r, --reference <FASTA>

FASTA (.fa, .fasta, .fna) reference genome. Required for CRAM input.

-o, --output <PATH>

bigWig file of cleavage proportion over the input intervals. Pass ‘-’ to write to standard output (stdout).

Default:

'-'

--min-length <BP>

Minimum fragment length to include.

Default:

0

--max-length <BP>

Maximum fragment length to include.

-q, --min-mapq <MAPQ>

Minimum mapping quality (MAPQ) for a fragment to be included.

Default:

20

--pad-left <BP>

Base pairs to subtract from each start coordinate. Useful for BED files containing only CpG coordinates.

Default:

0

--pad-right <BP>

Base pairs to add to each stop coordinate. Useful for BED files containing only CpG coordinates.

Default:

0

-t, --threads <N>

Number of worker processes to use.

Default:

1

-v, --verbose

Increase verbosity (repeatable, e.g. -vv) for detailed output.

Example: finaletoolkit cleavage-profile sample.bam cpg.bed hg38.chrom.sizes –pad-left 5 –pad-right 5 -o cleavage.bw

coverage

Fragmentation coverage over BED intervals from a BAM/CRAM/Fragment file.

INPUT BAM/CRAM/Fragment file of fragment data.
REGIONS BED file of intervals to calculate coverage over.
finaletoolkit coverage [OPTIONS] INPUT REGIONS

Options

-r, --reference <FASTA>

FASTA (.fa, .fasta, .fna) reference genome. Required for CRAM input.

-o, --output <PATH>

BED file of coverage values over the input intervals. Pass ‘-’ to write to standard output (stdout).

Default:

'-'

-n, --normalize

Normalize output by total coverage (and apply –scale-factor if given). May increase execution time for high-throughput data.

--scale-factor <X>

Scale factor for coverage values.

Default:

1.0

--min-length <BP>

Minimum fragment length to include in coverage.

Default:

0

--max-length <BP>

Maximum fragment length to include in coverage.

-p, --intersect-policy <intersect_policy>

How a fragment counts as inside an interval: ‘midpoint’ (the fragment midpoint lies in the interval) or ‘any’ (any overlap).

Default:

'midpoint'

Options:

midpoint | any

-q, --min-mapq <MAPQ>

Minimum mapping quality (MAPQ) for a fragment to be included.

Default:

30

-t, --threads <N>

Number of worker processes to use.

Default:

1

-v, --verbose

Increase verbosity (repeatable, e.g. -vv) for detailed output.

Example: finaletoolkit coverage sample.bam intervals.bed -o cov.bed

delfi

DELFI features: short/long fragments, DELFI ratio, and total fragments.

INPUT BAM/CRAM/Fragment file of fragment data.
CHROM_SIZES Tab-delimited chrom name and integer length (autosomes only
to replicate the original scripts).
REFERENCE A .2bit or FASTA (.fa, .fasta, .fna) reference genome file.
BINS BED file of bins over which to calculate DELFI.

See DELFI bins for which BINS file to use, how to convert the original HiC bins into a usable BED, and when to pass --no-remove-nocov. .. program:: finaletoolkit delfi .. code-block:: shell

finaletoolkit delfi [OPTIONS] INPUT CHROM_SIZES REFERENCE BINS

Options

-b, --blacklist <BED>

BED file of regions to ignore when calculating DELFI.

-g, --gap-file <GAPS>

Telomere/centromere annotations: a BED4 file (4th column “centromere”/”telomere”/”short_arm”) or a genome name (hg19/b37/human_g1k_v37/hg38/GRCh38).

-o, --output <PATH>

Output file (.bed, .bed.gz, .tsv, or .csv). Pass ‘-’ to write to standard output (stdout).

Default:

'-'

--no-gc-correct

Skip GC correction.

--remove-nocov, --no-remove-nocov

Remove the two hg19 regions with no coverage. They are removed by row position, so use –no-remove-nocov unless BINS are the original hg19 HiC bins with -g hg19 and all autosomes. On by default.

--merge-bins, --no-merge-bins

Merge input bins into –merge-size windows (use –no-merge-bins to keep the input bins). On by default.

--merge-size <BP>

Size of merged bins in bp. Must be a multiple of the (uniform) size of the input bins.

Default:

5000000

--strict-merge-size

Merge into windows exactly –merge-size wide, rather than a fixed number of consecutive bins (the original DELFI method), which can span more where bins overlapping gaps were removed.

-q, --min-mapq <MAPQ>

Minimum mapping quality (MAPQ) for a fragment to be included.

Default:

30

-t, --threads <N>

Number of worker processes to use.

Default:

1

-v, --verbose

Increase verbosity (repeatable, e.g. -vv) for detailed output.

Example: finaletoolkit delfi sample.bam autosomes.chrom.sizes hg19.2bit bins.bed -g hg19 -o delfi.tsv

end-motifs

Frequency of k-mer 5’ end motifs.

INPUT BAM/CRAM/Fragment file of fragment data.
REFERENCE .2bit or FASTA reference genome file.
finaletoolkit end-motifs [OPTIONS] INPUT REFERENCE

Options

-k, --kmer-length <K>

Length of the k-mer motif.

Default:

4

--min-length <BP>

Minimum fragment length to include.

Default:

50

--max-length <BP>

Maximum fragment length to include.

--strand <strand>

Fragment strand(s) for end motifs: ‘both’, ‘forward’ (5’ ends of the positive strand only), or ‘reverse’ (negative strand only).

Default:

'both'

Options:

both | forward | reverse

-o, --output <PATH>

TSV of k-mer frequencies. Pass ‘-’ to write to standard output (stdout).

Default:

'-'

-q, --min-mapq <MAPQ>

Minimum mapping quality (MAPQ) for a fragment to be included.

Default:

20

-t, --threads <N>

Number of worker processes to use.

Default:

1

-v, --verbose

Increase verbosity (repeatable, e.g. -vv) for detailed output.

Example: finaletoolkit end-motifs sample.bam hg38.2bit -k 4 -o motifs.tsv

filter-file

Filter a BED/BAM/CRAM file by pairing, MAPQ, flags, length, and regions.

INPUT BAM/CRAM/BED file to filter.
finaletoolkit filter-file [OPTIONS] INPUT

Options

-r, --reference <FASTA>

FASTA (.fa, .fasta, .fna) reference genome. Required for CRAM input.

-w, --whitelist <BED>

Only keep alignments overlapping intervals in this BED file.

-b, --blacklist <BED>

Only keep alignments outside intervals in this BED file.

-o, --output <PATH>

Output BED/BAM/CRAM file path. Pass ‘-’ to write to standard output (stdout).

Default:

'-'

-q, --min-mapq <MAPQ>

Minimum mapping quality (MAPQ) for a fragment to be included.

Default:

30

--min-length <BP>

Minimum fragment length to include.

--max-length <BP>

Maximum fragment length to include.

-p, --intersect-policy <intersect_policy>

How a fragment counts as inside an interval: ‘midpoint’ (the fragment midpoint lies in the interval) or ‘any’ (any overlap).

Default:

'midpoint'

Options:

midpoint | any

-t, --threads <N>

Number of worker processes to use.

Default:

1

-v, --verbose

Increase verbosity (repeatable, e.g. -vv) for detailed output.

Example: finaletoolkit filter-file sample.bam -q 30 –min-length 100 -o filtered.bam

frag-length-bins

Fragment lengths grouped into bins from a BAM/CRAM/Fragment file.

INPUT BAM/CRAM/Fragment file of fragment data.
finaletoolkit frag-length-bins [OPTIONS] INPUT

Options

-r, --reference <FASTA>

FASTA (.fa, .fasta, .fna) reference genome. Required for CRAM input.

-c, --contig <contig>

Contig/chromosome to select fragments from. (Required with –start or –stop.)

-S, --start <start>

0-based left-most coordinate of the interval. (Requires –contig.)

-E, --stop <stop>

1-based right-most coordinate of the interval. (Requires –contig.)

--min-length <BP>

Minimum fragment length to include.

Default:

0

--max-length <BP>

Maximum fragment length to include.

-p, --intersect-policy <intersect_policy>

How a fragment counts as inside an interval: ‘midpoint’ (the fragment midpoint lies in the interval) or ‘any’ (any overlap).

Default:

'midpoint'

Options:

midpoint | any

--bin-size <BP>

Width of the bins fragment lengths are grouped into.

Default:

1

-o, --output <PATH>

TSV of fragment lengths binned by the specified bin size. Pass ‘-’ to write to standard output (stdout).

Default:

'-'

--summary-stats

Append summary statistics as comment lines (e.g. #max: 100) to the output TSV.

--short-threshold <BP>

If set, include a short fraction (fragments <= this length) in the summary statistics.

--histogram <PNG>

If set, also render a histogram to this PNG path.

-q, --min-mapq <MAPQ>

Minimum mapping quality (MAPQ) for a fragment to be included.

Default:

30

-v, --verbose

Increase verbosity (repeatable, e.g. -vv) for detailed output.

Example: finaletoolkit frag-length-bins sample.bam –bin-size 5 -o bins.tsv

frag-length-intervals

Fragment-length summary statistics over BED intervals.

INPUT BAM/CRAM/Fragment file of fragment data.
REGIONS BED file of intervals to summarize fragment lengths over.
finaletoolkit frag-length-intervals [OPTIONS] INPUT REGIONS

Options

-r, --reference <FASTA>

FASTA (.fa, .fasta, .fna) reference genome. Required for CRAM input.

--min-length <BP>

Minimum fragment length to include.

Default:

0

--max-length <BP>

Maximum fragment length to include.

-p, --intersect-policy <intersect_policy>

How a fragment counts as inside an interval: ‘midpoint’ (the fragment midpoint lies in the interval) or ‘any’ (any overlap).

Default:

'midpoint'

Options:

midpoint | any

-o, --output <PATH>

BED of fragment-length summary statistics (mean, median, st. dev, min, max) over the input intervals. Pass ‘-’ to write to standard output (stdout).

Default:

'-'

--short-threshold <BP>

Length cutoff (bp) for the short-read fraction.

Default:

150

-q, --min-mapq <MAPQ>

Minimum mapping quality (MAPQ) for a fragment to be included.

Default:

30

-t, --threads <N>

Number of worker processes to use.

Default:

1

-v, --verbose

Increase verbosity (repeatable, e.g. -vv) for detailed output.

Example: finaletoolkit frag-length-intervals sample.bam intervals.bed -o out.bed

gap-bed

BED4 of centromeres, telomeres, and short-arm intervals (UCSC hg19 gaps).

‘Gap’ is used liberally; for hg38/GRCh38 it may refer to regions that no longer have gaps in the reference.

GENOME Reference genome (hg19, b37, human_g1k_v37, hg38, GRCh38).
OUTPUT Path to write the BED file to. Pass ‘-’ for standard output.
finaletoolkit gap-bed [OPTIONS] GENOME OUTPUT

Example: finaletoolkit gap-bed hg19 hg19_gaps.bed

interval-breakpoint-motifs

Frequency of k-mer breakpoint motifs in each region of a BED file.

INPUT BAM/CRAM/Fragment file of fragment data.
REFERENCE .2bit or FASTA reference genome file.
REGIONS BED file of intervals to retrieve breakpoint-motif frequencies
over.
finaletoolkit interval-breakpoint-motifs [OPTIONS] INPUT REFERENCE REGIONS

Options

-k, --kmer-length <K>

Length of the k-mer motif.

Default:

6

--min-length <BP>

Minimum fragment length to include.

Default:

50

--max-length <BP>

Maximum fragment length to include.

--strand <strand>

Fragment strand(s) for breakpoint motifs: ‘both’, ‘forward’ (5’ ends of the positive strand only), or ‘reverse’ (negative strand only).

Default:

'both'

Options:

both | forward | reverse

-o, --output <PATH>

TSV or CSV file to write breakpoint-motif frequencies to. Pass ‘-’ to write to standard output (stdout).

Default:

'-'

-q, --min-mapq <MAPQ>

Minimum mapping quality (MAPQ) for a fragment to be included.

Default:

20

-t, --threads <N>

Number of worker processes to use.

Default:

1

-v, --verbose

Increase verbosity (repeatable, e.g. -vv) for detailed output.

Example: finaletoolkit interval-breakpoint-motifs sample.bam hg38.2bit intervals.bed -o interval_bp.tsv

interval-end-motifs

Frequency of k-mer 5’ end motifs in each region of a BED file.

INPUT BAM/CRAM/Fragment file of fragment data.
REFERENCE .2bit or FASTA reference genome file.
REGIONS BED file of intervals to retrieve end-motif frequencies over.
finaletoolkit interval-end-motifs [OPTIONS] INPUT REFERENCE REGIONS

Options

-k, --kmer-length <K>

Length of the k-mer motif.

Default:

4

--min-length <BP>

Minimum fragment length to include.

Default:

50

--max-length <BP>

Maximum fragment length to include.

--strand <strand>

Fragment strand(s) for end motifs: ‘both’, ‘forward’ (5’ ends of the positive strand only), or ‘reverse’ (negative strand only).

Default:

'both'

Options:

both | forward | reverse

-o, --output <PATH>

TSV or CSV file to write end-motif frequencies to. Pass ‘-’ to write to standard output (stdout).

Default:

'-'

-q, --min-mapq <MAPQ>

Minimum mapping quality (MAPQ) for a fragment to be included.

Default:

20

-t, --threads <N>

Number of worker processes to use.

Default:

1

-v, --verbose

Increase verbosity (repeatable, e.g. -vv) for detailed output.

Example: finaletoolkit interval-end-motifs sample.bam hg38.2bit intervals.bed -o interval_motifs.tsv

mds

Motif diversity score (MDS) from k-mer frequencies (Jiang et al., 2020).

INPUT Tabular file with a k-mer column and a frequency column. Reads from
stdin by default.
finaletoolkit mds [OPTIONS] INPUT

Options

-s, --sep <sep>

Field separator. Default is a tab.

--header <header>

Number of header rows to ignore.

Default:

0

Example: finaletoolkit mds motifs.tsv

regional-mds

Regional Motif Diversity Score (rMDS) for each region (Bandaru et al. 2026).

INPUT Tabular file of per-region k-mer frequencies. Reads from stdin by
default.
OUTPUT BED/BEDGraph file of the regional MDS for each region.
finaletoolkit regional-mds [OPTIONS] INPUT OUTPUT

Options

-s, --sep <sep>

Field separator. Default is a tab.

--header <header>

Number of header rows to ignore.

Default:

0

--miller-madow

Apply the Miller-Madow bias correction to each region’s rMDS. Counteracts the downward bias of the plug-in entropy estimator in regions with few fragments.

Example: finaletoolkit regional-mds interval_motifs.tsv rmds.bed

wps

Windowed Protection Score (WPS) over BED sites.

INPUT BAM/CRAM/Fragment file of fragment data.
REGIONS BED file of sites, sorted by contig then start.
finaletoolkit wps [OPTIONS] INPUT REGIONS

Options

-r, --reference <FASTA>

FASTA (.fa, .fasta, .fna) reference genome. Required for CRAM input.

--chrom-sizes <CHROM_SIZES>

A .chrom.sizes file containing chromosome names and sizes.

-o, --output <PATH>

bigWig file of WPS results over the input intervals. Pass ‘-’ to write to standard output (stdout).

Default:

'-'

-i, --interval-size <BP>

Size in bp of the windows (centered on each site) to calculate WPS over.

Default:

5000

-W, --window-size <BP>

Size of the sliding window used to calculate WPS scores.

Default:

120

--min-length <BP>

Minimum fragment length to include (L-WPS).

Default:

120

--max-length <BP>

Maximum fragment length to include (L-WPS).

Default:

180

-q, --min-mapq <MAPQ>

Minimum mapping quality (MAPQ) for a fragment to be included.

Default:

30

-t, --threads <N>

Number of worker processes to use.

Default:

1

-v, --verbose

Increase verbosity (repeatable, e.g. -vv) for detailed output.

Example: finaletoolkit wps sample.bam tss.bed –chrom-sizes hg38.chrom.sizes -o wps.bw