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

smftools/informatics/sequence_encoding.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from typing import Iterable, Mapping
+
+import numpy as np
+
+from smftools.constants import (
+    MODKIT_EXTRACT_SEQUENCE_BASE_TO_INT,
+    MODKIT_EXTRACT_SEQUENCE_INT_TO_BASE,
+)
+
+
+def encode_sequence_to_int(
+    sequence: str | Iterable[str],
+    *,
+    base_to_int: Mapping[str, int] = MODKIT_EXTRACT_SEQUENCE_BASE_TO_INT,
+    unknown_base: str = "N",
+) -> np.ndarray:
+    """Encode a base sequence into integer values using constant mappings.
+
+    Args:
+        sequence: Sequence string or iterable of base characters.
+        base_to_int: Mapping of base characters to integer encodings.
+        unknown_base: Base to use when a character is not in the encoding map.
+
+    Returns:
+        np.ndarray: Integer-encoded sequence array.
+
+    Raises:
+        ValueError: If an unknown base is encountered and ``unknown_base`` is not mapped.
+    """
+    if unknown_base not in base_to_int:
+        raise ValueError(f"Unknown base '{unknown_base}' not present in encoding map.")
+
+    if isinstance(sequence, str):
+        sequence_iter = sequence
+    else:
+        sequence_iter = list(sequence)
+
+    fallback = base_to_int[unknown_base]
+    encoded = np.fromiter(
+        (base_to_int.get(base, fallback) for base in sequence_iter),
+        dtype=np.int16,
+        count=len(sequence_iter),
+    )
+    return encoded
+
+
+def decode_int_sequence(
+    encoded_sequence: Iterable[int] | np.ndarray,
+    *,
+    int_to_base: Mapping[int, str] = MODKIT_EXTRACT_SEQUENCE_INT_TO_BASE,
+    unknown_base: str = "N",
+) -> list[str]:
+    """Decode integer-encoded bases into characters using constant mappings.
+
+    Args:
+        encoded_sequence: Iterable of integer-encoded bases.
+        int_to_base: Mapping of integer encodings to base characters.
+        unknown_base: Base to use when an integer is not in the decoding map.
+
+    Returns:
+        list[str]: Decoded base characters.
+
+    Raises:
+        ValueError: If ``unknown_base`` is not available for fallback.
+    """
+    if unknown_base not in int_to_base.values():
+        raise ValueError(f"Unknown base '{unknown_base}' not present in decoding map.")
+
+    fallback = unknown_base
+    return [int_to_base.get(int(value), fallback) for value in encoded_sequence]

smftools/logging_utils.py

@@ -15,18 +15,37 @@ def setup_logging(
     fmt: str = DEFAULT_LOG_FORMAT,
     datefmt: str = DEFAULT_DATE_FORMAT,
     log_file: Optional[Union[str, Path]] = None,
+    reconfigure: bool = False,
 ) -> None:
     """
     Configure logging for smftools.
 
     Should be called once by the CLI entrypoint.
-    Safe to call multiple times.
+    Safe to call multiple times, with optional reconfiguration.
     """
     logger = logging.getLogger("smftools")
 
-    if logger.handlers:
+    if logger.handlers and not reconfigure:
+        if log_file is not None:
+            log_path = Path(log_file)
+            has_file_handler = any(
+                isinstance(handler, logging.FileHandler)
+                and Path(getattr(handler, "baseFilename", "")) == log_path
+                for handler in logger.handlers
+            )
+            if not has_file_handler:
+                log_path.parent.mkdir(parents=True, exist_ok=True)
+                file_handler = logging.FileHandler(log_path)
+                file_handler.setFormatter(logging.Formatter(fmt=fmt, datefmt=datefmt))
+                logger.addHandler(file_handler)
+        logger.setLevel(level)
         return
 
+    if logger.handlers and reconfigure:
+        for handler in list(logger.handlers):
+            logger.removeHandler(handler)
+            handler.close()
+
     formatter = logging.Formatter(fmt=fmt, datefmt=datefmt)
 
     # Console handler (stderr)

smftools/metadata.py

@@ -12,7 +12,7 @@ from typing import Any, Iterable, Optional
 from ._version import __version__
 from .schema import SCHEMA_REGISTRY_RESOURCE, SCHEMA_REGISTRY_VERSION
 
