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

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/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

smftools/plotting/__init__.py

@@ -1,32 +1,33 @@
-from .autocorrelation_plotting import *
-from .classifiers import (
-    plot_feature_importances_or_saliency,
-    plot_model_curves_from_adata,
-    plot_model_curves_from_adata_with_frequency_grid,
-    plot_model_performance,
-)
-from .general_plotting import (
-    combined_hmm_raw_clustermap,
-    combined_raw_clustermap,
-    plot_hmm_layers_rolling_by_sample_ref,
-)
-from .hmm_plotting import *
-from .position_stats import (
-    plot_bar_relative_risk,
-    plot_positionwise_matrix,
-    plot_positionwise_matrix_grid,
-    plot_volcano_relative_risk,
-)
-from .qc_plotting import *
+from __future__ import annotations
 
-__all__ = [
-    "combined_hmm_raw_clustermap",
-    "plot_bar_relative_risk",
-    "plot_positionwise_matrix",
-    "plot_positionwise_matrix_grid",
-    "plot_volcano_relative_risk",
-    "plot_feature_importances_or_saliency",
-    "plot_model_performance",
-    "plot_model_curves_from_adata",
-    "plot_model_curves_from_adata_with_frequency_grid",
-]
+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",
+    "plot_bar_relative_risk": "smftools.plotting.position_stats",
+    "plot_positionwise_matrix": "smftools.plotting.position_stats",
+    "plot_positionwise_matrix_grid": "smftools.plotting.position_stats",
+    "plot_volcano_relative_risk": "smftools.plotting.position_stats",
+    "plot_feature_importances_or_saliency": "smftools.plotting.classifiers",
+    "plot_model_curves_from_adata": "smftools.plotting.classifiers",
+    "plot_model_curves_from_adata_with_frequency_grid": "smftools.plotting.classifiers",
+    "plot_model_performance": "smftools.plotting.classifiers",
+    "plot_read_qc_histograms": "smftools.plotting.qc_plotting",
+    "plot_rolling_grid": "smftools.plotting.autocorrelation_plotting",
+    "plot_spatial_autocorr_grid": "smftools.plotting.autocorrelation_plotting",
+    "plot_hmm_size_contours": "smftools.plotting.hmm_plotting",
+}
+
+
+def __getattr__(name: str):
+    if name in _LAZY_ATTRS:
+        module = import_module(_LAZY_ATTRS[name])
+        attr = getattr(module, name)
+        globals()[name] = attr
+        return attr
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")
+
+
+__all__ = list(_LAZY_ATTRS.keys())

smftools/plotting/autocorrelation_plotting.py

@@ -1,8 +1,12 @@
+from __future__ import annotations
+
 from typing import Optional
 
 import numpy as np
 import pandas as pd
 
