smftools 0.3.1__py3-none-any.whl → 0.3.2__py3-none-any.whl

smftools/config/experiment_config.py

@@ -840,6 +840,10 @@ class ExperimentConfig:
     mismatch_frequency_range: Sequence[float] = field(default_factory=lambda: [0.05, 0.95])
     mismatch_frequency_layer: str = "mismatch_integer_encoding"
     mismatch_frequency_read_span_layer: str = "read_span_mask"
+    mismatch_base_frequency_exclude_mod_sites: bool = False
+    references_to_align_for_variant_annotation: List[Optional[str]] = field(
+        default_factory=lambda: [None, None]
+    )
 
     # Spatial Analysis - Clustermap params
     layer_for_clustermap_plotting: Optional[str] = "nan0_0minus1"
@@ -848,14 +852,45 @@ class ExperimentConfig:
     clustermap_cmap_cpg: Optional[str] = "coolwarm"
     clustermap_cmap_a: Optional[str] = "coolwarm"
     spatial_clustermap_sortby: Optional[str] = "gpc"
+    overlay_variant_calls: bool = False
+    variant_overlay_seq1_color: str = "white"
+    variant_overlay_seq2_color: str = "black"
+    variant_overlay_marker_size: float = 4.0
     rolling_nn_layer: Optional[str] = "nan0_0minus1"
     rolling_nn_plot_layer: Optional[str] = "nan0_0minus1"
-    rolling_nn_window: int = 15
-    rolling_nn_step: int = 2
-    rolling_nn_min_overlap: int = 10
+    rolling_nn_plot_layers: List[str] = field(
+        default_factory=lambda: ["nan0_0minus1", "nan0_0minus1"]
+    )
+    rolling_nn_window: int = 10
+    rolling_nn_step: int = 1
+    rolling_nn_min_overlap: int = 8
     rolling_nn_return_fraction: bool = True
     rolling_nn_obsm_key: str = "rolling_nn_dist"
     rolling_nn_site_types: Optional[List[str]] = None
+    rolling_nn_write_zero_pairs_csvs: bool = True
+    rolling_nn_zero_pairs_uns_key: Optional[str] = None
+    rolling_nn_zero_pairs_segments_key: Optional[str] = None
+    rolling_nn_zero_pairs_layer_key: Optional[str] = None
+    rolling_nn_zero_pairs_refine: bool = True
+    rolling_nn_zero_pairs_max_nan_run: Optional[int] = None
+    rolling_nn_zero_pairs_merge_gap: int = 0
+    rolling_nn_zero_pairs_max_segments_per_read: Optional[int] = None
+    rolling_nn_zero_pairs_max_overlap: Optional[int] = None
+    rolling_nn_zero_pairs_layer_overlap_mode: str = "binary"
+    rolling_nn_zero_pairs_layer_overlap_value: Optional[int] = None
+    rolling_nn_zero_pairs_keep_uns: bool = True
+    rolling_nn_zero_pairs_segments_keep_uns: bool = True
+    rolling_nn_zero_pairs_top_segments_per_read: Optional[int] = None
+    rolling_nn_zero_pairs_top_segments_max_overlap: Optional[int] = None
+    rolling_nn_zero_pairs_top_segments_min_span: Optional[float] = None
+    rolling_nn_zero_pairs_top_segments_write_csvs: bool = True
+    rolling_nn_zero_pairs_segment_histogram_bins: int = 30
+
+    # Cross-sample rolling NN analysis
+    cross_sample_analysis: bool = False
+    cross_sample_grouping_col: Optional[str] = None
+    cross_sample_random_seed: int = 42
+    delta_hamming_chimeric_span_threshold: int = 200
 
     # Spatial Analysis - UMAP/Leiden params
     layer_for_umap_plotting: Optional[str] = "nan_half"
@@ -1148,6 +1183,10 @@ class ExperimentConfig:
             merged["mod_target_bases"] = _parse_list(merged["mod_target_bases"])
         if "conversion_types" in merged:
             merged["conversion_types"] = _parse_list(merged["conversion_types"])
