smftools 0.1.6__py3-none-any.whl → 0.2.1__py3-none-any.whl

smftools/preprocessing/calculate_position_Youden.py

@@ -0,0 +1,115 @@
+## calculate_position_Youden
+
+## Calculating and applying position level thresholds for methylation calls to binarize the SMF data
+def calculate_position_Youden(adata, positive_control_sample='positive', negative_control_sample='negative', J_threshold=0.5, obs_column='Reference', infer_on_percentile=False, inference_variable='', save=False, output_directory=''):
+    """
+    Adds new variable metadata to each position indicating whether the position provides reliable SMF methylation calls. Also outputs plots of the positional ROC curves.
+
+    Parameters:
+        adata (AnnData): An AnnData object.
+        positive_control_sample (str): string representing the sample name corresponding to the Plus MTase control sample.
+        negative_control_sample (str): string representing the sample name corresponding to the Minus MTase control sample.
+        J_threshold (float): A float indicating the J-statistic used to indicate whether a position passes QC for methylation calls.
+        obs_column (str): The category to iterate over.
+        infer_on_perdentile (bool | int): If False, use defined postive and negative control samples. If an int (0 < int < 100) is passed, this uses the top and bottom int percentile of methylated reads based on metric in inference_variable column.
+        inference_variable (str): If infer_on_percentile has an integer value passed, use the AnnData observation column name passed by this string as the metric.
+        save (bool): Whether to save the ROC plots.
+        output_directory (str): String representing the path to the output directory to output the ROC curves.
+    
+    Returns: 
+        None
+    """
+    import numpy as np
+    import pandas as pd
+    import anndata as ad
+    import matplotlib.pyplot as plt
+    from sklearn.metrics import roc_curve, roc_auc_score
+
+    control_samples = [positive_control_sample, negative_control_sample]
+    categories = adata.obs[obs_column].cat.categories 
+    # Iterate over each category in the specified obs_column
+    for cat in categories:
+        print(f"Calculating position Youden statistics for {cat}")
+        # Subset to keep only reads associated with the category
+        cat_subset = adata[adata.obs[obs_column] == cat]
+        # Iterate over positive and negative control samples
+        for control in control_samples:
+            # Initialize a dictionary for the given control sample. This will be keyed by dataset and position to point to a tuple of coordinate position and an array of methylation probabilities
+            adata.uns[f'{cat}_position_methylation_dict_{control}'] = {}
+            if infer_on_percentile:
+                sorted_column = cat_subset.obs[inference_variable].sort_values(ascending=False)
+                if control == "positive":
+                    threshold = np.percentile(sorted_column, 100 - infer_on_percentile)
+                    control_subset = cat_subset[cat_subset.obs[inference_variable] >= threshold, :]
+                else:
+                    threshold = np.percentile(sorted_column, infer_on_percentile)
+                    control_subset = cat_subset[cat_subset.obs[inference_variable] <= threshold, :]   
+            else:
+                # get the current control subset on the given category
+                filtered_obs = cat_subset.obs[cat_subset.obs['Sample_names'].str.contains(control, na=False, regex=True)]
+                control_subset = cat_subset[filtered_obs.index]
+            # Iterate through every position in the control subset
+            for position in range(control_subset.shape[1]):
+                # Get the coordinate name associated with that position
+                coordinate = control_subset.var_names[position]
+                # Get the array of methlyation probabilities for each read in the subset at that position
+                position_data = control_subset.X[:, position]
+                # Get the indexes of everywhere that is not a nan value
+                nan_mask = ~np.isnan(position_data)
+                # Keep only the methlyation data that has real values
+                position_data = position_data[nan_mask]
+                # Get the position data coverage
+                position_coverage = len(position_data)
+                # Get fraction coverage
+                fraction_coverage = position_coverage / control_subset.shape[0]
+                # Save the position and the position methylation data for the control subset
+                adata.uns[f'{cat}_position_methylation_dict_{control}'][f'{position}'] = (position, position_data, fraction_coverage)
+
+    for cat in categories:
+        fig, ax = plt.subplots(figsize=(6, 4))
+        plt.plot([0, 1], [0, 1], linestyle='--', color='gray')
+        plt.xlabel('False Positive Rate')
+        plt.ylabel('True Positive Rate')
+        ax.spines['right'].set_visible(False)
+        ax.spines['top'].set_visible(False)
+        n_passed_positions = 0
+        n_total_positions = 0
+        # Initialize a list that will hold the positional thresholds for the category
+        probability_thresholding_list = [(np.nan, np.nan)] * adata.shape[1]
+        for i, key in enumerate(adata.uns[f'{cat}_position_methylation_dict_{positive_control_sample}'].keys()):
+            position = int(adata.uns[f'{cat}_position_methylation_dict_{positive_control_sample}'][key][0])
+            positive_position_array = adata.uns[f'{cat}_position_methylation_dict_{positive_control_sample}'][key][1]
+            fraction_coverage = adata.uns[f'{cat}_position_methylation_dict_{positive_control_sample}'][key][2]
+            if fraction_coverage > 0.2:
+                try:
+                    negative_position_array = adata.uns[f'{cat}_position_methylation_dict_{negative_control_sample}'][key][1] 
+                    # Combine the negative and positive control data
+                    data = np.concatenate([negative_position_array, positive_position_array])
+                    labels = np.array([0] * len(negative_position_array) + [1] * len(positive_position_array))
+                    # Calculate the ROC curve
+                    fpr, tpr, thresholds = roc_curve(labels, data)
+                    # Calculate Youden's J statistic
+                    J = tpr - fpr
+                    optimal_idx = np.argmax(J)
+                    optimal_threshold = thresholds[optimal_idx]
+                    max_J = np.max(J)
+                    data_tuple = (optimal_threshold, max_J)
+                    probability_thresholding_list[position] = data_tuple
+                    n_total_positions += 1
+                    if max_J > J_threshold:
+                        n_passed_positions += 1
+                        plt.plot(fpr, tpr, label='ROC curve')
+                except:
+                    probability_thresholding_list[position] = (0.8, np.nan)
+        title = f'ROC Curve for {n_passed_positions} positions with J-stat greater than {J_threshold}\n out of {n_total_positions} total positions on {cat}'
+        plt.title(title)
+        save_name = output_directory + f'/{title}'
+        if save:
+            plt.savefig(save_name)
+            plt.close()
+        else:
+            plt.show()   
+
+        adata.var[f'{cat}_position_methylation_thresholding_Youden_stats'] = probability_thresholding_list
+        J_max_list = [probability_thresholding_list[i][1] for i in range(adata.shape[1])]
+        adata.var[f'{cat}_position_passed_QC'] = [True if i > J_threshold else False for i in J_max_list]