+from smftools.optional_imports import require
+
 
 def plot_spatial_autocorr_grid(
     adata,
@@ -35,7 +39,7 @@ def plot_spatial_autocorr_grid(
     import os
     import warnings
 
-    import matplotlib.pyplot as plt
+    plt = require("matplotlib.pyplot", extra="plotting", purpose="autocorrelation plots")
 
     # Try importing analyzer (used only as fallback)
     try:
@@ -518,7 +522,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.
     """
-    import matplotlib.pyplot as plt
+    plt = require("matplotlib.pyplot", extra="plotting", purpose="autocorrelation plots")
 
     # sort by center
     df2 = df.sort_values("center")
@@ -543,12 +547,12 @@ 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")
         if not show:
-            import matplotlib
+            matplotlib = require("matplotlib", extra="plotting", purpose="autocorrelation plots")
 
             matplotlib.pyplot.close(fig)
         return out_png
     if not show:
-        import matplotlib
+        matplotlib = require("matplotlib", extra="plotting", purpose="autocorrelation plots")
 
         matplotlib.pyplot.close(fig)
     return fig
@@ -600,7 +604,7 @@ def plot_rolling_grid(
     """
     import os
 
-    import matplotlib.pyplot as plt
+    plt = require("matplotlib.pyplot", extra="plotting", purpose="autocorrelation plots")
 
     if per_metric_ylim is None:
         per_metric_ylim = {}

smftools/plotting/classifiers.py

@@ -1,8 +1,13 @@
+from __future__ import annotations
+
 import os
 
-import matplotlib.pyplot as plt
 import numpy as np
-import torch
+
+from smftools.optional_imports import require
+
+plt = require("matplotlib.pyplot", extra="plotting", purpose="model plots")
+torch = require("torch", extra="ml-base", purpose="model saliency plots")
 
 
 def plot_model_performance(metrics, save_path=None):
@@ -260,7 +265,10 @@ def plot_model_curves_from_adata(
         ylim_roc: Y-axis limits for ROC curve.
         ylim_pr: Y-axis limits for PR curve.
     """
-    from sklearn.metrics import auc, precision_recall_curve, roc_curve
+    sklearn_metrics = require("sklearn.metrics", extra="ml-base", purpose="model curves")
+    auc = sklearn_metrics.auc
+    precision_recall_curve = sklearn_metrics.precision_recall_curve
+    roc_curve = sklearn_metrics.roc_curve
 
     if omit_training:
         subset = adata[~adata.obs["used_for_training"].astype(bool)]
@@ -349,7 +357,11 @@ def plot_model_curves_from_adata_with_frequency_grid(
     import os
 
     import numpy as np
-    from sklearn.metrics import auc, precision_recall_curve, roc_curve
+
+    sklearn_metrics = require("sklearn.metrics", extra="ml-base", purpose="model curves")
+    auc = sklearn_metrics.auc
+    precision_recall_curve = sklearn_metrics.precision_recall_curve
+    roc_curve = sklearn_metrics.roc_curve
 
     if f1_levels is None:
         f1_levels = np.linspace(0.2, 0.9, 8)

smftools/plotting/general_plotting.py

@@ -5,12 +5,15 @@ import os
 from pathlib import Path
 from typing import Any, Dict, List, Mapping, Optional, Sequence, Tuple
 
-import matplotlib.gridspec as gridspec
-import matplotlib.pyplot as plt
 import numpy as np
 import pandas as pd
 import scipy.cluster.hierarchy as sch
-import seaborn as sns
+
+from smftools.optional_imports import require
+
+gridspec = require("matplotlib.gridspec", extra="plotting", purpose="heatmap plotting")
+plt = require("matplotlib.pyplot", extra="plotting", purpose="plot rendering")
+sns = require("seaborn", extra="plotting", purpose="plot styling")
 
 
 def _fixed_tick_positions(n_positions: int, n_ticks: int) -> np.ndarray:

smftools/plotting/hmm_plotting.py

@@ -1,9 +1,19 @@
+from __future__ import annotations
+
 import math
 from typing import Optional, Tuple, Union
 
-import matplotlib.pyplot as plt
 import numpy as np
-from matplotlib.backends.backend_pdf import PdfPages
+
+from smftools.optional_imports import require
+
+plt = require("matplotlib.pyplot", extra="plotting", purpose="HMM plots")
+pdf_backend = require(
+    "matplotlib.backends.backend_pdf",
+    extra="plotting",
+    purpose="PDF output",
+)
+PdfPages = pdf_backend.PdfPages
 
 
 def plot_hmm_size_contours(

smftools/plotting/position_stats.py

@@ -1,3 +1,8 @@
+from __future__ import annotations
+
+from smftools.optional_imports import require
+
+
 def plot_volcano_relative_risk(
     results_dict,
     save_path=None,
@@ -22,7 +27,7 @@ def plot_volcano_relative_risk(
     """
     import os
 
-    import matplotlib.pyplot as plt
+    plt = require("matplotlib.pyplot", extra="plotting", purpose="relative risk plots")
 
     for ref, group_results in results_dict.items():
         for group_label, (results_df, _) in group_results.items():
@@ -124,7 +129,7 @@ def plot_bar_relative_risk(
     """
     import os
 
-    import matplotlib.pyplot as plt
+    plt = require("matplotlib.pyplot", extra="plotting", purpose="relative risk plots")
 
     for ref, group_data in results_dict.items():
         for group_label, (df, _) in group_data.items():
@@ -229,10 +234,11 @@ def plot_positionwise_matrix(
     """
     import os
 
-    import matplotlib.pyplot as plt
     import numpy as np
     import pandas as pd
-    import seaborn as sns
+
+    plt = require("matplotlib.pyplot", extra="plotting", purpose="position stats plots")
+    sns = require("seaborn", extra="plotting", purpose="position stats plots")
 
     def find_closest_index(index, target):
         """Find the index value closest to a target value."""
@@ -408,12 +414,14 @@ def plot_positionwise_matrix_grid(
     """
     import os
 
-    import matplotlib.pyplot as plt
     import numpy as np
     import pandas as pd
-    import seaborn as sns
     from joblib import Parallel, delayed
-    from matplotlib.gridspec import GridSpec
+
+    plt = require("matplotlib.pyplot", extra="plotting", purpose="position stats plots")
+    sns = require("seaborn", extra="plotting", purpose="position stats plots")
+    grid_spec = require("matplotlib.gridspec", extra="plotting", purpose="position stats plots")
+    GridSpec = grid_spec.GridSpec
 
     matrices = adata.uns[key]
     group_labels = list(matrices.keys())

smftools/plotting/qc_plotting.py

@@ -1,9 +1,14 @@
+from __future__ import annotations
+
 import os
 
-import matplotlib.pyplot as plt
 import numpy as np
 import pandas as pd
 
+from smftools.optional_imports import require
+
+plt = require("matplotlib.pyplot", extra="plotting", purpose="QC plots")
+
 
 def plot_read_qc_histograms(
     adata,

smftools/preprocessing/__init__.py

@@ -1,38 +1,36 @@
-from .append_base_context import append_base_context
-from .append_binary_layer_by_base_context import append_binary_layer_by_base_context
-from .binarize import binarize_adata
-from .binarize_on_Youden import binarize_on_Youden
-from .calculate_complexity_II import calculate_complexity_II
-from .calculate_coverage import calculate_coverage
-from .calculate_position_Youden import calculate_position_Youden
-from .calculate_read_length_stats import calculate_read_length_stats
-from .calculate_read_modification_stats import calculate_read_modification_stats
-from .clean_NaN import clean_NaN
-from .filter_adata_by_nan_proportion import filter_adata_by_nan_proportion
-from .filter_reads_on_length_quality_mapping import filter_reads_on_length_quality_mapping
-from .filter_reads_on_modification_thresholds import filter_reads_on_modification_thresholds
-from .flag_duplicate_reads import flag_duplicate_reads
-from .invert_adata import invert_adata
-from .load_sample_sheet import load_sample_sheet
-from .reindex_references_adata import reindex_references_adata
-from .subsample_adata import subsample_adata
+from __future__ import annotations
 
-__all__ = [
-    "append_base_context",
-    "append_binary_layer_by_base_context",
-    "binarize_on_Youden",
-    "binarize_adata",
-    "calculate_complexity_II",
-    "calculate_read_modification_stats",
-    "calculate_coverage",
-    "calculate_position_Youden",
-    "calculate_read_length_stats",
-    "clean_NaN",
-    "filter_adata_by_nan_proportion",
-    "filter_reads_on_modification_thresholds",
-    "filter_reads_on_length_quality_mapping",
-    "invert_adata",
-    "load_sample_sheet",
-    "flag_duplicate_reads",
-    "subsample_adata",
-]
+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",
+    "binarize_adata": "smftools.preprocessing.binarize",
+    "binarize_on_Youden": "smftools.preprocessing.binarize_on_Youden",
+    "calculate_complexity_II": "smftools.preprocessing.calculate_complexity_II",
+    "calculate_coverage": "smftools.preprocessing.calculate_coverage",
+    "calculate_position_Youden": "smftools.preprocessing.calculate_position_Youden",
+    "calculate_read_length_stats": "smftools.preprocessing.calculate_read_length_stats",
+    "calculate_read_modification_stats": "smftools.preprocessing.calculate_read_modification_stats",
+    "clean_NaN": "smftools.preprocessing.clean_NaN",
+    "filter_adata_by_nan_proportion": "smftools.preprocessing.filter_adata_by_nan_proportion",
+    "filter_reads_on_length_quality_mapping": "smftools.preprocessing.filter_reads_on_length_quality_mapping",
+    "filter_reads_on_modification_thresholds": "smftools.preprocessing.filter_reads_on_modification_thresholds",
+    "flag_duplicate_reads": "smftools.preprocessing.flag_duplicate_reads",
+    "invert_adata": "smftools.preprocessing.invert_adata",
+    "load_sample_sheet": "smftools.preprocessing.load_sample_sheet",
+    "reindex_references_adata": "smftools.preprocessing.reindex_references_adata",
+    "subsample_adata": "smftools.preprocessing.subsample_adata",
+}
+
+
+def __getattr__(name: str):
+    if name in _LAZY_ATTRS:
+        module = import_module(_LAZY_ATTRS[name])
+        attr = getattr(module, name)
+        globals()[name] = attr
+        return attr
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")
+
+
+__all__ = list(_LAZY_ATTRS.keys())

smftools/preprocessing/archived/add_read_length_and_mapping_qc.py

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

smftools/preprocessing/archived/calculate_complexity.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 ## calculate_complexity
 
 def calculate_complexity(adata, output_directory='', obs_column='Reference', sample_col='Sample_names', plot=True, save_plot=False):

smftools/preprocessing/archived/mark_duplicates.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 ## mark_duplicates
 
 def mark_duplicates(adata, layers, obs_column='Reference', sample_col='Sample_names', method='N_masked_distances', distance_thresholds={}):

smftools/preprocessing/archived/preprocessing.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 ## preprocessing
 from .. import readwrite
 

smftools/preprocessing/archived/remove_duplicates.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 # remove_duplicates
 
 def remove_duplicates(adata):

smftools/preprocessing/binary_layers_to_ohe.py

@@ -1,5 +1,6 @@
-## binary_layers_to_ohe
+from __future__ import annotations
 
+## binary_layers_to_ohe
 from smftools.logging_utils import get_logger
 
 logger = get_logger(__name__)

smftools/preprocessing/calculate_complexity_II.py

@@ -3,6 +3,8 @@ from __future__ import annotations
 from pathlib import Path
 from typing import TYPE_CHECKING, Optional
 
+from smftools.optional_imports import require
+
 if TYPE_CHECKING:
     import anndata as ad
 
@@ -46,11 +48,12 @@ def calculate_complexity_II(
     """
     import os
 
-    import matplotlib.pyplot as plt
     import numpy as np
     import pandas as pd
     from scipy.optimize import curve_fit
 
+    plt = require("matplotlib.pyplot", extra="plotting", purpose="complexity plots")
+
     # early exits
     already = bool(adata.uns.get(uns_flag, False))
     if already and not force_redo:

smftools/preprocessing/calculate_pairwise_differences.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 # calculate_pairwise_differences
 
 

smftools/preprocessing/calculate_pairwise_hamming_distances.py

@@ -1,5 +1,8 @@
+from __future__ import annotations
+
 ## calculate_pairwise_hamming_distances
 
+
 ## Conversion SMF Specific
 def calculate_pairwise_hamming_distances(arrays):
     """

smftools/preprocessing/calculate_position_Youden.py

@@ -6,6 +6,7 @@ from pathlib import Path
 from typing import TYPE_CHECKING
 
 from smftools.logging_utils import get_logger
+from smftools.optional_imports import require
 
 if TYPE_CHECKING:
     import anndata as ad
@@ -40,9 +41,15 @@ def calculate_position_Youden(
         save: Whether to save ROC plots to disk.
         output_directory: Output directory for ROC plots.
     """
-    import matplotlib.pyplot as plt
     import numpy as np
-    from sklearn.metrics import roc_curve
+
+    plt = require("matplotlib.pyplot", extra="plotting", purpose="Youden ROC plots")
+    sklearn_metrics = require(
+        "sklearn.metrics",
+        extra="ml-base",
+        purpose="Youden ROC curve calculation",
+    )
+    roc_curve = sklearn_metrics.roc_curve
 
     control_samples = [positive_control_sample, negative_control_sample]
     references = adata.obs[ref_column].cat.categories

smftools/preprocessing/filter_reads_on_length_quality_mapping.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from typing import Optional, Sequence, Union
 
 import anndata as ad

smftools/preprocessing/filter_reads_on_modification_thresholds.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import gc
 from typing import List, Optional, Sequence