smftools.preprocessing.append_variant_call_layer

smftools.preprocessing.append_variant_call_layer#

smftools.preprocessing.append_variant_call_layer(adata, seq1_column, seq2_column, seq1_converted_column=None, seq2_converted_column=None, sequence_layer='sequence_integer_encoding', read_span_layer='read_span_mask', reference_col='Reference_strand', output_prefix=None, uns_flag='append_variant_call_layer_performed', force_redo=False, bypass=False)#

Append a layer recording per-read, per-position variant calls at reference mismatch sites.

Uses the substitution map from append_sequence_mismatch_annotations to correctly handle coordinate shifts caused by indels between references. For each substitution, reads aligned to ref1 are checked at ref1's var index, and reads aligned to ref2 are checked at ref2's var index.

For conversion SMF, reads are mapped to converted references while the alignment that identifies mismatch positions uses unconverted sequences. When seq1_converted_column / seq2_converted_column are provided, each reference gets a set of acceptable bases at each mismatch position (unconverted + converted), since not every base converts in every read. A position is informative only if the two acceptable-base sets are disjoint. A read base matching either the unconverted or converted form of a reference counts as a match for that reference.

Values in the output layer:

1 = matches seq1 base(s) 2 = matches seq2 base(s) 0 = unknown (N, PAD, no coverage, or matches neither) -1 = not a mismatch position (or not informative after conversion)

Parameters:

  • adata (AnnData) -- AnnData object.

  • seq1_column (str) -- Column in adata.var with the first reference base per position (unconverted).

  • seq2_column (str) -- Column in adata.var with the second reference base per position (unconverted).

  • seq1_converted_column (str | None (default: None)) -- Optional column in adata.var with the converted seq1 bases. When provided, both unconverted and converted bases are accepted as ref1 matches.

  • seq2_converted_column (str | None (default: None)) -- Optional column in adata.var with the converted seq2 bases.

  • sequence_layer (str (default: 'sequence_integer_encoding')) -- Layer containing integer-encoded actual read bases.

  • read_span_layer (str (default: 'read_span_mask')) -- Layer containing read span masks.

  • reference_col (str (default: 'Reference_strand')) -- Obs column defining which reference each read is aligned to.

  • output_prefix (str | None (default: None)) -- Prefix for the output layer name. Defaults to {seq1_column}__{seq2_column}.

  • uns_flag (str (default: 'append_variant_call_layer_performed')) -- Flag in adata.uns indicating prior completion.

  • force_redo (bool (default: False)) -- Whether to rerun even if uns_flag is set.

  • bypass (bool (default: False)) -- Whether to skip processing.

Return type:

None