smftools/preprocessing/calculate_read_length_stats.py

@@ -0,0 +1,79 @@
+## calculate_read_length_stats
+
+# Read length QC
+def calculate_read_length_stats(adata, reference_column='', sample_names_col=''):
+    """
+    Append first valid position in a read and last valid position in the read. From this determine and append the read length. 
+
+    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
+    
+    Returns:
+        upper_bound (int): last valid position in the dataset
+        lower_bound (int): first valid position in the dataset
+    """
+    import numpy as np
+    import anndata as ad
+    import pandas as pd
+
+    print('Calculating read length statistics')
+
+    references = set(adata.obs[reference_column])
+    sample_names = set(adata.obs[sample_names_col])
+
+    ## Add basic observation-level (read-level) metadata to the object: first valid position in a read and last valid position in the read. From this determine the read length. Save two new variable which hold the first and last valid positions in the entire dataset
+    print('calculating read length stats')
+    # Add some basic observation-level (read-level) metadata to the anndata object
+    read_first_valid_position = np.array([int(adata.var_names[i]) for i in np.argmax(~np.isnan(adata.X), axis=1)])
+    read_last_valid_position = np.array([int(adata.var_names[i]) for i in (adata.X.shape[1] - 1 - np.argmax(~np.isnan(adata.X[:, ::-1]), axis=1))])
+    read_length = read_last_valid_position - read_first_valid_position + np.ones(len(read_first_valid_position))
+
+    adata.obs['first_valid_position'] = pd.Series(read_first_valid_position, index=adata.obs.index, dtype=int)
+    adata.obs['last_valid_position'] = pd.Series(read_last_valid_position, index=adata.obs.index, dtype=int)
+    adata.obs['read_length'] = pd.Series(read_length, index=adata.obs.index, dtype=int)
+
+    # Define variables to hold the first and last valid position in the dataset
+    upper_bound = int(np.nanmax(adata.obs['last_valid_position']))
+    lower_bound = int(np.nanmin(adata.obs['first_valid_position']))
+
+    return upper_bound, lower_bound
+
+# # Add an unstructured element to the anndata object which points to a dictionary of read lengths keyed by reference and sample name. Points to a tuple containing (mean, median, stdev) of the read lengths of the sample for the given reference strand
+#     ## Plot histogram of read length data and save the median and stdev of the read lengths for each sample.
+#     adata.uns['read_length_dict'] = {}
+
+#     for reference in references:
+#         temp_reference_adata = adata[adata.obs[reference_column] == reference].copy()
+#         split_reference = reference.split('_')[0][1:]
+#         for sample in sample_names:
+#             temp_sample_adata = temp_reference_adata[temp_reference_adata.obs[sample_names_col] == sample].copy()
+#             temp_data = temp_sample_adata.obs['read_length']
+#             max_length = np.max(temp_data)
+#             mean = np.mean(temp_data)
+#             median = np.median(temp_data)
+#             stdev = np.std(temp_data)
+#             adata.uns['read_length_dict'][f'{reference}_{sample}'] = [mean, median, stdev]
+#             if not np.isnan(max_length):
+#                 n_bins = int(max_length // 100)
+#             else:
+#                 n_bins = 1
+#             if show_read_length_histogram or save_read_length_histogram:
+#                 plt.figure(figsize=(10, 6))
+#                 plt.text(median + 0.5, max(plt.hist(temp_data, bins=n_bins)[0]) / 2, f'Median: {median:.2f}', color='red')
+#                 plt.hist(temp_data, bins=n_bins, alpha=0.7, color='blue', edgecolor='black')
+#                 plt.xlabel('Read Length')
+#                 plt.ylabel('Count')
+#                 title = f'Read length distribution of {temp_sample_adata.shape[0]} total reads from {sample} sample on {split_reference} allele'
+#                 plt.title(title)
+#                 # Add a vertical line at the median
+#                 plt.axvline(median, color='red', linestyle='dashed', linewidth=1)
+#                 # Annotate the median
+#                 plt.xlim(lower_bound - 100, upper_bound + 100) 
+#                 if save_read_length_histogram:
+#                     save_name = output_directory + f'/{readwrite.date_string()} {title}'
+#                     plt.savefig(save_name, bbox_inches='tight', pad_inches=0.1)
+#                     plt.close()
+#                 else:
+#                     plt.show()

