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

smftools/informatics/modkit_functions.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import subprocess
 
 from smftools.logging_utils import get_logger

smftools/informatics/ohe.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import concurrent.futures
 import os
 

smftools/informatics/pod5_functions.py

@@ -5,9 +5,8 @@ import subprocess
 from pathlib import Path
 from typing import Iterable
 
-import pod5 as p5
-
 from smftools.logging_utils import get_logger
+from smftools.optional_imports import require
 
 from ..config import LoadExperimentConfig
 from ..informatics.basecalling import canoncall, modcall
@@ -15,6 +14,8 @@ from ..readwrite import make_dirs
 
 logger = get_logger(__name__)
 
+p5 = require("pod5", extra="ont", purpose="POD5 IO")
+
 
 def basecall_pod5s(config_path: str | Path) -> None:
     """Basecall POD5 inputs using a configuration file.

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/machine_learning/__init__.py

@@ -1,7 +1,23 @@
-from . import data, evaluation, inference, models, training, utils
+from __future__ import annotations
 
-__all__ = [
-    "calculate_relative_risk_on_activity",
-    "evaluate_models_by_subgroup",
-    "prepare_melted_model_data",
-]
+from importlib import import_module
+
+_LAZY_MODULES = {
+    "data": "smftools.machine_learning.data",
+    "evaluation": "smftools.machine_learning.evaluation",
+    "inference": "smftools.machine_learning.inference",
+    "models": "smftools.machine_learning.models",
+    "training": "smftools.machine_learning.training",
+    "utils": "smftools.machine_learning.utils",
+}
+
+
+def __getattr__(name: str):
+    if name in _LAZY_MODULES:
+        module = import_module(_LAZY_MODULES[name])
+        globals()[name] = module
+        return module
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")
+
+
+__all__ = list(_LAZY_MODULES.keys())

smftools/machine_learning/data/__init__.py

@@ -1,2 +1,4 @@
+from __future__ import annotations
+
 from .anndata_data_module import AnnDataModule, build_anndata_loader
 from .preprocessing import random_fill_nans

smftools/machine_learning/data/anndata_data_module.py

@@ -1,12 +1,26 @@
+from __future__ import annotations
+
 import numpy as np
 import pandas as pd
-import pytorch_lightning as pl
-import torch
-from sklearn.utils.class_weight import compute_class_weight
-from torch.utils.data import DataLoader, Dataset, Subset
+
+from smftools.optional_imports import require
 
 from .preprocessing import random_fill_nans
 
+pl = require("pytorch_lightning", extra="ml-extended", purpose="Lightning data modules")
+torch = require("torch", extra="ml-base", purpose="ML data loading")
+sklearn_class_weight = require(
+    "sklearn.utils.class_weight",
+    extra="ml-base",
+    purpose="class weighting",
+)
+torch_utils_data = require("torch.utils.data", extra="ml-base", purpose="ML data loading")
+
+compute_class_weight = sklearn_class_weight.compute_class_weight
+DataLoader = torch_utils_data.DataLoader
+Dataset = torch_utils_data.Dataset
+Subset = torch_utils_data.Subset
+
 
 class AnnDataDataset(Dataset):
     """

smftools/machine_learning/data/preprocessing.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import numpy as np
 
 

smftools/machine_learning/evaluation/__init__.py

@@ -1,2 +1,4 @@
+from __future__ import annotations
+
 from .eval_utils import flatten_sliding_window_results
 from .evaluators import ModelEvaluator, PostInferenceModelEvaluator

smftools/machine_learning/evaluation/eval_utils.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import pandas as pd
 
 

smftools/machine_learning/evaluation/evaluators.py

@@ -1,14 +1,19 @@
-import matplotlib.pyplot as plt
+from __future__ import annotations
+
 import numpy as np
 import pandas as pd
-from sklearn.metrics import (
-    auc,
-    confusion_matrix,
-    f1_score,
-    precision_recall_curve,
-    roc_auc_score,
-    roc_curve,
-)
+
+from smftools.optional_imports import require
+
+plt = require("matplotlib.pyplot", extra="plotting", purpose="evaluation plots")
+sklearn_metrics = require("sklearn.metrics", extra="ml-base", purpose="model evaluation")
+
+auc = sklearn_metrics.auc
+confusion_matrix = sklearn_metrics.confusion_matrix
+f1_score = sklearn_metrics.f1_score
+precision_recall_curve = sklearn_metrics.precision_recall_curve
+roc_auc_score = sklearn_metrics.roc_auc_score
+roc_curve = sklearn_metrics.roc_curve
 
 
 class ModelEvaluator:

smftools/machine_learning/inference/__init__.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from .lightning_inference import run_lightning_inference
 from .sklearn_inference import run_sklearn_inference
 from .sliding_window_inference import sliding_window_inference

