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

smftools/preprocessing/invert_adata.py

@@ -1,25 +1,40 @@
 ## invert_adata
 
-def invert_adata(adata, uns_flag='invert_adata_performed', force_redo=False):
-    """
-    Inverts the AnnData object along the column (variable) axis.
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from smftools.logging_utils import get_logger
+
+if TYPE_CHECKING:
+    import anndata as ad
 
-    Parameters:
-        adata (AnnData): An AnnData object.
+logger = get_logger(__name__)
+
+
+def invert_adata(
+    adata: "ad.AnnData",
+    uns_flag: str = "invert_adata_performed",
+    force_redo: bool = False,
+) -> "ad.AnnData":
+    """Invert the AnnData object along the column axis.
+
+    Args:
+        adata: AnnData object.
+        uns_flag: Flag in ``adata.uns`` indicating prior completion.
+        force_redo: Whether to rerun even if ``uns_flag`` is set.
 
     Returns:
-        AnnData: A new AnnData object with inverted column ordering.
+        anndata.AnnData: New AnnData object with inverted column ordering.
     """
-    import numpy as np
-    import anndata as ad
 
     # Only run if not already performed
     already = bool(adata.uns.get(uns_flag, False))
-    if (already and not force_redo):
+    if already and not force_redo:
         # QC already performed; nothing to do
         return adata
 
-    print("Inverting AnnData along the column axis...")
+    logger.info("Inverting AnnData along the column axis...")
 
     # Reverse the order of columns (variables)
     inverted_adata = adata[:, ::-1].copy()
@@ -33,5 +48,5 @@ def invert_adata(adata, uns_flag='invert_adata_performed', force_redo=False):
     # mark as done
     inverted_adata.uns[uns_flag] = True
 
-    print("Inversion complete!")
+    logger.info("Inversion complete!")
     return inverted_adata

smftools/preprocessing/load_sample_sheet.py

@@ -1,21 +1,36 @@
-def load_sample_sheet(adata, 
-                      sample_sheet_path, 
-                      mapping_key_column='obs_names',
-                      as_category=True,
-                      uns_flag='load_sample_sheet_performed',
-                      force_reload=True
-                        ):
-    """
-    Loads a sample sheet CSV and maps metadata into the AnnData object as categorical columns.
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from smftools.logging_utils import get_logger
+
+if TYPE_CHECKING:
+    import anndata as ad
+
+logger = get_logger(__name__)
 
-    Parameters:
-        adata (AnnData): The AnnData object to append sample information to.
-        sample_sheet_path (str): Path to the CSV file.
-        mapping_key_column (str): Column name in the CSV to map against adata.obs_names or an existing obs column.
-        as_category (bool): If True, added columns will be cast as pandas Categorical.
+
+def load_sample_sheet(
+    adata: "ad.AnnData",
+    sample_sheet_path: str | Path,
+    mapping_key_column: str = "obs_names",
+    as_category: bool = True,
+    uns_flag: str = "load_sample_sheet_performed",
+    force_reload: bool = True,
+) -> "ad.AnnData":
+    """Load a sample sheet CSV and map metadata into ``adata.obs``.
+
+    Args:
+        adata: AnnData object to append sample information to.
+        sample_sheet_path: Path to the CSV file.
+        mapping_key_column: Column name to map against ``adata.obs_names`` or an obs column.
+        as_category: Whether to cast added columns as pandas Categoricals.
+        uns_flag: Flag in ``adata.uns`` indicating prior completion.
+        force_reload: Whether to reload even if ``uns_flag`` is set.
 
     Returns:
-        AnnData: Updated AnnData object.
+        anndata.AnnData: Updated AnnData object.
     """
     import pandas as pd
 
