smftools.tools.rolling_nn_distance

Functions

annotate_zero_hamming_segments(adata[, ...])	Merge zero-Hamming windows into maximal segments and annotate onto AnnData.
assign_per_read_segments_layer(parent_adata, ...)	Assign per-read segments into a summed span layer on a parent AnnData.
assign_rolling_nn_results(parent_adata, ...)	Assign rolling NN results computed on a subset back onto a parent AnnData.
rolling_window_nn_distance(adata[, layer, ...])	Rolling-window nearest-neighbor distance per read, overlap-aware.
segments_to_per_read_dataframe(records, ...)	Build a per-read DataFrame of zero-Hamming segments.
select_top_segments_per_read(records, var_names)	Select top segments per read from distinct partner pairs.
zero_hamming_segments_to_dataframe(records, ...)	Build a DataFrame of merged/refined zero-Hamming segments.
zero_pairs_to_dataframe(adata, ...)	Build a DataFrame of zero-Hamming pairs per window.

smftools.tools.rolling_nn_distance.zero_pairs_to_dataframe(adata, zero_pairs_uns_key)

Build a DataFrame of zero-Hamming pairs per window.

Parameters:

• adata -- AnnData containing zero-pair window data in adata.uns.

• zero_pairs_uns_key (str) -- Key for zero-pair window data in adata.uns.

Return type:

DataFrame

Returns:

DataFrame with one row per zero-Hamming pair per window.

smftools.tools.rolling_nn_distance.zero_hamming_segments_to_dataframe(records, var_names)

Build a DataFrame of merged/refined zero-Hamming segments.

Parameters:

• records (list[dict]) -- Output records from annotate_zero_hamming_segments.

• var_names (ndarray) -- AnnData var names for labeling segment coordinates.

Return type:

DataFrame

Returns:

DataFrame with one row per zero-Hamming segment.

smftools.tools.rolling_nn_distance.rolling_window_nn_distance(adata, layer=None, window=15, step=2, min_overlap=10, return_fraction=True, block_rows=256, block_cols=2048, store_obsm='rolling_nn_dist', collect_zero_pairs=False, zero_pairs_uns_key=None, sample_labels=None, index_col_suffix=None, reference_col='Reference_strand')

Rolling-window nearest-neighbor distance per read, overlap-aware.

Return type:

Tuple[ndarray, ndarray]

Distance between reads i,j in a window:

• use only positions where BOTH are observed (non-NaN)

• require overlap >= min_overlap

• mismatch = count(x_i != x_j) over overlapped positions

• distance = mismatch/overlap (if return_fraction) else mismatch

index_col_suffix: If set and adata contains exactly one reference

value in reference_col, use adata.var[f"{ref}_{index_col_suffix}"] for the stored window centers instead of var_names (e.g. "reindexed"), so reindexing_offsets/reindexing_invert are reflected. Falls back to var_names when adata spans multiple references (no single offset/sign would apply) or the column is absent.

Returns

out(n_obs, n_windows) float

Nearest-neighbor distance per read per window (NaN if no valid neighbor).

starts(n_windows,) int

Window start indices in var-space.

centers(n_windows,) array-like

Window center coordinates derived from AnnData var positions (stored in .uns).

smftools.tools.rolling_nn_distance.annotate_zero_hamming_segments(adata, zero_pairs_uns_key=None, output_uns_key='zero_hamming_segments', layer=None, min_overlap=None, refine_segments=True, max_nan_run=None, merge_gap=0, max_segments_per_read=None, max_segment_overlap=None)

Merge zero-Hamming windows into maximal segments and annotate onto AnnData.

Parameters:

• adata -- AnnData containing zero-pair window data in .uns.

• zero_pairs_uns_key (Optional[str] (default: None)) -- Key for zero-pair window data in adata.uns.

• output_uns_key (str (default: 'zero_hamming_segments')) -- Key to store merged/refined segments in adata.uns.

• layer (Optional[str] (default: None)) -- Layer to use for refinement (defaults to adata.X).

