Frag File Utilities

finaletoolkit.utils.filter_file(input_file, whitelist_file=None, blacklist_file=None, output_file=None, min_length=None, max_length=None, intersect_policy='midpoint', quality_threshold=30, workers=1, verbose=False, fraction_low=None, fraction_high=None)[source]

Create a filtered copy of a BAM/CRAM or tabix BED fragment file.

Reads/intervals are kept when they exceed quality_threshold, fall within the length bounds, and (for whitelist/blacklist BEDs) intersect per intersect_policy. BAM/CRAM additionally keeps only read1 of proper pairs.

Parameters:

  • input_file (str) – Input BAM/CRAM/.gz/.bgz path.

  • whitelist_file (str, optional) – BED of regions to keep.

  • blacklist_file (str, optional) – BED of regions to exclude.

  • output_file (str, optional) – Output path ("-" for stdout).

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

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

  • intersect_policy ({"midpoint", "any"}, optional) – Whitelist/blacklist intersection policy (default "midpoint").

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

  • workers (int, optional) – Threads for samtools/bgzip (default 1).

  • verbose (bool, optional) – Print configuration and enable logging.

  • fraction_low (int, optional) – Deprecated aliases for min_length/max_length.

  • fraction_high (int, optional) – Deprecated aliases for min_length/max_length.

Returns:

The output path.

Return type:

str

finaletoolkit.utils.agg_bw(input_file, interval_file, output_file, median_window_size=1, mean=False, verbose=False)[source]

Aggregate bigWig signal over BED intervals (strand-aware).

The median filter used by adjust-wps trims each interval by half the window size. Account for that either by supplying smaller intervals or by passing the original median_window_size here (do not do both).

Parameters:

  • input_file (str or path) – bigWig of per-base signal.

  • interval_file (str or path) – BED of intervals; column 6 must contain the strand.

  • output_file (str or path) – Output WIG path.

  • median_window_size (int, optional) – Filter window used upstream (default 1 = no trimming; 120 replicates Snyder et al.).

  • mean (bool, optional) – Divide the aggregate by the number of intervals (mean instead of sum).

  • verbose (bool, optional) – Print progress/timing.

Returns:

The aggregated per-position signal.

Return type:

numpy.ndarray

Raises:

ValueError – If interval_file is not BED or output_file is not .wig.

finaletoolkit.utils.chrom_sizes_to_list(chrom_sizes_file)[source]

Read a .chrom.sizes file into a list of (name, size) tuples.

Parameters:

chrom_sizes_file (str or Path) – Tab-delimited file with contig name and size columns.

Returns:

Contig names and sizes, in file order.

Return type:

list of (str, int)

finaletoolkit.utils.chrom_sizes_to_dict(chrom_sizes_file)[source]

Read a .chrom.sizes file into a {name: size} dict.

Parameters:

chrom_sizes_file (str or Path) – Tab-delimited file with contig name and size columns.

Returns:

Maps contig name to integer size.

Return type:

dict

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

Stream fragments from a BAM/CRAM/fragment file with optional filtering.

Parameters:

  • input_file (str, Path, pysam.TabixFile, or pysam.AlignmentFile) – Fragment coordinates as a BAM, CRAM, or tabix-indexed FinaleDB fragment file (or an open pysam handle).

  • contig (str or None) – Chromosome to fetch over (None for genome-wide).

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

  • start (int, optional) – Region bounds; see intersect_policy.

  • stop (int, optional) – Region bounds; see intersect_policy.

  • min_length (int, optional) – Inclusive fragment-length bounds (None disables a bound).

  • max_length (int, optional) – Inclusive fragment-length bounds (None disables a bound).

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

  • verbose (bool or int, optional) – Unused placeholder kept for signature compatibility.

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

Yields:

tuple – (contig, start, stop, mapq, is_forward) for each passing fragment.

Raises:

InvalidInputError – If start/stop are given without contig (except the whole-genome special case start == 0, stop is None).

Return type:

Generator[Tuple[str, int, int, int, bool], None, None]

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

Read fragments into a structured (start, stop, strand) array.

Parameters:

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

  • contig (str) – Contig to read.

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

  • start (int, optional) – Region bounds.

  • stop (int, optional) – Region bounds.

  • min_length (int, optional) – Inclusive fragment-length bounds.

  • max_length (int, optional) – Inclusive fragment-length bounds.

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

  • verbose (bool, optional) – Print progress to stderr.

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

Returns:

1-D structured array with dtype [('start', 'i8'), ('stop', 'i8'), ('strand', '?')]. strand is True on the + strand. Shape (0,) if no fragments match.

Return type:

ndarray

finaletoolkit.utils.low_quality_read_pairs(read, min_mapq=30)[source]

Return True if read is not a clean, properly-paired alignment.

Equivalent to samtools -F 3852 -f 3 plus a -G 48 style same-strand check and an optional mate mapping-quality (MQ tag) check. Adapted from cofragr’s frag_summary_in_intervals.py.

Parameters:

  • read (pysam.AlignedSegment) – The read to inspect.

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

Returns:

True if the read is low quality, unmapped, or improperly paired.

Return type:

bool

finaletoolkit.utils.overlaps(contigs_1, starts_1, stops_1, contigs_2, starts_2, stops_2)[source]

Vectorized “does interval-set 1 overlap any interval in set 2?”.

Parameters:

  • contigs_1 (ndarray) – Parallel arrays describing the query intervals.

  • starts_1 (ndarray) – Parallel arrays describing the query intervals.

  • stops_1 (ndarray) – Parallel arrays describing the query intervals.

  • contigs_2 (ndarray) – Parallel arrays describing the reference intervals.

  • starts_2 (ndarray) – Parallel arrays describing the reference intervals.

  • stops_2 (ndarray) – Parallel arrays describing the reference intervals.

Returns:

Same shape as contigs_1; True where that query interval overlaps at least one interval in set 2 (same contig required).

Return type:

ndarray of bool