smftools 0.1.7__py3-none-any.whl → 0.2.3__py3-none-any.whl

smftools/preprocessing/add_read_length_and_mapping_qc.py

@@ -0,0 +1,129 @@
+import numpy as np
+import pandas as pd
+import scipy.sparse as sp
+from typing import Optional, List, Dict, Union
+
+def add_read_length_and_mapping_qc(
+    adata,
+    bam_files: Optional[List[str]] = None,
+    read_metrics: Optional[Dict[str, Union[list, tuple]]] = None,
+    uns_flag: str = "read_lenth_and_mapping_qc_performed",
+    extract_read_features_from_bam_callable = None,
+    bypass: bool = False,
+    force_redo: bool = True
+):
+    """
+    Populate adata.obs with read/mapping QC columns.
+
+    Parameters
+    ----------
+    adata
+        AnnData to annotate (modified in-place).
+    bam_files
+        Optional list of BAM files to extract metrics from. Ignored if read_metrics supplied.
+    read_metrics
+        Optional dict mapping obs_name -> [read_length, read_quality, reference_length, mapped_length, mapping_quality]
+        If provided, this will be used directly and bam_files will be ignored.
+    uns_flag
+        key in final_adata.uns used to record that QC was performed (kept the name with original misspelling).
+    extract_read_features_from_bam_callable
+        Optional callable(bam_path) -> dict mapping read_name -> list/tuple of metrics.
+        If not provided and bam_files is given, function will attempt to call `extract_read_features_from_bam`
+        from the global namespace (your existing helper).
+    Returns
+    -------
+    None (mutates final_adata in-place)
+    """
+
+    # 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
+
+    # Build read_metrics dict either from provided arg or by extracting from bam files
+    if read_metrics is None:
+        read_metrics = {}
+        if bam_files:
+            extractor = extract_read_features_from_bam_callable or globals().get("extract_read_features_from_bam")
+            if extractor is None:
+                raise ValueError("No `read_metrics` provided and `extract_read_features_from_bam` not found.")
+            for bam in bam_files:
+                bam_read_metrics = extractor(bam)
+                if not isinstance(bam_read_metrics, dict):
+                    raise ValueError(f"extract_read_features_from_bam returned non-dict for {bam}")
+                read_metrics.update(bam_read_metrics)
+        else:
+            # nothing to do
+            read_metrics = {}
+
+    # Convert read_metrics dict -> DataFrame (rows = read id)
+    # Values may be lists/tuples or scalars; prefer lists/tuples with 5 entries.
+    if len(read_metrics) == 0:
+        # fill with NaNs
+        n = adata.n_obs
+        adata.obs['read_length'] = np.full(n, np.nan)
+        adata.obs['mapped_length'] = np.full(n, np.nan)
+        adata.obs['reference_length'] = np.full(n, np.nan)
+        adata.obs['read_quality'] = np.full(n, np.nan)
+        adata.obs['mapping_quality'] = np.full(n, np.nan)
+    else:
+        # Build DF robustly
+        # Convert values to lists where possible, else to [val, val, val...]
+        max_cols = 5
+        rows = {}
+        for k, v in read_metrics.items():
+            if isinstance(v, (list, tuple, np.ndarray)):
+                vals = list(v)
+            else:
+                # scalar -> replicate into 5 columns to preserve original behavior
+                vals = [v] * max_cols
+            # Ensure length >= 5
+            if len(vals) < max_cols:
+                vals = vals + [np.nan] * (max_cols - len(vals))
+            rows[k] = vals[:max_cols]
+
+        df = pd.DataFrame.from_dict(rows, orient='index', columns=[
+            'read_length', 'read_quality', 'reference_length', 'mapped_length', 'mapping_quality'
+        ])
+
+        # Reindex to final_adata.obs_names so order matches adata
+        # If obs_names are not present as keys in df, the results will be NaN
+        df_reindexed = df.reindex(adata.obs_names).astype(float)
+
+        adata.obs['read_length'] = df_reindexed['read_length'].values
+        adata.obs['mapped_length'] = df_reindexed['mapped_length'].values
+        adata.obs['reference_length'] = df_reindexed['reference_length'].values
+        adata.obs['read_quality'] = df_reindexed['read_quality'].values
+        adata.obs['mapping_quality'] = df_reindexed['mapping_quality'].values
+
+    # Compute ratio columns safely (avoid divide-by-zero and preserve NaN)
+    # read_length_to_reference_length_ratio
+    rl = pd.to_numeric(adata.obs['read_length'], errors='coerce').to_numpy(dtype=float)
+    ref_len = pd.to_numeric(adata.obs['reference_length'], errors='coerce').to_numpy(dtype=float)
+    mapped_len = pd.to_numeric(adata.obs['mapped_length'], errors='coerce').to_numpy(dtype=float)
+
+    # safe divisions: use np.where to avoid warnings and replace inf with nan
+    with np.errstate(divide='ignore', invalid='ignore'):
+        rl_to_ref = np.where((ref_len != 0) & np.isfinite(ref_len), rl / ref_len, np.nan)
+        mapped_to_ref = np.where((ref_len != 0) & np.isfinite(ref_len), mapped_len / ref_len, np.nan)
+        mapped_to_read = np.where((rl != 0) & np.isfinite(rl), mapped_len / rl, np.nan)
+
+    adata.obs['read_length_to_reference_length_ratio'] = rl_to_ref
+    adata.obs['mapped_length_to_reference_length_ratio'] = mapped_to_ref
+    adata.obs['mapped_length_to_read_length_ratio'] = mapped_to_read
+
+    # Add read level raw modification signal: sum over X rows
+    X = adata.X
+    if sp.issparse(X):
+        # sum returns (n_obs, 1) sparse matrix; convert to 1d array
+        raw_sig = np.asarray(X.sum(axis=1)).ravel()
+    else:
+        raw_sig = np.asarray(X.sum(axis=1)).ravel()
+
+    adata.obs['Raw_modification_signal'] = raw_sig
+
+    # mark as done
+    adata.uns[uns_flag] = True
+
+    return None

