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

smftools/preprocessing/append_C_context.py

@@ -1,38 +1,68 @@
 ## append_C_context
-import numpy as np
-import anndata as ad
-import pandas as pd
 
 ## Conversion SMF Specific 
 # Read methylation QC
 def append_C_context(adata, obs_column='Reference', use_consensus=False):
     """
+    Adds Cytosine 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', 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.
     Input: An adata object, the obs_column of interst, and whether to use the consensus sequence from the category.
-    Output: Adds Cytosine 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.
+    
+    Returns:
+        None
     """
-    site_types = ['GpC_site', 'CpG_site', 'ambiguous_GpC_site', 'ambiguous_CpG_site', 'other_C']
+    import numpy as np
+    import anndata as ad
+    site_types = ['GpC_site', 'CpG_site', 'ambiguous_GpC_CpG_site', 'other_C']
     categories = adata.obs[obs_column].cat.categories
-    if use_consensus:
-        sequence = adata.uns[f'{cat}_consensus_sequence']
-    else:
-        sequence = adata.uns[f'{cat}_FASTA_sequence']
     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 use_consensus:
+            sequence = adata.uns[f'{cat}_consensus_sequence']
+        else:
+            # This sequence is the unconverted FASTA sequence of the original input FASTA for the locus
+            sequence = adata.uns[f'{cat}_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)
-        # Iterate through the sequence and apply the criteria
-        for i in range(1, len(sequence) - 1):
-            if sequence[i] == 'C':
-                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_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}_ambiguous_CpG_site'][i] = True
-                elif sequence[i - 1] != 'G' and sequence[i + 1] != 'G':
-                    boolean_dict[f'{cat}_other_C'][i] = True
+        
+        if strand == 'top':
+            # Iterate through the sequence and apply the criteria
+            for i in range(1, len(sequence) - 1):
+                if sequence[i] == 'C':
+                    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'][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':
+                    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'][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)
             adata.obsm[f'{cat}_{site_type}'] = adata[:, adata.var[f'{cat}_{site_type}'] == True].copy().X

smftools/preprocessing/binarize_on_Youden.py

@@ -1,13 +1,17 @@
 ## binarize_on_Youden
-import numpy as np
-import pandas as pd
-import anndata as ad
 
 def binarize_on_Youden(adata, obs_column='Reference'):
     """
+    Add a new layer to the adata object that has binarized SMF values based on the position thresholds determined by calculate_position_Youden
+
+    Parameters:
+        adata (AnnData): The anndata object to binarize. pp.calculate_position_Youden function has to be run first.
+        obs_column (str): The obs_column to stratify on. Needs to be the same as passed in pp.calculate_position_Youden.
     Input: adata object that has had calculate_position_Youden called on it.
-    Output: Add a new layer to the adata object that has binarized SMF values based on the position thresholds determined by calculate_position_Youden
+    Output: 
     """
+    import numpy as np
+    import anndata as ad
     temp_adata = None
     categories = adata.obs[obs_column].cat.categories 
     for cat in categories:

smftools/preprocessing/binary_layers_to_ohe.py

@@ -1,14 +1,19 @@
 ## binary_layers_to_ohe
-import numpy as np
-import anndata as ad
-import pandas as pd
 
 ## Conversion SMF Specific 
 def binary_layers_to_ohe(adata, layers, stack='hstack'):
     """
+    Parameters:
+        adata (AnnData): Anndata object.
+        layers (list): a list of strings. Each string represents a layer in the adata object. The layer should encode a binary matrix
+        stack (str): Dimension to stack the one-hot-encoding. Options include 'hstack' and 'vstack'. Default is 'hstack', since this is more efficient.
+    
+    Returns:
+        ohe_dict (dict): A dictionary keyed by obs_name that points to a stacked (hstack or vstack) one-hot encoding of the binary layers
     Input: An adata object and a list of layers containing a binary encoding.
-    Output: A dictionary keyed by obs_name that points to a stacked (hstack or vstack) one-hot encoding of the binary layers
     """
+    import numpy as np
+    import anndata as ad
     # Extract the layers
     layers = [adata.layers[layer_name] for layer_name in layers]
     n_reads = layers[0].shape[0]

smftools/preprocessing/calculate_complexity.py

@@ -1,21 +1,32 @@
 ## calculate_complexity
