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

smftools/preprocessing/calculate_read_modification_stats.py

@@ -1,62 +1,92 @@
-def calculate_read_modification_stats(adata, 
-                                      reference_column, 
-                                      sample_names_col, 
-                                      mod_target_bases,
-                                      uns_flag="calculate_read_modification_stats_performed",
-                                      bypass=False,
-                                      force_redo=False
-):
-    """
-    Adds methylation/deamination statistics for each read. 
-    Indicates the read GpC and CpG methylation ratio to other_C methylation (background false positive metric for Cytosine MTase SMF).
+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 adata object
-        reference_column (str): String representing the name of the Reference column to use
-        sample_names_col (str): String representing the name of the sample name column to use
-        mod_target_bases:
+logger = get_logger(__name__)
 
-    Returns:
-        None 
+
+def calculate_read_modification_stats(
+    adata: "ad.AnnData",
+    reference_column: str,
+    sample_names_col: str,
+    mod_target_bases: list[str],
+    uns_flag: str = "calculate_read_modification_stats_performed",
+    bypass: bool = False,
+    force_redo: bool = False,
+    valid_sites_only: bool = False,
+    valid_site_suffix: str = "_valid_coverage",
+) -> None:
+    """Add methylation/deamination statistics for each read.
+
+    Args:
+        adata: AnnData object.
+        reference_column: Obs column containing reference identifiers.
+        sample_names_col: Obs column containing sample identifiers.
+        mod_target_bases: List of target base contexts (e.g., ``["GpC", "CpG"]``).
+        uns_flag: Flag in ``adata.uns`` indicating prior completion.
+        bypass: Whether to skip processing.
+        force_redo: Whether to rerun even if ``uns_flag`` is set.
+        valid_sites_only: Whether to restrict to valid coverage sites.
+        valid_site_suffix: Suffix used for valid-site matrices.
     """
     import numpy as np
-    import anndata as ad
     import pandas as pd
 
+    if valid_sites_only:
+        if adata.uns.get("calculate_coverage_performed", False):
+            pass
+        else:
+            valid_sites_only = False
+
+    if not valid_sites_only:
+        valid_site_suffix = ""
+
     # Only run if not already performed
     already = bool(adata.uns.get(uns_flag, False))
     if (already and not force_redo) or bypass:
         # QC already performed; nothing to do
         return
 
-    print('Calculating read level Modification statistics')
+    logger.info("Calculating read level Modification statistics")
 
     references = set(adata.obs[reference_column])
     sample_names = set(adata.obs[sample_names_col])
     site_types = []
 
-    if any(base in mod_target_bases for base in ['GpC', 'CpG', 'C']):
-        site_types += ['GpC_site', 'CpG_site', 'ambiguous_GpC_CpG_site', 'other_C_site', 'C_site']
-    
-    if 'A' in mod_target_bases:
-        site_types += ['A_site']
+    if any(base in mod_target_bases for base in ["GpC", "CpG", "C"]):
+        site_types += ["GpC_site", "CpG_site", "ambiguous_GpC_CpG_site", "other_C_site", "C_site"]
 
-    for site_type in site_types:
-        adata.obs[f'Modified_{site_type}_count'] = pd.Series(0, index=adata.obs_names, dtype=int)
-        adata.obs[f'Total_{site_type}_in_read'] = pd.Series(0, index=adata.obs_names, dtype=int)
-        adata.obs[f'Fraction_{site_type}_modified'] = pd.Series(np.nan, index=adata.obs_names, dtype=float)
-        adata.obs[f'Total_{site_type}_in_reference'] = pd.Series(np.nan, index=adata.obs_names, dtype=int)
-        adata.obs[f'Valid_{site_type}_in_read_vs_reference'] = pd.Series(np.nan, index=adata.obs_names, dtype=float)
+    if "A" in mod_target_bases:
+        site_types += ["A_site"]
 
+    for site_type in site_types:
+        adata.obs[f"Modified_{site_type}_count"] = pd.Series(0, index=adata.obs_names, dtype=int)
+        adata.obs[f"Total_{site_type}_in_read"] = pd.Series(0, index=adata.obs_names, dtype=int)
+        adata.obs[f"Fraction_{site_type}_modified"] = pd.Series(
+            np.nan, index=adata.obs_names, dtype=float
+        )
+        adata.obs[f"Total_{site_type}_in_reference"] = pd.Series(
+            np.nan, index=adata.obs_names, dtype=int
+        )
+        adata.obs[f"Valid_{site_type}_in_read_vs_reference"] = pd.Series(
+            np.nan, index=adata.obs_names, dtype=float
+        )
 
     for ref in references:
         ref_subset = adata[adata.obs[reference_column] == ref]
         for site_type in site_types:
-            print(f'Iterating over {ref}_{site_type}')
-            observation_matrix = ref_subset.obsm[f'{ref}_{site_type}']
+            logger.info("Iterating over %s_%s", ref, site_type)
+            observation_matrix = ref_subset.obsm[f"{ref}_{site_type}{valid_site_suffix}"]
             total_positions_in_read = np.nansum(~np.isnan(observation_matrix), axis=1)
             total_positions_in_reference = observation_matrix.shape[1]
-            fraction_valid_positions_in_read_vs_ref = total_positions_in_read / total_positions_in_reference
+            fraction_valid_positions_in_read_vs_ref = (
+                total_positions_in_read / total_positions_in_reference
+            )
             number_mods_in_read = np.nansum(observation_matrix, axis=1)
             fraction_modified = number_mods_in_read / total_positions_in_read
 
@@ -64,38 +94,42 @@ def calculate_read_modification_stats(adata,
                 number_mods_in_read,
                 total_positions_in_read,
                 out=np.full_like(number_mods_in_read, np.nan, dtype=float),
-                where=total_positions_in_read != 0
+                where=total_positions_in_read != 0,
+            )
+
+            temp_obs_data = pd.DataFrame(
+                {
+                    f"Total_{site_type}_in_read": total_positions_in_read,
+                    f"Modified_{site_type}_count": number_mods_in_read,
+                    f"Fraction_{site_type}_modified": fraction_modified,
+                    f"Total_{site_type}_in_reference": total_positions_in_reference,
+                    f"Valid_{site_type}_in_read_vs_reference": fraction_valid_positions_in_read_vs_ref,
+                },
+                index=ref_subset.obs.index,
             )
 
-            temp_obs_data = pd.DataFrame({f'Total_{site_type}_in_read': total_positions_in_read,
-                                        f'Modified_{site_type}_count': number_mods_in_read,
-                                        f'Fraction_{site_type}_modified': fraction_modified,
-                                        f'Total_{site_type}_in_reference': total_positions_in_reference,
-                                        f'Valid_{site_type}_in_read_vs_reference': fraction_valid_positions_in_read_vs_ref}, 
-                                        index=ref_subset.obs.index)
-            
             adata.obs.update(temp_obs_data)
 
-    if any(base in mod_target_bases for base in ['GpC', 'CpG', 'C']):
-        with np.errstate(divide='ignore', invalid='ignore'):
+    if any(base in mod_target_bases for base in ["GpC", "CpG", "C"]):
+        with np.errstate(divide="ignore", invalid="ignore"):
             gpc_to_c_ratio = np.divide(
-                adata.obs[f'Fraction_GpC_site_modified'],
-                adata.obs[f'Fraction_other_C_site_modified'],
-                out=np.full_like(adata.obs[f'Fraction_GpC_site_modified'], np.nan, dtype=float),
-                where=adata.obs[f'Fraction_other_C_site_modified'] != 0
+                adata.obs["Fraction_GpC_site_modified"],
+                adata.obs["Fraction_other_C_site_modified"],
+                out=np.full_like(adata.obs["Fraction_GpC_site_modified"], np.nan, dtype=float),
+                where=adata.obs["Fraction_other_C_site_modified"] != 0,
             )
 
             cpg_to_c_ratio = np.divide(
-                adata.obs[f'Fraction_CpG_site_modified'],
-                adata.obs[f'Fraction_other_C_site_modified'],
-                out=np.full_like(adata.obs[f'Fraction_CpG_site_modified'], np.nan, dtype=float),
-                where=adata.obs[f'Fraction_other_C_site_modified'] != 0
-                )
-            
-        adata.obs['GpC_to_other_C_mod_ratio'] = gpc_to_c_ratio
-        adata.obs['CpG_to_other_C_mod_ratio'] = cpg_to_c_ratio
+                adata.obs["Fraction_CpG_site_modified"],
+                adata.obs["Fraction_other_C_site_modified"],
+                out=np.full_like(adata.obs["Fraction_CpG_site_modified"], np.nan, dtype=float),
+                where=adata.obs["Fraction_other_C_site_modified"] != 0,
+            )
+
+        adata.obs["GpC_to_other_C_mod_ratio"] = gpc_to_c_ratio
+        adata.obs["CpG_to_other_C_mod_ratio"] = cpg_to_c_ratio
 
     # mark as done
     adata.uns[uns_flag] = True
 
-    return
+    return

smftools/preprocessing/clean_NaN.py

@@ -1,23 +1,33 @@
-def clean_NaN(adata, 
-            layer=None,
-            uns_flag='clean_NaN_performed',
-            bypass=False,
-            force_redo=True
-):
-    """
-    Append layers to adata that contain NaN cleaning strategies.
+from __future__ import annotations
 