-_DEPENDENCIES = ("anndata", "numpy", "pandas", "scanpy", "torch")
+_DEPENDENCIES = ("anndata", "numpy", "pandas", "umap-learn", "pynndescent", "torch")
 
 
 def _iso_timestamp() -> str:

smftools/plotting/__init__.py

@@ -3,9 +3,32 @@ from __future__ import annotations
 from importlib import import_module
 
 _LAZY_ATTRS = {
-    "combined_hmm_raw_clustermap": "smftools.plotting.general_plotting",
-    "combined_raw_clustermap": "smftools.plotting.general_plotting",
-    "plot_hmm_layers_rolling_by_sample_ref": "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",

smftools/plotting/autocorrelation_plotting.py

@@ -5,8 +5,11 @@ from typing import Optional
 import numpy as np
 import pandas as pd
 
+from smftools.logging_utils import get_logger
 from smftools.optional_imports import require
 
+logger = get_logger(__name__)
+
 
 def plot_spatial_autocorr_grid(
     adata,
@@ -39,6 +42,12 @@ def plot_spatial_autocorr_grid(
     import os
     import warnings
 
+    logger.info(
+        "Plotting spatial autocorrelation grid to %s for site_types=%s.",
+        out_dir,
+        site_types,
+    )
+
     plt = require("matplotlib.pyplot", extra="plotting", purpose="autocorrelation plots")
 
     # Try importing analyzer (used only as fallback)
@@ -98,7 +107,7 @@ def plot_spatial_autocorr_grid(
     if sample_col not in adata.obs:
         raise KeyError(f"sample_col '{sample_col}' not present in adata.obs")
     samples = adata.obs[sample_col]
-    if not pd.api.types.is_categorical_dtype(samples):
+    if not isinstance(samples.dtype, pd.CategoricalDtype):
         samples = samples.astype("category")
     sample_levels = list(samples.cat.categories)
 
@@ -107,7 +116,7 @@ def plot_spatial_autocorr_grid(
         raise KeyError(f"reference_col '{reference_col}' not present in adata.obs")
     if references is None:
         refs_series = adata.obs[reference_col]
-        if not pd.api.types.is_categorical_dtype(refs_series):
+        if not isinstance(refs_series.dtype, pd.CategoricalDtype):
             refs_series = refs_series.astype("category")
         references = list(refs_series.cat.categories)
     references = list(references)
@@ -510,10 +519,10 @@ def plot_spatial_autocorr_grid(
     try:
         combined_df.to_csv(combined_out, index=False)
     except Exception as e:
-        import warnings
-
         warnings.warn(f"Failed to write combined CSV {combined_out}: {e}")
+        logger.warning("Failed to write combined CSV %s: %s", combined_out, e)
 
+    logger.info("Saved %s autocorrelation grid pages to %s.", len(saved_pages), out_dir)
     return saved_pages
 
 
@@ -522,6 +531,7 @@ def plot_rolling_metrics(df, out_png=None, title=None, figsize=(10, 3.5), dpi=16
     Plot NRL and SNR vs window center from the dataframe returned by rolling_autocorr_metrics.
     If out_png is None, returns the matplotlib Figure object; otherwise saves PNG and returns path.
     """
+    logger.info("Plotting rolling metrics%s.", f" -> {out_png}" if out_png else "")
     plt = require("matplotlib.pyplot", extra="plotting", purpose="autocorrelation plots")
 
     # sort by center
@@ -546,6 +556,7 @@ def plot_rolling_metrics(df, out_png=None, title=None, figsize=(10, 3.5), dpi=16
 
     if out_png:
         fig.savefig(out_png, bbox_inches="tight")
+        logger.info("Saved rolling metrics plot to %s.", out_png)
         if not show:
             matplotlib = require("matplotlib", extra="plotting", purpose="autocorrelation plots")
 
@@ -604,6 +615,12 @@ def plot_rolling_grid(
     """
     import os
 
+    logger.info(
+        "Plotting rolling metric grids for site=%s to %s (metrics=%s).",
+        site,
+        out_dir,
+        metrics,
+    )
     plt = require("matplotlib.pyplot", extra="plotting", purpose="autocorrelation plots")
 
     if per_metric_ylim is None:
@@ -708,6 +725,7 @@ def plot_rolling_grid(
             fig.savefig(out_png, bbox_inches="tight")
             plt.close(fig)
             saved_pages.append(out_png)
+            logger.info("Saved rolling grid page to %s.", out_png)
 
         pages_by_metric[metric] = saved_pages