smftools 0.1.0__tar.gz

smftools-0.1.0/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

smftools-0.1.0/.gitignore

@@ -0,0 +1,45 @@
+# Python
+__pycache__/
+/src/smftools/_version.py
+
+# Build files
+build/
+dist/
+/hatch.toml
+/Pipfile
+/Pipfile.lock
+
+# Environments
+.env
+.venv
+/*-env/
+/*-venv/
+/env-*/
+/venv-*/
+/environment.yml
+
+# OS
+*.DS_Store
+*.LSOverride
+*Thumbs.db
+*.ipynb_checkpoints/
+*.directory
+
+# IDEs and editors
+*.vscode/
+*.idea/
+*.iml
+
+# Logs
+*.log
+
+# temp files
+temp/
+tmp/
+
+# Coverage reports
+.coverage
+htmlcov/
+
+# Docs
+/docs

smftools-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 jkmckenna
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

smftools-0.1.0/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.3
+Name: smftools
+Version: 0.1.0
+Summary: Single Molecule Footprinting Analysis in Python.
+Project-URL: Source, https://github.com/jkmckenna/smftools
+Author: Joseph McKenna
+Maintainer-email: Joseph McKenna <jkmckenna@berkeley.edu>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: anndata,chromatin-accessibility,machine-learning,nanopore,protein-dna-binding,single-locus,single-molecule-footprinting
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.9
+Requires-Dist: anndata>=0.10.0
+Requires-Dist: biopython>=1.79
+Requires-Dist: cython>=0.29.28
+Requires-Dist: networkx>=3.2
+Requires-Dist: numpy<2,>=1.22.0
+Requires-Dist: pandas>=1.4.2
+Requires-Dist: pomegranate>1.0.0
+Requires-Dist: pysam>=0.19.1
+Requires-Dist: scanpy>=1.9
+Requires-Dist: scikit-learn>=1.0.2
+Requires-Dist: scipy>=1.7.3
+Requires-Dist: seaborn>=0.11
+Requires-Dist: tqdm
+Provides-Extra: base-tests
+Requires-Dist: pytest; extra == 'base-tests'
+Requires-Dist: pytest-cov; extra == 'base-tests'
+Provides-Extra: doc
+Requires-Dist: ipython>=7.20; extra == 'doc'
+Requires-Dist: matplotlib!=3.6.1; extra == 'doc'
+Requires-Dist: myst-nb>=1; extra == 'doc'
+Requires-Dist: myst-parser>=2; extra == 'doc'
+Requires-Dist: nbsphinx>=0.9; extra == 'doc'
+Requires-Dist: readthedocs-sphinx-search; extra == 'doc'
+Requires-Dist: setuptools; extra == 'doc'
+Requires-Dist: sphinx-autodoc-typehints>=1.25.2; extra == 'doc'
+Requires-Dist: sphinx-book-theme>=1.1.0; extra == 'doc'
+Requires-Dist: sphinx-copybutton; extra == 'doc'
+Requires-Dist: sphinx-design; extra == 'doc'
+Requires-Dist: sphinx>=7; extra == 'doc'
+Requires-Dist: sphinxcontrib-bibtex; extra == 'doc'
+Requires-Dist: sphinxext-opengraph; extra == 'doc'
+Provides-Extra: torch
+Requires-Dist: pomeganate>=1.0.0; extra == 'torch'
+Requires-Dist: torch>=1.9.0; extra == 'torch'
+Provides-Extra: torch-tests
+Requires-Dist: pomeganate>=1.0.0; extra == 'torch-tests'
+Requires-Dist: pytest; extra == 'torch-tests'
+Requires-Dist: pytest-cov; extra == 'torch-tests'
+Requires-Dist: torch>=1.9.0; extra == 'torch-tests'
+Description-Content-Type: text/markdown
+
+# smftools
+A tool for processing raw sequencing data for single molecule footprinting experiments at single genomic loci.
+
+## Dependencies
+The following tools need to be installed and configured:
+1) [Dorado](https://github.com/nanoporetech/dorado) -> For standard/modified basecalling and alignment. Can be attained by downloading and configuring nanopore MinKnow software.
+2) [Samtools](https://github.com/samtools/samtools) -> For working with SAM/BAM files
+3) [Minimap2](https://github.com/lh3/minimap2) -> The aligner used by Dorado
+4) [Modkit](https://github.com/nanoporetech/modkit) -> Extracting summary statistics and read level methylation calls from modified BAM files

smftools-0.1.0/README.md

@@ -0,0 +1,9 @@
+# smftools
+A tool for processing raw sequencing data for single molecule footprinting experiments at single genomic loci.
+
+## Dependencies
+The following tools need to be installed and configured:
+1) [Dorado](https://github.com/nanoporetech/dorado) -> For standard/modified basecalling and alignment. Can be attained by downloading and configuring nanopore MinKnow software.
+2) [Samtools](https://github.com/samtools/samtools) -> For working with SAM/BAM files
+3) [Minimap2](https://github.com/lh3/minimap2) -> The aligner used by Dorado
+4) [Modkit](https://github.com/nanoporetech/modkit) -> Extracting summary statistics and read level methylation calls from modified BAM files

smftools-0.1.0/experiment_config.csv

@@ -0,0 +1,20 @@
+variable,value,help,options,type
+base_dir,,Path to directory to act as root directory for analysis,,string
+smf_modality,,Modality of SMF. Can either be conversion or direct.,"conversion, direct",string
+pod5_dir,,Path to directory containing input POD5 files (If doing Nanopore SMF),,string
+fastq_dir,,Path to directory containing input FASTQ files (if doing Illumina based conversion SMF),,string
+fasta,,Path to initial FASTA file,,string
+bam_suffix,,The file suffix used for BAM files.,,string
+output_directory,,Directory within BASE_dir to create for analysis outputs,,string
+experiment_name,,An experiment name for the final h5ad file,,string
+model,,The dorado basecalling model to use,,string
+barcode_kit,,The barcoding kit used for the experiment,,string
+mapping_threshold,,Minimum proportion of reads mapping to a reference to further use that reference (Ranges from 0-1 as a proportion of mapped reads),,float
+filter_threshold,,Minimum probability to call a canonical base identity,,float
+m6A_threshold,,Minimum probability to flag m6A as True,,float
+m5C_threshold,,Minimum probability to flag m5C as True,,float
+hm5C_threshold,,Minimum probability to flag hm5C as True,,float
+mod_list,,Modified base names for Dorado,"""6mA"", ""5mC_5hmC""",list
+batch_size,,number of samples to analyze at a time,,int
+conversion_types,,Types of modification types to use in conversion SMF,"unconverted', '5mC', '6mA'",list
+strands,,Converted strands to analyze for conversion SMF,"top','bottom'",list

smftools-0.1.0/pyproject.toml

@@ -0,0 +1,132 @@
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[project]
+name = "smftools"
+description = "Single Molecule Footprinting Analysis in Python."
+requires-python = ">=3.9"
+license = "MIT"
+authors = [
+    {name = "Joseph McKenna"}
+]
+maintainers = [
+    {name = "Joseph McKenna", email = "jkmckenna@berkeley.edu"}
+]
+keywords = [
+  "single-molecule-footprinting",
+  "chromatin-accessibility",
+  "protein-dna-binding",
+  "nanopore",
+  "single-locus",
+  "anndata",
+  "machine-learning"
+]
+readme = "README.md"
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Development Status :: 2 - Pre-Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Natural Language :: English",
+    "Operating System :: MacOS :: MacOS X",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+    "Topic :: Scientific/Engineering :: Visualization"
+]
+dependencies = [
+    "anndata>=0.10.0",
+    "biopython>=1.79",
+    "Cython>=0.29.28",
+    "networkx>=3.2",
+    "numpy>=1.22.0,<2",
+    "pandas>=1.4.2",
+    "pomegranate>1.0.0",
+    "pysam>=0.19.1",
+    "scanpy>=1.9",
+    "scikit-learn>=1.0.2",
+    "scipy>=1.7.3",
+    "seaborn>=0.11",
+    "tqdm"
+]
+dynamic = ["version"]
+
+[project.urls]
+Source = "https://github.com/jkmckenna/smftools"
+
+[project.optional-dependencies]
+torch = ["torch>=1.9.0", "pomeganate>=1.0.0"]
+base_tests = [
+    "pytest",
+    "pytest-cov"
+]
+
+torch_tests = [
+    "smftools[base_tests]",
+    # Optional dependencies
+    "smftools[torch]"
+]
+
+doc = [
+    "sphinx>=7",
+    "sphinx-book-theme>=1.1.0",
+    "sphinx-autodoc-typehints>=1.25.2",
+    "myst-parser>=2",
+    "myst-nb>=1",
+    "sphinx-design",
+    "readthedocs-sphinx-search",
+    "sphinxext-opengraph", # for nice cards when sharing on social
+    "sphinx-copybutton",
+    "nbsphinx>=0.9",
+    "ipython>=7.20",  # for nbsphinx code highlighting
+    "matplotlib!=3.6.1",
+    "sphinxcontrib-bibtex",
+    "setuptools"
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/smftools"]
+
+[tool.hatch.version]
+path = "src/smftools/_version.py"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+xfail_strict = true
+markers = [
+    "internet: mark tests that requires internet access",
+    "optional: mark optional tests",
+    "private: mark tests that are private",
+]
+
+[tool.coverage.run]
+branch = true
+source = ["smftools"]
+omit = ["tests/*"]
+
+[tool.ruff]
+src = ["src"]
+line-length = 99
+indent-width = 4
+
+[tool.ruff.lint]
+select = [
+    "E",       # Error detected by Pycodestyle
+    "F",       # Errors detected by Pyflakes
+    "W",       # Warning detected by Pycodestyle
+    "UP",      # pyupgrade
+    "I",       # isort
+    "TCH",     # manage type checking blocks
+    "TID251",  # Banned imports
+    "ICN",     # Follow import conventions
+    "PTH",     # Pathlib instead of os.path
+    "PLR0917", # Ban APIs with too many positional parameters
+    "FBT",     # No positional boolean parameters
+    "PT"      # Pytest style
+]

smftools-0.1.0/requirements.txt

@@ -0,0 +1,14 @@
+# Essential packages
+anndata>=0.10.0
+biopython>=1.79
+Cython>=0.29.28
+networkx>=3
+numpy>=1.22.0,<2
+pandas>=1.4.2
+pomegranate>1.0.0
+pysam>=0.19.1
+scanpy>=1.9
+scikit-learn>=1.0.2
+scipy>=1.7.3
+seaborn>=0.11
+tqdm

smftools-0.1.0/src/smftools/__init__.py

@@ -0,0 +1,27 @@
+"""smftools"""
+
+import logging
+import warnings
+
+from anndata import AnnData
+from . import informatics as inform
+from . import preprocessing as pp
+from . import tools as tl
+from . import plotting as pl
+from . import readwrite, datasets
+
+
+from importlib.metadata import version
+
+package_name = "smftools"
+__version__ = version(package_name)
+
+__all__ = [
+    "AnnData",
+    "inform",
+    "pp",
+    "tl",
+    "pl",
+    "readwrite",
+    "datasets"
+]

smftools-0.1.0/src/smftools/_settings.py

@@ -0,0 +1,19 @@
+from pathlib import Path
+
+class SMFConfig:
+    """\
+    Config for smftools.
+    """
+
+    def __init__(
+        self,
+        *,
+        datasetdir: Path | str = "./datasets/"
+    ):
+        self.datasetdir = datasetdir
+
+    @property
+    def datasetdir(self) -> Path:
+        return self._datasetdir
+
+settings = SMFConfig()

smftools-0.1.0/src/smftools/datasets/__init__.py

@@ -0,0 +1,9 @@
+from .datasets import (
+    dCas9_kinetics,
+    Kissiov_and_McKenna_2025
+)
+
+__all__ = [
+    "dCas9_kinetics",
+    "Kissiov_and_McKenna_2025"
+]

smftools-0.1.0/src/smftools/datasets/datasets.py

@@ -0,0 +1,25 @@
+## 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 dCas9_kinetics():
+    """
+    
+    """
+    filepath = HERE / "dCas9_m6A_invitro_kinetics.h5ad.gz"
+    return ad.read_h5ad(filepath)
+
+def Kissiov_and_McKenna_2025():
+    """
+    
+    """
+    filepath = HERE / "F1_hybrid_NKG2A_enhander_promoter_GpC_conversion_SMF.h5ad.gz"
+    return ad.read_h5ad(filepath)

smftools-0.1.0/src/smftools/informatics/__init__.py

@@ -0,0 +1,11 @@
+from . import helpers
+from .pod5_conversion import pod5_conversion
+from .pod5_direct import pod5_direct
+from .pod5_to_adata import pod5_to_adata
+
+__all__ = [
+    "helpers",
+    "pod5_conversion",
+    "pod5_direct"
+    "pod5_to_adata"
+]

smftools-0.1.0/src/smftools/informatics/helpers/__init__.py

@@ -0,0 +1,42 @@
+from .align_BAM import align_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
+from .count_aligned_reads import count_aligned_reads
+from .extract_base_identities import extract_base_identities
+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 .make_dirs import make_dirs
+from .make_modbed import make_modbed
+from .modcall import modcall
+from .modkit_extract_to_adata import modkit_extract_to_adata
+from .modQC import modQC
+from .one_hot_encode import one_hot_encode
+from .separate_bam_by_bc import separate_bam_by_bc
+from .split_and_index_BAM import split_and_index_BAM
+
+__all__ = [
+    "align_BAM",
+    "binarize_converted_base_identities",
+    "canoncall",
+    "converted_BAM_to_adata",
+    "count_aligned_reads",
+    "extract_base_identities",
+    "extract_mods",
+    "find_conversion_sites",
+    "convert_FASTA_record",
+    "generate_converted_FASTA",
+    "get_native_references",
+    "load_experiment_config",
+    "make_dirs",
+    "make_modbed",
+    "modcall",
+    "modkit_extract_to_adata",
+    "modQC",
+    "one_hot_encode",
+    "separate_bam_by_bc",
+    "split_and_index_BAM"
+]

smftools-0.1.0/src/smftools/informatics/helpers/align_BAM.py

@@ -0,0 +1,49 @@
+## align_BAM
+import subprocess
+
+def align_BAM(fasta, bam, bam_suffix):
+    """
+    A wrapper for running dorado aligner and samtools functions
+    """
+    aligned_BAM=f"{bam}_aligned"
+    aligned_sorted_BAM=f"{aligned_BAM}_sorted"
+    output = bam + bam_suffix
+    aligned_output = aligned_BAM + bam_suffix
+    aligned_sorted_output = aligned_sorted_BAM + bam_suffix
+    
+    # Run dorado aligner
+    subprocess.run([
+        "dorado", "aligner",
+        "--secondary=no",
+        fasta,
+        output
+    ], 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
+    subprocess.run([
+        "samtools", "view",
+        aligned_sorted_output
+    ], stdout=subprocess.PIPE) | subprocess.run([
+        "awk", '{print $3, $4, $4+length($10)-1}'
+    ], stdin=subprocess.PIPE, stdout=open(f"{aligned_sorted_BAM}_bed.bed", "w"))
+
+    # Make a text file of reads for the BAM
+    subprocess.run([
+        "samtools", "view",
+        aligned_sorted_output
+    ], stdout=subprocess.PIPE) | subprocess.run([
+        "cut", "-f1"
+    ], stdin=subprocess.PIPE, stdout=open(f"aligned_sorted_BAM_read_names.txt", "w"))

smftools-0.1.0/src/smftools/informatics/helpers/binarize_converted_base_identities.py

@@ -0,0 +1,24 @@
+## 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.
+    """
+    binarized_base_identities = {}
+    # Iterate over base identity keys to binarize the base identities
+    for key in base_identities.keys():
+        if strand == 'top':
+            if modification_type == '5mC':
+                binarized_base_identities[key] = [1 if x == 'C' else 0 if x == 'T' else np.nan for x in base_identities[key]]
+            elif modification_type == '6mA':
+                binarized_base_identities[key] = [1 if x == 'A' else 0 if x == 'G' else np.nan for x in base_identities[key]]
+        elif strand == 'bottom':
+            if modification_type == '5mC':
+                binarized_base_identities[key] = [1 if x == 'G' else 0 if x == 'A' else np.nan for x in base_identities[key]]
+            elif modification_type == '6mA':
+                binarized_base_identities[key] = [1 if x == 'T' else 0 if x == 'C' else np.nan for x in base_identities[key]]
+        else:
+            pass
+    return binarized_base_identities

smftools-0.1.0/src/smftools/informatics/helpers/canoncall.py

@@ -0,0 +1,12 @@
+## canoncall
+import subprocess
+
+# Conversion SMF specific
+def canoncall(model, pod5_dir, barcode_kit, bam, bam_suffix):
+    """
+    Wrapper function for dorado canonical base calling.
+    """
+    output = bam + bam_suffix
+    command = ["dorado", "basecaller", model, pod5_dir, "--kit-name", barcode_kit, "-Y"]
+    with open(output, "w") as outfile:
+        subprocess.run(command, stdout=outfile)