-import numpy as np
-import pandas as pd
-from scipy.optimize import curve_fit
-import matplotlib.pyplot as plt
 
-def lander_waterman(x, C0):
-    return C0 * (1 - np.exp(-x / C0))
+def calculate_complexity(adata, output_directory='', obs_column='Reference', sample_col='Sample_names', plot=True, save_plot=False):
+    """
+    A complexity analysis of the library.
 
-def count_unique_reads(reads, depth):
-    subsample = np.random.choice(reads, depth, replace=False)
-    return len(np.unique(subsample))
+    Parameters:
+        adata (AnnData): An adata object with mark_duplicates already run.
+        output_directory (str): String representing the path to the output directory.
+        obs_column (str): String of the obs column to iterate over.
+        sample_col (str): String of the sample column to iterate over.
+        plot (bool): Whether to plot the complexity model.
+        save_plot (bool): Whether to save the complexity model.
+
+    Returns:
+        None
 
-def calculate_complexity(adata, obs_column='Reference', sample_col='Sample_names', plot=True, save_plot=False):
-    """
-    Input: adata object with mark_duplicates already run.
-    Output: A complexity analysis of the library
     """
+    import numpy as np
+    import pandas as pd
+    from scipy.optimize import curve_fit
+
+    def lander_waterman(x, C0):
+        return C0 * (1 - np.exp(-x / C0))
+
+    def count_unique_reads(reads, depth):
+        subsample = np.random.choice(reads, depth, replace=False)
+        return len(np.unique(subsample))
+
     categories = adata.obs[obs_column].cat.categories 
     sample_names = adata.obs[sample_col].cat.categories 
 
@@ -40,6 +51,7 @@ def calculate_complexity(adata, obs_column='Reference', sample_col='Sample_names
             y_data = lander_waterman(x_data, *popt)
             adata.uns[f'Library_complexity_{sample}_on_{cat}'] = popt[0]
             if plot:
+                import matplotlib.pyplot as plt
                 # Plot the complexity curve
                 plt.figure(figsize=(6, 4))
                 plt.plot(total_reads, unique_reads, 'o', label='Observed unique reads')
@@ -52,7 +64,7 @@ def calculate_complexity(adata, obs_column='Reference', sample_col='Sample_names
                 plt.grid(True)
                 if save_plot:
                     date_string = date_string()
-                    save_name = output_directory + f'/{date_string} {title}'
+                    save_name = output_directory + f'/{date_string}_{title}'
                     plt.savefig(save_name, bbox_inches='tight', pad_inches=0.1)
                     plt.close()
                 else:

smftools/preprocessing/calculate_consensus.py

@@ -0,0 +1,47 @@
+# calculate_consensus
+
+def calculate_consensus(adata, reference, sample=False, reference_column='Reference', sample_column='Sample'):
+    """
+    Takes an input AnnData object, the reference to subset on, and the sample name to subset on to calculate the consensus sequence of the read set.
+
+    Parameters:
+        adata (AnnData): The input adata to append consensus metadata to.
+        reference (str): The name of the reference to subset the adata on.
+        sample (bool | str): If False, uses all samples. If a string is passed, the adata is further subsetted to only analyze that sample.
+        reference_column (str): The name of the reference column (Default is 'Reference')
+        sample_column (str): The name of the sample column (Default is 'Sample)
+
+    Returns:
+        None
+    
+    """
+    import numpy as np
+
+    # Subset the adata on the refernce of interest. Optionally, subset additionally on a sample of interest.
+    record_subset = adata[adata.obs[reference_column] == reference].copy()
+    if sample:
+        record_subset = record_subset[record_subset.obs[sample_column] == sample].copy()
+    else:
+        pass
+
+    # Grab layer names from the adata object that correspond to the binary encodings of the read sequences.
+    layers = [layer for layer in record_subset.layers if '_binary_' in layer]
+    layer_map, layer_counts = {}, []
+    for i, layer in enumerate(layers):
+        # Gives an integer mapping to access which sequence base the binary layer is encoding
+        layer_map[i] = layer.split('_')[0]
+        # Get the positional counts from all reads for the given base identity.
+        layer_counts.append(np.sum(record_subset.layers[layer], axis=0))
+    # Combine the positional counts array derived from each binary base layer into an ndarray
+    count_array = np.array(layer_counts)
+    # Determine the row index that contains the largest count for each position and store this in an array.
+    nucleotide_indexes = np.argmax(count_array, axis=0)
+    # Map the base sequence derived from the row index array to attain the consensus sequence in a list.
+    consensus_sequence_list = [layer_map[i] for i in nucleotide_indexes]
+
+    if sample:
+        adata.var[f'{reference}_consensus_from_{sample}'] = consensus_sequence_list
+    else:
+        adata.var[f'{reference}_consensus_across_samples'] = consensus_sequence_list
+
+    adata.uns[f'{reference}_consensus_sequence'] = consensus_sequence_list

smftools/preprocessing/calculate_converted_read_methylation_stats.py

@@ -1,25 +1,41 @@
 ## calculate_converted_read_methylation_stats
-import numpy as np
-import anndata as ad
-import pandas as pd
 
 ## Conversion SMF Specific 
 # Read methylation QC
 
-def calculate_converted_read_methylation_stats(adata, obs_column='Reference'):
+def calculate_converted_read_methylation_stats(adata, reference_column, sample_names_col, output_directory, show_methylation_histogram=False, save_methylation_histogram=False):
     """
-    Input: adata and the observation category of interest
-    Output: Adds methylation statistics for each read. Indicates whether the read GpC methylation exceeded other_C methylation (background false positives)
+    Adds methylation statistics for each read. Indicates whether the read GpC methylation exceeded other_C methylation (background false positives).
+
+    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
+        output_directory (str): String representing the output directory to make and write out the histograms.
+        show_methylation_histogram (bool): Whether to display the histograms.
+        save_methylation_histogram (bool): Whether to save the histograms.
+
+    Returns:
+        None 
     """
-    site_types = ['GpC_site', 'CpG_site', 'ambiguous_GpC_site', 'ambiguous_CpG_site', 'other_C']
-    categories = adata.obs[obs_column].cat.categories
+    import numpy as np
+    import anndata as ad
+    import pandas as pd
+    import matplotlib.pyplot as plt
+    from .. import readwrite
+
+    references = set(adata.obs[reference_column])
+    sample_names = set(adata.obs[sample_names_col])
+
+    site_types = ['GpC_site', 'CpG_site', 'ambiguous_GpC_CpG_site', 'other_C']
+
     for site_type in site_types:
         adata.obs[f'{site_type}_row_methylation_sums'] = pd.Series(0, index=adata.obs_names, dtype=int)
         adata.obs[f'{site_type}_row_methylation_means'] = pd.Series(np.nan, index=adata.obs_names, dtype=float)
         adata.obs[f'number_valid_{site_type}_in_read'] = pd.Series(0, index=adata.obs_names, dtype=int)
         adata.obs[f'fraction_valid_{site_type}_in_range'] = pd.Series(np.nan, index=adata.obs_names, dtype=float)
-    for cat in categories:
-        cat_subset = adata[adata.obs[obs_column] == cat].copy()
+    for cat in references:
+        cat_subset = adata[adata.obs[reference_column] == cat].copy()
         for site_type in site_types:
             print(f'Iterating over {cat}_{site_type}')
             observation_matrix = cat_subset.obsm[f'{cat}_{site_type}']
@@ -35,4 +51,46 @@ def calculate_converted_read_methylation_stats(adata, obs_column='Reference'):
             adata.obs.update(temp_obs_data)
     # Indicate whether the read-level GpC methylation rate exceeds the false methylation rate of the read
     pass_array = np.array(adata.obs[f'GpC_site_row_methylation_means'] > adata.obs[f'other_C_row_methylation_means'])
-    adata.obs['GpC_above_other_C'] = pd.Series(pass_array, index=adata.obs.index, dtype=bool)
+    adata.obs['GpC_above_other_C'] = pd.Series(pass_array, index=adata.obs.index, dtype=bool)
+
+    adata.uns['methylation_dict'] = {}
+    n_bins = 50
+    site_types_to_analyze = ['GpC_site', 'CpG_site', 'ambiguous_GpC_CpG_site', 'other_C']
+
+    for reference in references:
+        reference_adata = adata[adata.obs[reference_column] == reference].copy()
+        split_reference = reference.split('_')[0][1:]
+        for sample in sample_names:
+            sample_adata = reference_adata[reference_adata.obs[sample_names_col] == sample].copy()
+            for site_type in site_types_to_analyze:
+                methylation_data = sample_adata.obs[f'{site_type}_row_methylation_means']
+                max_meth = np.max(sample_adata.obs[f'{site_type}_row_methylation_sums'])
+                if not np.isnan(max_meth):
+                    n_bins = int(max_meth // 2)
+                else:
+                    n_bins = 1
+                mean = np.mean(methylation_data)
+                median = np.median(methylation_data)
+                stdev = np.std(methylation_data)
+                adata.uns['methylation_dict'][f'{reference}_{sample}_{site_type}'] = [mean, median, stdev]
+                if show_methylation_histogram or save_methylation_histogram:
+                    fig, ax = plt.subplots(figsize=(6, 4))
+                    count, bins, patches =  plt.hist(methylation_data, bins=n_bins, weights=np.ones(len(methylation_data)) / len(methylation_data), alpha=0.7, color='blue', edgecolor='black')
+                    plt.axvline(median, color='red', linestyle='dashed', linewidth=1)
+                    plt.text(median + stdev, max(count)*0.8, f'Median: {median:.2f}', color='red')
+                    plt.axvline(median - stdev, color='green', linestyle='dashed', linewidth=1, label=f'Stdev: {stdev:.2f}')
+                    plt.axvline(median + stdev, color='green', linestyle='dashed', linewidth=1)
+                    plt.text(median + stdev + 0.05, max(count) / 3, f'+1 Stdev: {stdev:.2f}', color='green')
+                    plt.xlabel('Fraction methylated')
+                    plt.ylabel('Proportion')
+                    title = f'Distribution of {methylation_data.shape[0]} read {site_type} methylation means \nfor {sample} sample on {split_reference} after filtering'
+                    plt.title(title, pad=20)
+                    plt.xlim(-0.05, 1.05)  # Set x-axis range from 0 to 1
+                    ax.spines['right'].set_visible(False)
+                    ax.spines['top'].set_visible(False)
+                    save_name = output_directory + f'/{readwrite.date_string()} {title}'
+                    if save_methylation_histogram:
+                        plt.savefig(save_name, bbox_inches='tight', pad_inches=0.1)
+                        plt.close()
+                    else:
+                        plt.show()

smftools/preprocessing/calculate_coverage.py

@@ -1,21 +1,27 @@
 ## calculate_coverage
-from .. import readwrite
-import numpy as np
-import anndata as ad
-import pandas as pd
-
 
 def calculate_coverage(adata, obs_column='Reference', position_nan_threshold=0.05):
     """
-    Input: An adata object and an observation column of interest. Assess if the position is present in the dataset category.
-    Output: Append position level metadata indicating whether the position is informative within the given observation category.
+    Append position level metadata regarding whether the position is informative within the given observation category.
+
+    Parameters:
+        adata (AnnData): An AnnData object
+        obs_column (str): Observation column value to subset on prior to calculating position statistics for that category.
+        position_nan_threshold (float): A minimal fractional threshold of coverage within the obs_column category to call the position as valid.
+
+    Returns:
+        None
     """
+    import numpy as np
+    import anndata as ad
+    import pandas as pd
+
     categories = adata.obs[obs_column].cat.categories
     n_categories_with_position = np.zeros(adata.shape[1])
     # Loop over categories
     for cat in categories:
         # Look at positional information for each reference
-        temp_cat_adata = adata[adata.obs[obs_column] == cat]
+        temp_cat_adata = adata[adata.obs[obs_column] == cat].copy()
         # Look at read coverage on the given category strand
         cat_valid_coverage = np.sum(~np.isnan(temp_cat_adata.X), axis=0)
         cat_invalid_coverage = np.sum(np.isnan(temp_cat_adata.X), axis=0)

smftools/preprocessing/calculate_pairwise_hamming_distances.py

@@ -1,15 +1,20 @@
 ## calculate_pairwise_hamming_distances
-import numpy as np
-import tqdm
-from scipy.spatial.distance import hamming
 
 ## Conversion SMF Specific 
 def calculate_pairwise_hamming_distances(arrays):
     """
-    Calculate the pairwise Hamming distances for a list of ndarrays.
-    Input: A list of ndarrays
-    Output: a 2D array containing the pairwise Hamming distances.
+    Calculate the pairwise Hamming distances for a list of h-stacked ndarrays.
+
+    Parameters:
+        arrays (str): A list of ndarrays.
+
+    Returns:
+        distance_matrix (ndarray): a 2D array containing the pairwise Hamming distances between all arrays.
+
     """
+    import numpy as np
+    from tqdm import tqdm
+    from scipy.spatial.distance import hamming
     num_arrays = len(arrays)
     # Initialize an empty distance matrix
     distance_matrix = np.zeros((num_arrays, num_arrays))

smftools/preprocessing/calculate_position_Youden.py

@@ -1,20 +1,28 @@
 ## calculate_position_Youden
-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
-
-
 
 ## Calculating and applying position level thresholds for methylation calls to binarize the SMF data
 def calculate_position_Youden(adata, positive_control_sample, negative_control_sample, J_threshold=0.4, obs_column='Reference', save=False, output_directory=''):
     """
-    Input: An adata object, a plus MTase control, a minus MTase control, the minimal J-statistic threshold, and a categorical observation column to iterate over.
-    Input notes: The control samples are passed as string names of the samples as they appear in the 'Sample_names' obs column
-    Output: Adds new variable metadata to each position indicating whether the position provides reliable SMF methylation calls. Also outputs plots of the positional ROC curves.
-    Can optionally save the output plots of the ROC curve
+    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.
+        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
@@ -89,7 +97,8 @@ def calculate_position_Youden(adata, positive_control_sample, negative_control_s
             plt.savefig(save_name)
             plt.close()
         else:
-            plt.show()    
+            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

@@ -1,17 +1,36 @@
 ## calculate_read_length_stats
-import numpy as np
-import anndata as ad
-import pandas as pd
 
 # Read length QC
-def calculate_read_length_stats(adata):
+def calculate_read_length_stats(adata, reference_column, sample_names_col, output_directory, show_read_length_histogram=False, save_read_length_histogram=False):
     """
-    Input: An adata object
-    Output: Append first valid position in a read and last valid position in the read. From this determine and append the read length. 
-    Return two new variable which hold the first and last valid positions in the entire dataset
+    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
+        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
+        lower_bound (int): first valid position in the dataset
     """
-    ## 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
+    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])
 