+        if "references_to_align_for_variant_annotation" in merged:
+            merged["references_to_align_for_variant_annotation"] = _parse_list(
+                merged["references_to_align_for_variant_annotation"]
+            )
 
         merged["filter_threshold"] = float(_parse_numeric(merged.get("filter_threshold", 0.8), 0.8))
         merged["m6A_threshold"] = float(_parse_numeric(merged.get("m6A_threshold", 0.7), 0.7))
@@ -1360,14 +1399,65 @@ class ExperimentConfig:
             clustermap_cmap_cpg=merged.get("clustermap_cmap_cpg", "coolwarm"),
             clustermap_cmap_a=merged.get("clustermap_cmap_a", "coolwarm"),
             spatial_clustermap_sortby=merged.get("spatial_clustermap_sortby", "gpc"),
+            overlay_variant_calls=_parse_bool(merged.get("overlay_variant_calls", False)),
+            variant_overlay_seq1_color=merged.get("variant_overlay_seq1_color", "white"),
+            variant_overlay_seq2_color=merged.get("variant_overlay_seq2_color", "black"),
+            variant_overlay_marker_size=float(merged.get("variant_overlay_marker_size", 4.0)),
             rolling_nn_layer=merged.get("rolling_nn_layer", "nan0_0minus1"),
             rolling_nn_plot_layer=merged.get("rolling_nn_plot_layer", "nan0_0minus1"),
+            rolling_nn_plot_layers=merged.get(
+                "rolling_nn_plot_layers", ["nan0_0minus1", "nan0_0minus1"]
+            ),
             rolling_nn_window=merged.get("rolling_nn_window", 15),
             rolling_nn_step=merged.get("rolling_nn_step", 2),
             rolling_nn_min_overlap=merged.get("rolling_nn_min_overlap", 10),
             rolling_nn_return_fraction=merged.get("rolling_nn_return_fraction", True),
             rolling_nn_obsm_key=merged.get("rolling_nn_obsm_key", "rolling_nn_dist"),
             rolling_nn_site_types=merged.get("rolling_nn_site_types", None),
+            rolling_nn_write_zero_pairs_csvs=merged.get("rolling_nn_write_zero_pairs_csvs", True),
+            rolling_nn_zero_pairs_uns_key=merged.get("rolling_nn_zero_pairs_uns_key", None),
+            rolling_nn_zero_pairs_segments_key=merged.get(
+                "rolling_nn_zero_pairs_segments_key", None
+            ),
+            rolling_nn_zero_pairs_layer_key=merged.get("rolling_nn_zero_pairs_layer_key", None),
+            rolling_nn_zero_pairs_refine=merged.get("rolling_nn_zero_pairs_refine", True),
+            rolling_nn_zero_pairs_max_nan_run=merged.get("rolling_nn_zero_pairs_max_nan_run", None),
+            rolling_nn_zero_pairs_merge_gap=merged.get("rolling_nn_zero_pairs_merge_gap", 0),
+            rolling_nn_zero_pairs_max_segments_per_read=merged.get(
+                "rolling_nn_zero_pairs_max_segments_per_read", None
+            ),
+            rolling_nn_zero_pairs_max_overlap=merged.get("rolling_nn_zero_pairs_max_overlap", None),
+            rolling_nn_zero_pairs_layer_overlap_mode=merged.get(
+                "rolling_nn_zero_pairs_layer_overlap_mode", "binary"
+            ),
+            rolling_nn_zero_pairs_layer_overlap_value=merged.get(
+                "rolling_nn_zero_pairs_layer_overlap_value", None
+            ),
+            rolling_nn_zero_pairs_keep_uns=merged.get("rolling_nn_zero_pairs_keep_uns", True),
+            rolling_nn_zero_pairs_segments_keep_uns=merged.get(
+                "rolling_nn_zero_pairs_segments_keep_uns", True
+            ),
+            rolling_nn_zero_pairs_top_segments_per_read=merged.get(
+                "rolling_nn_zero_pairs_top_segments_per_read", None
+            ),
+            rolling_nn_zero_pairs_top_segments_max_overlap=merged.get(
+                "rolling_nn_zero_pairs_top_segments_max_overlap", None
+            ),
+            rolling_nn_zero_pairs_top_segments_min_span=merged.get(
+                "rolling_nn_zero_pairs_top_segments_min_span", None
+            ),
+            rolling_nn_zero_pairs_top_segments_write_csvs=merged.get(
+                "rolling_nn_zero_pairs_top_segments_write_csvs", True
+            ),
+            rolling_nn_zero_pairs_segment_histogram_bins=merged.get(
+                "rolling_nn_zero_pairs_segment_histogram_bins", 30
+            ),
+            cross_sample_analysis=merged.get("cross_sample_analysis", False),
+            cross_sample_grouping_col=merged.get("cross_sample_grouping_col", None),
+            cross_sample_random_seed=merged.get("cross_sample_random_seed", 42),
+            delta_hamming_chimeric_span_threshold=merged.get(
+                "delta_hamming_chimeric_span_threshold", 200
+            ),
             layer_for_umap_plotting=merged.get("layer_for_umap_plotting", "nan_half"),
             umap_layers_to_plot=merged.get(
                 "umap_layers_to_plot", ["mapped_length", "Raw_modification_signal"]
@@ -1531,6 +1621,9 @@ class ExperimentConfig:
             force_redo_hmm_fit=merged.get("force_redo_hmm_fit", False),
             bypass_hmm_apply=merged.get("bypass_hmm_apply", False),
             force_redo_hmm_apply=merged.get("force_redo_hmm_apply", False),
+            references_to_align_for_variant_annotation=merged.get(
+                "references_to_align_for_variant_annotation", [None, None]
+            ),
             config_source=config_source or "<var_dict>",
         )
 