smftools/preprocessing/calculate_read_modification_stats.py

@@ -0,0 +1,101 @@
+def calculate_read_modification_stats(adata, 
+                                      reference_column, 
+                                      sample_names_col, 
+                                      mod_target_bases,
+                                      uns_flag="read_modification_stats_calculated",
+                                      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).
+
+    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:
+
+    Returns:
+        None 
+    """
+    import numpy as np
+    import anndata as ad
+    import pandas as pd
+
+    # 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')
+
+    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', 'any_C_site']
+    
+    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}']
+            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
+            number_mods_in_read = np.nansum(observation_matrix, axis=1)
+            fraction_modified = number_mods_in_read / total_positions_in_read
+
+            fraction_modified = np.divide(
+                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
+            )
+
+            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'):
+            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
+            )
+
+            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
+
+    # mark as done
+    adata.uns[uns_flag] = True
+
+    return

smftools/preprocessing/clean_NaN.py

@@ -0,0 +1,62 @@
+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.
+
+    Parameters:
+        adata (AnnData): an anndata object
+        layer (str, optional): Name of the layer to fill NaN values in. If None, uses adata.X.
+
+    Modifies:
+        - Adds new layers to `adata.layers` with different NaN-filling strategies.
+    """
+    import numpy as np
+    import pandas as pd
+    import anndata as ad
+    from ..readwrite import adata_to_df 
+
+    # 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
+
+    # Ensure the specified layer exists
+    if layer and layer not in adata.layers:
+        raise ValueError(f"Layer '{layer}' not found in adata.layers.")
+
+    # Convert to DataFrame
+    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
+
+    # Replace NaN with 0, and 0 with -1
+    print('Making layer: nan0_0minus1')
+    df_nan0_0minus1 = df.replace(0, -1).fillna(0)
+    adata.layers['nan0_0minus1'] = df_nan0_0minus1.values
+
+    # Replace NaN with 1, and 1 with 2
+    print('Making layer: nan1_12')
+    df_nan1_12 = df.replace(1, 2).fillna(1)
+    adata.layers['nan1_12'] = df_nan1_12.values
+
+    # Replace NaN with -1
+    print('Making layer: nan_minus_1')
+    df_nan_minus_1 = df.fillna(-1)
+    adata.layers['nan_minus_1'] = df_nan_minus_1.values
+
+    # Replace NaN with -1
+    print('Making layer: nan_half')
+    df_nan_half = df.fillna(0.5)
+    adata.layers['nan_half'] = df_nan_half.values
+
+    # mark as done
+    adata.uns[uns_flag] = True
+
+    return None

