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

smftools/tools/calculate_umap.py

@@ -1,7 +1,42 @@
-def calculate_umap(adata, layer='nan_half', var_filters=None, n_pcs=15, knn_neighbors=100, overwrite=True, threads=8):
-    import scanpy as sc
-    import numpy as np
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Sequence
+
+from smftools.logging_utils import get_logger
+
+if TYPE_CHECKING:
+    import anndata as ad
+
+logger = get_logger(__name__)
+
+
+def calculate_umap(
+    adata: "ad.AnnData",
+    layer: str | None = "nan_half",
+    var_filters: Sequence[str] | None = None,
+    n_pcs: int = 15,
+    knn_neighbors: int = 100,
+    overwrite: bool = True,
+    threads: int = 8,
+) -> "ad.AnnData":
+    """Compute PCA, neighbors, and UMAP embeddings.
+
+    Args:
+        adata: AnnData object to update.
+        layer: Layer name to use for PCA/UMAP (``None`` uses ``adata.X``).
+        var_filters: Optional list of var masks to subset features.
+        n_pcs: Number of principal components.
+        knn_neighbors: Number of neighbors for the graph.
+        overwrite: Whether to recompute embeddings if they exist.
+        threads: Number of OMP threads for computation.
+
+    Returns:
+        anndata.AnnData: Updated AnnData object.
+    """
     import os
+
+    import numpy as np
+    import scanpy as sc
     from scipy.sparse import issparse
 
     os.environ["OMP_NUM_THREADS"] = str(threads)