smftools/constants.py

@@ -44,7 +44,11 @@ PREPROCESS_DIR: Final[str] = "preprocess_adata_outputs"
 SPATIAL_DIR: Final[str] = "spatial_adata_outputs"
 HMM_DIR: Final[str] = "hmm_adata_outputs"
 LATENT_DIR: Final[str] = "latent_adata_outputs"
+VARIANT_DIR: Final[str] = "variant_adata_outputs"
+CHIMERIC_DIR: Final[str] = "chimeric_adata_outputs"
+
 LOGGING_DIR: Final[str] = "logs"
+
 TRIM: Final[bool] = False
 
 _private_conversions = ["unconverted"]

smftools/hmm/call_hmm_peaks.py

@@ -51,7 +51,7 @@ def call_hmm_peaks(
         raise KeyError(f"obs column '{ref_column}' not found")
 
     # Ensure categorical for predictable ref iteration
-    if not pd.api.types.is_categorical_dtype(adata.obs[ref_column]):
+    if not isinstance(adata.obs[ref_column].dtype, pd.CategoricalDtype):
         adata.obs[ref_column] = adata.obs[ref_column].astype("category")
 
     # Optional: drop duplicate obs columns once to avoid Pandas/AnnData view quirks

smftools/informatics/binarize_converted_base_identities.py

@@ -5,20 +5,19 @@ def binarize_converted_base_identities(
     base_identities,
     strand,
     modification_type,
-    bam,
-    device="cpu",
     deaminase_footprinting=False,
     mismatch_trend_per_read={},
     on_missing="nan",
 ):
     """
     Efficiently binarizes conversion SMF data within a sequence string using NumPy arrays.
+    For conversion modality, the strand parameter is used for mapping.
+    For deaminase modality, the mismatch_trend_per_read is used for mapping.
 
     Parameters:
         base_identities (dict): A dictionary returned by extract_base_identities. Keyed by read name. Points to a list of base identities.
         strand (str): A string indicating which strand was converted in the experiment (options are 'top' and 'bottom').
         modification_type (str): A string indicating the modification type of interest (options are '5mC' and '6mA').
-        bam (str): The bam file path
         deaminase_footprinting (bool): Whether direct deaminase footprinting chemistry was used.
         mismatch_trend_per_read (dict): For deaminase footprinting, indicates the type of conversion relative to the top strand reference for each read. (C->T or G->A if bottom strand was converted)
         on_missing (str): Error handling if a read is missing
@@ -98,89 +97,3 @@ def binarize_converted_base_identities(
         out[read_id] = res
 
     return out
-
-    # if mismatch_trend_per_read is None:
-    #     mismatch_trend_per_read = {}
-
-    # # If the modification type is 'unconverted', return NaN for all positions if the deaminase_footprinting strategy is not being used.
-    # if modification_type == "unconverted" and not deaminase_footprinting:
-    #     #print(f"Skipping binarization for unconverted {strand} reads on bam: {bam}.")
-    #     return {key: np.full(len(bases), np.nan) for key, bases in base_identities.items()}
-
-    # # Define mappings for binarization based on strand and modification type
-    # if deaminase_footprinting:
-    #     binarization_maps = {
-    #         ('C->T'): {'C': 0, 'T': 1},
-    #         ('G->A'): {'G': 0, 'A': 1},
-    #     }
-
-    #     binarized_base_identities = {}
-    #     for key, bases in base_identities.items():
-    #         arr = np.array(bases, dtype='<U1')
-    #         # Fetch the appropriate mapping
-    #         conversion_type = mismatch_trend_per_read[key]
-    #         base_map = binarization_maps.get(conversion_type, None)
-    #         binarized = np.vectorize(lambda x: base_map.get(x, np.nan))(arr)  # Apply mapping with fallback to NaN
-    #         binarized_base_identities[key] = binarized
-
-    #     return binarized_base_identities
-
-    # else:
-    #     binarization_maps = {
-    #         ('top', '5mC'): {'C': 1, 'T': 0},
-    #         ('top', '6mA'): {'A': 1, 'G': 0},
-    #         ('bottom', '5mC'): {'G': 1, 'A': 0},
-    #         ('bottom', '6mA'): {'T': 1, 'C': 0}
-    #     }
-
-    #     if (strand, modification_type) not in binarization_maps:
-    #         raise ValueError(f"Invalid combination of strand='{strand}' and modification_type='{modification_type}'")
-
-    #     # Fetch the appropriate mapping
-    #     base_map = binarization_maps[(strand, modification_type)]
-
-    #     binarized_base_identities = {}
-    #     for key, bases in base_identities.items():
-    #         arr = np.array(bases, dtype='<U1')
-    #         binarized = np.vectorize(lambda x: base_map.get(x, np.nan))(arr)  # Apply mapping with fallback to NaN
-    #         binarized_base_identities[key] = binarized
-
-    #     return binarized_base_identities
-    # import torch
-
-    # # If the modification type is 'unconverted', return NaN for all positions
-    # if modification_type == "unconverted":
-    #     print(f"Skipping binarization for unconverted {strand} reads on bam: {bam}.")
-    #     return {key: torch.full((len(bases),), float('nan'), device=device) for key, bases in base_identities.items()}
-
-    # # Define mappings for binarization based on strand and modification type
-    # binarization_maps = {
-    #     ('top', '5mC'): {'C': 1, 'T': 0},
-    #     ('top', '6mA'): {'A': 1, 'G': 0},
-    #     ('bottom', '5mC'): {'G': 1, 'A': 0},
-    #     ('bottom', '6mA'): {'T': 1, 'C': 0}
-    # }
-
-    # if (strand, modification_type) not in binarization_maps:
-    #     raise ValueError(f"Invalid combination of strand='{strand}' and modification_type='{modification_type}'")
-
-    # # Fetch the appropriate mapping
-    # base_map = binarization_maps[(strand, modification_type)]
-
-    # # Convert mapping to tensor
-    # base_keys = list(base_map.keys())
-    # base_values = torch.tensor(list(base_map.values()), dtype=torch.float32, device=device)
-
-    # # Create a lookup dictionary (ASCII-based for fast mapping)
-    # lookup_table = torch.full((256,), float('nan'), dtype=torch.float32, device=device)
-    # for k, v in zip(base_keys, base_values):
-    #     lookup_table[ord(k)] = v
-
-    # # Process reads
-    # binarized_base_identities = {}
-    # for key, bases in base_identities.items():
-    #     bases_tensor = torch.tensor([ord(c) for c in bases], dtype=torch.uint8, device=device)  # Convert chars to ASCII
-    #     binarized = lookup_table[bases_tensor]  # Efficient lookup
-    #     binarized_base_identities[key] = binarized
-
-    # return binarized_base_identities

smftools/informatics/converted_BAM_to_adata.py

@@ -272,6 +272,10 @@ def converted_BAM_to_adata(
             consensus_sequence_list
         )
 
+    from .h5ad_functions import append_reference_strand_quality_stats
+
+    append_reference_strand_quality_stats(final_adata)
+
     if input_already_demuxed:
         final_adata.obs[DEMUX_TYPE] = ["already"] * final_adata.shape[0]
         final_adata.obs[DEMUX_TYPE] = final_adata.obs[DEMUX_TYPE].astype("category")
@@ -321,15 +325,17 @@ def process_conversion_sites(
     conversion_types = conversions[1:]
 
     # Process the unconverted sequence once
+    # modification dict is keyed by mod type (ie unconverted, 5mC, 6mA)
+    # modification_dict[unconverted] points to a dictionary keyed by unconverted record.id keys.
+    # This then maps to [sequence_length, [], [], unconverted sequence, unconverted complement]
     modification_dict[unconverted] = find_conversion_sites(
         converted_FASTA, unconverted, conversions, deaminase_footprinting
     )
-    # Above points to record_dict[record.id] = [sequence_length, [], [], sequence, complement] with only unconverted record.id keys
 
-    # Get **max sequence length** from unconverted records
+    # Get max sequence length from unconverted records
     max_reference_length = max(values[0] for values in modification_dict[unconverted].values())
 
-    # Add **unconverted records** to `record_FASTA_dict`
+    # Add unconverted records to `record_FASTA_dict`
     for record, values in modification_dict[unconverted].items():
         sequence_length, top_coords, bottom_coords, sequence, complement = values
 
@@ -358,25 +364,34 @@ def process_conversion_sites(
             )
 
     # Process converted records
+    # For each conversion type (ie 5mC, 6mA), add the conversion type as a key to modification_dict.
+    # This points to a dictionary keyed by the unconverted record id key.
+    # This points to [sequence_length, top_strand_coordinates, bottom_strand_coordinates, unconverted sequence, unconverted complement]
     for conversion in conversion_types:
         modification_dict[conversion] = find_conversion_sites(
             converted_FASTA, conversion, conversions, deaminase_footprinting
         )
-        # Above points to record_dict[record.id] = [sequence_length, top_strand_coordinates, bottom_strand_coordinates, sequence, complement] with only unconverted record.id keys
 
+        # Iterate over the unconverted record ids in mod_dict, as well as the
+        # [sequence_length, top_strand_coordinates, bottom_strand_coordinates, unconverted sequence, unconverted complement] for the conversion type
         for record, values in modification_dict[conversion].items():
             sequence_length, top_coords, bottom_coords, sequence, complement = values
 
             if not deaminase_footprinting:
-                chromosome = record.split(f"_{unconverted}_")[0]  # Extract chromosome name
+                # For conversion smf, make the chromosome name the base record name
+                chromosome = record.split(f"_{unconverted}_")[0]
             else:
+                # For deaminase smf, make the chromosome and record name the same
                 chromosome = record
 
-            # Add **both strands** for converted records
+            # Add both strands for converted records
             for strand in ["top", "bottom"]:
+                # Generate converted/unconverted record names that are found in the converted FASTA
                 converted_name = f"{chromosome}_{conversion}_{strand}"
                 unconverted_name = f"{chromosome}_{unconverted}_top"
 
+                # Use the converted FASTA record names as keys to a dict that points to RecordFastaInfo objects.
+                # These objects will contain the unconverted sequence/complement.
                 record_FASTA_dict[converted_name] = RecordFastaInfo(
                     sequence=sequence + "N" * (max_reference_length - sequence_length),
                     complement=complement + "N" * (max_reference_length - sequence_length),
@@ -577,16 +592,19 @@ def process_single_bam(
     """
     adata_list: list[ad.AnnData] = []
 
+    # Iterate over BAM records that passed filtering.
     for record in records_to_analyze:
         sample = bam.stem
         record_info = record_FASTA_dict[record]
         chromosome = record_info.chromosome
         current_length = record_info.sequence_length
+        # Note, mod_type and strand are only correctly load for conversion smf and not deaminase
+        # However, these variables are only used for conversion smf and not deaminase, so works.
         mod_type, strand = record_info.conversion, record_info.strand
         non_converted_sequence = chromosome_FASTA_dict[chromosome][0]
         record_sequence = converted_FASTA_record_seq_map[record][1]
 
-        # Extract Base Identities
+        # Extract Base Identities for forward and reverse mapped reads.
         (
             fwd_bases,
             rev_bases,
@@ -615,13 +633,12 @@ def process_single_bam(
         merged_bin = {}
 
         # Binarize the Base Identities if they exist
+        # Note, mod_type is always unconverted and strand is always top currently for deaminase smf. this works for now.
         if fwd_bases:
             fwd_bin = binarize_converted_base_identities(
                 fwd_bases,
                 strand,
                 mod_type,
-                bam,
-                device,
                 deaminase_footprinting,
                 mismatch_trend_per_read,
             )
@@ -632,8 +649,6 @@ def process_single_bam(
                 rev_bases,
                 strand,
                 mod_type,
-                bam,
-                device,
                 deaminase_footprinting,
                 mismatch_trend_per_read,
             )
@@ -742,10 +757,35 @@ def process_single_bam(
         adata.obs[REFERENCE] = [chromosome] * len(adata)
         adata.obs[STRAND] = [strand] * len(adata)
         adata.obs[DATASET] = [mod_type] * len(adata)
-        adata.obs[REFERENCE_DATASET_STRAND] = [f"{chromosome}_{mod_type}_{strand}"] * len(adata)
-        adata.obs[REFERENCE_STRAND] = [f"{chromosome}_{strand}"] * len(adata)
         adata.obs[READ_MISMATCH_TREND] = adata.obs_names.map(mismatch_trend_series)
 
+        # Currently, deaminase footprinting uses mismatch trend to define the strand.
+        if deaminase_footprinting:
+            is_ct = adata.obs[READ_MISMATCH_TREND] == "C->T"
+            is_ga = adata.obs[READ_MISMATCH_TREND] == "G->A"
+
+            adata.obs.loc[is_ct, STRAND] = "top"
+            adata.obs.loc[is_ga, STRAND] = "bottom"
+        # Currently, conversion footprinting uses strand to define the mismatch trend.
+        else:
+            is_top = adata.obs[STRAND] == "top"
+            is_bottom = adata.obs[STRAND] == "bottom"
+
+            adata.obs.loc[is_top, READ_MISMATCH_TREND] = "C->T"
+            adata.obs.loc[is_bottom, READ_MISMATCH_TREND] = "G->A"
+
+        adata.obs[REFERENCE_DATASET_STRAND] = (
+            adata.obs[REFERENCE].astype(str)
+            + "_"
+            + adata.obs[DATASET].astype(str)
+            + "_"
+            + adata.obs[STRAND].astype(str)
+        )
+
+        adata.obs[REFERENCE_STRAND] = (
+            adata.obs[REFERENCE].astype(str) + "_" + adata.obs[STRAND].astype(str)
+        )
+
         read_mapping_direction = []
         for read_id in adata.obs_names:
             if read_id in fwd_reads:

smftools/informatics/h5ad_functions.py

@@ -10,6 +10,7 @@ import numpy as np
 import pandas as pd
 import scipy.sparse as sp
 
+from smftools.constants import BASE_QUALITY_SCORES, READ_SPAN_MASK, REFERENCE_STRAND
 from smftools.logging_utils import get_logger
 from smftools.optional_imports import require
 
@@ -84,6 +85,88 @@ def add_demux_type_annotation(
     return adata
 
 
+def append_reference_strand_quality_stats(
+    adata,
+    ref_column: str = REFERENCE_STRAND,
+    quality_layer: str = BASE_QUALITY_SCORES,
+    read_span_layer: str = READ_SPAN_MASK,
+    uns_flag: str = "append_reference_strand_quality_stats_performed",
+    force_redo: bool = False,
+    bypass: bool = False,
+) -> None:
+    """Append per-position quality and error rate stats for each reference strand.
+
+    Args:
+        adata: AnnData object to annotate in-place.
+        ref_column: Obs column defining reference strand groups.
+        quality_layer: Layer containing base quality scores.
+        read_span_layer: Optional layer marking covered positions (1=covered, 0=not covered).
+        uns_flag: Flag in ``adata.uns`` indicating prior completion.
+        force_redo: Whether to rerun even if ``uns_flag`` is set.
+        bypass: Whether to skip this step.
+    """
+    if bypass:
+        return
+
+    already = bool(adata.uns.get(uns_flag, False))
+    if already and not force_redo:
+        return
+
+    if ref_column not in adata.obs:
+        logger.debug("Reference column '%s' not found; skipping quality stats.", ref_column)
+        return
+
+    if quality_layer not in adata.layers:
+        logger.debug("Quality layer '%s' not found; skipping quality stats.", quality_layer)
+        return
+
+    ref_values = adata.obs[ref_column]
+    references = (
+        ref_values.cat.categories if hasattr(ref_values, "cat") else pd.Index(pd.unique(ref_values))
+    )
+    n_vars = adata.shape[1]
+    has_span_mask = read_span_layer in adata.layers
+
+    for ref in references:
+        ref_mask = ref_values == ref
+        ref_position_mask = adata.var.get(f"position_in_{ref}")
+        if ref_position_mask is None:
+            ref_position_mask = pd.Series(np.ones(n_vars, dtype=bool), index=adata.var.index)
+        else:
+            ref_position_mask = ref_position_mask.astype(bool)
+
+        mean_quality = np.full(n_vars, np.nan, dtype=float)
+        std_quality = np.full(n_vars, np.nan, dtype=float)
+        mean_error = np.full(n_vars, np.nan, dtype=float)
+        std_error = np.full(n_vars, np.nan, dtype=float)
+
+        if ref_mask.sum() > 0:
+            quality_matrix = np.asarray(adata.layers[quality_layer][ref_mask]).astype(float)
+            quality_matrix[quality_matrix < 0] = np.nan
+            if has_span_mask:
+                coverage_mask = np.asarray(adata.layers[read_span_layer][ref_mask]) > 0
+                quality_matrix = np.where(coverage_mask, quality_matrix, np.nan)
+
+            mean_quality = np.nanmean(quality_matrix, axis=0)
+            std_quality = np.nanstd(quality_matrix, axis=0)
+
+            error_matrix = np.power(10.0, -quality_matrix / 10.0)
+            mean_error = np.nanmean(error_matrix, axis=0)
+            std_error = np.nanstd(error_matrix, axis=0)
+
+        mean_quality = np.where(ref_position_mask.values, mean_quality, np.nan)
+        std_quality = np.where(ref_position_mask.values, std_quality, np.nan)
+        mean_error = np.where(ref_position_mask.values, mean_error, np.nan)
+        std_error = np.where(ref_position_mask.values, std_error, np.nan)
+
+        adata.var[f"{ref}_mean_base_quality"] = pd.Series(mean_quality, index=adata.var.index)
+        adata.var[f"{ref}_std_base_quality"] = pd.Series(std_quality, index=adata.var.index)
+        adata.var[f"{ref}_mean_error_rate"] = pd.Series(mean_error, index=adata.var.index)
+        adata.var[f"{ref}_std_error_rate"] = pd.Series(std_error, index=adata.var.index)
+
+    adata.uns[uns_flag] = True
+
+
 def add_read_tag_annotations(
     adata,
     bam_files: Optional[List[str]] = None,

smftools/informatics/modkit_extract_to_adata.py

@@ -1881,6 +1881,10 @@ def modkit_extract_to_adata(
                     f"{record}_{strand}_{mapping_dir}_consensus_sequence_from_all_samples"
                 ] = consensus_sequence_list
 
+    from .h5ad_functions import append_reference_strand_quality_stats
+
+    append_reference_strand_quality_stats(final_adata)
+
     if input_already_demuxed:
         final_adata.obs[DEMUX_TYPE] = ["already"] * final_adata.shape[0]
         final_adata.obs[DEMUX_TYPE] = final_adata.obs[DEMUX_TYPE].astype("category")

smftools/plotting/__init__.py

@@ -3,18 +3,32 @@ from __future__ import annotations
 from importlib import import_module
 
 _LAZY_ATTRS = {
-    "combined_hmm_length_clustermap": "smftools.plotting.general_plotting",
-    "combined_hmm_raw_clustermap": "smftools.plotting.general_plotting",
-    "combined_raw_clustermap": "smftools.plotting.general_plotting",
-    "plot_rolling_nn_and_layer": "smftools.plotting.general_plotting",
-    "plot_hmm_layers_rolling_by_sample_ref": "smftools.plotting.general_plotting",
-    "plot_nmf_components": "smftools.plotting.general_plotting",
-    "plot_cp_sequence_components": "smftools.plotting.general_plotting",
-    "plot_embedding": "smftools.plotting.general_plotting",
-    "plot_read_span_quality_clustermaps": "smftools.plotting.general_plotting",
-    "plot_pca": "smftools.plotting.general_plotting",
-    "plot_sequence_integer_encoding_clustermaps": "smftools.plotting.general_plotting",
-    "plot_umap": "smftools.plotting.general_plotting",
+    "combined_hmm_length_clustermap": "smftools.plotting.hmm_plotting",
+    "combined_hmm_raw_clustermap": "smftools.plotting.hmm_plotting",
+    "combined_raw_clustermap": "smftools.plotting.spatial_plotting",
+    "plot_delta_hamming_summary": "smftools.plotting.chimeric_plotting",
+    "plot_hamming_span_trio": "smftools.plotting.chimeric_plotting",
+    "plot_rolling_nn_and_layer": "smftools.plotting.chimeric_plotting",
+    "plot_rolling_nn_and_two_layers": "smftools.plotting.chimeric_plotting",
+    "plot_segment_length_histogram": "smftools.plotting.chimeric_plotting",
+    "plot_span_length_distributions": "smftools.plotting.chimeric_plotting",
+    "plot_zero_hamming_pair_counts": "smftools.plotting.chimeric_plotting",
+    "plot_zero_hamming_span_and_layer": "smftools.plotting.chimeric_plotting",
+    "plot_hmm_layers_rolling_by_sample_ref": "smftools.plotting.hmm_plotting",
+    "plot_nmf_components": "smftools.plotting.latent_plotting",
+    "plot_pca_components": "smftools.plotting.latent_plotting",
+    "plot_cp_sequence_components": "smftools.plotting.latent_plotting",
+    "plot_embedding": "smftools.plotting.latent_plotting",
+    "plot_embedding_grid": "smftools.plotting.latent_plotting",
+    "plot_read_span_quality_clustermaps": "smftools.plotting.preprocess_plotting",
+    "plot_mismatch_base_frequency_by_position": "smftools.plotting.variant_plotting",
+    "plot_pca": "smftools.plotting.latent_plotting",
+    "plot_pca_grid": "smftools.plotting.latent_plotting",
+    "plot_pca_explained_variance": "smftools.plotting.latent_plotting",
+    "plot_sequence_integer_encoding_clustermaps": "smftools.plotting.variant_plotting",
+    "plot_variant_segment_clustermaps": "smftools.plotting.variant_plotting",
+    "plot_umap": "smftools.plotting.latent_plotting",
+    "plot_umap_grid": "smftools.plotting.latent_plotting",
     "plot_bar_relative_risk": "smftools.plotting.position_stats",
     "plot_positionwise_matrix": "smftools.plotting.position_stats",
     "plot_positionwise_matrix_grid": "smftools.plotting.position_stats",