-    Parameters:
-        adata (AnnData): an anndata object
-        layer (str, optional): Name of the layer to fill NaN values in. If None, uses adata.X.
+from typing import TYPE_CHECKING
 
-    Modifies:
-        - Adds new layers to `adata.layers` with different NaN-filling strategies.
-    """
-    import numpy as np
-    import pandas as pd
+from smftools.logging_utils import get_logger
+
+if TYPE_CHECKING:
     import anndata as ad
-    from ..readwrite import adata_to_df 
+
+logger = get_logger(__name__)
+
+
+def clean_NaN(
+    adata: "ad.AnnData",
+    layer: str | None = None,
+    uns_flag: str = "clean_NaN_performed",
+    bypass: bool = False,
+    force_redo: bool = True,
+) -> None:
+    """Append layers to ``adata`` that contain NaN-cleaning strategies.
+
+    Args:
+        adata: AnnData object.
+        layer: Layer to fill NaN values in. If ``None``, uses ``adata.X``.
+        uns_flag: Flag in ``adata.uns`` indicating prior completion.
+        bypass: Whether to skip processing.
+        force_redo: Whether to rerun even if ``uns_flag`` is set.
+    """
+
+    from ..readwrite import adata_to_df
 
     # Only run if not already performed
     already = bool(adata.uns.get(uns_flag, False))
@@ -33,30 +43,30 @@ def clean_NaN(adata,
     df = adata_to_df(adata, layer=layer)
 
     # Fill NaN with closest SMF value (forward then backward fill)
-    print('Making layer: fill_nans_closest')
-    adata.layers['fill_nans_closest'] = df.ffill(axis=1).bfill(axis=1).values
+    logger.info("Making layer: fill_nans_closest")
+    adata.layers["fill_nans_closest"] = df.ffill(axis=1).bfill(axis=1).values
 
     # Replace NaN with 0, and 0 with -1
-    print('Making layer: nan0_0minus1')
+    logger.info("Making layer: nan0_0minus1")
     df_nan0_0minus1 = df.replace(0, -1).fillna(0)
-    adata.layers['nan0_0minus1'] = df_nan0_0minus1.values
+    adata.layers["nan0_0minus1"] = df_nan0_0minus1.values
 
     # Replace NaN with 1, and 1 with 2
-    print('Making layer: nan1_12')
+    logger.info("Making layer: nan1_12")
     df_nan1_12 = df.replace(1, 2).fillna(1)
-    adata.layers['nan1_12'] = df_nan1_12.values
+    adata.layers["nan1_12"] = df_nan1_12.values
 
     # Replace NaN with -1
-    print('Making layer: nan_minus_1')
+    logger.info("Making layer: nan_minus_1")
     df_nan_minus_1 = df.fillna(-1)
-    adata.layers['nan_minus_1'] = df_nan_minus_1.values
+    adata.layers["nan_minus_1"] = df_nan_minus_1.values
 
     # Replace NaN with -1
-    print('Making layer: nan_half')
+    logger.info("Making layer: nan_half")
     df_nan_half = df.fillna(0.5)
-    adata.layers['nan_half'] = df_nan_half.values
+    adata.layers["nan_half"] = df_nan_half.values
 
     # mark as done
     adata.uns[uns_flag] = True
 
-    return None
+    return None

smftools/preprocessing/filter_adata_by_nan_proportion.py

@@ -1,26 +1,38 @@
 ## filter_adata_by_nan_proportion
 
-def filter_adata_by_nan_proportion(adata, threshold, axis='obs'):
-    """
-    Filters an anndata object on a nan proportion threshold in a given matrix axis.
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import anndata as ad
+
+
+def filter_adata_by_nan_proportion(
+    adata: "ad.AnnData", threshold: float, axis: str = "obs"
+) -> "ad.AnnData":
+    """Filter an AnnData object on NaN proportion in a matrix axis.
+
+    Args:
+        adata: AnnData object to filter.
+        threshold: Maximum allowed NaN proportion.
+        axis: Whether to filter based on ``"obs"`` or ``"var"`` NaN content.
 
-    Parameters:
-        adata (AnnData):
-        threshold (float): The max np.nan content to allow in the given axis.
-        axis (str): Whether to filter the adata based on obs or var np.nan content
     Returns:
-        filtered_adata
+        anndata.AnnData: Filtered AnnData object.
+
+    Raises:
+        ValueError: If ``axis`` is not ``"obs"`` or ``"var"``.
     """
     import numpy as np
