gkmsvm-lite 0.1.0__tar.gz

gkmsvm_lite-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adam Youlin He
+
+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.

gkmsvm_lite-0.1.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: gkmsvm-lite
+Version: 0.1.0
+Summary: Gapped k-mer SVMs for DNA sequence classification and regression
+Author-email: Adam Youlin He <ayhe@stanford.edu>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/adamyhe/gkmsvm-lite
+Project-URL: Repository, https://github.com/adamyhe/gkmsvm-lite
+Project-URL: Issues, https://github.com/adamyhe/gkmsvm-lite/issues
+Project-URL: Documentation, https://github.com/adamyhe/gkmsvm-lite/tree/main/docs
+Keywords: gkm-svm,svm,dna,genomics,bioinformatics,kernel-methods
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: numba>=0.57
+Requires-Dist: tqdm
+Requires-Dist: scikit-learn>=1.0
+Requires-Dist: pyfaidx
+Requires-Dist: dinuc-shuf>=0.1.0b1
+Provides-Extra: gpu
+Requires-Dist: cupy-cuda12x[ctk]>=12.0; extra == "gpu"
+Provides-Extra: mlx
+Requires-Dist: mlx>=0.10.0; extra == "mlx"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Provides-Extra: examples
+Requires-Dist: jupyter; extra == "examples"
+Requires-Dist: matplotlib; extra == "examples"
+Requires-Dist: pandas; extra == "examples"
+Requires-Dist: scipy; extra == "examples"
+Requires-Dist: modisco>=2.5; extra == "examples"
+Requires-Dist: h5py; extra == "examples"
+Requires-Dist: openpyxl; extra == "examples"
+Dynamic: license-file
+
+# gkmsvm-lite
+
+[![PyPI](https://img.shields.io/pypi/v/gkmsvm-lite)](https://pypi.org/project/gkmsvm-lite/)
+[![CI](https://github.com/adamyhe/gkmsvm-lite/actions/workflows/ci.yml/badge.svg)](https://github.com/adamyhe/gkmsvm-lite/actions/workflows/ci.yml)
+[![Downloads](https://static.pepy.tech/badge/gkmsvm-lite)](https://pepy.tech/projects/gkmsvm-lite)
+
+A pure-Python implementation of gapped k-mer SVMs (gkm-SVMs) for DNA sequence analysis. Supports classification (C-SVC) and regression (epsilon-SVR), all six kernel types, GPU acceleration via CuPy (NVIDIA) and MLX (Apple Silicon), and compatibility with models from LS-GKM, classic gkmSVM, and the R gkmSVM package.
+
+## Install
+
+```bash
+pip install gkmsvm-lite              # CPU (NumPy + Numba)
+pip install gkmsvm-lite[gpu]         # NVIDIA GPU (+ CuPy)
+pip install gkmsvm-lite[mlx]         # Apple Silicon GPU (+ MLX)
+```
+
+For development installation from source, see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Quick start
+
+```python
+from gkmsvm import load_lsgkm_model, one_hot_encode, ism, gkmexplain
+
+# Load an existing model
+model = load_lsgkm_model("model.txt.gz")
+
+# Score a sequence
+x = one_hot_encode("ACGTACGTACGTACGT")[None, ...]  # [1, 4, 16]
+score = model(x)  # [1, 1]
+
+# Variant effect prediction
+ref = one_hot_encode("ACGTACGTACGTACGT")[None, ...]
+alt = one_hot_encode("ACGTACGAACGTACGT")[None, ...]
+delta = model(alt).item() - model(ref).item()
+
+# Attribution
+hyp = gkmexplain(model, x, mode=1)   # [1, 4, 16] hypothetical importance
+attr = gkmexplain(model, x, mode=0)  # [1, 4, 16] importance (= mode 1 × input)
+deltas = ism(model, x)                # [1, 4, 16] mutation deltas
+
+# GPU acceleration
+model.cuda()  # NVIDIA (~6x speedup)
+model.mlx()   # Apple Silicon (~2-6x speedup)
+```
+
+## Command-line interface
+
+```bash
+gkmsvm predict -m model.npz -i sequences.fa -o scores.tsv --device cuda
+gkmsvm train -p positive.fa -n negative.fa -o model.npz -l 11 -k 7 -d 3
+gkmsvm explain -m model.npz -i sequences.fa -o attr.npz -s seqs.npz
+gkmsvm ism -m model.npz -i sequences.fa -o ism.npz
+gkmsvm score-variants -m model.npz --ref ref.fa --alt alt.fa -o deltas.tsv
+gkmsvm to-deltasvm -m model.npz -o weights.txt
+gkmsvm import -i model.txt.gz -f lsgkm -o model.npz
+```
+
+See [docs/cli.md](docs/cli.md) for full usage.
+
+## Train a model
+
+```python
+from gkmsvm import train_gkmsvm, train_gkmsvr
+
+# Classification
+model = train_gkmsvm(pos_seqs, neg_seqs, l=11, k=7, d=3, C=1.0)
+
+# Regression (e.g., chromatin accessibility)
+model = train_gkmsvr(sequences, labels, l=11, k=7, d=3, epsilon=0.1)
+
+model.save("my_model.npz")
+```
+
+## Load models from any gkm-SVM package
+
+```python
+from gkmsvm import (
+    load_lsgkm_model,      # LS-GKM / kundajelab/lsgkm
+    load_classic_model,     # C gkmSVM (LIBSVM-style format)
+    load_r_gkmsvm_model,   # R gkmSVM (Ghandi et al. 2016)
+    load_deltasvm_model,    # DeltaSVM k-mer weights
+    load_model,             # auto-detect npz or LS-GKM text
+)
+```
+
+See [docs/models.md](docs/models.md) for format details, training options, and examples.
+
+## Kernel types
+
+All six LS-GKM kernel types are supported:
+
+| `-t` | Name | Description |
+|------|------|-------------|
+| 0 | gkm | Direct gapped k-mer count |
+| 1 | gkm_estfull | Estimated full l-mer |
+| 2 | gkm_esttrunc | Estimated truncated l-mer (LS-GKM default) |
+| 3 | gkmrbf | RBF-transformed estimated |
+| 4 | wgkm | Center-weighted gapped k-mer |
+| 5 | wgkmrbf | Center-weighted RBF |
+
+## Documentation
+
+| Guide | Contents |
+|---|---|
+| [CLI reference](docs/cli.md) | All `gkmsvm` subcommands, flags, and usage examples |
+| [Loading and training models](docs/models.md) | Importing from all formats, training SVC/SVR, solver selection, kernel types |
+| [Scoring and variant effects](docs/scoring.md) | Inference, batch scoring, VEP, GPU acceleration, memory management |
+| [Interpretation](docs/interpretation.md) | GkmExplain, ISM, when to use each, why gradients don't work |
+| [Performance](docs/performance.md) | Benchmarks, optimization details, tuning guidance |
+| [Design decisions](docs/design.md) | Architecture, kernel math, format specifications |
+| [Roadmap](docs/roadmap.md) | Completed features and what's next |
+
+## Citation
+
+If you use gkmsvm-lite, please cite the relevant methods papers:
+
+> Ghandi M, Lee D, Mohammad-Noori M, Beer MA. Enhanced regulatory sequence prediction using gapped k-mer features. *PLoS Comput Biol* 10(7):e1003711 (2014).
+
+> Ghandi M, Mohammad-Noori M, Ghareghani N, Lee D, Garraway L, Beer MA. gkmSVM: an R package for gapped-kmer SVM. *Bioinformatics* 32(14):2205-2207 (2016).
+
+> Lee D. LS-GKM: a new gkm-SVM for large-scale datasets. *Bioinformatics* 32(14):2196-2198 (2016).
+
+If you use GkmExplain:
+
+> Shrikumar A, Prakash E, Kundaje A. GkmExplain: fast and accurate interpretation of nonlinear gapped k-mer SVMs. *Bioinformatics* 35(14):i173-i182 (2019).
+
+If you use DeltaSVM:
+
+> Lee D, Gorkin DU, Baker M, Strober BJ, Asoni AL, McCallion AS, Beer MA. A method to predict the impact of regulatory variants from DNA sequence. *Nat Genet* 47(8):955-961 (2015).
+
+See [CITATION.cff](CITATION.cff) for machine-readable citation metadata.
+
+## License
+
+MIT. LS-GKM C (Dongwon-Lee/lsgkm) is GPL v3 — gkmsvm-lite is a clean-room reimplementation.

gkmsvm_lite-0.1.0/README.md

@@ -0,0 +1,135 @@
+# gkmsvm-lite
+
+[![PyPI](https://img.shields.io/pypi/v/gkmsvm-lite)](https://pypi.org/project/gkmsvm-lite/)
+[![CI](https://github.com/adamyhe/gkmsvm-lite/actions/workflows/ci.yml/badge.svg)](https://github.com/adamyhe/gkmsvm-lite/actions/workflows/ci.yml)
+[![Downloads](https://static.pepy.tech/badge/gkmsvm-lite)](https://pepy.tech/projects/gkmsvm-lite)
+
+A pure-Python implementation of gapped k-mer SVMs (gkm-SVMs) for DNA sequence analysis. Supports classification (C-SVC) and regression (epsilon-SVR), all six kernel types, GPU acceleration via CuPy (NVIDIA) and MLX (Apple Silicon), and compatibility with models from LS-GKM, classic gkmSVM, and the R gkmSVM package.
+
+## Install
+
+```bash
+pip install gkmsvm-lite              # CPU (NumPy + Numba)
+pip install gkmsvm-lite[gpu]         # NVIDIA GPU (+ CuPy)
+pip install gkmsvm-lite[mlx]         # Apple Silicon GPU (+ MLX)
+```
+
+For development installation from source, see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Quick start
+
+```python
+from gkmsvm import load_lsgkm_model, one_hot_encode, ism, gkmexplain
+
+# Load an existing model
+model = load_lsgkm_model("model.txt.gz")
+
+# Score a sequence
+x = one_hot_encode("ACGTACGTACGTACGT")[None, ...]  # [1, 4, 16]
+score = model(x)  # [1, 1]
+
+# Variant effect prediction
+ref = one_hot_encode("ACGTACGTACGTACGT")[None, ...]
+alt = one_hot_encode("ACGTACGAACGTACGT")[None, ...]
+delta = model(alt).item() - model(ref).item()
+
+# Attribution
+hyp = gkmexplain(model, x, mode=1)   # [1, 4, 16] hypothetical importance
+attr = gkmexplain(model, x, mode=0)  # [1, 4, 16] importance (= mode 1 × input)
+deltas = ism(model, x)                # [1, 4, 16] mutation deltas
+
+# GPU acceleration
+model.cuda()  # NVIDIA (~6x speedup)
+model.mlx()   # Apple Silicon (~2-6x speedup)
+```
+
+## Command-line interface
+
+```bash
+gkmsvm predict -m model.npz -i sequences.fa -o scores.tsv --device cuda
+gkmsvm train -p positive.fa -n negative.fa -o model.npz -l 11 -k 7 -d 3
+gkmsvm explain -m model.npz -i sequences.fa -o attr.npz -s seqs.npz
+gkmsvm ism -m model.npz -i sequences.fa -o ism.npz
+gkmsvm score-variants -m model.npz --ref ref.fa --alt alt.fa -o deltas.tsv
+gkmsvm to-deltasvm -m model.npz -o weights.txt
+gkmsvm import -i model.txt.gz -f lsgkm -o model.npz
+```
+
+See [docs/cli.md](docs/cli.md) for full usage.
+
+## Train a model
+
+```python
+from gkmsvm import train_gkmsvm, train_gkmsvr
+
+# Classification
+model = train_gkmsvm(pos_seqs, neg_seqs, l=11, k=7, d=3, C=1.0)
+
+# Regression (e.g., chromatin accessibility)
+model = train_gkmsvr(sequences, labels, l=11, k=7, d=3, epsilon=0.1)
+
+model.save("my_model.npz")
+```
+
+## Load models from any gkm-SVM package
+
+```python
+from gkmsvm import (
+    load_lsgkm_model,      # LS-GKM / kundajelab/lsgkm
+    load_classic_model,     # C gkmSVM (LIBSVM-style format)
+    load_r_gkmsvm_model,   # R gkmSVM (Ghandi et al. 2016)
+    load_deltasvm_model,    # DeltaSVM k-mer weights
+    load_model,             # auto-detect npz or LS-GKM text
+)
+```
+
+See [docs/models.md](docs/models.md) for format details, training options, and examples.
+
+## Kernel types
+
+All six LS-GKM kernel types are supported:
+
+| `-t` | Name | Description |
+|------|------|-------------|
+| 0 | gkm | Direct gapped k-mer count |
+| 1 | gkm_estfull | Estimated full l-mer |
+| 2 | gkm_esttrunc | Estimated truncated l-mer (LS-GKM default) |
+| 3 | gkmrbf | RBF-transformed estimated |
+| 4 | wgkm | Center-weighted gapped k-mer |
+| 5 | wgkmrbf | Center-weighted RBF |
+
+## Documentation
+
+| Guide | Contents |
+|---|---|
+| [CLI reference](docs/cli.md) | All `gkmsvm` subcommands, flags, and usage examples |
+| [Loading and training models](docs/models.md) | Importing from all formats, training SVC/SVR, solver selection, kernel types |
+| [Scoring and variant effects](docs/scoring.md) | Inference, batch scoring, VEP, GPU acceleration, memory management |
+| [Interpretation](docs/interpretation.md) | GkmExplain, ISM, when to use each, why gradients don't work |
+| [Performance](docs/performance.md) | Benchmarks, optimization details, tuning guidance |
+| [Design decisions](docs/design.md) | Architecture, kernel math, format specifications |
+| [Roadmap](docs/roadmap.md) | Completed features and what's next |
+
+## Citation
+
+If you use gkmsvm-lite, please cite the relevant methods papers:
+
+> Ghandi M, Lee D, Mohammad-Noori M, Beer MA. Enhanced regulatory sequence prediction using gapped k-mer features. *PLoS Comput Biol* 10(7):e1003711 (2014).
+
+> Ghandi M, Mohammad-Noori M, Ghareghani N, Lee D, Garraway L, Beer MA. gkmSVM: an R package for gapped-kmer SVM. *Bioinformatics* 32(14):2205-2207 (2016).
+
+> Lee D. LS-GKM: a new gkm-SVM for large-scale datasets. *Bioinformatics* 32(14):2196-2198 (2016).
+
+If you use GkmExplain:
+
+> Shrikumar A, Prakash E, Kundaje A. GkmExplain: fast and accurate interpretation of nonlinear gapped k-mer SVMs. *Bioinformatics* 35(14):i173-i182 (2019).
+
+If you use DeltaSVM:
+
+> Lee D, Gorkin DU, Baker M, Strober BJ, Asoni AL, McCallion AS, Beer MA. A method to predict the impact of regulatory variants from DNA sequence. *Nat Genet* 47(8):955-961 (2015).
+
+See [CITATION.cff](CITATION.cff) for machine-readable citation metadata.
+
+## License
+
+MIT. LS-GKM C (Dongwon-Lee/lsgkm) is GPL v3 — gkmsvm-lite is a clean-room reimplementation.

gkmsvm_lite-0.1.0/pyproject.toml

@@ -0,0 +1,69 @@
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "gkmsvm-lite"
+version = "0.1.0"
+description = "Gapped k-mer SVMs for DNA sequence classification and regression"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+keywords = ["gkm-svm", "svm", "dna", "genomics", "bioinformatics", "kernel-methods"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+authors = [
+    {name = "Adam Youlin He", email = "ayhe@stanford.edu"},
+]
+dependencies = [
+    "numpy",
+    "numba>=0.57",
+    "tqdm",
+    "scikit-learn>=1.0",
+    "pyfaidx",
+    "dinuc-shuf>=0.1.0b1",
+]
+
+[project.urls]
+Homepage = "https://github.com/adamyhe/gkmsvm-lite"
+Repository = "https://github.com/adamyhe/gkmsvm-lite"
+Issues = "https://github.com/adamyhe/gkmsvm-lite/issues"
+Documentation = "https://github.com/adamyhe/gkmsvm-lite/tree/main/docs"
+
+[project.scripts]
+gkmsvm = "gkmsvm.cli:main"
+
+[project.optional-dependencies]
+gpu = [
+    "cupy-cuda12x[ctk]>=12.0",
+]
+mlx = [
+    "mlx>=0.10.0",
+]
+dev = [
+    "pytest",
+    "pytest-cov",
+]
+examples = [
+    "jupyter",
+    "matplotlib",
+    "pandas",
+    "scipy",
+    "modisco>=2.5",
+    "h5py",
+    "openpyxl",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

gkmsvm_lite-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

gkmsvm_lite-0.1.0/setup.py

@@ -0,0 +1,42 @@
+"""Build configuration for C extensions."""
+
+import sys
+
+from setuptools import Extension, setup
+from setuptools.command.build_ext import build_ext
+
+
+class OptionalBuildExt(build_ext):
+    """Allow the build to succeed even if the C extension fails to compile."""
+
+    def run(self):
+        try:
+            super().run()
+        except Exception:
+            self._warn_failed()
+
+    def build_extension(self, ext):
+        try:
+            super().build_extension(ext)
+        except Exception:
+            self._warn_failed(ext.name)
+
+    @staticmethod
+    def _warn_failed(name="C SMO extension"):
+        print(
+            f"WARNING: Failed to build {name}. "
+            "The SMO solver will fall back to the Python implementation.",
+            file=sys.stderr,
+        )
+
+
+setup(
+    ext_modules=[
+        Extension(
+            "gkmsvm._csmo",
+            sources=["src/gkmsvm/_csmo.c"],
+            extra_compile_args=["-O2"],
+        ),
+    ],
+    cmdclass={"build_ext": OptionalBuildExt},
+)

gkmsvm_lite-0.1.0/src/gkmsvm/__init__.py

@@ -0,0 +1,49 @@
+from gkmsvm._threading import pin_threading_layer
+
+pin_threading_layer()
+
+from gkmsvm.codec import (
+    encode_batch,
+    one_hot_decode,
+    one_hot_encode,
+    reverse_complement,
+    validate,
+)
+from gkmsvm.deltasvm import DeltaSVM
+from gkmsvm.explain import gkmexplain
+from gkmsvm.fasta import extract_loci, read_fasta, write_fasta
+from gkmsvm.importers.classic import load_classic_model
+from gkmsvm.importers.deltasvm import load_deltasvm_model
+from gkmsvm.importers.lsgkm import load_lsgkm_model
+from gkmsvm.importers.r_gkmsvm import load_r_gkmsvm_model
+from gkmsvm.ism import ism
+from gkmsvm.serialization import load_model, load_npz, save_lsgkm, save_npz
+from gkmsvm.svm import KERNEL_ALIASES, GkmSVM, resolve_kernel_type
+from gkmsvm.train import train_gkmsvm, train_gkmsvr
+
+__all__ = [
+    "one_hot_encode",
+    "one_hot_decode",
+    "reverse_complement",
+    "validate",
+    "encode_batch",
+    "GkmSVM",
+    "KERNEL_ALIASES",
+    "resolve_kernel_type",
+    "DeltaSVM",
+    "load_lsgkm_model",
+    "load_classic_model",
+    "load_r_gkmsvm_model",
+    "load_deltasvm_model",
+    "read_fasta",
+    "write_fasta",
+    "extract_loci",
+    "ism",
+    "gkmexplain",
+    "train_gkmsvm",
+    "train_gkmsvr",
+    "load_model",
+    "load_npz",
+    "save_npz",
+    "save_lsgkm",
+]