@@ -25,29 +40,32 @@ def load_sample_sheet(adata,
         # QC already performed; nothing to do
         return
 
-    print('Loading sample sheet...')
+    logger.info("Loading sample sheet...")
     df = pd.read_csv(sample_sheet_path)
     df[mapping_key_column] = df[mapping_key_column].astype(str)
-    
+
     # If matching against obs_names directly
-    if mapping_key_column == 'obs_names':
+    if mapping_key_column == "obs_names":
         key_series = adata.obs_names.astype(str)
     else:
         key_series = adata.obs[mapping_key_column].astype(str)
 
     value_columns = [col for col in df.columns if col != mapping_key_column]
-    
-    print(f'Appending metadata columns: {value_columns}')
+
+    logger.info("Appending metadata columns: %s", value_columns)
     df = df.set_index(mapping_key_column)
 
     for col in value_columns:
         mapped = key_series.map(df[col])
         if as_category:
-            mapped = mapped.astype('category')
+            mapped = mapped.astype("category")
         adata.obs[col] = mapped
 
     # mark as done
     adata.uns[uns_flag] = True
 
-    print('Sample sheet metadata successfully added as categories.' if as_category else 'Metadata added.')
+    if as_category:
+        logger.info("Sample sheet metadata successfully added as categories.")
+    else:
+        logger.info("Metadata added.")
     return adata

smftools/preprocessing/make_dirs.py

@@ -1,4 +1,10 @@
+from __future__ import annotations
+
 ## make_dirs
+from smftools.logging_utils import get_logger
+
+logger = get_logger(__name__)
+
 
 # General
 def make_dirs(directories):
@@ -7,7 +13,7 @@ def make_dirs(directories):
 
     Parameters:
         directories (list): A list of directories to make
-    
+
     Returns:
         None
     """
@@ -16,6 +22,6 @@ def make_dirs(directories):
     for directory in directories:
         if not os.path.isdir(directory):
             os.mkdir(directory)
-            print(f"Directory '{directory}' created successfully.")
+            logger.info("Directory '%s' created successfully.", directory)
         else:
-            print(f"Directory '{directory}' already exists.")
+            logger.info("Directory '%s' already exists.", directory)

smftools/preprocessing/min_non_diagonal.py

@@ -1,5 +1,8 @@
+from __future__ import annotations
+
 ## min_non_diagonal
 
+
 def min_non_diagonal(matrix):
     """
     Takes a matrix and returns the smallest value from each row with the diagonal masked.
@@ -22,4 +25,4 @@ def min_non_diagonal(matrix):
         row = matrix[i, row_mask]
         # Find the minimum value in the row
         min_values.append(np.min(row))
-    return min_values
+    return min_values

smftools/preprocessing/recipes.py

@@ -1,6 +1,17 @@
+from __future__ import annotations
+
 # recipes
 
-def recipe_1_Kissiov_and_McKenna_2025(adata, sample_sheet_path, output_directory, mapping_key_column='Sample', reference_column = 'Reference', sample_names_col='Sample_names', invert=True):
+
+def recipe_1_Kissiov_and_McKenna_2025(
+    adata,
+    sample_sheet_path,
+    output_directory,
+    mapping_key_column="Sample",
+    reference_column="Reference",
+    sample_names_col="Sample_names",
+    invert=True,
+):
     """
     The first part of the preprocessing workflow applied to the smf.inform.pod_to_adata() output derived from Kissiov_and_McKenna_2025.
 
@@ -26,36 +37,38 @@ def recipe_1_Kissiov_and_McKenna_2025(adata, sample_sheet_path, output_directory
     Returns:
         variables (dict): A dictionary of variables to append to the parent scope.
     """
-    import anndata as ad
-    import pandas as pd
-    import numpy as np
-    from .load_sample_sheet import load_sample_sheet
-    from .calculate_coverage import calculate_coverage
+
     from .append_C_context import append_C_context
-    from .calculate_converted_read_methylation_stats import calculate_converted_read_methylation_stats
-    from .invert_adata import invert_adata
+    from .calculate_converted_read_methylation_stats import (
+        calculate_converted_read_methylation_stats,
+    )
+    from .calculate_coverage import calculate_coverage
     from .calculate_read_length_stats import calculate_read_length_stats
     from .clean_NaN import clean_NaN
+    from .invert_adata import invert_adata
+    from .load_sample_sheet import load_sample_sheet
 
     # Clean up some of the Reference metadata and save variable names that point to sets of values in the column.
-    adata.obs[reference_column] = adata.obs[reference_column].astype('category')
+    adata.obs[reference_column] = adata.obs[reference_column].astype("category")
     references = adata.obs[reference_column].cat.categories
-    split_references = [(reference, reference.split('_')[0][1:]) for reference in references]
+    split_references = [(reference, reference.split("_")[0][1:]) for reference in references]
     reference_mapping = {k: v for k, v in split_references}
-    adata.obs[f'{reference_column}_short'] = adata.obs[reference_column].map(reference_mapping)
-    short_references = set(adata.obs[f'{reference_column}_short'])
+    adata.obs[f"{reference_column}_short"] = adata.obs[reference_column].map(reference_mapping)
+    short_references = set(adata.obs[f"{reference_column}_short"])
     binary_layers = list(adata.layers.keys())
 
     # load sample sheet metadata
     load_sample_sheet(adata, sample_sheet_path, mapping_key_column)
 
     # hold sample names set
-    adata.obs[sample_names_col] = adata.obs[sample_names_col].astype('category')
+    adata.obs[sample_names_col] = adata.obs[sample_names_col].astype("category")
     sample_names = adata.obs[sample_names_col].cat.categories
 
     # Add position level metadata
     calculate_coverage(adata, obs_column=reference_column)
-    adata.var['SNP_position'] = (adata.var[f'N_{reference_column}_with_position'] > 0) & (adata.var[f'N_{reference_column}_with_position'] < len(references)).astype(bool)
+    adata.var["SNP_position"] = (adata.var[f"N_{reference_column}_with_position"] > 0) & (
+        adata.var[f"N_{reference_column}_with_position"] < len(references)
+    ).astype(bool)
 
     # Append cytosine context to the reference positions based on the conversion strand.
     append_C_context(adata, obs_column=reference_column, use_consensus=False)
@@ -64,7 +77,9 @@ def recipe_1_Kissiov_and_McKenna_2025(adata, sample_sheet_path, output_directory
     calculate_converted_read_methylation_stats(adata, reference_column, sample_names_col)
 
     # Calculate read length statistics
-    upper_bound, lower_bound = calculate_read_length_stats(adata, reference_column, sample_names_col)
+    upper_bound, lower_bound = calculate_read_length_stats(
+        adata, reference_column, sample_names_col
+    )
 
     # Invert the adata object (ie flip the strand orientation for visualization)
     if invert:
@@ -81,11 +96,19 @@ def recipe_1_Kissiov_and_McKenna_2025(adata, sample_sheet_path, output_directory
         "sample_names": sample_names,
         "upper_bound": upper_bound,
         "lower_bound": lower_bound,
-        "references": references
+        "references": references,
     }
     return variables
 
-def recipe_2_Kissiov_and_McKenna_2025(adata, output_directory, binary_layers, distance_thresholds={}, reference_column = 'Reference', sample_names_col='Sample_names'):
+
+def recipe_2_Kissiov_and_McKenna_2025(
+    adata,
+    output_directory,
+    binary_layers,
+    distance_thresholds={},
+    reference_column="Reference",
+    sample_names_col="Sample_names",
+):
     """
     The second part of the preprocessing workflow applied to the adata that has already been preprocessed by recipe_1_Kissiov_and_McKenna_2025.
 
@@ -107,20 +130,32 @@ def recipe_2_Kissiov_and_McKenna_2025(adata, output_directory, binary_layers, di
         filtered_adata (AnnData): An AnnData object containing the filtered reads
         duplicates (AnnData): An AnnData object containing the duplicate reads
     """
-    import anndata as ad
-    import pandas as pd
-    import numpy as np
-    from .mark_duplicates import mark_duplicates
+
     from .calculate_complexity import calculate_complexity
+    from .mark_duplicates import mark_duplicates
     from .remove_duplicates import remove_duplicates
 
     # Add here a way to remove reads below a given read quality (based on nan content). Need to also add a way to pull from BAM files the read quality from each read
 
     # Duplicate detection using pairwise hamming distance across reads
-    mark_duplicates(adata, binary_layers, obs_column=reference_column, sample_col=sample_names_col, distance_thresholds=distance_thresholds, method='N_masked_distances')
+    mark_duplicates(
+        adata,
+        binary_layers,
+        obs_column=reference_column,
+        sample_col=sample_names_col,
+        distance_thresholds=distance_thresholds,
+        method="N_masked_distances",
+    )
 
     # Complexity analysis using the marked duplicates and the lander-watermann algorithm
-    calculate_complexity(adata, output_directory, obs_column=reference_column, sample_col=sample_names_col, plot=True, save_plot=False)
+    calculate_complexity(
+        adata,
+        output_directory,
+        obs_column=reference_column,
+        sample_col=sample_names_col,
+        plot=True,
+        save_plot=False,
+    )
 
     # Remove duplicate reads and store the duplicate reads in a new AnnData object named duplicates.
     filtered_adata, duplicates = remove_duplicates(adata)

smftools/preprocessing/reindex_references_adata.py

@@ -1,37 +1,103 @@
-## reindex_references_adata
-
-def reindex_references_adata(adata, 
-                             reference_col="Reference_strand", 
-                             offsets=None, 
-                             new_col="reindexed",
-                             uns_flag='reindex_references_adata_performed', 
-                             force_redo=False):
-    
-    # Only run if not already performed
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from smftools.logging_utils import get_logger
+
+if TYPE_CHECKING:
+    import anndata as ad
+
+logger = get_logger(__name__)
+
+
+def reindex_references_adata(
+    adata: "ad.AnnData",
+    reference_col: str = "Reference_strand",
+    offsets: dict | None = None,
+    new_col: str = "reindexed",
+    uns_flag: str = "reindex_references_adata_performed",
+    force_redo: bool = False,
+) -> None:
+    """Reindex genomic coordinates by adding per-reference offsets.
+
+    Args:
+        adata: AnnData object.
+        reference_col: Obs column containing reference identifiers.
+        offsets: Mapping of reference to integer offset.
+        new_col: Suffix for generated reindexed columns.
+        uns_flag: Flag in ``adata.uns`` indicating prior completion.
+        force_redo: Whether to rerun even if ``uns_flag`` is set.
+
+    Notes:
+        If ``offsets`` is ``None`` or missing a reference, the new column mirrors
+        the existing ``var_names`` values.
+    """
+
+    import numpy as np
+
+    # ============================================================
+    # 1. Skip if already done
+    # ============================================================
     already = bool(adata.uns.get(uns_flag, False))
-    if (already and not force_redo):
+    if already and not force_redo:
+        logger.info("%s already set; skipping. Use force_redo=True to recompute.", uns_flag)
         return None
-    
+
+    # Normalize offsets
     if offsets is None:
-        pass
-    else:
-        # Ensure var_names are numeric
+        offsets = {}
+    elif not isinstance(offsets, dict):
+        raise TypeError("offsets must be a dict {ref: int} or None.")
+
+    # ============================================================
+    # 2. Ensure var_names are numeric
+    # ============================================================
+    try:
         var_coords = adata.var_names.astype(int)
+    except Exception as e:
+        raise ValueError(
+            "reindex_references_adata requires adata.var_names to be integer-like."
+        ) from e
+
+    # ============================================================
+    # 3. Gather all references
+    # ============================================================
+    ref_series = adata.obs[reference_col]
+    references = ref_series.cat.categories if hasattr(ref_series, "cat") else ref_series.unique()
+
+    # ============================================================
+    # 4. Create reindexed columns
+    # ============================================================
+    for ref in references:
+        colname = f"{ref}_{new_col}"
+
+        # Case 1: No offset provided → identity mapping
+        if ref not in offsets:
+            logger.info("No offset for ref=%r; using identity positions.", ref)
+            adata.var[colname] = var_coords
+            continue
+
+        offset_value = offsets[ref]
 
-        for ref in adata.obs[reference_col].unique():
-            if ref not in offsets:
-                pass
-            else:
-                offset_value = offsets[ref]
+        # Case 2: offset explicitly None → identity mapping
+        if offset_value is None:
+            logger.info("Offset for ref=%r is None; using identity positions.", ref)
+            adata.var[colname] = var_coords
+            continue
 
-                # Create a new var column for this reference
-                colname = f"{ref}_{new_col}"
+        # Case 3: real shift
+        if not isinstance(offset_value, (int, np.integer)):
+            raise TypeError(
+                f"Offset for reference {ref!r} must be an integer or None. Got {offset_value!r}"
+            )
 
-                # Add offset to all var positions
-                adata.var[colname] = var_coords + offset_value
+        adata.var[colname] = var_coords + offset_value
+        logger.info("Added reindexed column '%s' (offset=%s).", colname, offset_value)
 
-    # mark as done
+    # ============================================================
+    # 5. Mark complete
+    # ============================================================
     adata.uns[uns_flag] = True
+    logger.info("Reindexing complete!")
 
-    print("Reindexing complete!")
-    return None
+    return None

smftools/preprocessing/subsample_adata.py

@@ -1,19 +1,36 @@
-def subsample_adata(adata, obs_columns=None, max_samples=2000, random_seed=42):
-    """
-    Subsamples an AnnData object so that each unique combination of categories 
-    in the given `obs_columns` has at most `max_samples` observations.
-    If `obs_columns` is None or empty, the function randomly subsamples the entire dataset.
-    
-    Parameters:
-        adata (AnnData): The AnnData object to subsample.
-        obs_columns (list of str, optional): List of observation column names to group by.
-        max_samples (int): The maximum number of observations per category combination.
-        random_seed (int): Random seed for reproducibility.
+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 subsample_adata(
+    adata: "ad.AnnData",
+    obs_columns: Sequence[str] | None = None,
+    max_samples: int = 2000,
+    random_seed: int = 42,
+) -> "ad.AnnData":
+    """Subsample an AnnData object by observation categories.
+
+    Each unique combination of categories in ``obs_columns`` is capped at
+    ``max_samples`` observations. If ``obs_columns`` is ``None``, the function
+    randomly subsamples the entire dataset.
+
+    Args:
+        adata: AnnData object to subsample.
+        obs_columns: Observation column names to group by.
+        max_samples: Maximum observations per category combination.
+        random_seed: Random seed for reproducibility.
 
     Returns:
-        AnnData: A new AnnData object with subsampled observations.
+        anndata.AnnData: Subsampled AnnData object.
     """
-    import anndata as ad
     import numpy as np
 
     np.random.seed(random_seed)  # Ensure reproducibility
@@ -23,7 +40,7 @@ def subsample_adata(adata, obs_columns=None, max_samples=2000, random_seed=42):
             sampled_indices = np.random.choice(adata.obs.index, max_samples, replace=False)
         else:
             sampled_indices = adata.obs.index  # Keep all if fewer than max_samples
-        
+
         return adata[sampled_indices].copy()
 
     sampled_indices = []
@@ -34,7 +51,7 @@ def subsample_adata(adata, obs_columns=None, max_samples=2000, random_seed=42):
     for _, row in unique_combinations.iterrows():
         # Build filter condition dynamically for multiple columns
         condition = (adata.obs[obs_columns] == row.values).all(axis=1)
-        
+
         # Get indices for the current category combination
         subset_indices = adata.obs[condition].index.to_numpy()
 
@@ -48,7 +65,7 @@ def subsample_adata(adata, obs_columns=None, max_samples=2000, random_seed=42):
 
     # ⚠ Handle backed mode detection
     if adata.isbacked:
-        print("⚠ Detected backed mode. Subset will be loaded fully into memory.")
+        logger.warning("Detected backed mode. Subset will be loaded fully into memory.")
         subset = adata[sampled_indices]
         subset = subset.to_memory()
     else: