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

smftools/__init__.py

@@ -3,7 +3,6 @@
 import logging
 import warnings
 
-from anndata import AnnData
 from . import informatics as inform
 from . import preprocessing as pp
 from . import tools as tl
@@ -17,7 +16,6 @@ package_name = "smftools"
 __version__ = version(package_name)
 
 __all__ = [
-    "AnnData",
     "inform",
     "pp",
     "tl",

smftools/_settings.py

@@ -10,7 +10,7 @@ class SMFConfig:
         *,
         datasetdir: Path | str = "./datasets/"
     ):
-        self.datasetdir = datasetdir
+         self._datasetdir = Path(datasetdir) if isinstance(datasetdir, str) else datasetdir
 
     @property
     def datasetdir(self) -> Path:

smftools/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.1"

smftools/datasets/datasets.py

@@ -1,19 +1,20 @@
 ## datasets
 
-import numpy as np
-import pandas as pd
-import anndata as ad
-from pathlib import Path
-
-from .._settings import settings
-
-HERE = Path(__file__).parent
-
+def import_deps():
+    """
+    
+    """
+    import anndata as ad
+    from pathlib import Path
+    from .._settings import settings
+    HERE = Path(__file__).parent
+    return HERE
 
 def dCas9_kinetics():
     """
     
     """
+    HERE = import_deps()
     filepath = HERE / "dCas9_m6A_invitro_kinetics.h5ad.gz"
     return ad.read_h5ad(filepath)
 
@@ -21,5 +22,6 @@ def Kissiov_and_McKenna_2025():
     """
     
     """
+    HERE = import_deps()
     filepath = HERE / "F1_hybrid_NKG2A_enhander_promoter_GpC_conversion_SMF.h5ad.gz"
     return ad.read_h5ad(filepath)

smftools/informatics/__init__.py

@@ -1,11 +1,12 @@
-from . import helpers
-from .pod5_conversion import pod5_conversion
-from .pod5_direct import pod5_direct
 from .pod5_to_adata import pod5_to_adata
+from .basecalls_to_adata import basecalls_to_adata
+from .subsample_pod5 import subsample_pod5
+from .fast5_to_pod5 import fast5_to_pod5
+
 
 __all__ = [
-    "helpers",
-    "pod5_conversion",
-    "pod5_direct"
-    "pod5_to_adata"
+    "pod5_to_adata",
+    "basecalls_to_adata",
+    "subsample_pod5",
+    "fast5_to_pod5"
 ]

smftools/informatics/bam_conversion.py

@@ -0,0 +1,47 @@
+## bam_conversion
+
+def bam_conversion(fasta, output_directory, conversion_types, strands, basecalled_path, split_dir, mapping_threshold, experiment_name, bam_suffix):
+    """
+    Converts a BAM file from a nanopore conversion SMF experiment to an adata object.
+
+    Parameters:
+        fasta (str): File path to the reference genome to align to.
+        output_directory (str): A file path to the directory to output all the analyses.
+        conversion_type (list): A list of strings of the conversion types to use in the analysis.
+        strands (list): A list of converstion strands to use in the experiment.
+        basecalled_path (str): a string representing the file path to the experiment BAM or FASTQ file.
+        split_dir (str): A string representing the file path to the directory to split the BAMs into.
+        mapping_threshold (float): A value in between 0 and 1 to threshold the minimal fraction of aligned reads which map to the reference region. References with values above the threshold are included in the output adata.
+        experiment_name (str): A string to provide an experiment name to the output adata file.
+        bam_suffix (str): A suffix to add to the bam file.
+
+    Returns:
+        None
+    """
+    from .helpers import align_and_sort_BAM, converted_BAM_to_adata, generate_converted_FASTA, split_and_index_BAM
+    import os
+    input_basecalled_basename = os.path.basename(basecalled_path)
+    bam_basename = input_basecalled_basename.split(".")[0]
+    output_bam=f"{output_directory}/{bam_basename}"
+    aligned_BAM=f"{output_bam}_aligned"
+    aligned_sorted_BAM=f"{aligned_BAM}_sorted"
+
+    os.chdir(output_directory)
+
+    # 1) Convert FASTA file
+    fasta_basename = os.path.basename(fasta)
+    converted_FASTA_basename = fasta_basename.split('.fa')[0]+'_converted.fasta'
+    converted_FASTA = os.path.join(output_directory, converted_FASTA_basename)
+    if os.path.exists(converted_FASTA):
+        print(converted_FASTA + ' already exists. Using existing converted FASTA.')
+    else:
+        generate_converted_FASTA(fasta, conversion_types, strands, converted_FASTA)
+
+    # 2) Align the basecalled file to the converted reference FASTA and sort the bam on positional coordinates. Also make an index and a bed file of mapped reads
+    align_and_sort_BAM(converted_FASTA, basecalled_path, bam_suffix, output_directory)
+
+    ### 3) Split the aligned and sorted BAM files by barcode (BC Tag) into the split_BAM directory###
+    split_and_index_BAM(aligned_sorted_BAM, split_dir, bam_suffix)
+
+    # 4) Take the converted BAM and load it into an adata object. 
+    converted_BAM_to_adata(converted_FASTA, split_dir, mapping_threshold, experiment_name, conversion_types, bam_suffix)