smftools/preprocessing/append_base_context.py

@@ -0,0 +1,122 @@
+def append_base_context(adata, 
+                        obs_column='Reference_strand', 
+                        use_consensus=False,
+                        native=False, 
+                        mod_target_bases=['GpC', 'CpG'],
+                        bypass=False,
+                        force_redo=False,
+                        uns_flag='base_context_added'
+):
+    """
+    Adds nucleobase context to the position within the given category. When use_consensus is True, it uses the consensus sequence, otherwise it defaults to the FASTA sequence.
+
+    Parameters:
+        adata (AnnData): The input adata object.
+        obs_column (str): The observation column in which to stratify on. Default is 'Reference_strand', which should not be changed for most purposes.
+        use_consensus (bool): A truth statement indicating whether to use the consensus sequence from the reads mapped to the reference. If False, the reference FASTA is used instead.
+        native (bool): If False, perform conversion SMF assumptions. If True, perform native SMF assumptions
+        mod_target_bases (list): Base contexts that may be modified.
+    
+    Returns:
+        None
+    """
+    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) or bypass:
+        # QC already performed; nothing to do
+        return
+
+    print('Adding base context based on reference FASTA sequence for sample')
+    categories = adata.obs[obs_column].cat.categories
+    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']
+
+    for cat in categories:
+        # Assess if the strand is the top or bottom strand converted
+        if 'top' in cat:
+            strand = 'top'
+        elif 'bottom' in cat:
+            strand = 'bottom'
+
+        if native:
+            basename = cat.split(f"_{strand}")[0]
+            if use_consensus:
+                sequence = adata.uns[f'{basename}_consensus_sequence']
+            else:
+                # This sequence is the unconverted FASTA sequence of the original input FASTA for the locus
+                sequence = adata.uns[f'{basename}_FASTA_sequence']
+        else:
+            basename = cat.split(f"_{strand}")[0]
+            if use_consensus:
+                sequence = adata.uns[f'{basename}_consensus_sequence']
+            else:
+                # This sequence is the unconverted FASTA sequence of the original input FASTA for the locus
+                sequence = adata.uns[f'{basename}_FASTA_sequence']
+        # Init a dict keyed by reference site type that points to a bool of whether the position is that site type.    
+        boolean_dict = {}
+        for site_type in site_types:
+            boolean_dict[f'{cat}_{site_type}'] = np.full(len(sequence), False, dtype=bool)
+
+        if any(base in mod_target_bases for base in ['GpC', 'CpG', 'C']):
+            if strand == 'top':
+                # Iterate through the sequence and apply the criteria
+                for i in range(1, len(sequence) - 1):
+                    if sequence[i] == 'C':
+                        boolean_dict[f'{cat}_C_site'][i] = True
+                        if sequence[i - 1] == 'G' and sequence[i + 1] != 'G':
+                            boolean_dict[f'{cat}_GpC_site'][i] = True
+                        elif sequence[i - 1] == 'G' and sequence[i + 1] == 'G':
+                            boolean_dict[f'{cat}_ambiguous_GpC_CpG_site'][i] = True
+                        elif sequence[i - 1] != 'G' and sequence[i + 1] == 'G':
+                            boolean_dict[f'{cat}_CpG_site'][i] = True
+                        elif sequence[i - 1] != 'G' and sequence[i + 1] != 'G':
+                            boolean_dict[f'{cat}_other_C_site'][i] = True
+            elif strand == 'bottom':
+                # Iterate through the sequence and apply the criteria
+                for i in range(1, len(sequence) - 1):
+                    if sequence[i] == 'G':
+                        boolean_dict[f'{cat}_C_site'][i] = True
+                        if sequence[i + 1] == 'C' and sequence[i - 1] != 'C':
+                            boolean_dict[f'{cat}_GpC_site'][i] = True
+                        elif sequence[i - 1] == 'C' and sequence[i + 1] == 'C':
+                            boolean_dict[f'{cat}_ambiguous_GpC_CpG_site'][i] = True
+                        elif sequence[i - 1] == 'C' and sequence[i + 1] != 'C':
+                            boolean_dict[f'{cat}_CpG_site'][i] = True
+                        elif sequence[i - 1] != 'C' and sequence[i + 1] != 'C':
+                            boolean_dict[f'{cat}_other_C_site'][i] = True
+            else:
+                print('Error: top or bottom strand of conversion could not be determined. Ensure this value is in the Reference name.')
+
+        if 'A' in mod_target_bases:
+            if strand == 'top':
+                # Iterate through the sequence and apply the criteria
+                for i in range(1, len(sequence) - 1):
+                    if sequence[i] == 'A':
+                        boolean_dict[f'{cat}_A_site'][i] = True
+            elif strand == 'bottom':
+                # Iterate through the sequence and apply the criteria
+                for i in range(1, len(sequence) - 1):
+                    if sequence[i] == 'T':
+                        boolean_dict[f'{cat}_A_site'][i] = True
+            else:
+                print('Error: top or bottom strand of conversion could not be determined. Ensure this value is in the Reference name.')
+
+        for site_type in site_types:
+            adata.var[f'{cat}_{site_type}'] = boolean_dict[f'{cat}_{site_type}'].astype(bool)
+            if native:
+                adata.obsm[f'{cat}_{site_type}'] = adata[:, adata.var[f'{cat}_{site_type}'] == True].layers['binarized_methylation']
+            else:
+                adata.obsm[f'{cat}_{site_type}'] = adata[:, adata.var[f'{cat}_{site_type}'] == True].X
+
+    # mark as done
+    adata.uns[uns_flag] = True
+
+    return None