@@ -10,32 +45,38 @@ def calculate_umap(adata, layer='nan_half', var_filters=None, n_pcs=15, knn_neig
     if var_filters:
         subset_mask = np.logical_or.reduce([adata.var[f].values for f in var_filters])
         adata_subset = adata[:, subset_mask].copy()
-        print(f"Subsetting adata: Retained {adata_subset.shape[1]} features based on filters {var_filters}")
+        logger.info(
+            "Subsetting adata: retained %s features based on filters %s",
+            adata_subset.shape[1],
+            var_filters,
+        )
     else:
         adata_subset = adata.copy()
-        print("No var filters provided. Using all features.")
+        logger.info("No var filters provided. Using all features.")
 
     # Step 2: NaN handling inside layer
     if layer:
         data = adata_subset.layers[layer]
         if not issparse(data):
             if np.isnan(data).any():
-                print("⚠ NaNs detected, filling with 0.5 before PCA + neighbors.")
+                logger.warning("NaNs detected, filling with 0.5 before PCA + neighbors.")
                 data = np.nan_to_num(data, nan=0.5)
                 adata_subset.layers[layer] = data
             else:
-                print("No NaNs detected.")
+                logger.info("No NaNs detected.")
         else:
-            print("Sparse matrix detected; skipping NaN check (sparse formats typically do not store NaNs).")
+            logger.info(
+                "Sparse matrix detected; skipping NaN check (sparse formats typically do not store NaNs)."
+            )
 
     # Step 3: PCA + neighbors + UMAP on subset
     if "X_umap" not in adata_subset.obsm or overwrite:
         n_pcs = min(adata_subset.shape[1], n_pcs)
-        print(f"Running PCA with n_pcs={n_pcs}")
+        logger.info("Running PCA with n_pcs=%s", n_pcs)
         sc.pp.pca(adata_subset, layer=layer)
-        print('Running neighborhood graph')
+        logger.info("Running neighborhood graph")
         sc.pp.neighbors(adata_subset, use_rep="X_pca", n_pcs=n_pcs, n_neighbors=knn_neighbors)
-        print('Running UMAP')
+        logger.info("Running UMAP")
         sc.tl.umap(adata_subset)
 
     # Step 4: Store results in original adata
@@ -45,7 +86,6 @@ def calculate_umap(adata, layer='nan_half', var_filters=None, n_pcs=15, knn_neig
     adata.obsp["connectivities"] = adata_subset.obsp["connectivities"]
     adata.uns["neighbors"] = adata_subset.uns["neighbors"]
 
-
     # Fix varm["PCs"] shape mismatch
     pc_matrix = np.zeros((adata.shape[1], adata_subset.varm["PCs"].shape[1]))
     if var_filters:
@@ -56,7 +96,6 @@ def calculate_umap(adata, layer='nan_half', var_filters=None, n_pcs=15, knn_neig
 
     adata.varm["PCs"] = pc_matrix
 
+    logger.info("Stored: adata.obsm['X_pca'] and adata.obsm['X_umap']")
 
-    print(f"Stored: adata.obsm['X_pca'] and adata.obsm['X_umap']")
-
-    return adata
+    return adata

smftools/tools/cluster_adata_on_methylation.py

@@ -1,35 +1,50 @@
+from __future__ import annotations
+
 # cluster_adata_on_methylation
+from typing import TYPE_CHECKING, Sequence
 
-def cluster_adata_on_methylation(adata, obs_columns, method='hierarchical', n_clusters=3, layer=None, site_types = ['GpC_site', 'CpG_site']):
-    """
-    Adds cluster groups to the adata object as an observation column
-
-    Parameters:
-        adata
-        obs_columns
-        method
-        n_clusters
-        layer
-        site_types
-
-    Returns:
-        None
+from smftools.logging_utils import get_logger
+
+if TYPE_CHECKING:
+    import anndata as ad
+
+logger = get_logger(__name__)
+
+
+def cluster_adata_on_methylation(
+    adata: "ad.AnnData",
+    obs_columns: Sequence[str],
+    method: str = "hierarchical",
+    n_clusters: int = 3,
+    layer: str | None = None,
+    site_types: Sequence[str] = ("GpC_site", "CpG_site"),
+) -> None:
+    """Add clustering groups to ``adata.obs`` based on methylation patterns.
+
+    Args:
+        adata: AnnData object to annotate.
+        obs_columns: Observation columns to define subgroups.
+        method: Clustering method (``"hierarchical"`` or ``"kmeans"``).
+        n_clusters: Number of clusters for k-means.
+        layer: Layer to use for clustering.
+        site_types: Site types to analyze.
     """
-    import pandas as pd
     import numpy as np
-    from . import subset_adata
+    import pandas as pd
+
     from ..readwrite import adata_to_df
+    from . import subset_adata
 
     # Ensure obs_columns are categorical
     for col in obs_columns:
-        adata.obs[col] = adata.obs[col].astype('category')
+        adata.obs[col] = adata.obs[col].astype("category")
 
-    references = adata.obs['Reference'].cat.categories
+    references = adata.obs["Reference"].cat.categories
 
     # Add subset metadata to the adata
     subset_adata(adata, obs_columns)
 
-    subgroup_name = '_'.join(obs_columns)
+    subgroup_name = "_".join(obs_columns)
     subgroups = adata.obs[subgroup_name].cat.categories
 
     subgroup_to_reference_map = {}
@@ -40,66 +55,120 @@ def cluster_adata_on_methylation(adata, obs_columns, method='hierarchical', n_cl
             else:
                 pass
 
-    if method == 'hierarchical':
+    if method == "hierarchical":
         for site_type in site_types:
-            adata.obs[f'{site_type}_{layer}_hierarchical_clustering_index_within_{subgroup_name}'] = pd.Series(-1, index=adata.obs_names, dtype=int)
-    elif method == 'kmeans':
+            adata.obs[
+                f"{site_type}_{layer}_hierarchical_clustering_index_within_{subgroup_name}"
+            ] = pd.Series(-1, index=adata.obs_names, dtype=int)
+    elif method == "kmeans":
         for site_type in site_types:
-            adata.obs[f'{site_type}_{layer}_kmeans_clustering_index_within_{subgroup_name}'] = pd.Series(-1, index=adata.obs_names, dtype=int)
-        
+            adata.obs[f"{site_type}_{layer}_kmeans_clustering_index_within_{subgroup_name}"] = (
+                pd.Series(-1, index=adata.obs_names, dtype=int)
+            )
+
     for subgroup in subgroups:
         subgroup_subset = adata[adata.obs[subgroup_name] == subgroup].copy()
         reference = subgroup_to_reference_map[subgroup]
         for site_type in site_types:
-            site_subset = subgroup_subset[:, np.array(subgroup_subset.var[f'{reference}_{site_type}'])].copy()
+            site_subset = subgroup_subset[
+                :, np.array(subgroup_subset.var[f"{reference}_{site_type}"])
+            ].copy()
             df = adata_to_df(site_subset, layer=layer)
             df2 = df.reset_index(drop=True)
-            if method == 'hierarchical':
+            if method == "hierarchical":
                 try:
-                    from scipy.cluster.hierarchy import linkage, dendrogram
+                    from scipy.cluster.hierarchy import dendrogram, linkage
+
                     # Perform hierarchical clustering on rows using the average linkage method and Euclidean metric
-                    row_linkage = linkage(df2.values, method='average', metric='euclidean')
+                    row_linkage = linkage(df2.values, method="average", metric="euclidean")
 
                     # Generate the dendrogram to get the ordered indices
                     dendro = dendrogram(row_linkage, no_plot=True)
-                    reordered_row_indices = np.array(dendro['leaves']).astype(int)
+                    reordered_row_indices = np.array(dendro["leaves"]).astype(int)
 
                     # Get the reordered observation names
                     reordered_obs_names = [df.index[i] for i in reordered_row_indices]
 
-                    temp_obs_data = pd.DataFrame({f'{site_type}_{layer}_hierarchical_clustering_index_within_{subgroup_name}': np.arange(0, len(reordered_obs_names), 1)}, index=reordered_obs_names, dtype=int)
+                    temp_obs_data = pd.DataFrame(
+                        {
+                            f"{site_type}_{layer}_hierarchical_clustering_index_within_{subgroup_name}": np.arange(
+                                0, len(reordered_obs_names), 1
+                            )
+                        },
+                        index=reordered_obs_names,
+                        dtype=int,
+                    )
                     adata.obs.update(temp_obs_data)
-                except:
-                    print(f'Error found in {subgroup} of {site_type}_{layer}_hierarchical_clustering_index_within_{subgroup_name}')
-            elif method == 'kmeans':
+                except Exception:
+                    logger.exception(
+                        "Error found in %s of %s_%s_hierarchical_clustering_index_within_%s",
+                        subgroup,
+                        site_type,
+                        layer,
+                        subgroup_name,
+                    )
+            elif method == "kmeans":
                 try:
                     from sklearn.cluster import KMeans
+
                     kmeans = KMeans(n_clusters=n_clusters)
                     kmeans.fit(site_subset.layers[layer])
                     # Get the cluster labels for each data point
                     cluster_labels = kmeans.labels_
                     # Add the kmeans cluster data as an observation to the anndata object
-                    site_subset.obs[f'{site_type}_{layer}_kmeans_clustering_index_within_{subgroup_name}'] = cluster_labels.astype(str)
+                    site_subset.obs[
+                        f"{site_type}_{layer}_kmeans_clustering_index_within_{subgroup_name}"
+                    ] = cluster_labels.astype(str)
                     # Calculate the mean of each observation categoty of each cluster
-                    cluster_means = site_subset.obs.groupby(f'{site_type}_{layer}_kmeans_clustering_index_within_{subgroup_name}').mean()
+                    cluster_means = site_subset.obs.groupby(
+                        f"{site_type}_{layer}_kmeans_clustering_index_within_{subgroup_name}"
+                    ).mean()
                     # Sort the cluster indices by mean methylation value
-                    sorted_clusters = cluster_means.sort_values(by=f'{site_type}_row_methylation_means', ascending=False).index
+                    sorted_clusters = cluster_means.sort_values(
+                        by=f"{site_type}_row_methylation_means", ascending=False
+                    ).index
                     # Create a mapping of the old cluster values to the new cluster values
                     sorted_cluster_mapping = {old: new for new, old in enumerate(sorted_clusters)}
                     # Apply the mapping to create a new observation value: kmeans_labels_reordered
-                    site_subset.obs[f'{site_type}_{layer}_kmeans_clustering_index_within_{subgroup_name}'] = site_subset.obs[f'{site_type}_{layer}_kmeans_clustering_index_within_{subgroup_name}'].map(sorted_cluster_mapping)
-                    temp_obs_data = pd.DataFrame({f'{site_type}_{layer}_kmeans_clustering_index_within_{subgroup_name}': site_subset.obs[f'{site_type}_{layer}_kmeans_clustering_index_within_{subgroup_name}']}, index=site_subset.obs_names, dtype=int)
-                    adata.obs.update(temp_obs_data)      
-                except:
-                        print(f'Error found in {subgroup} of {site_type}_{layer}_kmeans_clustering_index_within_{subgroup_name}')   
+                    site_subset.obs[
+                        f"{site_type}_{layer}_kmeans_clustering_index_within_{subgroup_name}"
+                    ] = site_subset.obs[
+                        f"{site_type}_{layer}_kmeans_clustering_index_within_{subgroup_name}"
+                    ].map(sorted_cluster_mapping)
+                    temp_obs_data = pd.DataFrame(
+                        {
+                            f"{site_type}_{layer}_kmeans_clustering_index_within_{subgroup_name}": site_subset.obs[
+                                f"{site_type}_{layer}_kmeans_clustering_index_within_{subgroup_name}"
+                            ]
+                        },
+                        index=site_subset.obs_names,
+                        dtype=int,
+                    )
+                    adata.obs.update(temp_obs_data)
+                except Exception:
+                    logger.exception(
+                        "Error found in %s of %s_%s_kmeans_clustering_index_within_%s",
+                        subgroup,
+                        site_type,
+                        layer,
+                        subgroup_name,
+                    )
 
-    if method == 'hierarchical':             
+    if method == "hierarchical":
         # Ensure that the observation values are type int
         for site_type in site_types:
-            adata.obs[f'{site_type}_{layer}_hierarchical_clustering_index_within_{subgroup_name}'] = adata.obs[f'{site_type}_{layer}_hierarchical_clustering_index_within_{subgroup_name}'].astype(int)
-    elif method == 'kmeans':
+            adata.obs[
+                f"{site_type}_{layer}_hierarchical_clustering_index_within_{subgroup_name}"
+            ] = adata.obs[
+                f"{site_type}_{layer}_hierarchical_clustering_index_within_{subgroup_name}"
+            ].astype(int)
+    elif method == "kmeans":
         # Ensure that the observation values are type int
         for site_type in site_types:
-            adata.obs[f'{site_type}_{layer}_kmeans_clustering_index_within_{subgroup_name}'] = adata.obs[f'{site_type}_{layer}_kmeans_clustering_index_within_{subgroup_name}'].astype(int)
+            adata.obs[f"{site_type}_{layer}_kmeans_clustering_index_within_{subgroup_name}"] = (
+                adata.obs[
+                    f"{site_type}_{layer}_kmeans_clustering_index_within_{subgroup_name}"
+                ].astype(int)
+            )
 
-    return None   
+    return None

smftools/tools/general_tools.py

@@ -1,14 +1,48 @@
-def create_nan_mask_from_X(adata, new_layer_name="nan_mask"):
-    """
-    Generates a nan mask where 1 = NaN in adata.X and 0 = valid value.
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Sequence
+
+from smftools.logging_utils import get_logger
+
+if TYPE_CHECKING:
+    import anndata as ad
+
+logger = get_logger(__name__)
+
+
+def create_nan_mask_from_X(adata: "ad.AnnData", new_layer_name: str = "nan_mask") -> "ad.AnnData":
+    """Generate a NaN mask layer from ``adata.X``.
+
+    Args:
+        adata: AnnData object.
+        new_layer_name: Name of the output mask layer.
+
+    Returns:
+        anndata.AnnData: Updated AnnData object.
     """
     import numpy as np
+
     nan_mask = np.isnan(adata.X).astype(int)
     adata.layers[new_layer_name] = nan_mask
-    print(f"Created '{new_layer_name}' layer based on NaNs in adata.X")
+    logger.info("Created '%s' layer based on NaNs in adata.X", new_layer_name)
     return adata
 
-def create_nan_or_non_gpc_mask(adata, obs_column, new_layer_name="nan_or_non_gpc_mask"):
+
+def create_nan_or_non_gpc_mask(
+    adata: "ad.AnnData",
+    obs_column: str,
+    new_layer_name: str = "nan_or_non_gpc_mask",
+) -> "ad.AnnData":
+    """Generate a mask layer combining NaNs and non-GpC positions.
+
+    Args:
+        adata: AnnData object.
+        obs_column: Obs column used to derive reference-specific GpC masks.
+        new_layer_name: Name of the output mask layer.
+
+    Returns:
+        anndata.AnnData: Updated AnnData object.
+    """
     import numpy as np
 
     nan_mask = np.isnan(adata.X).astype(int)
@@ -22,30 +56,37 @@ def create_nan_or_non_gpc_mask(adata, obs_column, new_layer_name="nan_or_non_gpc
     mask = np.maximum(nan_mask, combined_mask)
     adata.layers[new_layer_name] = mask
 
-    print(f"Created '{new_layer_name}' layer based on NaNs in adata.X and non-GpC regions using {obs_column}")
+    logger.info(
+        "Created '%s' layer based on NaNs in adata.X and non-GpC regions using %s",
+        new_layer_name,
+        obs_column,
+    )
     return adata
 
-def combine_layers(adata, input_layers, output_layer, negative_mask=None, values=None, binary_mode=False):
-    """
-    Combines layers into a single layer with specific coding:
-        - Background stays 0
-        - If binary_mode=True: any overlap = 1
-        - If binary_mode=False:
-            - Defaults to [1, 2, 3, ...] if values=None
-            - Later layers take precedence in overlaps
-    
-    Parameters:
-        adata: AnnData object
-        input_layers: list of str
-        output_layer: str, name of the output layer
-        negative_mask: str (optional), binary mask to enforce 0s
-        values: list of ints (optional), values to assign to each input layer
-        binary_mode: bool, if True, creates a simple 0/1 mask regardless of values
-    
+
+def combine_layers(
+    adata: "ad.AnnData",
+    input_layers: Sequence[str],
+    output_layer: str,
+    negative_mask: str | None = None,
+    values: Sequence[int] | None = None,
+    binary_mode: bool = False,
+) -> "ad.AnnData":
+    """Combine layers into a single coded layer.
+
+    Args:
+        adata: AnnData object.
+        input_layers: Input layer names.
+        output_layer: Name of the output layer.
+        negative_mask: Optional binary mask layer to enforce zeros.
+        values: Values assigned to each input layer when ``binary_mode`` is ``False``.
+        binary_mode: Whether to build a simple 0/1 mask.
+
     Returns:
-        Updated AnnData with new layer.
+        anndata.AnnData: Updated AnnData object.
     """
     import numpy as np
+
     combined = np.zeros_like(adata.layers[input_layers[0]])
 
     if binary_mode:
@@ -64,6 +105,10 @@ def combine_layers(adata, input_layers, output_layer, negative_mask=None, values
         combined[mask == 0] = 0
 
     adata.layers[output_layer] = combined
-    print(f"Combined layers into {output_layer} {'(binary)' if binary_mode else f'with values {values}'}")
+    logger.info(
+        "Combined layers into %s %s",
+        output_layer,
+        "(binary)" if binary_mode else f"with values {values}",
+    )
 
     return adata