smftools/preprocessing/filter_adata_by_nan_proportion.py

@@ -0,0 +1,31 @@
+## 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.
+
+    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
+    """
+    import numpy as np
+    import anndata as ad
+
+    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':
+        # 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
+        filtered_indices = np.where(nan_proportion <= threshold)[0]
+        filtered_adata = adata[:, filtered_indices].copy()
+    else:
+        raise ValueError("Axis must be either 'obs' or 'var'")
+    return filtered_adata

smftools/preprocessing/filter_reads_on_length_quality_mapping.py

@@ -0,0 +1,158 @@
+from typing import Optional, Union, Sequence
+import numpy as np
+import pandas as pd
+import anndata as ad
+
+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)
+    uns_flag: str = "reads_removed_failing_length_quality_mapping_qc",
+    bypass: bool = False,
+    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.
+    """
+    # early exit
+    already = bool(adata.uns.get(uns_flag, False))
+    if bypass or (already and not force_redo):
+        return adata
+
+    adata_work = adata
+    start_n = adata_work.n_obs
+
+    # --- coordinate filtering (unchanged) ---
+    if filter_on_coordinates:
+        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).")
+        try:
+            var_coords = np.array([float(v) for v in adata_work.var_names])
+            if low > high:
+                low, high = high, low
+            col_mask_bool = (var_coords >= float(low)) & (var_coords <= float(high))
+            if not col_mask_bool.any():
+                start_idx = int(np.argmin(np.abs(var_coords - float(low))))
+                end_idx = int(np.argmin(np.abs(var_coords - float(high))))
+                lo_idx, hi_idx = min(start_idx, end_idx), max(start_idx, end_idx)
+                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.")
+            adata_work = adata_work[:, selected_cols].copy()
+        except Exception:
+            print("Warning: could not interpret adata.var_names as numeric coordinates — skipping coordinate filtering.")
+
+    # --- helper to coerce range inputs ---
+    def _coerce_range(range_arg):
+        """
+        Given range_arg which may be None or a 2-seq [min,max], return (min_or_None, max_or_None).
+        If both present and min>max they are swapped.
+        """
+        if range_arg is None:
+            return None, None
+        if not isinstance(range_arg, (list, tuple, np.ndarray)) or len(range_arg) != 2:
+            # not a 2-element range -> treat as no restriction (or you could raise)
+            return None, None
+        lo_raw, hi_raw = range_arg[0], range_arg[1]
+        lo = None if lo_raw is None else float(lo_raw)
+        hi = None if hi_raw is None else float(hi_raw)
+        if (lo is not None) and (hi is not None) and lo > hi:
+            lo, hi = hi, lo
+        return lo, hi
+
+    # Resolve ranges using only the provided range arguments
+    rl_min, rl_max = _coerce_range(read_length)
+    lr_min, lr_max = _coerce_range(length_ratio)
+    rq_min, rq_max = _coerce_range(read_quality)
+    mq_min, mq_max = _coerce_range(mapping_quality)
+
+    # --- build combined mask ---
+    combined_mask = pd.Series(True, index=adata_work.obs.index)
+
+    # 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.")
+        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)
+            if rl_max is not None:
+                mask &= (vals <= rl_max)
+            mask &= vals.notna()
+            combined_mask &= mask
+            print(f"Planned read_length filter: min={rl_min}, max={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.")
+        else:
+            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)
+            if lr_max is not None:
+                mask &= (vals <= lr_max)
+            mask &= vals.notna()
+            combined_mask &= mask
+            print(f"Planned length_ratio filter: min={lr_min}, max={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.")
+        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)
+            if rq_max is not None:
+                mask &= (vals <= rq_max)
+            mask &= vals.notna()
+            combined_mask &= mask
+            print(f"Planned read_quality filter: min={rq_min}, max={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.")
+        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)
+            if mq_max is not None:
+                mask &= (vals <= mq_max)
+            mask &= vals.notna()
+            combined_mask &= mask
+            print(f"Planned mapping_quality filter: min={mq_min}, max={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})")
+
+    final_n = adata_work.n_obs
+    print(f"Filtering complete: start={start_n}, final={final_n}, removed={start_n - final_n}")
+
+    # mark as done
+    adata_work.uns[uns_flag] = True
+
+    return adata_work