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

smftools/preprocessing/calculate_read_length_stats.py

@@ -1,7 +1,7 @@
 ## calculate_read_length_stats
 
 # Read length QC
-def calculate_read_length_stats(adata, reference_column, sample_names_col, output_directory, show_read_length_histogram=False, save_read_length_histogram=False):
+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. 
 
@@ -9,9 +9,6 @@ def calculate_read_length_stats(adata, reference_column, sample_names_col, outpu
         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
-        output_directory (str): String representing the output directory to make and write out the histograms.
-        show_read_length_histogram (bool): Whether to display the histograms.
-        save_read_length_histogram (bool): Whether to save the histograms.
     
     Returns:
         upper_bound (int): last valid position in the dataset
@@ -20,11 +17,8 @@ def calculate_read_length_stats(adata, reference_column, sample_names_col, outpu
     import numpy as np
     import anndata as ad
     import pandas as pd
-    import matplotlib.pyplot as plt
-    from .. import readwrite
-    from .make_dirs import make_dirs
 
-    make_dirs([output_directory])
+    print('Calculating read length statistics')
 
     references = set(adata.obs[reference_column])
     sample_names = set(adata.obs[sample_names_col])
@@ -44,43 +38,42 @@ def calculate_read_length_stats(adata, reference_column, sample_names_col, outpu
     upper_bound = int(np.nanmax(adata.obs['last_valid_position']))
     lower_bound = int(np.nanmin(adata.obs['first_valid_position']))
 
-# 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
+    return upper_bound, lower_bound
 
-    ## Plot histogram of read length data and save the median and stdev of the read lengths for each sample.
-    adata.uns['read_length_dict'] = {}
+# # 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()
-
-    return upper_bound, lower_bound
+#     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/clean_NaN.py

@@ -1,38 +1,46 @@
-## clean_NaN
-
 def clean_NaN(adata, layer=None):
     """
     Append layers to adata that contain NaN cleaning strategies.
 
     Parameters:
-        adata (AnnData): an adata object
-        layer (str): string representing the layer to fill NaN values in
+        adata (AnnData): an anndata object
+        layer (str, optional): Name of the layer to fill NaN values in. If None, uses adata.X.
 
-    Returns:
-        None
+    Modifies:
+        - Adds new layers to `adata.layers` with different NaN-filling strategies.
     """
     import numpy as np
-    import anndata as ad
     import pandas as pd
-    from ..readwrite import adata_to_df
+    import anndata as ad
+    from ..readwrite import adata_to_df 
 
-    # Fill NaN with closest SMF value
-    df = adata_to_df(adata, layer=layer)
-    df = df.ffill(axis=1).bfill(axis=1)
-    adata.layers['fill_nans_closest'] = df.values
+    # Ensure the specified layer exists
+    if layer and layer not in adata.layers:
+        raise ValueError(f"Layer '{layer}' not found in adata.layers.")
 
-    # Replace NaN values with 0, and 0 with minus 1
-    old_value, new_value = [0, -1]
+    # Convert to DataFrame
     df = adata_to_df(adata, layer=layer)
-    df = df.replace(old_value, new_value)
-    old_value, new_value = [np.nan, 0]
-    df = df.replace(old_value, new_value)
-    adata.layers['nan0_0minus1'] = df.values
 
-    # Replace NaN values with 1, and 1 with 2
-    old_value, new_value = [1, 2]
-    df = adata_to_df(adata, layer=layer)
-    df = df.replace(old_value, new_value)
-    old_value, new_value = [np.nan, 1]
-    df = df.replace(old_value, new_value)
-    adata.layers['nan1_12'] = df.values
+    # 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

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_converted_reads_on_methylation.py

@@ -1,8 +1,7 @@
 ## filter_converted_reads_on_methylation
 
 ## Conversion SMF Specific 
-# Read methylation QC
-def filter_converted_reads_on_methylation(adata, valid_SMF_site_threshold=0.8, min_SMF_threshold=0.025):
+def filter_converted_reads_on_methylation(adata, valid_SMF_site_threshold=0.8, min_SMF_threshold=0.025, max_SMF_threshold=0.975):
     """
     Filter adata object using minimum thresholds for valid SMF site fraction in read, as well as minimum methylation content in read.
 
@@ -11,7 +10,7 @@ def filter_converted_reads_on_methylation(adata, valid_SMF_site_threshold=0.8, m
         valid_SMF_site_threshold (float): A minimum proportion of valid SMF sites that must be present in the read. Default is 0.8
         min_SMF_threshold (float): A minimum read methylation level. Default is 0.025
     Returns:
-        adata (AnnData): The filtered adata object.
+        Anndata
     """
     import numpy as np
     import anndata as ad
@@ -20,10 +19,26 @@ def filter_converted_reads_on_methylation(adata, valid_SMF_site_threshold=0.8, m
     if valid_SMF_site_threshold:
         # Keep reads that have over a given valid GpC site content
         adata = adata[adata.obs['fraction_valid_GpC_site_in_range'] > valid_SMF_site_threshold].copy()
+
     if min_SMF_threshold:
         # Keep reads with SMF methylation over background methylation.
+        below_background = (~adata.obs['GpC_above_other_C']).sum()
+        print(f'Removing {below_background} reads that have GpC conversion below background conversion rate')
         adata = adata[adata.obs['GpC_above_other_C'] == True].copy()
         # Keep reads over a defined methylation threshold
+        s0 = adata.shape[0]
         adata = adata[adata.obs['GpC_site_row_methylation_means'] > min_SMF_threshold].copy()
-        
-    return adata
+        s1 = adata.shape[0]
+        below_threshold = s0 - s1
+        print(f'Removing {below_threshold} reads that have GpC conversion below a minimum threshold conversion rate')
+
+    if max_SMF_threshold:
+        # Keep reads below a defined methylation threshold
+        s0 = adata.shape[0]
+        adata = adata[adata.obs['GpC_site_row_methylation_means'] < max_SMF_threshold].copy()
+        s1 = adata.shape[0]
+        above_threshold = s0 - s1
+        print(f'Removing {above_threshold} reads that have GpC conversion above a maximum threshold conversion rate')
+
+    return adata
+

smftools/preprocessing/filter_reads_on_length.py

@@ -1,6 +1,6 @@
 ## filter_reads_on_length
 
-def filter_reads_on_length(adata, filter_on_coordinates=False, min_read_length=2700):
+def filter_reads_on_length(adata, filter_on_coordinates=False, min_read_length=2700, max_read_length=3200):
     """
     Filters the adata object to keep a defined coordinate window, as well as reads that are over a minimum threshold in length.
 
@@ -8,15 +8,15 @@ def filter_reads_on_length(adata, filter_on_coordinates=False, min_read_length=2
         adata (AnnData): An adata object.
         filter_on_coordinates (bool | list): If False, skips filtering. Otherwise, provide a list containing integers representing the lower and upper bound coordinates to filter on. Default is False.
         min_read_length (int): The minimum read length to keep in the filtered dataset. Default is 2700.
+        max_read_length (int): The maximum query read length to keep in the filtered dataset. Default is 3200.
 
     Returns:
-        adata (AnnData): The filtered adata object
-    Input: Adata object. a list of lower and upper bound (set to False or None if not wanted), and a minimum read length integer.
- 
+        adata
     """
     import numpy as np
     import anndata as ad
     import pandas as pd
+
     if filter_on_coordinates:
         lower_bound, upper_bound = filter_on_coordinates
         # Extract the position information from the adata object as an np array
@@ -36,6 +36,16 @@ def filter_reads_on_length(adata, filter_on_coordinates=False, min_read_length=2
 
     if min_read_length:
         print(f'Subsetting adata to keep reads longer than {min_read_length}')
+        s0 = adata.shape[0]
         adata = adata[adata.obs['read_length'] > min_read_length].copy()
+        s1 = adata.shape[0]
+        print(f'Removed {s0-s1} reads less than {min_read_length} basepairs in length')
+
+    if max_read_length:
+        print(f'Subsetting adata to keep reads shorter than {max_read_length}')
+        s0 = adata.shape[0]
+        adata = adata[adata.obs['read_length'] < max_read_length].copy()
+        s1 = adata.shape[0]
+        print(f'Removed {s0-s1} reads greater than {max_read_length} basepairs in length')
 
     return adata

smftools/preprocessing/flag_duplicate_reads.py

@@ -0,0 +1,149 @@
+import torch
+from tqdm import tqdm
+
+class UnionFind:
+    def __init__(self, size):
+        self.parent = torch.arange(size)
+
+    def find(self, x):
+        while self.parent[x] != x:
+            self.parent[x] = self.parent[self.parent[x]]
+            x = self.parent[x]
+        return x
+
+    def union(self, x, y):
+        root_x = self.find(x)
+        root_y = self.find(y)
+        if root_x != root_y:
+            self.parent[root_y] = root_x
+
+
+def flag_duplicate_reads(adata, var_filters_sets, distance_threshold=0.05, obs_reference_col='Reference_strand'):
+    import numpy as np
+    import pandas as pd
+    import matplotlib.pyplot as plt
+
+    all_hamming_dists = []
+    merged_results = []
+
+    references = adata.obs[obs_reference_col].cat.categories
+
+    for ref in references:
+        print(f'🔹 Processing reference: {ref}')
+
+        ref_mask = adata.obs[obs_reference_col] == ref
+        adata_subset = adata[ref_mask].copy()
+        N = adata_subset.shape[0]
+
+        combined_mask = torch.zeros(len(adata.var), dtype=torch.bool)
+        for var_set in var_filters_sets:
+            if any(ref in v for v in var_set):
+                set_mask = torch.ones(len(adata.var), dtype=torch.bool)
+                for key in var_set:
+                    set_mask &= torch.from_numpy(adata.var[key].values)
+                combined_mask |= set_mask
+
+        selected_cols = adata.var.index[combined_mask.numpy()].to_list()
+        col_indices = [adata.var.index.get_loc(col) for col in selected_cols]
+
+        print(f"Selected {len(col_indices)} columns out of {adata.var.shape[0]} for {ref}")
+
+        X = adata_subset.X
+        if not isinstance(X, np.ndarray):
+            X = X.toarray()
+        X_subset = X[:, col_indices]
+        X_tensor = torch.from_numpy(X_subset.astype(np.float32))
+
+        fwd_hamming_to_next = torch.full((N,), float('nan'))
+        rev_hamming_to_prev = torch.full((N,), float('nan'))
+
+        def cluster_pass(X_tensor, reverse=False, window_size=50, record_distances=False):
+            N_local = X_tensor.shape[0]
+            X_sortable = X_tensor.nan_to_num(-1)
+            sort_keys = X_sortable.tolist()
+            sorted_idx = sorted(range(N_local), key=lambda i: sort_keys[i], reverse=reverse)
+            sorted_X = X_tensor[sorted_idx]
+
+            cluster_pairs = []
+
+            for i in tqdm(range(len(sorted_X)), desc=f"Pass {'rev' if reverse else 'fwd'} ({ref})"):
+                row_i = sorted_X[i]
+                j_range = range(i + 1, min(i + 1 + window_size, len(sorted_X)))
+
+                if len(j_range) > 0:
+                    row_i_exp = row_i.unsqueeze(0)
+                    block_rows = sorted_X[j_range]
+                    valid_mask = (~torch.isnan(row_i_exp)) & (~torch.isnan(block_rows))
+                    valid_counts = valid_mask.sum(dim=1)
+                    diffs = (row_i_exp != block_rows) & valid_mask
+                    hamming_dists = diffs.sum(dim=1) / valid_counts.clamp(min=1)
+                    all_hamming_dists.extend(hamming_dists.cpu().numpy().tolist())
+
+                    matches = (hamming_dists < distance_threshold) & (valid_counts > 0)
+                    for offset_idx, m in zip(j_range, matches):
+                        if m:
+                            cluster_pairs.append((sorted_idx[i], sorted_idx[offset_idx]))
+
+                    if record_distances and i + 1 < len(sorted_X):
+                        next_idx = sorted_idx[i + 1]
+                        valid_mask_pair = (~torch.isnan(row_i)) & (~torch.isnan(sorted_X[i + 1]))
+                        if valid_mask_pair.sum() > 0:
+                            d = (row_i[valid_mask_pair] != sorted_X[i + 1][valid_mask_pair]).sum()
+                            norm_d = d.item() / valid_mask_pair.sum().item()
+                            if reverse:
+                                rev_hamming_to_prev[next_idx] = norm_d
+                            else:
+                                fwd_hamming_to_next[sorted_idx[i]] = norm_d
+
+            return cluster_pairs
+
+        pairs_fwd = cluster_pass(X_tensor, reverse=False, record_distances=True)
+        involved_in_fwd = set([p[0] for p in pairs_fwd] + [p[1] for p in pairs_fwd])
+        mask_for_rev = torch.ones(N, dtype=torch.bool)
+        mask_for_rev[list(involved_in_fwd)] = False
+        pairs_rev = cluster_pass(X_tensor[mask_for_rev], reverse=True, record_distances=True)
+
+        all_pairs = pairs_fwd + [(list(mask_for_rev.nonzero(as_tuple=True)[0])[i], list(mask_for_rev.nonzero(as_tuple=True)[0])[j]) for i, j in pairs_rev]
+
+        uf = UnionFind(N)
+        for i, j in all_pairs:
+            uf.union(i, j)
+
+        merged_cluster = torch.zeros(N, dtype=torch.long)
+        for i in range(N):
+            merged_cluster[i] = uf.find(i)
+
+        cluster_sizes = torch.zeros_like(merged_cluster)
+        for cid in merged_cluster.unique():
+            members = (merged_cluster == cid).nonzero(as_tuple=True)[0]
+            cluster_sizes[members] = len(members)
+
+        is_duplicate = torch.zeros(N, dtype=torch.bool)
+        for cid in merged_cluster.unique():
+            members = (merged_cluster == cid).nonzero(as_tuple=True)[0]
+            if len(members) > 1:
+                is_duplicate[members[1:]] = True
+
+        adata_subset.obs['is_duplicate'] = is_duplicate.numpy()
+        adata_subset.obs['merged_cluster_id'] = merged_cluster.numpy()
+        adata_subset.obs['cluster_size'] = cluster_sizes.numpy()
+        adata_subset.obs['fwd_hamming_to_next'] = fwd_hamming_to_next.numpy()
+        adata_subset.obs['rev_hamming_to_prev'] = rev_hamming_to_prev.numpy()
+
+        merged_results.append(adata_subset.obs)
+
+    merged_obs = pd.concat(merged_results)
+    adata.obs = adata.obs.join(merged_obs[['is_duplicate', 'merged_cluster_id', 'cluster_size', 'fwd_hamming_to_next', 'rev_hamming_to_prev']])
+
+    adata_unique = adata[~adata.obs['is_duplicate']].copy()
+
+    plt.figure(figsize=(5, 4))
+    plt.hist(all_hamming_dists, bins=50, alpha=0.75)
+    plt.axvline(distance_threshold, color="red", linestyle="--", label=f"threshold = {distance_threshold}")
+    plt.xlabel("Hamming Distance")
+    plt.ylabel("Frequency")
+    plt.title("Histogram of Pairwise Hamming Distances")
+    plt.legend()
+    plt.show()
+
+    return adata_unique, adata

smftools/preprocessing/invert_adata.py

@@ -1,23 +1,30 @@
 ## invert_adata
 
 # Optional inversion of the adata
+
 def invert_adata(adata):
     """
-    Inverts the adata object along the variable axis
+    Inverts the AnnData object along the column (variable) axis.
 
     Parameters:
-        adata (AnnData): An adata object.
+        adata (AnnData): An AnnData object.
 
     Returns:
-        None
+        AnnData: A new AnnData object with inverted column ordering.
     """
     import numpy as np
     import anndata as ad
-    print('Inverting adata')
-    # Reassign var_names with new names
-    old_var_names = adata.var_names.astype(int).to_numpy()
-    new_var_names = np.sort(old_var_names)[::-1].astype(str)
-    adata.var['Original_positional_coordinate'] = old_var_names.astype(str)
-    adata.var_names = new_var_names
-    # Sort the AnnData object based on the old var_names
-    adata = adata[:, old_var_names.astype(str)]
+
+    print("🔄 Inverting AnnData along the column axis...")
+
+    # Reverse the order of columns (variables)
+    inverted_adata = adata[:, ::-1].copy()
+
+    # Reassign var_names with new order
+    inverted_adata.var_names = adata.var_names
+
+    # Optional: Store original coordinates for reference
+    inverted_adata.var["Original_var_names"] = adata.var_names[::-1]
+
+    print("✅ Inversion complete!")
+    return inverted_adata

smftools/preprocessing/load_sample_sheet.py

@@ -1,24 +1,38 @@
-# load_sample_sheet
-
-def load_sample_sheet(adata, sample_sheet_path, mapping_key_column):
+def load_sample_sheet(adata, sample_sheet_path, mapping_key_column='obs_names', as_category=True):
     """
-    Loads a sample sheet csv and uses one of the columns to map sample information into the AnnData object.
+    Loads a sample sheet CSV and maps metadata into the AnnData object as categorical columns.
 
     Parameters:
-        adata (AnnData): The Anndata object to append sample information to.
-        sample_sheet_path (str):
-        mapping_key_column (str):
+        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.
 
     Returns:
-        None
+        AnnData: Updated AnnData object.
     """
     import pandas as pd
-    import anndata as ad
+
+    print('🔹 Loading sample sheet...')
     df = pd.read_csv(sample_sheet_path)
-    key_column = mapping_key_column
-    df[key_column] = df[key_column].astype(str)
-    value_columns = [column for column in df.columns if column != key_column]
-    mapping_dict = df.set_index(key_column)[value_columns].to_dict(orient='index')
-    for column in value_columns:
-        column_map = {key: value[column] for key, value in mapping_dict.items()}
-        adata.obs[column] = adata.obs[key_column].map(column_map)
+    df[mapping_key_column] = df[mapping_key_column].astype(str)
+    
+    # If matching against obs_names directly
+    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}')
+    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')
+        adata.obs[col] = mapped
+
+    print('✅ Sample sheet metadata successfully added as categories.' if as_category else '✅ Metadata added.')
+    return adata