smftools.informatics.signal_features

smftools.informatics.signal_features#

Per-base nanopore current features from the dorado move table.

The dorado mv BAM tag (emitted with --emit-moves) is [stride, m0, m1, ...] where each mi is a 0/1 flag per signal block of stride samples and a 1 marks the start of a new basecalled base. The ts tag is the number of samples trimmed from the start of the raw signal before basecalling. Composing the move table with the raw POD5 signal yields, per basecalled base, the signal sample range that produced it -- and hence per-base current statistics (mean/std/dwell). These are read-relative (query/basecall order); downstream CIGAR placement scatters them onto reference positions.

Functions

base_signal_features(signal, start, end)

Compute per-base current mean/std/dwell/start via prefix sums (vectorized).

base_signal_trace(signal, start, end, k)

Per-base linearly-resampled current trace, k points per base.

move_table_to_base_ranges(mv[, ts])

Return per-base (start, end) signal sample indices in basecall order.

read_signal_features(mv, ts, reverse, signal, *)

Per-base current features for one read, oriented to BAM query order.

read_signal_trace(mv, ts, reverse, signal, k, *)

Per-base resampled current trace for one read, oriented to BAM query order.
smftools.informatics.signal_features.move_table_to_base_ranges(mv, ts=0)#

Return per-base (start, end) signal sample indices in basecall order.

Parameters:

  • mv -- The dorado move table (mv[0] is the stride; mv[1:] are 0/1 per-block move flags).

  • ts (int (default: 0)) -- Samples trimmed from the signal start (the ts tag).

Return type:

tuple[ndarray, ndarray]

Returns:

Two int arrays (one entry per basecalled base) giving inclusive-start, exclusive-end sample indices into the full (untrimmed) POD5 signal.

smftools.informatics.signal_features.base_signal_features(signal, start, end)#

Compute per-base current mean/std/dwell/start via prefix sums (vectorized).

Parameters:

  • signal -- 1-D current samples (raw or picoamps) for the whole read.

  • start (ndarray) -- Per-base inclusive start sample indices.

  • end (ndarray) -- Per-base exclusive end sample indices.

Return type:

dict[str, ndarray]

Returns:

Dict with current_mean/current_std (float32), dwell (samples) and signal_start (clipped start index), one value per base.

smftools.informatics.signal_features.base_signal_trace(signal, start, end, k)#

Per-base linearly-resampled current trace, k points per base.

Unlike base_signal_features (which reduces each base's sample range to a single mean), this preserves within-base current dynamics by resampling to a fixed width so bases with different dwell times still produce comparable, stackable rows.

Parameters:

  • signal -- 1-D current samples (raw or picoamps) for the whole read.

  • start (ndarray) -- Per-base inclusive start sample indices.

  • end (ndarray) -- Per-base exclusive end sample indices.

  • k (int) -- Number of resampled points per base.

Return type:

ndarray

Returns:

(n_bases, k) float32 array; a base with zero samples is all-NaN.

smftools.informatics.signal_features.read_signal_trace(mv, ts, reverse, signal, k, *, expected_bases=None)#

Per-base resampled current trace for one read, oriented to BAM query order.

Mirrors read_signal_features: move tables index bases in basecall order; for reverse-mapped reads the BAM query is reverse-complemented, so the per-base trace rows are flipped (base order only -- each row's k samples are already in forward-time order and are not reversed) to match the query coordinate arrays produced by alignment_to_ragged_record.

Parameters:

  • mv -- Move table tag.

  • ts (int) -- Trim offset (ts tag).

  • reverse (bool) -- Whether the read is reverse-mapped.

  • signal -- Full current sample array for the read.

  • k (int) -- Number of resampled points per base.

  • expected_bases (int | None (default: None)) -- If given, return None when the basecalled base count does not match (e.g. hard-clipped/supplementary reads).

Return type:

ndarray | None

Returns:

(n_bases, k) float32 array in BAM query order, or None if the move table is unusable or the base count mismatches expected_bases.

smftools.informatics.signal_features.read_signal_features(mv, ts, reverse, signal, *, expected_bases=None)#

Per-base current features for one read, oriented to BAM query order.

Move tables index bases in basecall order; for reverse-mapped reads the BAM query is reverse-complemented, so features are flipped to match the query coordinate arrays produced by alignment_to_ragged_record.

Parameters:

  • mv -- Move table tag.

  • ts (int) -- Trim offset (ts tag).

  • reverse (bool) -- Whether the read is reverse-mapped.

  • signal -- Full current sample array for the read.

  • expected_bases (int | None (default: None)) -- If given, return None when the basecalled base count does not match (e.g. hard-clipped/supplementary reads).

Return type:

dict[str, ndarray] | None

Returns:

Dict of per-base feature arrays in BAM query order, or None if the move table is unusable or the base count mismatches expected_bases.