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.

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/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 (use –no-remove-nocov for non-hg19 reference genomes). On by default.

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

Merge input bins to 5Mb (use –no-merge-bins to keep the input bins). On by default.

--merge-size <BP>

Target size of merged genomic intervals.

Default:

5000000

-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

-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

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