smftools/machine_learning/inference/inference_utils.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import pandas as pd
 
 

smftools/machine_learning/inference/lightning_inference.py

@@ -1,9 +1,14 @@
+from __future__ import annotations
+
 import numpy as np
 import pandas as pd
-import torch
+
+from smftools.optional_imports import require
 
 from .inference_utils import annotate_split_column
 
+torch = require("torch", extra="ml-base", purpose="Lightning inference")
+
 
 def run_lightning_inference(adata, model, datamodule, trainer, prefix="model", devices=1):
     """

smftools/machine_learning/inference/sklearn_inference.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import numpy as np
 import pandas as pd
 

smftools/machine_learning/inference/sliding_window_inference.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from ..data import AnnDataModule
 from ..evaluation import PostInferenceModelEvaluator
 from .lightning_inference import run_lightning_inference

smftools/machine_learning/models/__init__.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from .base import BaseTorchModel
 from .cnn import CNNClassifier
 from .lightning_base import TorchClassifierWrapper

smftools/machine_learning/models/base.py

@@ -1,9 +1,14 @@
+from __future__ import annotations
+
 import numpy as np
-import torch
-import torch.nn as nn
+
+from smftools.optional_imports import require
 
 from ..utils.device import detect_device
 
+torch = require("torch", extra="ml-base", purpose="ML base models")
+nn = torch.nn
+
 
 class BaseTorchModel(nn.Module):
     """

smftools/machine_learning/models/cnn.py

@@ -1,9 +1,14 @@
+from __future__ import annotations
+
 import numpy as np
-import torch
-import torch.nn as nn
+
+from smftools.optional_imports import require
 
 from .base import BaseTorchModel
 