smftools/preprocessing/append_binary_layer_by_base_context.py

@@ -0,0 +1,143 @@
+import numpy as np
+import scipy.sparse as sp
+
+def append_binary_layer_by_base_context(
+    adata,
+    reference_column: str,
+    smf_modality: str = "conversion",
+    verbose: bool = True,
+    uns_flag: str = "binary_layers_by_base_context_added",
+    bypass: bool = False,
+    force_redo: bool = False
+):
+    """
+    Build per-reference C/G-site masked layers:
+      - GpC_site_binary
+      - CpG_site_binary
+      - GpC_CpG_combined_site_binary (numeric sum where present; NaN where neither present)
+      - C_site_binary
+      - other_C_site_binary
+
+    Behavior:
+      - If X is sparse it will be converted to dense for these layers (keeps original adata.X untouched).
+      - Missing var columns are warned about but do not crash.
+      - Masked positions are filled with np.nan to make masked vs unmasked explicit.
+      - Requires append_base_context to be run first
+    """
+
+    # Only run if not already performed
+    already = bool(adata.uns.get(uns_flag, False))
+    if (already and not force_redo) or bypass or ("base_context_added" not in adata.uns):
+        # QC already performed; nothing to do
+        return adata
+
+    # check inputs
+    if reference_column not in adata.obs.columns:
+        raise KeyError(f"reference_column '{reference_column}' not found in adata.obs")
+
+    # modality flag (kept for your potential use)
+    if smf_modality != "direct":
+        if smf_modality == "conversion":
+            deaminase = False
+        else:
+            deaminase = True
+    else:
+        deaminase = None  # unused but preserved
+
+    # expected per-reference var column names
+    references = adata.obs[reference_column].astype("category").cat.categories
+    reference_to_gpc_column = {ref: f"{ref}_GpC_site" for ref in references}
+    reference_to_cpg_column = {ref: f"{ref}_CpG_site" for ref in references}
+    reference_to_c_column = {ref: f"{ref}_C_site" for ref in references}
+    reference_to_other_c_column = {ref: f"{ref}_other_C_site" for ref in references}
+
+    # verify var columns exist and build boolean masks per ref (len = n_vars)
+    n_obs, n_vars = adata.shape
+    def _col_mask_or_warn(colname):
+        if colname not in adata.var.columns:
+            if verbose:
+                print(f"Warning: var column '{colname}' not found; treating as all-False mask.")
+            return np.zeros(n_vars, dtype=bool)
+        vals = adata.var[colname].values
+        # coerce truthiness
+        try:
+            return vals.astype(bool)
+        except Exception:
+            return np.array([bool(v) for v in vals], dtype=bool)
+
+    gpc_var_masks = {ref: _col_mask_or_warn(col) for ref, col in reference_to_gpc_column.items()}
+    cpg_var_masks = {ref: _col_mask_or_warn(col) for ref, col in reference_to_cpg_column.items()}
+    c_var_masks =   {ref: _col_mask_or_warn(col) for ref, col in reference_to_c_column.items()}
+    other_c_var_masks = {ref: _col_mask_or_warn(col) for ref, col in reference_to_other_c_column.items()}
+
+    # prepare X as dense float32 for layer filling (we leave adata.X untouched)
+    X = adata.X
+    if sp.issparse(X):
+        if verbose:
+            print("Converting sparse X to dense array for layer construction (temporary).")
+        X = X.toarray()
+    X = np.asarray(X, dtype=np.float32)
+
+    # initialize masked arrays filled with NaN
+    masked_gpc = np.full((n_obs, n_vars), np.nan, dtype=np.float32)
+    masked_cpg = np.full((n_obs, n_vars), np.nan, dtype=np.float32)
+    masked_any_c = np.full((n_obs, n_vars), np.nan, dtype=np.float32)
+    masked_other_c = np.full((n_obs, n_vars), np.nan, dtype=np.float32)
+
+    # fill row-blocks per reference (this avoids creating a full row×var boolean mask)
+    obs_ref_series = adata.obs[reference_column]
+    for ref in references:
+        rows_mask = (obs_ref_series.values == ref)
+        if not rows_mask.any():
+            continue
+        row_idx = np.nonzero(rows_mask)[0]  # integer indices of rows for this ref
+
+        # column masks for this ref
+        gpc_cols = gpc_var_masks.get(ref, np.zeros(n_vars, dtype=bool))
+        cpg_cols = cpg_var_masks.get(ref, np.zeros(n_vars, dtype=bool))
+        c_cols   = c_var_masks.get(ref, np.zeros(n_vars, dtype=bool))
+        other_c_cols = other_c_var_masks.get(ref, np.zeros(n_vars, dtype=bool))
+
+        if gpc_cols.any():
+            # assign only the submatrix (rows x selected cols)
+            masked_gpc[np.ix_(row_idx, gpc_cols)] = X[np.ix_(row_idx, gpc_cols)]
+        if cpg_cols.any():
+            masked_cpg[np.ix_(row_idx, cpg_cols)] = X[np.ix_(row_idx, cpg_cols)]
+        if c_cols.any():
+            masked_any_c[np.ix_(row_idx, c_cols)] = X[np.ix_(row_idx, c_cols)]
+        if other_c_cols.any():
+            masked_other_c[np.ix_(row_idx, other_c_cols)] = X[np.ix_(row_idx, other_c_cols)]
+
+    # Build combined layer:
+    # - numeric_sum: sum where either exists, NaN where neither exists
+    #   we compute numeric sum but preserve NaN where both are NaN
+    gpc_nan = np.isnan(masked_gpc)
+    cpg_nan = np.isnan(masked_cpg)
+    combined_sum = np.nan_to_num(masked_gpc, nan=0.0) + np.nan_to_num(masked_cpg, nan=0.0)
+    both_nan = gpc_nan & cpg_nan
+    combined_sum[both_nan] = np.nan
+
+    # Alternative: if you prefer a boolean OR combined layer, uncomment:
+    # combined_bool = (~gpc_nan & (masked_gpc != 0)) | (~cpg_nan & (masked_cpg != 0))
+    # combined_layer = combined_bool.astype(np.float32)
+
+    adata.layers['GpC_site_binary'] = masked_gpc
+    adata.layers['CpG_site_binary'] = masked_cpg
+    adata.layers['GpC_CpG_combined_site_binary'] = combined_sum
+    adata.layers['C_site_binary'] = masked_any_c
+    adata.layers['other_C_site_binary'] = masked_other_c
+
+    if verbose:
+        def _filled_positions(arr):
+            return int(np.sum(~np.isnan(arr)))
+        print("Layer build summary (non-NaN cell counts):")
+        print(f"  GpC: {_filled_positions(masked_gpc)}")
+        print(f"  CpG: {_filled_positions(masked_cpg)}")
+        print(f"  GpC+CpG combined: {_filled_positions(combined_sum)}")
+        print(f"  C: {_filled_positions(masked_any_c)}")
+        print(f"  other_C: {_filled_positions(masked_other_c)}")
+
+    # mark as done
+    adata.uns[uns_flag] = True
+
+    return adata