smftools/informatics/bam_direct.py

@@ -0,0 +1,49 @@
+## bam_direct
+
+def bam_direct(fasta, output_directory, mod_list, thresholds, bam_path, split_dir, mapping_threshold, experiment_name, bam_suffix, batch_size):
+    """
+    Converts a POD5 file from a nanopore native SMF experiment to an adata object.
+
+    Parameters:
+        fasta (str): File path to the reference genome to align to.
+        output_directory (str): A file path to the directory to output all the analyses.
+        mod_list (list): A list of strings of the modification types to use in the analysis.
+        thresholds (list): A list of floats to pass for call thresholds.
+        bam_path (str): a string representing the file path to the the BAM file.
+        split_dir (str): A string representing the file path to the directory to split the BAMs into.
+        mapping_threshold (float): A value in between 0 and 1 to threshold the minimal fraction of aligned reads which map to the reference region. References with values above the threshold are included in the output adata.
+        experiment_name (str): A string to provide an experiment name to the output adata file.
+        bam_suffix (str): A suffix to add to the bam file.
+        batch_size (int): An integer number of TSV files to analyze in memory at once while loading the final adata object.
+
+    Returns:
+        None   
+    """
+    from .helpers import align_and_sort_BAM, extract_mods, make_modbed, modkit_extract_to_adata, modQC, split_and_index_BAM, make_dirs
+    import os
+    input_bam_base = os.path.basename(bam_path)
+    bam_basename = input_bam_base.split(bam_suffix)[0]
+    output_bam=f"{output_directory}/{bam_basename}"
+    aligned_BAM=f"{output_bam}_aligned"
+    aligned_sorted_BAM=f"{aligned_BAM}_sorted"
+    mod_bed_dir=f"{output_directory}/split_mod_beds"
+    mod_tsv_dir=f"{output_directory}/split_mod_tsvs"
+
+    make_dirs([mod_bed_dir, mod_tsv_dir])
+
+    aligned_sorted_output = aligned_sorted_BAM + bam_suffix
+    mod_map = {'6mA': '6mA', '5mC_5hmC': '5mC'}
+    mods = [mod_map[mod] for mod in mod_list]
+
+    os.chdir(output_directory)
+
+    # 1) Align the BAM to the reference FASTA. Also make an index and a bed file of mapped reads
+    align_and_sort_BAM(fasta, bam_path, bam_suffix, output_directory)
+    # 2) Split the aligned and sorted BAM files by barcode (BC Tag) into the split_BAM directory
+    split_and_index_BAM(aligned_sorted_BAM, split_dir, bam_suffix)
+    # 3) Using nanopore modkit to work with modified BAM files ###
+    modQC(aligned_sorted_output, thresholds) # get QC metrics for mod calls
+    make_modbed(aligned_sorted_output, thresholds, mod_bed_dir) # Generate bed files of position methylation summaries for every sample
+    extract_mods(thresholds, mod_tsv_dir, split_dir, bam_suffix) # Extract methylations calls for split BAM files into split TSV files
+    #4 Load the modification data from TSVs into an adata object
+    modkit_extract_to_adata(fasta, aligned_sorted_output, mapping_threshold, experiment_name, mods, batch_size)