• min_overlap (Optional[int] (default: None)) -- Minimum overlap required to keep a refined segment.

• refine_segments (bool (default: True)) -- Whether to refine merged windows to maximal segments.

• max_nan_run (Optional[int] (default: None)) -- Maximum consecutive NaN positions allowed when expanding segments. If reached, expansion stops before the NaN run. Set to None to ignore NaNs.

• merge_gap (int (default: 0)) -- Merge segments with gaps of at most this size (in positions).

• max_segments_per_read (Optional[int] (default: None)) -- Maximum number of segments to retain per read pair.

• max_segment_overlap (Optional[int] (default: None)) -- Maximum allowed overlap between retained segments (inclusive, in var-index coordinates).

Return type:

list[dict]

Returns:

List of segment records stored in adata.uns[output_uns_key].

smftools.tools.rolling_nn_distance.assign_per_read_segments_layer(parent_adata, subset_adata, per_read_segments, layer_key)

Assign per-read segments into a summed span layer on a parent AnnData.

Parameters:

• parent_adata (AnnData) -- AnnData that should receive the span layer.

• subset_adata (AnnData) -- AnnData used to compute per-read segments.

• per_read_segments (DataFrame) -- DataFrame with read_id, segment_start, and segment_end_exclusive columns. If segment_start_label and segment_end_label are present and numeric, they are used to map segments using label coordinates.

• layer_key (str) -- Name of the layer to store in parent_adata.layers.

Return type:

None

smftools.tools.rolling_nn_distance.segments_to_per_read_dataframe(records, var_names)

Build a per-read DataFrame of zero-Hamming segments.

Parameters:

• records (list[dict]) -- Output records from annotate_zero_hamming_segments.

• var_names (ndarray) -- AnnData var names for labeling segment coordinates.

Return type:

DataFrame

Returns:

DataFrame with one row per segment per read.

smftools.tools.rolling_nn_distance.select_top_segments_per_read(records, var_names, max_segments_per_read=None, max_segment_overlap=None, min_span=None)

Select top segments per read from distinct partner pairs.

Parameters:

• records (list[dict]) -- Output records from annotate_zero_hamming_segments.

• var_names (ndarray) -- AnnData var names for labeling segment coordinates.

• max_segments_per_read (Optional[int] (default: None)) -- Maximum number of segments to keep per read.

• max_segment_overlap (Optional[int] (default: None)) -- Maximum allowed overlap between kept segments.

• min_span (Optional[float] (default: None)) -- Minimum span length to keep (var-name coordinate if numeric, else index span).

Return type:

tuple[DataFrame, DataFrame]

Returns:

Tuple of (raw per-read segments, filtered per-read segments).

smftools.tools.rolling_nn_distance.assign_rolling_nn_results(parent_adata, subset_adata, values, starts, obsm_key, window, step, min_overlap, return_fraction, layer, index_col_suffix=None, reference_col='Reference_strand')

Assign rolling NN results computed on a subset back onto a parent AnnData.

Return type:

None

Parameters

parent_adataAnnData

Parent AnnData that should store the combined results.

subset_adataAnnData

Subset AnnData used to compute values.

valuesnp.ndarray

Rolling NN output with shape (n_subset_obs, n_windows).

startsnp.ndarray

Window start indices corresponding to values.

obsm_keystr

Key to store results under in parent_adata.obsm.

windowint

Rolling window size (stored in parent_adata.uns).

stepint

Rolling window step size (stored in parent_adata.uns).

min_overlapint

Minimum overlap (stored in parent_adata.uns).

return_fractionbool

Whether distances are fractional (stored in parent_adata.uns).

layerstr | None

Layer used for calculations (stored in parent_adata.uns).

index_col_suffixstr | None

Passed through to _window_center_coordinates via the same single-reference resolution used in rolling_window_nn_distance, so reindexing_offsets/reindexing_invert are reflected in the stored window centers.

reference_colstr

Obs column used to resolve the single reference for index_col_suffix.