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

smftools/plotting/hmm_plotting.py

@@ -1,13 +1,15 @@
 from __future__ import annotations
 
 import math
-from typing import Optional, Tuple, Union
+from typing import Optional, Sequence, Tuple, Union
 
 import numpy as np
+import pandas as pd
 
 from smftools.optional_imports import require
 
 plt = require("matplotlib.pyplot", extra="plotting", purpose="HMM plots")
+mpl_colors = require("matplotlib.colors", extra="plotting", purpose="HMM plots")
 pdf_backend = require(
     "matplotlib.backends.backend_pdf",
     extra="plotting",
@@ -32,6 +34,9 @@ def plot_hmm_size_contours(
     dpi: int = 150,
     vmin: Optional[float] = None,
     vmax: Optional[float] = None,
+    feature_ranges: Optional[Sequence[Tuple[int, int, str]]] = None,
+    zero_color: str = "#f5f1e8",
+    nan_color: str = "#E6E6E6",
     # ---------------- smoothing params ----------------
     smoothing_sigma: Optional[Union[float, Tuple[float, float]]] = None,
     normalize_after_smoothing: bool = True,
@@ -40,6 +45,9 @@ def plot_hmm_size_contours(
     """
     Create contour/pcolormesh plots of P(length | position) using a length-encoded HMM layer.
     Optional Gaussian smoothing applied to the 2D probability grid before plotting.
+    When feature_ranges is provided, each length row is assigned a base color based
+    on the matching (min_len, max_len) range and the probability value modulates
+    the color intensity.
 
     smoothing_sigma: None or 0 -> no smoothing.
         float -> same sigma applied to (length_axis, position_axis)
@@ -48,6 +56,51 @@ def plot_hmm_size_contours(
 
     Other args are the same as prior function.
     """
+    feature_ranges = tuple(feature_ranges or ())
+
+    def _resolve_length_color(length: int, fallback: str) -> Tuple[float, float, float, float]:
+        for min_len, max_len, color in feature_ranges:
+            if min_len <= length <= max_len:
+                return mpl_colors.to_rgba(color)
+        return mpl_colors.to_rgba(fallback)
+
+    def _build_length_facecolors(
+        Z_values: np.ndarray,
+        lengths: np.ndarray,
+        fallback_color: str,
+        *,
+        vmin_local: Optional[float],
+        vmax_local: Optional[float],
+    ) -> np.ndarray:
+        zero_rgba = np.array(mpl_colors.to_rgba(zero_color))
+        nan_rgba = np.array(mpl_colors.to_rgba(nan_color))
+        base_colors = np.array(
+            [_resolve_length_color(int(length), fallback_color) for length in lengths],
+            dtype=float,
+        )
+        base_colors[:, 3] = 1.0
+
+        scale = np.array(Z_values, copy=True, dtype=float)
+        finite_mask = np.isfinite(scale)
+        if not finite_mask.any():
+            facecolors = np.zeros(scale.shape + (4,), dtype=float)
+            facecolors[:] = nan_rgba
+            return facecolors.reshape(-1, 4)
+
+        vmin_use = np.nanmin(scale) if vmin_local is None else vmin_local
+        vmax_use = np.nanmax(scale) if vmax_local is None else vmax_local
+        denom = vmax_use - vmin_use
+        if denom <= 0:
+            norm = np.zeros_like(scale)
+        else:
+            norm = (scale - vmin_use) / denom
+        norm = np.clip(norm, 0, 1)
+
+        row_colors = base_colors[:, None, :]
+        facecolors = zero_rgba + norm[..., None] * (row_colors - zero_rgba)
+        facecolors[..., 3] = 1.0
+        facecolors[~finite_mask] = nan_rgba
+        return facecolors.reshape(-1, 4)
 
     # --- helper: gaussian smoothing (scipy fallback -> numpy separable conv) ---
     def _gaussian_1d_kernel(sigma: float, eps: float = 1e-12):
@@ -150,7 +203,8 @@ def plot_hmm_size_contours(
     figs = []
 
     # decide global max length to allocate y axis (cap to avoid huge memory)
-    observed_max_len = int(np.max(full_layer)) if full_layer.size > 0 else 0
+    finite_lengths = full_layer[np.isfinite(full_layer) & (full_layer > 0)]
+    observed_max_len = int(np.nanmax(finite_lengths)) if finite_lengths.size > 0 else 0
     if max_length_cap is None:
         max_len = observed_max_len
     else:
@@ -205,10 +259,15 @@ def plot_hmm_size_contours(
                     ax.text(0.5, 0.5, "no data", ha="center", va="center")
                     ax.set_title(f"{sample} / {ref}")
                     continue
+                valid_lengths = sub[np.isfinite(sub) & (sub > 0)]
+                if valid_lengths.size == 0:
+                    ax.text(0.5, 0.5, "no data", ha="center", va="center")
+                    ax.set_title(f"{sample} / {ref}")
+                    continue
 
                 # compute counts per length per position
                 n_positions = sub.shape[1]
-                max_len_local = int(sub.max()) if sub.size > 0 else 0
+                max_len_local = int(valid_lengths.max()) if valid_lengths.size > 0 else 0
                 max_len_here = min(max_len, max_len_local)
 
                 lengths_range = np.arange(1, max_len_here + 1, dtype=int)
@@ -219,7 +278,7 @@ def plot_hmm_size_contours(
                 # fill Z by efficient bincount across columns
                 for j in range(n_positions):
                     col_vals = sub[:, j]
-                    pos_vals = col_vals[col_vals > 0].astype(int)
+                    pos_vals = col_vals[np.isfinite(col_vals) & (col_vals > 0)].astype(int)
                     if pos_vals.size == 0:
                         continue
                     clipped = np.clip(pos_vals, 1, max_len_here)
@@ -258,9 +317,28 @@ def plot_hmm_size_contours(
                 dy = 1.0
                 y_edges = np.concatenate([y - 0.5, [y[-1] + 0.5]])
 
-                pcm = ax.pcolormesh(
-                    x_edges, y_edges, Z_plot, cmap=cmap, shading="auto", vmin=vmin, vmax=vmax
-                )
+                if feature_ranges:
+                    fallback_color = mpl_colors.to_rgba(plt.get_cmap(cmap)(1.0))
+                    facecolors = _build_length_facecolors(
+                        Z_plot,
+                        lengths_range,
+                        fallback_color,
+                        vmin_local=vmin,
+                        vmax_local=vmax,
+                    )
+                    pcm = ax.pcolormesh(
+                        x_edges,
+                        y_edges,
+                        Z_plot,
+                        shading="auto",
+                        vmin=vmin,
+                        vmax=vmax,
+                        facecolors=facecolors,
+                    )
+                else:
+                    pcm = ax.pcolormesh(
+                        x_edges, y_edges, Z_plot, cmap=cmap, shading="auto", vmin=vmin, vmax=vmax
+                    )
                 ax.set_title(f"{sample} / {ref}")
                 ax.set_ylabel("length")
                 if i_row == rows_on_page - 1:

smftools/preprocessing/__init__.py

@@ -5,6 +5,7 @@ from importlib import import_module
 _LAZY_ATTRS = {
     "append_base_context": "smftools.preprocessing.append_base_context",
     "append_binary_layer_by_base_context": "smftools.preprocessing.append_binary_layer_by_base_context",
+    "append_mismatch_frequency_sites": "smftools.preprocessing.append_mismatch_frequency_sites",
     "binarize_adata": "smftools.preprocessing.binarize",
     "binarize_on_Youden": "smftools.preprocessing.binarize_on_Youden",
     "calculate_complexity_II": "smftools.preprocessing.calculate_complexity_II",

smftools/preprocessing/append_base_context.py

@@ -133,23 +133,23 @@ def append_base_context(
                 adata.var[f"{ref}_{site_type}_valid_coverage"] = (
                     (adata.var[f"{ref}_{site_type}"]) & (adata.var[f"position_in_{ref}"])
                 )
-                if native:
-                    adata.obsm[f"{ref}_{site_type}_valid_coverage"] = adata[
-                        :, adata.var[f"{ref}_{site_type}_valid_coverage"]
-                    ].layers["binarized_methylation"]
-                else:
-                    adata.obsm[f"{ref}_{site_type}_valid_coverage"] = adata[
-                        :, adata.var[f"{ref}_{site_type}_valid_coverage"]
-                    ].X
-            else:
-                pass
-
-            if native:
-                adata.obsm[f"{ref}_{site_type}"] = adata[:, adata.var[f"{ref}_{site_type}"]].layers[
-                    "binarized_methylation"
-                ]
-            else:
-                adata.obsm[f"{ref}_{site_type}"] = adata[:, adata.var[f"{ref}_{site_type}"]].X
+            #     if native:
+            #         adata.obsm[f"{ref}_{site_type}_valid_coverage"] = adata[
+            #             :, adata.var[f"{ref}_{site_type}_valid_coverage"]
+            #         ].layers["binarized_methylation"]
+            #     else:
+            #         adata.obsm[f"{ref}_{site_type}_valid_coverage"] = adata[
+            #             :, adata.var[f"{ref}_{site_type}_valid_coverage"]
+            #         ].X
+            # else:
+            #     pass
+
+            # if native:
+            #     adata.obsm[f"{ref}_{site_type}"] = adata[:, adata.var[f"{ref}_{site_type}"]].layers[
+            #         "binarized_methylation"
+            #     ]
+            # else:
+            #     adata.obsm[f"{ref}_{site_type}"] = adata[:, adata.var[f"{ref}_{site_type}"]].X
 
     # mark as done
     adata.uns[uns_flag] = True

smftools/preprocessing/append_mismatch_frequency_sites.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Iterable, Sequence
+
+import numpy as np
+import pandas as pd
+
+from smftools.constants import MODKIT_EXTRACT_SEQUENCE_BASE_TO_INT
+from smftools.logging_utils import get_logger
+
+if TYPE_CHECKING:
+    import anndata as ad
+
+logger = get_logger(__name__)
+
+
+def append_mismatch_frequency_sites(
+    adata: "ad.AnnData",
+    ref_column: str = "Reference_strand",
+    mismatch_layer: str = "mismatch_integer_encoding",
+    read_span_layer: str = "read_span_mask",
+    mismatch_frequency_range: Sequence[float] | None = (0.05, 0.95),
+    uns_flag: str = "append_mismatch_frequency_sites_performed",
+    force_redo: bool = False,
+    bypass: bool = False,
+) -> None:
+    """Append mismatch frequency metadata and variable-site flags per reference.
+
+    Args:
+        adata: AnnData object.
+        ref_column: Obs column defining reference categories.
+        mismatch_layer: Layer containing mismatch integer encodings.
+        read_span_layer: Layer containing read span masks (1=covered, 0=not covered).
+        mismatch_frequency_range: Lower/upper bounds (inclusive) for variable site flagging.
+        uns_flag: Flag in ``adata.uns`` indicating prior completion.
+        force_redo: Whether to rerun even if ``uns_flag`` is set.
+        bypass: Whether to skip running this step.
+    """
+    if bypass:
+        return
+
+    already = bool(adata.uns.get(uns_flag, False))
+    if already and not force_redo:
+        return
+
+    if mismatch_layer not in adata.layers:
+        logger.debug(
+            "Mismatch layer '%s' not found; skipping mismatch frequency step.", mismatch_layer
+        )
+        return
+
+    mismatch_map = adata.uns.get("mismatch_integer_encoding_map", {})
+    if not mismatch_map:
+        logger.debug("Mismatch encoding map not found; skipping mismatch frequency step.")
+        return
+
+    n_value = mismatch_map.get("N", MODKIT_EXTRACT_SEQUENCE_BASE_TO_INT["N"])
+    pad_value = mismatch_map.get("PAD", MODKIT_EXTRACT_SEQUENCE_BASE_TO_INT["PAD"])
+
+    base_int_to_label = {
+        int(value): str(base)
+        for base, value in mismatch_map.items()
+        if base not in {"N", "PAD"} and isinstance(value, (int, np.integer))
+    }
+    if not base_int_to_label:
+        logger.debug("Mismatch encoding map missing base labels; skipping mismatch frequency step.")
+        return
+
+    has_span_mask = read_span_layer in adata.layers
+    if not has_span_mask:
+        logger.debug(
+            "Read span mask '%s' not found; mismatch frequencies will be computed over all reads.",
+            read_span_layer,
+        )
+
+    references = adata.obs[ref_column].cat.categories
+    n_vars = adata.shape[1]
+
+    if mismatch_frequency_range is None:
+        mismatch_frequency_range = (0.0, 1.0)
+
+    lower_bound, upper_bound = mismatch_frequency_range
+
+    for ref in references:
+        ref_mask = adata.obs[ref_column] == 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)
+
+        frequency_values = np.full(n_vars, np.nan, dtype=float)
+        variable_flags = np.zeros(n_vars, dtype=bool)
+        mismatch_base_frequencies: list[list[tuple[str, float]]] = [[] for _ in range(n_vars)]
+
+        if ref_mask.sum() == 0:
+            adata.var[f"{ref}_mismatch_frequency"] = pd.Series(
+                frequency_values, index=adata.var.index
+            )
+            adata.var[f"{ref}_variable_sequence_site"] = pd.Series(
+                variable_flags, index=adata.var.index
+            )
+            adata.var[f"{ref}_mismatch_base_frequencies"] = pd.Series(
+                mismatch_base_frequencies, index=adata.var.index
+            )
+            continue
+
+        mismatch_matrix = np.asarray(adata.layers[mismatch_layer][ref_mask])
+        if has_span_mask:
+            span_matrix = np.asarray(adata.layers[read_span_layer][ref_mask])
+            coverage_mask = span_matrix > 0
+            coverage_counts = coverage_mask.sum(axis=0).astype(float)
+        else:
+            coverage_mask = np.ones_like(mismatch_matrix, dtype=bool)
+            coverage_counts = np.full(n_vars, ref_mask.sum(), dtype=float)
+
+        mismatch_mask = (~np.isin(mismatch_matrix, [n_value, pad_value])) & coverage_mask
+        mismatch_counts = mismatch_mask.sum(axis=0)
+
+        frequency_values = np.divide(
+            mismatch_counts,
+            coverage_counts,
+            out=np.full(n_vars, np.nan, dtype=float),
+            where=coverage_counts > 0,
+        )
+        frequency_values = np.where(ref_position_mask.values, frequency_values, np.nan)
+
+        variable_flags = (
+            (frequency_values >= lower_bound)
+            & (frequency_values <= upper_bound)
+            & ref_position_mask.values
+        )
+
+        base_counts_by_int: dict[int, np.ndarray] = {}
+        for base_int in base_int_to_label:
+            base_counts_by_int[base_int] = ((mismatch_matrix == base_int) & coverage_mask).sum(
+                axis=0
+            )
+
+        for idx in range(n_vars):
+            if not ref_position_mask.iloc[idx] or coverage_counts[idx] == 0:
+                continue
+            base_freqs: list[tuple[str, float]] = []
+            for base_int, base_label in base_int_to_label.items():
+                count = base_counts_by_int[base_int][idx]
+                if count > 0:
+                    base_freqs.append((base_label, float(count / coverage_counts[idx])))
+            mismatch_base_frequencies[idx] = base_freqs
+
+        adata.var[f"{ref}_mismatch_frequency"] = pd.Series(frequency_values, index=adata.var.index)
+        adata.var[f"{ref}_variable_sequence_site"] = pd.Series(
+            variable_flags, index=adata.var.index
+        )
+        adata.var[f"{ref}_mismatch_base_frequencies"] = pd.Series(
+            mismatch_base_frequencies, index=adata.var.index
+        )
+
+    adata.uns[uns_flag] = True

smftools/preprocessing/calculate_consensus.py

@@ -53,4 +53,4 @@ def calculate_consensus(
     else:
         adata.var[f"{reference}_consensus_across_samples"] = consensus_sequence_list
 
-    adata.uns[f"{reference}_consensus_sequence"] = consensus_sequence_list
+    adata.uns[f"{reference}_consensus_sequence"] = str(consensus_sequence_list)

smftools/preprocessing/calculate_read_modification_stats.py

@@ -20,6 +20,7 @@ def calculate_read_modification_stats(
     force_redo: bool = False,
     valid_sites_only: bool = False,
     valid_site_suffix: str = "_valid_coverage",
+    smf_modality: str = "conversion",
 ) -> None:
     """Add methylation/deamination statistics for each read.
 
@@ -80,8 +81,12 @@ def calculate_read_modification_stats(
     for ref in references:
         ref_subset = adata[adata.obs[reference_column] == ref]
         for site_type in site_types:
+            site_subset = ref_subset[:, ref_subset.var[f"{ref}_{site_type}{valid_site_suffix}"]]
             logger.info("Iterating over %s_%s", ref, site_type)
-            observation_matrix = ref_subset.obsm[f"{ref}_{site_type}{valid_site_suffix}"]
+            if smf_modality == "native":
+                observation_matrix = site_subset.layers["binarized_methylation"]
+            else:
+                observation_matrix = site_subset.X
             total_positions_in_read = np.nansum(~np.isnan(observation_matrix), axis=1)
             total_positions_in_reference = observation_matrix.shape[1]
             fraction_valid_positions_in_read_vs_ref = (

smftools/readwrite.py

@@ -431,6 +431,8 @@ def safe_write_h5ad(adata, path, compression="gzip", backup=False, backup_dir=No
         "layers_skipped": [],
         "obsm_converted": [],
         "obsm_skipped": [],
+        "varm_converted": [],
+        "varm_skipped": [],
         "X_replaced_or_converted": None,
         "errors": [],
     }
@@ -605,10 +607,16 @@ def safe_write_h5ad(adata, path, compression="gzip", backup=False, backup_dir=No
 
     def _sanitize_layers_obsm(src_dict, which: str):
         """
-        Ensure arrays in layers/obsm are numeric and non-object dtype.
+        Ensure arrays in layers/obsm/varm are numeric and non-object dtype.
         Returns a cleaned dict suitable to pass into AnnData(...)
         If an entry is not convertible, it is backed up & skipped.
         """
+        report_map = {
+            "layers": ("layers_converted", "layers_skipped"),
+            "obsm": ("obsm_converted", "obsm_skipped"),
+            "varm": ("varm_converted", "varm_skipped"),
+        }
+        converted_key, skipped_key = report_map[which]
         cleaned = {}
         for k, v in src_dict.items():
             try:
@@ -618,9 +626,7 @@ def safe_write_h5ad(adata, path, compression="gzip", backup=False, backup_dir=No
                         arr_f = arr.astype(float)
                         cleaned[k] = arr_f
                         report_key = f"{which}.{k}"
-                        report["layers_converted"].append(
-                            report_key
-                        ) if which == "layers" else report["obsm_converted"].append(report_key)
+                        report[converted_key].append(report_key)
                         if verbose:
                             print(f"  {which}.{k} object array coerced to float.")
                     except Exception:
@@ -628,18 +634,13 @@ def safe_write_h5ad(adata, path, compression="gzip", backup=False, backup_dir=No
                             arr_i = arr.astype(int)
                             cleaned[k] = arr_i
                             report_key = f"{which}.{k}"
-                            report["layers_converted"].append(
-                                report_key
-                            ) if which == "layers" else report["obsm_converted"].append(report_key)
+                            report[converted_key].append(report_key)
                             if verbose:
                                 print(f"  {which}.{k} object array coerced to int.")
                         except Exception:
                             if backup:
                                 _backup(v, f"{which}_{k}_backup")
-                            if which == "layers":
-                                report["layers_skipped"].append(k)
-                            else:
-                                report["obsm_skipped"].append(k)
+                            report[skipped_key].append(k)
                             if verbose:
                                 print(
                                     f"  SKIPPING {which}.{k} (object dtype not numeric). Backed up: {backup}"
@@ -650,10 +651,7 @@ def safe_write_h5ad(adata, path, compression="gzip", backup=False, backup_dir=No
             except Exception as e:
                 if backup:
                     _backup(v, f"{which}_{k}_backup")
-                if which == "layers":
-                    report["layers_skipped"].append(k)
-                else:
-                    report["obsm_skipped"].append(k)
+                report[skipped_key].append(k)
                 msg = f"  SKIPPING {which}.{k} due to conversion error: {e}"
                 report["errors"].append(msg)
                 if verbose:
@@ -693,6 +691,7 @@ def safe_write_h5ad(adata, path, compression="gzip", backup=False, backup_dir=No
     # ---------- sanitize layers and obsm ----------
     layers_src = getattr(adata, "layers", {})
     obsm_src = getattr(adata, "obsm", {})
+    varm_src = getattr(adata, "varm", {})
 
     try:
         layers_clean = _sanitize_layers_obsm(layers_src, "layers")
@@ -712,6 +711,15 @@ def safe_write_h5ad(adata, path, compression="gzip", backup=False, backup_dir=No
             print(msg)
         obsm_clean = {}
 
+    try:
+        varm_clean = _sanitize_layers_obsm(varm_src, "varm")
+    except Exception as e:
+        msg = f"Failed to sanitize varm: {e}"
+        report["errors"].append(msg)
+        if verbose:
+            print(msg)
+        varm_clean = {}
+
     # ---------- handle X ----------
     X_to_use = adata.X
     try:
@@ -747,7 +755,7 @@ def safe_write_h5ad(adata, path, compression="gzip", backup=False, backup_dir=No
             layers=layers_clean,
             uns=uns_clean,
             obsm=obsm_clean,
-            varm=getattr(adata, "varm", None),
+            varm=varm_clean,
         )
 
         # preserve names (as strings)
@@ -872,6 +880,16 @@ def safe_write_h5ad(adata, path, compression="gzip", backup=False, backup_dir=No
                 }
             )
 
+        # varm
+        for k, v in adata_copy.varm.items():
+            meta_rows.append(
+                {
+                    "kind": "varm",
+                    "name": k,
+                    "dtype": str(np.asarray(v).dtype),
+                }
+            )
+
         # uns
         for k, v in adata_copy.uns.items():
             meta_rows.append(
@@ -977,6 +995,7 @@ def safe_read_h5ad(
         "parsed_uns_json_keys": [],
         "restored_layers": [],
         "restored_obsm": [],
+        "restored_varm": [],
         "recategorized_obs": [],
         "recategorized_var": [],
         "missing_backups": [],
@@ -1215,7 +1234,7 @@ def safe_read_h5ad(
                 print(f"[safe_read_h5ad] restored adata.uns['{key}'] from {full}")
 
     # 5) Restore layers and obsm from backups if present
-    # expected backup names: layers_<name>_backup.pkl, obsm_<name>_backup.pkl
+    # expected backup names: layers_<name>_backup.pkl, obsm_<name>_backup.pkl, varm_<name>_backup.pkl
     if os.path.isdir(backup_dir):
         for fname in os.listdir(backup_dir):
             if fname.startswith("layers_") and fname.endswith("_backup.pkl"):
@@ -1248,6 +1267,21 @@ def safe_read_h5ad(
                             f"Failed to restore obsm['{obsm_name}'] from {full}: {e}"
                         )
 
+            if fname.startswith("varm_") and fname.endswith("_backup.pkl"):
+                varm_name = fname[len("varm_") : -len("_backup.pkl")]
+                full = os.path.join(backup_dir, fname)
+                val = _load_pickle_if_exists(full)
+                if val is not None:
+                    try:
+                        adata.varm[varm_name] = np.asarray(val)
+                        report["restored_varm"].append((varm_name, full))
+                        if verbose:
+                            print(f"[safe_read_h5ad] restored varm['{varm_name}'] from {full}")
+                    except Exception as e:
+                        report["errors"].append(
+                            f"Failed to restore varm['{varm_name}'] from {full}: {e}"
+                        )
+
     # 6) If restore_backups True but some expected backups missing, note them
     if restore_backups and os.path.isdir(backup_dir):
         # detect common expected names from obs/var/uns/layers in adata
@@ -1297,6 +1331,8 @@ def safe_read_h5ad(
             print("Restored layers:", report["restored_layers"])
         if report["restored_obsm"]:
             print("Restored obsm:", report["restored_obsm"])
+        if report["restored_varm"]:
+            print("Restored varm:", report["restored_varm"])
         if report["recategorized_obs"] or report["recategorized_var"]:
             print(
                 "Recategorized columns (obs/var):",

smftools/schema/anndata_schema_v1.yaml

@@ -60,6 +60,20 @@ stages:
         notes: "Mapping quality score."
         requires: []
         optional_inputs: []
+      reference_start:
+        dtype: "float"
+        created_by: "smftools.informatics.h5ad_functions.add_read_length_and_mapping_qc"
+        modified_by: []
+        notes: "0-based reference start position for the alignment."
+        requires: []
+        optional_inputs: []
+      reference_end:
+        dtype: "float"
+        created_by: "smftools.informatics.h5ad_functions.add_read_length_and_mapping_qc"
+        modified_by: []
+        notes: "0-based reference end position (exclusive) for the alignment."
+        requires: []
+        optional_inputs: []
       read_length_to_reference_length_ratio:
         dtype: "float"
         created_by: "smftools.informatics.h5ad_functions.add_read_length_and_mapping_qc"
@@ -179,7 +193,7 @@ stages:
     obs:
       leiden:
         dtype: "category"
-        created_by: "smftools.tools.calculate_umap"
+        created_by: "smftools.tools.calculate_leiden"
         modified_by: []
         notes: "Leiden cluster assignments."
         requires: [["obsm.X_umap"]]

smftools/tools/__init__.py

@@ -3,6 +3,9 @@ from __future__ import annotations
 from importlib import import_module
 
 _LAZY_ATTRS = {
+    "calculate_leiden": "smftools.tools.calculate_leiden",
+    "calculate_nmf": "smftools.tools.calculate_nmf",
+    "calculate_sequence_cp_decomposition": "smftools.tools.tensor_factorization",
     "calculate_umap": "smftools.tools.calculate_umap",
     "cluster_adata_on_methylation": "smftools.tools.cluster_adata_on_methylation",
     "combine_layers": "smftools.tools.general_tools",
@@ -11,6 +14,7 @@ _LAZY_ATTRS = {
     "calculate_relative_risk_on_activity": "smftools.tools.position_stats",
     "compute_positionwise_statistics": "smftools.tools.position_stats",
     "calculate_row_entropy": "smftools.tools.read_stats",
+    "rolling_window_nn_distance": "smftools.tools.rolling_nn_distance",
     "subset_adata": "smftools.tools.subset_adata",
 }
 

smftools/tools/calculate_leiden.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+import pandas as pd
+
+from smftools.logging_utils import get_logger
+from smftools.optional_imports import require
+
+if TYPE_CHECKING:
+    import anndata as ad
+
+logger = get_logger(__name__)
+
+
+def calculate_leiden(
+    adata: "ad.AnnData",
+    *,
+    resolution: float = 0.1,
+    key_added: str = "leiden",
+    connectivities_key: str = "connectivities",
+) -> "ad.AnnData":
+    """Compute Leiden clusters from a connectivity graph.
+
+    Args:
+        adata: AnnData object with ``obsp[connectivities_key]`` set.
+        resolution: Resolution parameter for Leiden clustering.
+        key_added: Column name to store cluster assignments in ``adata.obs``.
+        connectivities_key: Key in ``adata.obsp`` containing a sparse adjacency matrix.
+
+    Returns:
+        Updated AnnData object with Leiden labels in ``adata.obs``.
+    """
+    if connectivities_key not in adata.obsp:
+        raise KeyError(f"Missing connectivities '{connectivities_key}' in adata.obsp.")
+
+    igraph = require("igraph", extra="cluster", purpose="Leiden clustering")
+    leidenalg = require("leidenalg", extra="cluster", purpose="Leiden clustering")
+
+    connectivities = adata.obsp[connectivities_key]
+    coo = connectivities.tocoo()
+    edges = list(zip(coo.row.tolist(), coo.col.tolist()))
+    graph = igraph.Graph(n=connectivities.shape[0], edges=edges, directed=False)
+    graph.es["weight"] = coo.data.tolist()
+
+    partition = leidenalg.find_partition(
+        graph,
+        leidenalg.RBConfigurationVertexPartition,
+        weights=graph.es["weight"],
+        resolution_parameter=resolution,
+    )
+
+    labels = np.array(partition.membership, dtype=str)
+    adata.obs[key_added] = pd.Categorical(labels)
+    logger.info("Stored Leiden clusters in adata.obs['%s'].", key_added)
+    return adata