smftools/informatics/basecalls_to_adata.py

@@ -0,0 +1,42 @@
+## basecalls_to_adata
+
+def basecalls_to_adata(config_path):
+    """
+    High-level function to call for loading basecalled SMF data from a BAM file into an adata object. Also works with FASTQ for conversion SMF.
+
+    Parameters:
+        config_path (str): A string representing the file path to the experiment configuration csv file.
+
+    Returns:
+        None
+    """
+    from .helpers import LoadExperimentConfig, make_dirs
+    import os
+    bam_suffix = '.bam' # If different, change from here.
+    split_dir = 'split_BAMs' # If different, change from here.
+    strands = ['bottom', 'top'] # If different, change from here. Having both listed generally doesn't slow things down too much.
+    conversions = ['unconverted'] # The name to use for the unconverted files. If different, change from here.
+
+    # Load experiment config parameters into global variables
+    experiment_config = LoadExperimentConfig(config_path)
+    var_dict = experiment_config.var_dict
+    for key, value in var_dict.items():
+        globals()[key] = value
+
+    split_path = os.path.join(output_directory, split_dir)
+    make_dirs([output_directory, split_path])
+    os.chdir(output_directory)
+
+    conversions += conversion_types
+
+    if smf_modality == 'conversion':
+        from .bam_conversion import bam_conversion
+        bam_conversion(fasta, output_directory, conversions, strands, basecalled_path, split_path, mapping_threshold, experiment_name, bam_suffix)
+    elif smf_modality == 'direct':
+        if bam_suffix in basecalled_path:
+            from .bam_direct import bam_direct
+            bam_direct(fasta, output_directory, mod_list, thresholds, basecalled_path, split_path, mapping_threshold, experiment_name, bam_suffix, batch_size)
+        else:
+            print('basecalls_to_adata function only work with the direct modality when the input filetype is BAM and not FASTQ.')
+    else:
+        print("Error")

smftools/informatics/fast5_to_pod5.py

@@ -0,0 +1,19 @@
+# fast5_to_pod5
+
+def fast5_to_pod5(fast5_dir, output_dir='outputs/', output_pod5='FAST5s_to_POD5.pod5'):
+    """
+    Convert Nanopore FAST5 files to POD5 file
+
+    Parameters:
+        fast5_dir (str): String representing the file path to a directory containing all FAST5 files to convert into a single POD5 output.
+        output_dir (str): String representing the file path to the output directory.
+        output_pod5 (str): The name of the output POD5 to write out within the output directory.
+    
+    Returns:
+        None
+    
+    """
+    import subprocess
+    import os
+    pod5 = os.path.join(output_dir, output_pod5)
+    subprocess.run(["pod5", "convert", "fast5", f".{fast5_dir}*.fast5", "--output", pod5])

smftools/informatics/helpers/LoadExperimentConfig.py

