Window Protection Score (WPS)

finaletoolkit.frag.wps(input_file, chrom, start, stop, chrom_size, output_file=None, window_size=120, min_length=120, max_length=180, quality_threshold=30, verbose=0, fraction_low=None, fraction_high=None, reference_file=None)[source]

Compute raw Windowed Protection Scores over chrom:[start, stop).

Parameters:

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

  • chrom (str) – Contig name.

  • start (int) – Region bounds (0-based, half-open).

  • stop (int) – Region bounds (0-based, half-open).

  • chrom_size (int) – Length of chrom (bounds the fragment-fetch window).

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

  • window_size (int, optional) – WPS window width (default 120, i.e. L-WPS).

  • min_length (int, optional) – Fragment-length filter (defaults 120/180, i.e. long fraction).

  • max_length (int, optional) – Fragment-length filter (defaults 120/180, i.e. long fraction).

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

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

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

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

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

Returns:

Structured array with fields ('contig', 'start', 'wps'). Empty for a degenerate interval.

Return type:

numpy.ndarray

finaletoolkit.frag.multi_wps(input_file, site_bed, chrom_sizes=None, output_file=None, window_size=120, interval_size=5000, min_length=120, max_length=180, quality_threshold=30, workers=1, verbose=0, fraction_low=None, fraction_high=None, reference_file=None)[source]

Aggregate WPS over sites in a BED file.

Each BED interval is replaced by a interval_size-bp window centered on its midpoint; WPS is computed per window and written to a bigWig (or bed.gz/bedGraph.gz) file.

Parameters:

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

  • site_bed (str or path) – BED of sites, sorted by contig then start. "-" reads stdin.

  • chrom_sizes (str or path, optional) – .chrom.sizes file (required when input_file is a fragment file).

  • output_file (str, optional) – .bw or .bed.gz/.bedGraph.gz path.

  • window_size (int, optional) – WPS window width (default 120).

  • interval_size (int, optional) – Window size centered on each site midpoint (default 5000).

  • min_length (int, optional) – Fragment-length filter (defaults 120/180).

  • max_length (int, optional) – Fragment-length filter (defaults 120/180).

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

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

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

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

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

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

Returns:

The output path (or None if no output was requested).

Return type:

str or None

finaletoolkit.frag.adjust_wps(input_file, interval_file, output_file, chrom_sizes, interval_size=5000, median_window_size=1000, savgol_window_size=21, savgol_poly_deg=2, savgol=True, mean=False, subtract_edges=False, edge_size=500, workers=1, verbose=False)[source]

Adjust raw WPS in a bigWig with median/mean and Savitzky-Golay filters.

Parameters:

  • input_file (str) – Path to a bigWig of raw WPS.

  • interval_file (str) – BED of intervals WPS was computed over.

  • output_file (str) – Output bigWig path.

  • chrom_sizes (str) – .chrom.sizes file for the bigWig header.

  • interval_size (int, optional) – Size of each centered interval (default 5000).

  • median_window_size (int, optional) – Median/mean filter window (default 1000).

  • savgol_window_size (int, optional) – Savitzky-Golay window (default 21).

  • savgol_poly_deg (int, optional) – Savitzky-Golay polynomial degree (default 2).

  • savgol (bool, optional) – Apply the Savitzky-Golay filter (default True).

  • mean (bool, optional) – Use a mean filter instead of median (default False).

  • subtract_edges (bool, optional) – Subtract the mean of the interval edges before filtering.

  • edge_size (int, optional) – Edge width for subtract_edges (default 500).

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

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

Return type:

None