Basic Features

Coverage

finaletoolkit.frag.coverage(input_file, interval_file, output_file, scale_factor=1.0, min_length=None, max_length=None, normalize=False, intersect_policy='midpoint', quality_threshold=30, workers=1, verbose=False, reference_file=None)[source]

Estimate fragment coverage over every interval in a BED file.

Parameters:

  • input_file (str or pysam handle) – BAM/CRAM/fragment input.

  • interval_file (str) – BED4 file of intervals.

  • output_file (str) – Output BED/.bedgraph/.bed.gz path, or "-" for stdout. None suppresses file output and only returns results.

  • scale_factor (float, optional) – Multiplier applied to coverage values (default 1.0).

  • min_length (int, optional) – Fragment-length filter.

  • max_length (int, optional) – Fragment-length filter.

  • normalize (bool, optional) – Divide scale_factor by the genome-wide coverage before scaling.

  • intersect_policy ({"midpoint", "any"}, optional) – Region-membership policy (default "midpoint").

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

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

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

  • reference_file (str or Path, optional) – Reference genome (required for CRAM).

Returns:

Scaled coverage for each interval.

Return type:

list of CoverageResult

finaletoolkit.frag.single_coverage(input_file, contig=None, start=0, stop=None, name='.', min_length=None, max_length=None, intersect_policy='midpoint', quality_threshold=30, verbose=False, reference_file=None)[source]

Estimate fragment coverage over a single region.

Counts fragments (per intersect_policy) falling in contig:[start, stop). Not suitable when fragment sizes approach the region size.

Parameters:

  • input_file (str or pysam handle) – BAM/CRAM/fragment input.

  • contig (str, optional) – Contig name.

  • start (int, optional) – 0-based start (default 0).

  • stop (int, optional) – 1-based stop (default: end of contig).

  • name (str, optional) – Interval name ('.' if None).

  • min_length (int, optional) – Fragment-length filter.

  • max_length (int, optional) – Fragment-length filter.

  • intersect_policy ({"midpoint", "any"}, optional) – Region-membership policy (default "midpoint").

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

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

  • reference_file (str or Path, optional) – Reference genome (required for CRAM).

Returns:

(contig, start, stop, name, coverage).

Return type:

CoverageResult

class finaletoolkit.frag.CoverageResult(contig, start, stop, name, coverage)[source]

Coverage over a single interval.

A named tuple: it unpacks and indexes like (contig, start, stop, name, coverage) and also exposes named fields.

Parameters:

  • contig (str | None)

  • start (int | None)

  • stop (int | None)

  • name (str)

  • coverage (float)

contig

Interval contig.

Type:

str or None

start

0-based start coordinate.

Type:

int or None

stop

Stop coordinate.

Type:

int or None

name

Interval name.

Type:

str

coverage

Coverage value over the interval.

Type:

float

Fragment length

finaletoolkit.frag.frag_length(input_file, contig=None, start=None, stop=None, intersect_policy='midpoint', output_file=None, quality_threshold=30, verbose=False, reference_file=None)[source]

Return an array of fragment lengths from an alignment/fragment file.

Parameters:

  • input_file (str, AlignmentFile, or TabixFile) – BAM, CRAM, or tabix-indexed fragment file (or open pysam handle).

  • contig (str, optional) – Restrict to this contig.

  • start (int, optional) – 0-based left-most coordinate of the interval.

  • stop (int, optional) – 1-based right-most coordinate of the interval.

  • intersect_policy ({"midpoint", "any"}, optional) – Region-membership policy (default "midpoint").

  • output_file (str, optional) – .bin writes a raw binary array; "-" writes one length per line to stdout.

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

  • verbose (bool, optional) – Print timing information.

  • reference_file (str or Path, optional) – Reference genome (required for CRAM).

Returns:

int32 array of fragment lengths.

Return type:

numpy.ndarray

finaletoolkit.frag.frag_length_bins(input_file, contig=None, start=None, stop=None, min_length=0, max_length=None, bin_size=1, output_file=None, intersect_policy='midpoint', quality_threshold=30, summary_stats=False, short_fraction=None, histogram_path=None, verbose=False, reference_file=None)[source]

Bin fragment lengths and optionally write a TSV table or histogram.

Parameters:

  • input_file (str, AlignmentFile, or TabixFile) – BAM/CRAM/fragment input.

  • contig (str, optional) – Restrict to this contig (genome-wide if omitted).

  • start (int, optional) – Interval bounds (require contig).

  • stop (int, optional) – Interval bounds (require contig).

  • min_length (int, optional) – Fragment-length filter applied before binning.

  • max_length (int, optional) – Fragment-length filter applied before binning.

  • bin_size (int, optional) – Bin width in bp (default 1).

  • output_file (str, optional) – TSV/.gz path, or "-" for stdout.

  • intersect_policy ({"midpoint", "any"}, optional) – Region-membership policy.

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

  • summary_stats (bool, optional) – Append summary statistics as #-comment lines to the TSV.

  • short_fraction (int, optional) – If set, add a short-fraction statistic (fragments <= this length).

  • histogram_path (str, optional) – If set, also render a histogram PNG here.

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

  • reference_file (str or Path, optional) – Reference genome (required for CRAM).

Returns:

  • bins (numpy.ndarray) – Bin lower bounds.

  • counts (list of int) – Fragment count per bin (same length as bins).

Return type:

tuple[ndarray, list]

finaletoolkit.frag.frag_length_intervals(input_file, interval_file, output_file=None, min_length=0, max_length=None, quality_threshold=30, intersect_policy='midpoint', short_reads=150, workers=1, verbose=False, reference_file=None)[source]

Compute per-interval fragment-length statistics over a BED file.

Parameters:

  • input_file (str or AlignmentFile) – BAM/CRAM/fragment input.

  • interval_file (str) – BED file of intervals.

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

  • min_length (int, optional) – Fragment-length filter.

  • max_length (int, optional) – Fragment-length filter.

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

  • intersect_policy ({"midpoint", "any"}, optional) – Region-membership policy.

  • short_reads (int, optional) – Short-read length cutoff for the short fraction (default 150).

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

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

  • reference_file (str or Path, optional) – Reference genome (required for CRAM).

Returns:

One record per interval (contig, start, stop, name, mean, median, stdev, min, max, count, frac_short_reads).

Return type:

list of FragLengthStats

class finaletoolkit.frag.FragLengthStats(contig, start, stop, name, mean, median, stdev, minimum, maximum, count, frac_short_reads)[source]

Fragment-length summary statistics over one interval.

A named tuple: it unpacks and indexes like a plain tuple and also exposes named fields. Intervals with no fragments report -1 for every numeric field.

Parameters:
contig

Interval contig.

Type:

str

start

0-based start coordinate.

Type:

int

stop

Stop coordinate.

Type:

int

name

Interval name.

Type:

str

mean

Mean fragment length.

Type:

float

median

Median fragment length.

Type:

float

stdev

Standard deviation of the fragment lengths.

Type:

float

minimum

Shortest fragment length.

Type:

int

maximum

Longest fragment length.

Type:

int

count

Number of fragments in the interval.

Type:

int

frac_short_reads

Fraction of fragments below the short-read length threshold.

Type:

float