@@ -0,0 +1,74 @@
+## LoadExperimentConfig
+
+class LoadExperimentConfig:
+    """
+    Loads in the experiment configuration csv and saves global variables with experiment configuration parameters.
+    Parameters:
+        experiment_config (str): A string representing the file path to the experiment configuration csv file.
+    
+    Attributes:
+        var_dict (dict): A dictionary containing experiment configuration parameters.
+
+    Example:
+        >>> import pandas as pd
+        >>> from io import StringIO
+        >>> csv_data = '''variable,value,type
+        ... mapping_threshold,0.05,float
+        ... batch_size,4,int
+        ... testing_bool,True,bool
+        ... strands,"[bottom, top]",list
+        ... split_dir,split_bams,string
+        ... pod5_dir,None,string
+        ... pod5_dir,,string
+        ... '''
+        >>> csv_file = StringIO(csv_data)
+        >>> df = pd.read_csv(csv_file)
+        >>> df.to_csv('test_config.csv', index=False)
+        >>> config_loader = LoadExperimentConfig('test_config.csv')
+        >>> config_loader.var_dict['mapping_threshold']
+        0.05
+        >>> config_loader.var_dict['batch_size']
+        4
+        >>> config_loader.var_dict['testing_bool']
+        True
+        >>> config_loader.var_dict['strands']
+        ['bottom', 'top']
+        >>> config_loader.var_dict['split_dir']
+        'split_bams'
+        >>> config_loader.var_dict['pod5_dir'] is None
+        True
+        >>> config_loader.var_dict['pod5_dir'] is None
+        True
+    """
+    def __init__(self, experiment_config):
+        import pandas as pd
+        # Read the CSV into a pandas DataFrame
+        df = pd.read_csv(experiment_config)
+        # Initialize an empty dictionary to store variables
+        var_dict = {}
+        # Iterate through each row in the DataFrame
+        for _, row in df.iterrows():
+            var_name = str(row['variable'])
+            value = row['value']
+            dtype = row['type']
+            # Handle empty and None values
+            if pd.isna(value) or value in ['None', '']:
+                value = None
+            else:
+                # Handle different data types
+                if dtype == 'list':
+                    # Convert the string representation of a list to an actual list
+                    value = value.strip('()[]').replace(', ', ',').split(',')
+                elif dtype == 'int':
+                    value = int(value)
+                elif dtype == 'float':
+                    value = float(value)
+                elif dtype == 'bool':
+                    value = value.lower() == 'true'
+                elif dtype == 'string':
+                    value = str(value)
+            # Store the variable in the dictionary
+            var_dict[var_name] = value
+        # Save the dictionary as an attribute of the class
+        self.var_dict = var_dict
+

smftools/informatics/helpers/__init__.py

@@ -1,4 +1,4 @@
-from .align_BAM import align_BAM
+from .align_and_sort_BAM import align_and_sort_BAM
 from .binarize_converted_base_identities import binarize_converted_base_identities
 from .canoncall import canoncall
 from .converted_BAM_to_adata import converted_BAM_to_adata
@@ -8,7 +8,7 @@ from .extract_mods import extract_mods
 from .find_conversion_sites import find_conversion_sites
 from .generate_converted_FASTA import convert_FASTA_record, generate_converted_FASTA
 from .get_native_references import get_native_references
-from .load_experiment_config import load_experiment_config
+from .LoadExperimentConfig import LoadExperimentConfig
 from .make_dirs import make_dirs
 from .make_modbed import make_modbed
 from .modcall import modcall