+torch = require("torch", extra="ml-base", purpose="CNN models")
+nn = torch.nn
+
 
 class CNNClassifier(BaseTorchModel):
     def __init__(

smftools/machine_learning/models/lightning_base.py

@@ -1,15 +1,20 @@
-import matplotlib.pyplot as plt
+from __future__ import annotations
+
 import numpy as np
-import pytorch_lightning as pl
-import torch
-from sklearn.metrics import (
-    auc,
-    confusion_matrix,
-    f1_score,
-    precision_recall_curve,
-    roc_auc_score,
-    roc_curve,
-)
+
+from smftools.optional_imports import require
+
+plt = require("matplotlib.pyplot", extra="plotting", purpose="model evaluation plots")
+pl = require("pytorch_lightning", extra="ml-extended", purpose="Lightning models")
+torch = require("torch", extra="ml-base", purpose="Lightning models")
+sklearn_metrics = require("sklearn.metrics", extra="ml-base", purpose="model evaluation")
+
+auc = sklearn_metrics.auc
+confusion_matrix = sklearn_metrics.confusion_matrix
+f1_score = sklearn_metrics.f1_score
+precision_recall_curve = sklearn_metrics.precision_recall_curve
+roc_auc_score = sklearn_metrics.roc_auc_score
+roc_curve = sklearn_metrics.roc_curve
 
 
 class TorchClassifierWrapper(pl.LightningModule):

smftools/machine_learning/models/mlp.py

@@ -1,7 +1,11 @@
-import torch.nn as nn
+from __future__ import annotations
+
+from smftools.optional_imports import require
 
 from .base import BaseTorchModel
 
+nn = require("torch.nn", extra="ml-base", purpose="MLP models")
+
 
 class MLPClassifier(BaseTorchModel):
     def __init__(

smftools/machine_learning/models/positional.py

@@ -1,6 +1,11 @@
+from __future__ import annotations
+
 import numpy as np
-import torch
-import torch.nn as nn
+
+from smftools.optional_imports import require
+
+torch = require("torch", extra="ml-base", purpose="positional encoding")
+nn = torch.nn
 
 
 class PositionalEncoding(nn.Module):

smftools/machine_learning/models/rnn.py

@@ -1,7 +1,11 @@
-import torch.nn as nn
+from __future__ import annotations
+
+from smftools.optional_imports import require
 
 from .base import BaseTorchModel
 
+nn = require("torch.nn", extra="ml-base", purpose="RNN models")
+
 
 class RNNClassifier(BaseTorchModel):
     def __init__(self, input_size, hidden_dim, num_classes, **kwargs):

smftools/machine_learning/models/sklearn_models.py

@@ -1,13 +1,18 @@
-import matplotlib.pyplot as plt
+from __future__ import annotations
+
 import numpy as np
-from sklearn.metrics import (
-    auc,
-    confusion_matrix,
-    f1_score,
-    precision_recall_curve,
-    roc_auc_score,
-    roc_curve,
-)
+
+from smftools.optional_imports import require
+
+plt = require("matplotlib.pyplot", extra="plotting", purpose="model evaluation plots")
+sklearn_metrics = require("sklearn.metrics", extra="ml-base", purpose="model evaluation")
+
+auc = sklearn_metrics.auc
+confusion_matrix = sklearn_metrics.confusion_matrix
+f1_score = sklearn_metrics.f1_score
+precision_recall_curve = sklearn_metrics.precision_recall_curve
+roc_auc_score = sklearn_metrics.roc_auc_score
+roc_curve = sklearn_metrics.roc_curve
 
 
 class SklearnModelWrapper:

smftools/machine_learning/models/transformer.py

@@ -1,11 +1,16 @@
+from __future__ import annotations
+
 import numpy as np
-import torch
-import torch.nn as nn
+
+from smftools.optional_imports import require
 
 from ..utils.grl import grad_reverse
 from .base import BaseTorchModel
 from .positional import PositionalEncoding
 
+torch = require("torch", extra="ml-base", purpose="Transformer models")
+nn = torch.nn
+
 
 class TransformerEncoderLayerWithAttn(nn.TransformerEncoderLayer):
     def __init__(self, *args, **kwargs):

smftools/machine_learning/models/wrappers.py

@@ -1,5 +1,9 @@
-import torch
-import torch.nn as nn
+from __future__ import annotations
+
+from smftools.optional_imports import require
+
+torch = require("torch", extra="ml-base", purpose="model wrappers")
+nn = torch.nn
 
 
 class ScaledModel(nn.Module):

smftools/machine_learning/training/__init__.py

@@ -1,2 +1,4 @@
+from __future__ import annotations
+
 from .train_lightning_model import run_sliding_window_lightning_training, train_lightning_model
 from .train_sklearn_model import run_sliding_window_sklearn_training, train_sklearn_model

smftools/machine_learning/training/train_lightning_model.py

@@ -1,10 +1,20 @@
-import torch
-from pytorch_lightning import Trainer
-from pytorch_lightning.callbacks import EarlyStopping, ModelCheckpoint
+from __future__ import annotations
+
+from smftools.optional_imports import require
 
 from ..data import AnnDataModule
 from ..models import TorchClassifierWrapper
 
+torch = require("torch", extra="ml-base", purpose="Lightning training")
+pytorch_lightning = require("pytorch_lightning", extra="ml-extended", purpose="Lightning training")
+pl_callbacks = require(
+    "pytorch_lightning.callbacks", extra="ml-extended", purpose="Lightning training"
+)
+
+Trainer = pytorch_lightning.Trainer
+EarlyStopping = pl_callbacks.EarlyStopping
+ModelCheckpoint = pl_callbacks.ModelCheckpoint
+
 
 def train_lightning_model(
     model,

smftools/machine_learning/training/train_sklearn_model.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from ..data import AnnDataModule
 from ..models import SklearnModelWrapper
 

smftools/machine_learning/utils/__init__.py

@@ -1,2 +1,4 @@
+from __future__ import annotations
+
 from .device import detect_device
 from .grl import GradReverse

smftools/machine_learning/utils/device.py

@@ -1,4 +1,8 @@
-import torch
+from __future__ import annotations
+
+from smftools.optional_imports import require
+
+torch = require("torch", extra="ml-base", purpose="device selection")
 
 
 def detect_device():

smftools/machine_learning/utils/grl.py

@@ -1,4 +1,8 @@
-import torch
+from __future__ import annotations
+
+from smftools.optional_imports import require
+
+torch = require("torch", extra="ml-base", purpose="gradient reversal layers")
 
 
 class GradReverse(torch.autograd.Function):

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/optional_imports.py

@@ -0,0 +1,31 @@
+"""Utilities for optional dependency handling."""
+
+from __future__ import annotations
+
+from importlib import import_module
+from typing import Any
+
+
+def require(package: str, *, extra: str, purpose: str | None = None) -> Any:
+    """Import an optional dependency with a helpful error message.
+
+    Args:
+        package: Importable module name (e.g., "torch", "scanpy").
+        extra: Extra name users should install (e.g., "ml", "omics").
+        purpose: Optional context describing the feature needing the dependency.
+
+    Returns:
+        The imported module.
+
+    Raises:
+        ModuleNotFoundError: If the package is not installed.
+    """
+    try:
+        return import_module(package)
+    except ModuleNotFoundError as exc:  # pragma: no cover - depends on env
+        reason = f" for {purpose}" if purpose else ""
+        message = (
+            f"Optional dependency '{package}' is required{reason}. "
+            f"Install it with: pip install 'smftools[{extra}]'"
+        )
+        raise ModuleNotFoundError(message) from exc