+    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))])
@@ -24,4 +43,44 @@ def calculate_read_length_stats(adata):
     # 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']))
+
+# 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

smftools/preprocessing/clean_NaN.py

@@ -1,14 +1,21 @@
 ## clean_NaN
-import numpy as np
-import anndata as ad
-import pandas as pd
 
-# NaN handling
 def clean_NaN(adata, layer=None):
     """
-    Input: An adata object and the layer to fill Nan values of
-    Output: Append layers to adata that contain NaN cleaning strategies
+    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
+
+    Returns:
+        None
     """
+    import numpy as np
+    import anndata as ad
+    import pandas as pd
+    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)

smftools/preprocessing/filter_converted_reads_on_methylation.py

@@ -1,15 +1,22 @@
 ## filter_converted_reads_on_methylation
-import numpy as np
-import anndata as ad
-import pandas as pd
 
 ## Conversion SMF Specific 
 # Read methylation QC
 def filter_converted_reads_on_methylation(adata, valid_SMF_site_threshold=0.8, min_SMF_threshold=0.025):
     """
-    Input: Adata object. Minimum thresholds for valid SMF site fraction in read, as well as minimum methylation content in read
-    Output: A subset of the adata object
+    Filter adata object using minimum thresholds for valid SMF site fraction in read, as well as minimum methylation content in read.
+
+    Parameters:
+        adata (AnnData): An adata object.
+        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.
     """
+    import numpy as np
+    import anndata as ad
+    import pandas as pd
+
     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()
@@ -17,4 +24,6 @@ def filter_converted_reads_on_methylation(adata, valid_SMF_site_threshold=0.8, m
         # Keep reads with SMF methylation over background methylation.
         adata = adata[adata.obs['GpC_above_other_C'] == True].copy()
         # Keep reads over a defined methylation threshold
-        adata = adata[adata.obs['GpC_site_row_methylation_means'] > min_SMF_threshold].copy()
+        adata = adata[adata.obs['GpC_site_row_methylation_means'] > min_SMF_threshold].copy()
+        
+    return adata