@@ -19,7 +19,7 @@ from .separate_bam_by_bc import separate_bam_by_bc
 from .split_and_index_BAM import split_and_index_BAM
 
 __all__ = [
-    "align_BAM",
+    "align_and_sort_BAM",
     "binarize_converted_base_identities",
     "canoncall",
     "converted_BAM_to_adata",
@@ -30,7 +30,7 @@ __all__ = [
     "convert_FASTA_record",
     "generate_converted_FASTA",
     "get_native_references",
-    "load_experiment_config",
+    "LoadExperimentConfig",
     "make_dirs",
     "make_modbed",
     "modcall",

smftools/informatics/helpers/align_and_sort_BAM.py

@@ -0,0 +1,52 @@
+## align_and_sort_BAM
+
+def align_and_sort_BAM(fasta, input, bam_suffix, output_directory):
+    """
+    A wrapper for running dorado aligner and samtools functions
+    
+    Parameters:
+        fasta (str): File path to the reference genome to align to.
+        input (str): File path to the basecalled file to align. Works for .bam and .fastq files
+        bam_suffix (str): The suffix to use for the BAM file.
+        output_directory (str): A file path to the directory to output all the analyses.
+
+    Returns:
+        None
+            The function writes out files for: 1) An aligned BAM, 2) and aligned_sorted BAM, 3) an index file for the aligned_sorted BAM, 4) A bed file for the aligned_sorted BAM, 5) A text file containing read names in the aligned_sorted BAM
+    """
+    import subprocess
+    import os
+    input_basename = os.path.basename(input)
+    input_suffix = '.' + input_basename.split('.')[1]
+
+    output_path_minus_suffix = os.path.join(output_directory, input_basename.split(input_suffix)[0])
+    
+    aligned_BAM=f"{output_path_minus_suffix}_aligned"
+    aligned_sorted_BAM=f"{aligned_BAM}_sorted"
+    aligned_output = aligned_BAM + bam_suffix
+    aligned_sorted_output = aligned_sorted_BAM + bam_suffix
+    
+    # Run dorado aligner
+    subprocess.run(["dorado", "aligner", "--secondary=no", fasta, input], stdout=open(aligned_output, "w"))
+
+    # Sort the BAM on positional coordinates
+    subprocess.run(["samtools", "sort", "-o", aligned_sorted_output, aligned_output])
+
+    # Create a BAM index file
+    subprocess.run(["samtools", "index", aligned_sorted_output])
+
+    # Make a bed file of coordinates for the BAM
+    samtools_view = subprocess.Popen(["samtools", "view", aligned_sorted_output], stdout=subprocess.PIPE) 
+    with open(f"{aligned_sorted_BAM}_bed.bed", "w") as output_file:
+        awk_process = subprocess.Popen(["awk", '{print $3, $4, $4+length($10)-1}'], stdin=samtools_view.stdout, stdout=output_file)    
+    samtools_view.stdout.close()
+    awk_process.wait()
+    samtools_view.wait()
+
+    # Make a text file of reads for the BAM
+    samtools_view = subprocess.Popen(["samtools", "view", aligned_sorted_output], stdout=subprocess.PIPE)
+    with open(f"{aligned_sorted_BAM}_read_names.txt", "w") as output_file:
+        cut_process = subprocess.Popen(["cut", "-f1"], stdin=samtools_view.stdout, stdout=output_file)   
+    samtools_view.stdout.close()
+    cut_process.wait()
+    samtools_view.wait()

smftools/informatics/helpers/binarize_converted_base_identities.py

@@ -1,11 +1,18 @@
 ## binarize_converted_base_identities
-import numpy as np
 # Conversion SMF specific
 def binarize_converted_base_identities(base_identities, strand, modification_type):
     """
-    Input: The base identities dictionary returned by extract_base_identity_at_coordinates.
-    Output: A binarized format of the dictionary, where 1 represents a methylated site. 0 represents an unmethylated site. NaN represents a site that does not carry SMF information.
+    Binarizes conversion SMF data within a sequence string
+
+    Parameters:
+        base_identities (dict): A dictionary returned by extract_base_identity_at_coordinates.
+        strand (str): A string indicating which strand was converted in the experiment (options are 'top' and 'bottom').
+        modification_type (str): A string indicating the modification type of interest (options are '5mC' and '6mA').
+    
+    Returns:
+        binarized_base_identities (dict): A binarized dictionary, where 1 represents a methylated site. 0 represents an unmethylated site. NaN represents a site that does not carry methylation information.
     """
+    import numpy as np
     binarized_base_identities = {}
     # Iterate over base identity keys to binarize the base identities
     for key in base_identities.keys():

smftools/informatics/helpers/canoncall.py

@@ -1,11 +1,22 @@
 ## canoncall
-import subprocess
 
 # Conversion SMF specific
 def canoncall(model, pod5_dir, barcode_kit, bam, bam_suffix):
     """
     Wrapper function for dorado canonical base calling.
+
+    Parameters:
+        model (str): a string representing the file path to the dorado basecalling model.
+        pod5_dir (str): a string representing the file path to the experiment directory containing the POD5 files.
+        barcode_kit (str): A string reppresenting the barcoding kit used in the experiment.
+        bam (str): File path to the BAM file to output.
+        bam_suffix (str): The suffix to use for the BAM file.
+    
+    Returns:
+        None
+            Outputs a BAM file holding the canonical base calls output by the dorado basecaller.
     """
+    import subprocess
     output = bam + bam_suffix
     command = ["dorado", "basecaller", model, pod5_dir, "--kit-name", barcode_kit, "-Y"]
     with open(output, "w") as outfile:

smftools/informatics/helpers/converted_BAM_to_adata.py

@@ -1,19 +1,32 @@
 ## converted_BAM_to_adata
-from .. import readwrite
-from .binarize_converted_base_identities import binarize_converted_base_identities
-from .find_conversion_sites import find_conversion_sites
-from .count_aligned_reads import count_aligned_reads
-from .extract_base_identities import extract_base_identities
-from .one_hot_encode import one_hot_encode
-import pandas as pd
-import numpy as np
-import anndata as ad
-import os
 
 def converted_BAM_to_adata(converted_FASTA, split_dir, mapping_threshold, experiment_name, conversion_types, bam_suffix):
     """
+    A wrapper function to take converted aligned_sorted_split BAM files and format the data into an anndata object.
+
+    Parameters:
+        converted_FASTA (str): A string representing the file path to the converted FASTA reference.
+        split_dir (str): A string representing the file path to the directory containing the converted aligned_sorted_split BAM files.
+        mapping_threshold (float): A value in between 0 and 1 to threshold the minimal fraction of aligned reads which map to the reference region. References with values above the threshold are included in the output adata.
+        experiment_name (str): A string to provide an experiment name to the output adata file.
+        conversion_types (list): A list of strings of the conversion types to use in the analysis.
+        bam_suffix (str): The suffix to use for the BAM file.
     
+    Returns:
+        None
+        Outputs a single gzipped adata object for the experiment.
     """
+    from .. import readwrite
+    from .binarize_converted_base_identities import binarize_converted_base_identities
+    from .find_conversion_sites import find_conversion_sites
+    from .count_aligned_reads import count_aligned_reads
+    from .extract_base_identities import extract_base_identities
+    from .one_hot_encode import one_hot_encode
+    import pandas as pd
+    import numpy as np
+    import anndata as ad
+    import os
+
     # Get all of the input BAM files
     files = os.listdir(split_dir)
     # Change directory to the BAM directory
@@ -30,11 +43,14 @@ def converted_BAM_to_adata(converted_FASTA, split_dir, mapping_threshold, experi
     # While populating the dictionary, also extract the longest sequence record in the input references
     max_reference_length = 0
     for conversion_type in conversion_types:
-        modification_dict[conversion_type] = find_conversion_sites(converted_FASTA, conversion_type)
+        modification_dict[conversion_type] = find_conversion_sites(converted_FASTA, conversion_type, conversion_types)
         for record in modification_dict[conversion_type].keys():
             if modification_dict[conversion_type][record][0] > max_reference_length:
                 max_reference_length = modification_dict[conversion_type][record][0]
 
+    # Init a dict to be keyed by FASTA record that points to the sequence string of the unconverted record
+    record_FASTA_dict = {}
+
     # Iterate over the experiment BAM files
     for bam_index, bam in enumerate(bams):
         # Give each bam a sample name
@@ -51,7 +67,6 @@ def converted_BAM_to_adata(converted_FASTA, split_dir, mapping_threshold, experi
                 records_to_analyze.append(record)
         print(f'Records to analyze: {records_to_analyze}')
         # Iterate over records to analyze (ie all conversions detected)
-        record_FASTA_dict = {}
         for record in records_to_analyze:
             mod_type, strand = record.split('_')[-2:]
             if strand == 'top':
@@ -60,7 +75,7 @@ def converted_BAM_to_adata(converted_FASTA, split_dir, mapping_threshold, experi
                 strand_index = 2
 
             chromosome = record.split('_{0}_{1}'.format(mod_type, strand))[0]
-            unconverted_chromosome_name = chromosome + '_unconverted_top'
+            unconverted_chromosome_name = f'{chromosome}_{conversion_types[0]}_top'
             positions = modification_dict[mod_type][unconverted_chromosome_name][strand_index]
             current_reference_length = modification_dict[mod_type][unconverted_chromosome_name][0]
             delta_max_length = max_reference_length - current_reference_length
@@ -130,6 +145,8 @@ def converted_BAM_to_adata(converted_FASTA, split_dir, mapping_threshold, experi
         sequence = record_FASTA_dict[record]
         final_adata.uns[f'{record}_FASTA_sequence'] = sequence
         final_adata.var[f'{record}_FASTA_sequence'] = list(sequence)
+
+        # May need to remove the bottom for conversion SMF
         record_subset = final_adata[final_adata.obs['Reference'] == record].copy()
         layer_map, layer_counts = {}, []
         for i, layer in enumerate(record_subset.layers):

smftools/informatics/helpers/count_aligned_reads.py

@@ -1,14 +1,21 @@
 ## count_aligned_reads
-from .. import readwrite
-# bioinformatic operations
-import pysam
 
 # General
 def count_aligned_reads(bam_file):
     """
-    Input: A BAM alignment file.
-    Output: The number of aligned/unaligned reads in the BAM file. Also returns a dictionary, keyed by reference id that points to a tuple. The tuple contains an integer number of mapped reads to that reference, followed by the proportion of mapped reads that map to that reference
+    Counts the number of aligned reads in a bam file that map to each reference record.
+    
+    Parameters:
+        bam_file (str): A string representing the path to an aligned BAM file.
+    
+    Returns:
+       aligned_reads_count (int): The total number or reads aligned in the BAM.
+       unaligned_reads_count (int): The total number of reads not aligned in the BAM.
+       record_counts (dict): A dictionary keyed by reference record instance that points toa tuple containing the total reads mapped to the record and the fraction of mapped reads which map to the record.
+
     """
+    from .. import readwrite
+    import pysam
     print('{0}: Counting aligned reads in BAM > {1}'.format(readwrite.time_string(), bam_file))
     aligned_reads_count = 0
     unaligned_reads_count = 0

smftools/informatics/helpers/extract_base_identities.py

@@ -1,15 +1,22 @@
 ## extract_base_identities
-from .. import readwrite
-# bioinformatic operations
-import pysam
 
 # General
 def extract_base_identities(bam_file, chromosome, positions, max_reference_length):
     """
-    Input: A position sorted BAM file, chromosome number, position coordinate set, and reference length to extract the base identitity from the read.
-    Output: A dictionary, keyed by read name, that points to a list of Base identities from each read.
-    If the read does not contain that position, fill the list at that index with a N value.
+    Extracts the base identities from every position within the read that has a reference coordinate
+
+    Parameters:
+        bam (str): File path to the BAM file to align (excluding the file suffix).
+        chromosome (str): A string representing the name of the record within the reference FASTA.
+        positions (list): A list of position coordinates within the record to extract.
+        max_reference_length (int): The maximum length of a record in the reference set.
+
+    Returns:
+        base_identities (dict): A dictionary, keyed by read name, that points to a list of base identities. If the read does not contain that position, fill the list at that index with a N value.
+    
     """
+    from .. import readwrite
+    import pysam
     positions = set(positions)
     # Initialize a base identity dictionary that will hold key-value pairs that are: key (read-name) and value (list of base identities at positions of interest)
     base_identities = {}

smftools/informatics/helpers/extract_mods.py

@@ -1,13 +1,25 @@
 ## extract_mods
-import os
-import subprocess
-import glob
-import zipfile
 
 def extract_mods(thresholds, mod_tsv_dir, split_dir, bam_suffix):
     """
     Takes all of the aligned, sorted, split modified BAM files and runs Nanopore Modkit Extract to load the modification data into zipped TSV files
+
+    Parameters:
+        thresholds (list): A list of thresholds to use for marking each basecalled base as passing or failing on canonical and modification call status.
+        mod_tsv_dir (str): A string representing the file path to the directory to hold the modkit extract outputs.
+        split_dit (str): A string representing the file path to the directory containing the converted aligned_sorted_split BAM files.
+        bam_suffix (str): The suffix to use for the BAM file.
+
+    Returns:
+        None
+        Runs modkit extract on input aligned_sorted_split modified BAM files to output zipped TSVs containing modification calls.
+
     """
+    import os
+    import subprocess
+    import glob
+    import zipfile
+    
     os.chdir(mod_tsv_dir)
     filter_threshold, m6A_threshold, m5C_threshold, hm5C_threshold = thresholds
     bam_files = glob.glob(os.path.join(split_dir, f"*{bam_suffix}"))
@@ -23,7 +35,7 @@ def extract_mods(thresholds, mod_tsv_dir, split_dir, bam_suffix):
         # Run modkit extract
         subprocess.run([
             "modkit", "extract",
-            "--filter-threshold", filter_threshold,
+            "--filter-threshold", f'{filter_threshold}',
             "--mod-thresholds", f"m:{m5C_threshold}",
             "--mod-thresholds", f"a:{m6A_threshold}",
             "--mod-thresholds", f"h:{hm5C_threshold}",