-    import anndata as ad
 
-    if axis == 'obs':
+    if axis == "obs":
         # Calculate the proportion of NaN values in each read
         nan_proportion = np.isnan(adata.X).mean(axis=1)
         # Filter reads to keep reads with less than a certain NaN proportion
         filtered_indices = np.where(nan_proportion <= threshold)[0]
         filtered_adata = adata[filtered_indices, :].copy()
-    elif axis == 'var':
+    elif axis == "var":
         # Calculate the proportion of NaN values at a given position
         nan_proportion = np.isnan(adata.X).mean(axis=0)
         # Filter positions to keep positions with less than a certain NaN proportion
@@ -28,4 +40,4 @@ def filter_adata_by_nan_proportion(adata, threshold, axis='obs'):
         filtered_adata = adata[:, filtered_indices].copy()
     else:
         raise ValueError("Axis must be either 'obs' or 'var'")
-    return filtered_adata
+    return filtered_adata

smftools/preprocessing/filter_reads_on_length_quality_mapping.py

@@ -1,28 +1,43 @@
-from typing import Optional, Union, Sequence
+from __future__ import annotations
+
+from typing import Optional, Sequence, Union
+
+import anndata as ad
 import numpy as np
 import pandas as pd
-import anndata as ad
+
+from smftools.logging_utils import get_logger
+
+logger = get_logger(__name__)
+
 
 def filter_reads_on_length_quality_mapping(
     adata: ad.AnnData,
     filter_on_coordinates: Union[bool, Sequence] = False,
     # New single-range params (preferred):
-    read_length: Optional[Sequence[float]] = None,          # e.g. [min, max]
-    length_ratio: Optional[Sequence[float]] = None,         # e.g. [min, max]
-    read_quality: Optional[Sequence[float]] = None,         # e.g. [min, max]  (commonly min only)
-    mapping_quality: Optional[Sequence[float]] = None,      # e.g. [min, max]  (commonly min only)
+    read_length: Optional[Sequence[float]] = None,  # e.g. [min, max]
+    length_ratio: Optional[Sequence[float]] = None,  # e.g. [min, max]
+    read_quality: Optional[Sequence[float]] = None,  # e.g. [min, max]  (commonly min only)
+    mapping_quality: Optional[Sequence[float]] = None,  # e.g. [min, max]  (commonly min only)
     uns_flag: str = "filter_reads_on_length_quality_mapping_performed",
     bypass: bool = False,
-    force_redo: bool = True
+    force_redo: bool = True,
 ) -> ad.AnnData:
-    """
-    Filter AnnData by coordinate window, read length, length ratios, read quality and mapping quality.
-
-    New: you may pass `read_length=[min, max]` (or tuple) to set both min/max in one argument.
-    If `read_length` is given it overrides scalar min/max variants (which are not present in this signature).
-    Same behavior supported for `length_ratio`, `read_quality`, `mapping_quality`.
-
-    Returns a filtered copy of the input AnnData and marks adata.uns[uns_flag] = True.
+    """Filter AnnData by coordinates, read length, quality, and mapping metrics.
+
+    Args:
+        adata: AnnData object to filter.
+        filter_on_coordinates: Optional coordinate window as a two-value sequence.
+        read_length: Read length range as ``[min, max]``.
+        length_ratio: Length ratio range as ``[min, max]``.
+        read_quality: Read quality range as ``[min, max]``.
+        mapping_quality: Mapping quality range as ``[min, max]``.
+        uns_flag: Flag in ``adata.uns`` indicating prior completion.
+        bypass: Whether to skip processing.
+        force_redo: Whether to rerun even if ``uns_flag`` is set.
+
+    Returns:
+        anndata.AnnData: Filtered copy of the input AnnData.
     """
     # early exit
     already = bool(adata.uns.get(uns_flag, False))
@@ -37,7 +52,9 @@ def filter_reads_on_length_quality_mapping(
         try:
             low, high = tuple(filter_on_coordinates)
         except Exception:
-            raise ValueError("filter_on_coordinates must be False or an iterable of two numbers (low, high).")
+            raise ValueError(
+                "filter_on_coordinates must be False or an iterable of two numbers (low, high)."
+            )
         try:
             var_coords = np.array([float(v) for v in adata_work.var_names])
             if low > high:
@@ -50,10 +67,17 @@ def filter_reads_on_length_quality_mapping(
                 selected_cols = list(adata_work.var_names[lo_idx : hi_idx + 1])
             else:
                 selected_cols = list(adata_work.var_names[col_mask_bool])
-            print(f"Subsetting adata to coordinates between {low} and {high}: keeping {len(selected_cols)} variables.")
+            logger.info(
+                "Subsetting adata to coordinates between %s and %s: keeping %s variables.",
+                low,
+                high,
+                len(selected_cols),
+            )
             adata_work = adata_work[:, selected_cols].copy()
         except Exception:
-            print("Warning: could not interpret adata.var_names as numeric coordinates — skipping coordinate filtering.")
+            logger.warning(
+                "Could not interpret adata.var_names as numeric coordinates — skipping coordinate filtering."
+            )
 
     # --- helper to coerce range inputs ---
     def _coerce_range(range_arg):
@@ -85,72 +109,83 @@ def filter_reads_on_length_quality_mapping(
     # read length filter
     if (rl_min is not None) or (rl_max is not None):
         if "mapped_length" not in adata_work.obs.columns:
-            print("Warning: 'mapped_length' not found in adata.obs — skipping read_length filter.")
+            logger.warning("'mapped_length' not found in adata.obs — skipping read_length filter.")
         else:
             vals = pd.to_numeric(adata_work.obs["mapped_length"], errors="coerce")
             mask = pd.Series(True, index=adata_work.obs.index)
             if rl_min is not None:
-                mask &= (vals >= rl_min)
+                mask &= vals >= rl_min
             if rl_max is not None:
-                mask &= (vals <= rl_max)
+                mask &= vals <= rl_max
             mask &= vals.notna()
             combined_mask &= mask
-            print(f"Planned read_length filter: min={rl_min}, max={rl_max}")
+            logger.info("Planned read_length filter: min=%s, max=%s", rl_min, rl_max)
 
     # length ratio filter
     if (lr_min is not None) or (lr_max is not None):
         if "mapped_length_to_reference_length_ratio" not in adata_work.obs.columns:
-            print("Warning: 'mapped_length_to_reference_length_ratio' not found in adata.obs — skipping length_ratio filter.")
+            logger.warning(
+                "'mapped_length_to_reference_length_ratio' not found in adata.obs — skipping length_ratio filter."
+            )
         else:
-            vals = pd.to_numeric(adata_work.obs["mapped_length_to_reference_length_ratio"], errors="coerce")
+            vals = pd.to_numeric(
+                adata_work.obs["mapped_length_to_reference_length_ratio"], errors="coerce"
+            )
             mask = pd.Series(True, index=adata_work.obs.index)
             if lr_min is not None:
-                mask &= (vals >= lr_min)
+                mask &= vals >= lr_min
             if lr_max is not None:
-                mask &= (vals <= lr_max)
+                mask &= vals <= lr_max
             mask &= vals.notna()
             combined_mask &= mask
-            print(f"Planned length_ratio filter: min={lr_min}, max={lr_max}")
+            logger.info("Planned length_ratio filter: min=%s, max=%s", lr_min, lr_max)
 
     # read quality filter (supporting optional range but typically min only)
     if (rq_min is not None) or (rq_max is not None):
         if "read_quality" not in adata_work.obs.columns:
-            print("Warning: 'read_quality' not found in adata.obs — skipping read_quality filter.")
+            logger.warning("'read_quality' not found in adata.obs — skipping read_quality filter.")
         else:
             vals = pd.to_numeric(adata_work.obs["read_quality"], errors="coerce")
             mask = pd.Series(True, index=adata_work.obs.index)
             if rq_min is not None:
-                mask &= (vals >= rq_min)
+                mask &= vals >= rq_min
             if rq_max is not None:
-                mask &= (vals <= rq_max)
+                mask &= vals <= rq_max
             mask &= vals.notna()
             combined_mask &= mask
-            print(f"Planned read_quality filter: min={rq_min}, max={rq_max}")
+            logger.info("Planned read_quality filter: min=%s, max=%s", rq_min, rq_max)
 
     # mapping quality filter (supporting optional range but typically min only)
     if (mq_min is not None) or (mq_max is not None):
         if "mapping_quality" not in adata_work.obs.columns:
-            print("Warning: 'mapping_quality' not found in adata.obs — skipping mapping_quality filter.")
+            logger.warning(
+                "'mapping_quality' not found in adata.obs — skipping mapping_quality filter."
+            )
         else:
             vals = pd.to_numeric(adata_work.obs["mapping_quality"], errors="coerce")
             mask = pd.Series(True, index=adata_work.obs.index)
             if mq_min is not None:
-                mask &= (vals >= mq_min)
+                mask &= vals >= mq_min
             if mq_max is not None:
-                mask &= (vals <= mq_max)
+                mask &= vals <= mq_max
             mask &= vals.notna()
             combined_mask &= mask
-            print(f"Planned mapping_quality filter: min={mq_min}, max={mq_max}")
+            logger.info("Planned mapping_quality filter: min=%s, max=%s", mq_min, mq_max)
 
     # Apply combined mask and report
     s0 = adata_work.n_obs
     combined_mask_bool = combined_mask.astype(bool).values
     adata_work = adata_work[combined_mask_bool].copy()
     s1 = adata_work.n_obs
-    print(f"Combined filters applied: kept {s1} / {s0} reads (removed {s0 - s1})")
+    logger.info("Combined filters applied: kept %s / %s reads (removed %s)", s1, s0, s0 - s1)
 
     final_n = adata_work.n_obs
-    print(f"Filtering complete: start={start_n}, final={final_n}, removed={start_n - final_n}")
+    logger.info(
+        "Filtering complete: start=%s, final=%s, removed=%s",
+        start_n,
+        final_n,
+        start_n - final_n,
+    )
 
     # mark as done
     adata_work.uns[uns_flag] = True