smftools/preprocessing/binarize.py

@@ -0,0 +1,17 @@
+import numpy as np
+
+def binarize_adata(adata, source="X", target_layer="binary", threshold=0.8):
+    """
+    Binarize a dense matrix and preserve NaN.
+    source: "X" or layer name
+    """
+    X = adata.X if source == "X" else adata.layers[source]
+
+    # Copy to avoid modifying original in-place
+    X_bin = X.copy()
+
+    # Where not NaN: apply threshold
+    mask = ~np.isnan(X_bin)
+    X_bin[mask] = (X_bin[mask] > threshold).astype(np.int8)
+
+    adata.layers[target_layer] = X_bin

smftools/preprocessing/binarize_on_Youden.py

@@ -1,4 +1,4 @@
-def binarize_on_Youden(adata, obs_column='Reference'):
+def binarize_on_Youden(adata, obs_column='Reference', output_layer_name='binarized_methylation'):
     """
     Binarize SMF values based on position thresholds determined by calculate_position_Youden.
 
@@ -42,4 +42,4 @@ def binarize_on_Youden(adata, obs_column='Reference'):
         binarized_methylation[cat_mask, :] = binarized_matrix
 
     # Store the binarized matrix in a new layer
-    adata.layers['binarized_methylation'] = binarized_methylation
+    adata.layers[output_layer_name] = binarized_methylation

smftools/preprocessing/calculate_complexity_II.py

@@ -0,0 +1,248 @@
+from typing import Optional
+def calculate_complexity_II(
+    adata,
+    output_directory='',
+    sample_col='Sample_names',
+    ref_col: Optional[str] = 'Reference_strand',
+    cluster_col='sequence__merged_cluster_id',
+    plot=True,
+    save_plot=False,
+    n_boot=30,
+    n_depths=12,
+    random_state=0,
+    csv_summary=True,
+    uns_flag='complexity_analysis_complete',
+    force_redo=False,
+    bypass=False
+):
+    """
+    Estimate and plot library complexity.
+
+    If ref_col is None (default), behaves as before: one calculation per sample.
+    If ref_col is provided, computes complexity for each (sample, ref) pair.
+
+    Results:
+      - adata.uns['Library_complexity_results'] : dict keyed by (sample,) or (sample, ref) -> dict with fields
+          C0, n_reads, n_unique, depths, mean_unique, ci_low, ci_high
+      - Also stores per-entity record in adata.uns[f'Library_complexity_{sanitized_name}'] (backwards compatible)
+      - Optionally saves PNGs and CSVs (curve points + fit summary)
+    """
+    import os
+    import numpy as np
+    import pandas as pd
+    import matplotlib.pyplot as plt
+    from scipy.optimize import curve_fit
+    from datetime import datetime
+
+    # early exits
+    already = bool(adata.uns.get(uns_flag, False))
+    if (already and not force_redo):
+        return None
+    if bypass:
+        return None
+
+    rng = np.random.default_rng(random_state)
+
+    def lw(x, C0):
+        return C0 * (1.0 - np.exp(-x / C0))
+
+    def sanitize(name: str) -> str:
+        return "".join(c if c.isalnum() or c in "-._" else "_" for c in str(name))
+
+    # checks
+    for col in (sample_col, cluster_col):
+        if col not in adata.obs.columns:
+            raise KeyError(f"Required column '{col}' not found in adata.obs")
+    if ref_col is not None and ref_col not in adata.obs.columns:
+        raise KeyError(f"ref_col '{ref_col}' not found in adata.obs")
+
+    if save_plot or csv_summary:
+        os.makedirs(output_directory or ".", exist_ok=True)
+
+    # containers to collect CSV rows across all groups
+    fit_records = []
+    curve_records = []
+
+    # output dict stored centrally
+    results = {}
+
+    # build list of groups: either samples only, or (sample, ref) pairs
+    sseries = adata.obs[sample_col].astype("category")
+    samples = list(sseries.cat.categories)
+    if ref_col is None:
+        group_keys = [(s,) for s in samples]
+    else:
+        rseries = adata.obs[ref_col].astype("category")
+        references = list(rseries.cat.categories)
+        group_keys = []
+        # iterate only pairs that exist in data to avoid empty processing
+        for s in samples:
+            mask_s = (adata.obs[sample_col] == s)
+            # find references present for this sample
+            ref_present = pd.Categorical(adata.obs.loc[mask_s, ref_col]).categories
+            # Use intersection of known reference categories and those present for sample
+            for r in ref_present:
+                group_keys.append((s, r))
+
+    # iterate groups
+    for g in group_keys:
+        if ref_col is None:
+            sample = g[0]
+            # filter mask
+            mask = (adata.obs[sample_col] == sample).values
+            group_label = f"{sample}"
+        else:
+            sample, ref = g
+            mask = (adata.obs[sample_col] == sample) & (adata.obs[ref_col] == ref)
+            group_label = f"{sample}__{ref}"
+
+        n_reads = int(mask.sum())
+        if n_reads < 2:
+            # store empty placeholders and continue
+            results[g] = {
+                "C0": np.nan,
+                "n_reads": int(n_reads),
+                "n_unique": 0,
+                "depths": np.array([], dtype=int),
+                "mean_unique": np.array([], dtype=float),
+                "ci_low": np.array([], dtype=float),
+                "ci_high": np.array([], dtype=float),
+            }
+            # also store back-compat key
+            adata.uns[f'Library_complexity_{sanitize(group_label)}'] = results[g]
+            continue
+
+        # cluster ids array for this group
+        clusters = adata.obs.loc[mask, cluster_col].to_numpy()
+        # observed unique molecules at full depth
+        observed_unique = int(pd.unique(clusters).size)
+
+        # choose subsampling depths
+        if n_depths < 2:
+            depths = np.array([n_reads], dtype=int)
+        else:
+            lo = max(10, int(0.05 * n_reads))
+            depths = np.unique(np.linspace(lo, n_reads, n_depths, dtype=int))
+            depths = depths[depths > 0]
+        depths = depths.astype(int)
+        if depths.size == 0:
+            depths = np.array([n_reads], dtype=int)
+
+        # bootstrap sampling: for each depth, sample without replacement (if possible)
+        idx_all = np.arange(n_reads)
+        boot_unique = np.zeros((len(depths), n_boot), dtype=float)
+        for di, d in enumerate(depths):
+            d_use = int(min(d, n_reads))
+            # if d_use == n_reads we can short-circuit and set boot results to full observed uniques
+            if d_use == n_reads:
+                # bootstraps are deterministic in this special case
+                uniq_val = float(observed_unique)
+                boot_unique[di, :] = uniq_val
+                continue
+            # otherwise run bootstraps
+            for b in range(n_boot):
+                take = rng.choice(idx_all, size=d_use, replace=False)
+                boot_unique[di, b] = np.unique(clusters[take]).size
+
+        mean_unique = boot_unique.mean(axis=1)
+        lo_ci = np.percentile(boot_unique, 2.5, axis=1)
+        hi_ci = np.percentile(boot_unique, 97.5, axis=1)
+
+        # fit Lander-Waterman to the mean curve (safe bounds)
+        C0_init = max(observed_unique, mean_unique[-1] if mean_unique.size else observed_unique)
+        try:
+            popt, _ = curve_fit(
+                lw,
+                xdata=depths.astype(float),
+                ydata=mean_unique.astype(float),
+                p0=[C0_init],
+                bounds=(1.0, 1e12),
+                maxfev=10000,
+            )
+            C0 = float(popt[0])
+        except Exception:
+            C0 = float(observed_unique)
+
+        # store results
+        results[g] = {
+            "C0": C0,
+            "n_reads": int(n_reads),
+            "n_unique": int(observed_unique),
+            "depths": depths,
+            "mean_unique": mean_unique,
+            "ci_low": lo_ci,
+            "ci_high": hi_ci,
+        }
+
+        # save per-group in adata.uns for backward compatibility
+        adata.uns[f'Library_complexity_{sanitize(group_label)}'] = results[g]
+
+        # prepare curve and fit records for CSV
+        fit_records.append({
+            "sample": sample,
+            "reference": ref if ref_col is not None else "",
+            "C0": float(C0),
+            "n_reads": int(n_reads),
+            "n_unique_observed": int(observed_unique),
+        })
+
+        x_fit = np.linspace(0, max(n_reads, int(depths[-1]) if depths.size else n_reads), 200)
+        y_fit = lw(x_fit, C0)
+        for d, mu, lo, hi in zip(depths, mean_unique, lo_ci, hi_ci):
+            curve_records.append({
+                "sample": sample,
+                "reference": ref if ref_col is not None else "",
+                "type": "bootstrap",
+                "depth": int(d),
+                "mean_unique": float(mu),
+                "ci_low": float(lo),
+                "ci_high": float(hi),
+            })
+        for xf, yf in zip(x_fit, y_fit):
+            curve_records.append({
+                "sample": sample,
+                "reference": ref if ref_col is not None else "",
+                "type": "fit",
+                "depth": float(xf),
+                "mean_unique": float(yf),
+                "ci_low": np.nan,
+                "ci_high": np.nan,
+            })
+
+        # plotting for this group
+        if plot:
+            plt.figure(figsize=(6.5, 4.5))
+            plt.fill_between(depths, lo_ci, hi_ci, alpha=0.25, label="Bootstrap 95% CI")
+            plt.plot(depths, mean_unique, "o", label="Bootstrap mean")
+            plt.plot([n_reads], [observed_unique], "s", label="Observed (full)")
+            plt.plot(x_fit, y_fit, "-", label=f"LW fit  C0≈{C0:,.0f}")
+            plt.xlabel("Total reads (subsampled depth)")
+            plt.ylabel("Unique molecules (clusters)")
+            title = f"Library Complexity — {sample}" + (f" / {ref}" if ref_col is not None else "")
+            plt.title(title)
+            plt.grid(True, alpha=0.3)
+            plt.legend()
+            plt.tight_layout()
+
+            if save_plot:
+                fname = f"complexity_{sanitize(group_label)}.png"
+                plt.savefig(os.path.join(output_directory or ".", fname), dpi=160, bbox_inches="tight")
+                plt.close()
+            else:
+                plt.show()
+
+    # store central results dict
+    adata.uns["Library_complexity_results"] = results
+
+    # mark complexity analysis as complete
+    adata.uns[uns_flag] = True
+
+    # CSV outputs
+    if csv_summary and (fit_records or curve_records):
+        fit_df = pd.DataFrame(fit_records)
+        curve_df = pd.DataFrame(curve_records)
+        base = output_directory or "."
+        fit_df.to_csv(os.path.join(base, f"complexity_fit_summary.csv"), index=False)
+        curve_df.to_csv(os.path.join(base, f"complexity_curves.csv"), index=False)
+
+    return results