📄 / / profiles / r-and-d / raw_evidence / scientific-agent-skills / skills / gtars / references / coverage.md

Coverage, uniwig, and bigWig

Coverage, uniwig, and bigWig

Verified against gtars-cli==0.9.0 / gtars-uniwig==0.9.0 on 2026-07-23. The public BEDbase page is partly under construction; tagged CLI and crate source take precedence where examples differ.

Distinguish two meanings of coverage

Python RegionSet.coverage(other) returns a single fraction of base pairs in the first set covered by the second.
gtars uniwig creates positional signal tracks (WIG, NPY, bedGraph, bigWig, and limited BAM-derived outputs).

Python 0.9.2 does not export gtars.uniwig. Old examples using gtars.uniwig.coverage_from_bed, coverage.normalize(), smooth(), call_peaks(), or to_bigwig() are not current APIs.

Input contract

For BED and narrowPeak:

use 0-based half-open intervals;
supply the exact assembly's local chrom.sizes;
require every contig to exist and every end to be within bounds;
sort by chromosome dictionary order, then numeric start/end;
use one local file (BED, narrowPeak, or BAM);
preserve strand separately—uniwig's BED path produces start/end/core counts, not a generic BED6 strand-aware split.

The official module guide states that uniwig expects a single chromosome-sorted input. Never concatenate samples, patients, or assemblies without a reviewed aggregation policy.

Run the deterministic preflight:

python3 -B scripts/coverage_preflight.py \
  --input fragments.sorted.bed.gz \
  --input-type bed \
  --chrom-sizes GRCh38.p14.chrom.sizes \
  --assembly GRCh38.p14 \
  --output-prefix derived/sample01 \
  --output-type bw \
  --count-type core \
  --threads 4

It validates local paths, bounds, sorting, Gtars u32 coordinates, output collision, and a conservative dense-value budget. It writes and executes nothing.

Current batch CLI

BigWig generation uses the root uniwig command directly—there is no generate subcommand:

gtars uniwig \
  --file fragments.sorted.bed.gz \
  --filetype bed \
  --chromref GRCh38.p14.chrom.sizes \
  --smoothsize 5 \
  --stepsize 1 \
  --fileheader derived/sample01_ \
  --outputtype bw \
  --counttype core \
  --threads 4 \
  --zoom 1

Equivalent short options are -f, -t, -c, -m, -s, -l, -y, -u, -p, and -z. Valid batch count types are:

start: accumulations at interval starts;
end: accumulations at interval ends;
core: interval-body accumulations;
all: produce start, end, and core;
shift: BAM-specific shifted workflow.

The implementation accepts wig, npy, bedgraph, bw, and bigwig strings along relevant paths, but use the documented compact bw for BigWig. BED and narrowPeak can produce WIG, NPY, bedGraph, or BigWig. BAM paths produce BigWig or BED in the documented workflow.

Other batch flags:

--score uses narrowPeak score;
--bamscale FLOAT scales BAM values (default 1.0);
--no-bamshift disables direction-aware BAM shifting;
--wigstep fixed|variable selects WIG step style;
--debug increases output.

Validate scientific meaning before using start/end/shift signals. ATAC cut-site shifts and ChIP fragment-body counts are not interchangeable.

Streaming mode

For very large BED input, 0.9.0 exposes a streaming processor whose state is bounded by smoothing/gap behavior:

gtars uniwig \
  --file fragments.sorted.bed.gz \
  --filetype bed \
  --chromref GRCh38.p14.chrom.sizes \
  --smoothsize 5 \
  --stepsize 1 \
  --fileheader derived/sample01_ \
  --outputtype bedgraph \
  --counttype core \
  --streaming \
  --dense 0

Streaming constraints in tagged source:

only BED input;
only wig or bedgraph output, not BigWig or NPY;
count type start, end, core, or all (not BAM shift);
--dense 0 is sparse, --dense -1 is fully dense, and positive N fills gaps no wider than N;
--stdout is available; multiple count types receive separator comments.

If stdin is used with --counttype all, the handler buffers stdin into memory so it can replay it. Do not claim constant memory for that combination.

BAM QC and BAM coverage

Library-complexity metrics are a subcommand:

gtars uniwig bamqc \
  --input aligned.bam \
  --output bamqc.tsv \
  --threads 1

Parallel BAM QC (--threads >1) requires a .bai index. Bound BAM size, index size, decompression work, threads, and output. Metrics NRF/PBC1/PBC2 are technical QC summaries, not evidence of biological quality or suitability.

For BAM-to-bigWig, the batch path requires the same --smoothsize, --stepsize, --fileheader, --chromref, and output controls. Keep alignment assembly, filtering, duplicate policy, paired-end handling, and shift/scaling in the provenance record.

BigWig preflight and postflight

Before generation:

verify the exact chromosome dictionary and checksum;
reject unknown/out-of-bounds contigs;
ensure sorted input and numeric signal values;
reserve disk for intermediate bedGraph plus final BigWig;
set threads explicitly (upstream batch default is 6);
use a new output prefix;
avoid patient identifiers in filenames and track labels.

After generation:

verify nonzero file size and BigWig readability with a trusted, pinned reader;
compare its chromosome dictionary and lengths with the input checksum;
query fixed synthetic positions with known expected coverage;
check min/max/NaN behavior and start/end/core suffixes;
record SHA-256, tool versions, parameters, and input hashes.

UCSC documents bedGraph coordinates as 0-based half-open and numerically ordered. Its BigWig tools require matching chromosome sizes. A successful binary write does not prove the assembly or signal semantics are correct.

Rust APIs

Enable only uniwig:

[dependencies]
gtars = { version = "=0.9.0", default-features = false, features = ["uniwig"] }

The wrapper re-exports gtars_uniwig as gtars::uniwig. The primary batch function is:

uniwig_main(
  vec_count_type, smoothsize, filepath, chromsizerefpath, bwfileheader,
  output_type, filetype, num_threads, score, stepsize, zoom, debug,
  bam_shift, bam_scale, wigstep
) -> Result<(), Box<dyn Error>>

It is deliberately string-heavy and has many arguments; prefer the pinned CLI unless embedding is necessary. The typed streaming API is:

uniwig::stream::uniwig_streaming(
  input, output, chrom_sizes, smooth_size, step_size,
  CountType::{Start|End|Core},
  OutputFormat::{Wig|BedGraph},
  max_gap
)

read_chrom_sizes(BufRead) parses the dictionary. BigWig is a batch API, not a streaming OutputFormat.

Threading and resources

Batch uniwig builds a Rayon pool of exactly --threads; the CLI default is 6.
Streaming mode is not controlled by the batch --threads path.
Output work can scale with total assembly span divided by step size, not only with BED row count.
Smoothing, dense gap filling, three count types, BigWig intermediates, and high thread counts can multiply memory/disk.
Start with one thread and one small synthetic contig. Increase only after measuring peak RSS, temporary disk, throughput, and deterministic equivalence.