denseclass 0.1.0__tar.gz

denseclass-0.1.0/LICENCE.txt

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

denseclass-0.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include README.md
+include requirements.txt

denseclass-0.1.0/PKG-INFO

@@ -0,0 +1,246 @@
+Metadata-Version: 2.4
+Name: denseclass
+Version: 0.1.0
+Author: linlian
+Author-email: 21620151153308@stu.xmu.edu.cn
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Operating System :: POSIX :: Linux
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENCE.txt
+Requires-Dist: numpy>=1.23
+Requires-Dist: scipy>=1.9
+Requires-Dist: pandas>=1.5
+Requires-Dist: h5py>=3.7
+Requires-Dist: torch>=2.0
+Requires-Dist: tqdm>=4.64
+Requires-Dist: toml>=0.10
+Requires-Dist: scikit-learn>=1.1
+Requires-Dist: matplotlib>=3.6
+Requires-Dist: seaborn>=0.12
+Requires-Dist: biopython>=1.80
+Requires-Dist: numba>=0.57
+Requires-Dist: plotnine>=0.12
+Requires-Dist: ont-fast5-api>=4.1
+Requires-Dist: ont-bonito>=0.7
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+
+<div align="center">
+
+# 🦠 **denseclass**
+
+**Nanopore signal classification** — label every raw read by species, barcode or taxon,
+straight from the current, with no basecalling step.
+
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENCE.txt)
+
+</div>
+
+---
+
+## 📖 Table of Contents
+
+- [Overview](#-overview)
+- [Installation](#-installation)
+- [Quick start](#-quick-start)
+- [Subcommands](#-subcommands)
+- [Training modes](#-training-modes)
+- [Examples](#-examples)
+- [Relationship to densecall](#-relationship-to-densecall)
+- [Development](#-development)
+
+---
+
+## 🧬 Overview
+
+Reads are trimmed to their informative region (adapter/polyA detection for DNA,
+poly(A)-tail trimming for RNA), encoded, and passed through a small 1-D CNN that
+predicts one class per read. Training works either on **real** labelled reads or on
+**signal simulated** from reference genomes, so you can build a classifier without
+per-species reads for every class.
+
+This package was split out of [DenseCall](https://github.com/n-damo/densecall) and
+now stands alone — see [Relationship to densecall](#-relationship-to-densecall).
+
+---
+
+## 📦 Installation
+
+```bash
+git clone <this-repo>
+cd denseclass
+pip install -e .
+```
+
+`torch` is deliberately unpinned so the resolver picks a build matching your local
+CUDA toolkit. For GPU basecalling-adjacent work, install the CUDA toolkit first and
+verify `nvcc` is on `$PATH`:
+
+```bash
+conda install -c nvidia cuda-toolkit=12.8
+```
+
+---
+
+## 🚀 Quick start
+
+```bash
+denseclass --help
+denseclass label --help
+```
+
+---
+
+## 🎯 Subcommands
+
+| Subcommand | Purpose |
+|:--|:--|
+| `label` | Build `label_map.json` / `inverse_label_map.json` from a FASTA whose headers are the class names |
+| `split` | Split a read→label pairs file into train / test sets |
+| `gendata` | Convert POD5/FAST5 + labels into `train.hdf5` / `valid.hdf5` |
+| `train` | Train the classification CNN (real or simulated data) |
+| `predict` | Classify reads with a trained model |
+| `precision` | One-class precision / recall / F1 / ROC evaluation |
+| `evaluation` | Full multiclass panel (confusion matrix, PR/ROC, ...) |
+| `comparison` | Side-by-side comparison of two models |
+
+---
+
+## 🧪 Training modes
+
+| Mode | Description |
+|:--|:--|
+| **Real-data** | `gendata` extracts signal chunks from reads already labelled by species, then `train` (no `--simu`) fits the CNN directly. |
+| **Simulation** | `train --simu <refs.fa> --preset <name>` synthesises chunks on the fly from a FASTA of reference genomes. Presets: `dna-r9-min`, `dna-r10-min`, `rna-r9-min`, `rna004-min`, ... |
+
+The CNN architecture is set by a small TOML (`dna.toml` with `strides=[2,2,2,2,2]` for
+DNA, `rna.toml` with `strides=[5,2,2,2,2]` for RNA) passed via `-config`. The
+`label_map.json` / `inverse_label_map.json` pair must be produced first with
+`denseclass label`.
+
+---
+
+## 🧪 Examples
+
+### Barcode / species classification on real reads
+
+```bash
+# 1. build the label map
+denseclass label species.fa
+
+# 2. split read→label pairs
+denseclass split readid_species.txt --train_file train_labels.txt --test_file test_labels.txt
+
+# 3. extract training chunks
+denseclass gendata train.pod5 \
+  --label_path train_labels.txt --save_path ./ --seqlen 6000 --do-trim
+
+# 4. train
+denseclass train model_real \
+  -config dna.toml --directory ./ --label-map label_map.json \
+  --chunksize 6000 -f --new -y
+
+# 5. predict
+denseclass predict model_real test.pod5 inverse_label_map.json \
+  --chunksize 6000 > result_real.txt
+
+# 6. evaluate
+denseclass evaluation result_real.txt test_labels.txt \
+  -m label_map.json -o ./real
+```
+
+### Simulation-based training (no real per-species data)
+
+```bash
+denseclass label species.fa
+
+denseclass train model_simu \
+  -config dna.toml --directory ./ --label-map label_map.json \
+  --chunksize 25000 -f --new --simu species.fa --preset dna-r10-min -y
+
+denseclass predict model_simu reads_dir/ inverse_label_map.json \
+  --chunksize 25000 > result_simu.txt
+
+denseclass precision result_simu.txt test_labels.txt -m label_map.json
+```
+
+### RNA direct-read classification
+
+RNA reads are reverse-complement mapped and sequenced after the poly(A) tail, so
+`gendata` / `predict` take `--rna --tail`, and RNA models use `rna.toml`:
+
+```bash
+denseclass gendata train.pod5 \
+  --label_path train_labels.txt --save_path ./ --rna --seqlen 50000 --tail
+
+denseclass train model \
+  -config rna.toml --directory ./ --label-map label_map.json \
+  -f --new -y --chunksize 50000 --rna
+
+denseclass predict model test.pod5 inverse_label_map.json \
+  --rna --tail --chunksize 50000 > result_real.txt
+```
+
+---
+
+## 🔗 Relationship to densecall
+
+This package was previously `densecall classify`, wrapping `densecall/microbiome/`.
+It is now standalone:
+
+- **No `densecall` import anywhere.** The one helper that used to be shared
+  (`convert_base_name`) is vendored in `denseclass/base_util.py`.
+- **Separate dependency set and release cycle.** Install and upgrade it on its own.
+- **The trained `model/` directory is a normal model directory** and can be used with
+  the DenseCall basecalling `train` / `predict` tooling where applicable.
+
+Migration is a command rename:
+
+| Before | After |
+|:--|:--|
+| `densecall classify label` | `denseclass label` |
+| `densecall classify gendata` | `denseclass gendata` |
+| `densecall classify train` | `denseclass train` |
+| `densecall classify predict` | `denseclass predict` |
+
+All flags are unchanged.
+
+---
+
+## 🛠 Development
+
+```bash
+pytest tests/            # structural checks: imports, CLI tree, packaging
+```
+
+The test suite is purely structural — it verifies that every module imports, the
+command tree builds and formats, and the packaging metadata is consistent. It needs
+no signal data or checkpoints. End-to-end behaviour is exercised through the examples
+above.
+
+### Publishing
+
+```bash
+# 1. bump __version__ in denseclass/cli.py
+python -m build
+twine check dist/* && twine upload dist/*
+```
+
+---
+
+## 📄 License
+
+MIT — see [LICENCE.txt](LICENCE.txt).

denseclass-0.1.0/README.md

@@ -0,0 +1,207 @@
+<div align="center">
+
+# 🦠 **denseclass**
+
+**Nanopore signal classification** — label every raw read by species, barcode or taxon,
+straight from the current, with no basecalling step.
+
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENCE.txt)
+
+</div>
+
+---
+
+## 📖 Table of Contents
+
+- [Overview](#-overview)
+- [Installation](#-installation)
+- [Quick start](#-quick-start)
+- [Subcommands](#-subcommands)
+- [Training modes](#-training-modes)
+- [Examples](#-examples)
+- [Relationship to densecall](#-relationship-to-densecall)
+- [Development](#-development)
+
+---
+
+## 🧬 Overview
+
+Reads are trimmed to their informative region (adapter/polyA detection for DNA,
+poly(A)-tail trimming for RNA), encoded, and passed through a small 1-D CNN that
+predicts one class per read. Training works either on **real** labelled reads or on
+**signal simulated** from reference genomes, so you can build a classifier without
+per-species reads for every class.
+
+This package was split out of [DenseCall](https://github.com/n-damo/densecall) and
+now stands alone — see [Relationship to densecall](#-relationship-to-densecall).
+
+---
+
+## 📦 Installation
+
+```bash
+git clone <this-repo>
+cd denseclass
+pip install -e .
+```
+
+`torch` is deliberately unpinned so the resolver picks a build matching your local
+CUDA toolkit. For GPU basecalling-adjacent work, install the CUDA toolkit first and
+verify `nvcc` is on `$PATH`:
+
+```bash
+conda install -c nvidia cuda-toolkit=12.8
+```
+
+---
+
+## 🚀 Quick start
+
+```bash
+denseclass --help
+denseclass label --help
+```
+
+---
+
+## 🎯 Subcommands
+
+| Subcommand | Purpose |
+|:--|:--|
+| `label` | Build `label_map.json` / `inverse_label_map.json` from a FASTA whose headers are the class names |
+| `split` | Split a read→label pairs file into train / test sets |
+| `gendata` | Convert POD5/FAST5 + labels into `train.hdf5` / `valid.hdf5` |
+| `train` | Train the classification CNN (real or simulated data) |
+| `predict` | Classify reads with a trained model |
+| `precision` | One-class precision / recall / F1 / ROC evaluation |
+| `evaluation` | Full multiclass panel (confusion matrix, PR/ROC, ...) |
+| `comparison` | Side-by-side comparison of two models |
+
+---
+
+## 🧪 Training modes
+
+| Mode | Description |
+|:--|:--|
+| **Real-data** | `gendata` extracts signal chunks from reads already labelled by species, then `train` (no `--simu`) fits the CNN directly. |
+| **Simulation** | `train --simu <refs.fa> --preset <name>` synthesises chunks on the fly from a FASTA of reference genomes. Presets: `dna-r9-min`, `dna-r10-min`, `rna-r9-min`, `rna004-min`, ... |
+
+The CNN architecture is set by a small TOML (`dna.toml` with `strides=[2,2,2,2,2]` for
+DNA, `rna.toml` with `strides=[5,2,2,2,2]` for RNA) passed via `-config`. The
+`label_map.json` / `inverse_label_map.json` pair must be produced first with
+`denseclass label`.
+
+---
+
+## 🧪 Examples
+
+### Barcode / species classification on real reads
+
+```bash
+# 1. build the label map
+denseclass label species.fa
+
+# 2. split read→label pairs
+denseclass split readid_species.txt --train_file train_labels.txt --test_file test_labels.txt
+
+# 3. extract training chunks
+denseclass gendata train.pod5 \
+  --label_path train_labels.txt --save_path ./ --seqlen 6000 --do-trim
+
+# 4. train
+denseclass train model_real \
+  -config dna.toml --directory ./ --label-map label_map.json \
+  --chunksize 6000 -f --new -y
+
+# 5. predict
+denseclass predict model_real test.pod5 inverse_label_map.json \
+  --chunksize 6000 > result_real.txt
+
+# 6. evaluate
+denseclass evaluation result_real.txt test_labels.txt \
+  -m label_map.json -o ./real
+```
+
+### Simulation-based training (no real per-species data)
+
+```bash
+denseclass label species.fa
+
+denseclass train model_simu \
+  -config dna.toml --directory ./ --label-map label_map.json \
+  --chunksize 25000 -f --new --simu species.fa --preset dna-r10-min -y
+
+denseclass predict model_simu reads_dir/ inverse_label_map.json \
+  --chunksize 25000 > result_simu.txt
+
+denseclass precision result_simu.txt test_labels.txt -m label_map.json
+```
+
+### RNA direct-read classification
+
+RNA reads are reverse-complement mapped and sequenced after the poly(A) tail, so
+`gendata` / `predict` take `--rna --tail`, and RNA models use `rna.toml`:
+
+```bash
+denseclass gendata train.pod5 \
+  --label_path train_labels.txt --save_path ./ --rna --seqlen 50000 --tail
+
+denseclass train model \
+  -config rna.toml --directory ./ --label-map label_map.json \
+  -f --new -y --chunksize 50000 --rna
+
+denseclass predict model test.pod5 inverse_label_map.json \
+  --rna --tail --chunksize 50000 > result_real.txt
+```
+
+---
+
+## 🔗 Relationship to densecall
+
+This package was previously `densecall classify`, wrapping `densecall/microbiome/`.
+It is now standalone:
+
+- **No `densecall` import anywhere.** The one helper that used to be shared
+  (`convert_base_name`) is vendored in `denseclass/base_util.py`.
+- **Separate dependency set and release cycle.** Install and upgrade it on its own.
+- **The trained `model/` directory is a normal model directory** and can be used with
+  the DenseCall basecalling `train` / `predict` tooling where applicable.
+
+Migration is a command rename:
+
+| Before | After |
+|:--|:--|
+| `densecall classify label` | `denseclass label` |
+| `densecall classify gendata` | `denseclass gendata` |
+| `densecall classify train` | `denseclass train` |
+| `densecall classify predict` | `denseclass predict` |
+
+All flags are unchanged.
+
+---
+
+## 🛠 Development
+
+```bash
+pytest tests/            # structural checks: imports, CLI tree, packaging
+```
+
+The test suite is purely structural — it verifies that every module imports, the
+command tree builds and formats, and the packaging metadata is consistent. It needs
+no signal data or checkpoints. End-to-end behaviour is exercised through the examples
+above.
+
+### Publishing
+
+```bash
+# 1. bump __version__ in denseclass/cli.py
+python -m build
+twine check dist/* && twine upload dist/*
+```
+
+---
+
+## 📄 License
+
+MIT — see [LICENCE.txt](LICENCE.txt).

denseclass-0.1.0/denseclass/__init__.py

@@ -0,0 +1,12 @@
+"""Signal classification for nanopore reads.
+
+Split out of the ``densecall`` basecaller into this standalone package. Nothing
+here imports ``densecall``: the only helper that was shared
+(``convert_base_name``) is vendored in ``base_util.py``.
+
+Pipeline: label -> split -> gendata -> train -> predict -> evaluate
+"""
+
+from denseclass.cli import __version__, argparser, main, subcommands
+
+__all__ = ['main', 'argparser', 'subcommands', '__version__']

denseclass-0.1.0/denseclass/__main__.py

@@ -0,0 +1,4 @@
+from denseclass.cli import main
+
+if __name__ == '__main__':
+    main()

denseclass-0.1.0/denseclass/base_util.py

@@ -0,0 +1,41 @@
+"""Base-name to IUPAC regular-expression helpers.
+
+Vendored from ``densecall.mod_util`` so this package has no dependency on the
+basecaller. Only ``convert_base_name`` was ever used here; the rest of
+``mod_util`` pulls in remora/mappy, which this package does not need.
+"""
+
+# IUPAC degenerate codes expanded into character classes.
+_MERGE_BASES = {
+    "A": "A",
+    "C": "C",
+    "G": "G",
+    "T": "T",
+    "M": "[AC]",
+    "V": "[ACG]",
+    "R": "[AG]",
+    "H": "[ACT]",
+    "W": "[AT]",
+    "D": "[AGT]",
+    "S": "[CG]",
+    "B": "[CGT]",
+    "Y": "[CT]",
+    "N": "[ACGT]",
+    "K": "[GT]",
+}
+
+
+def convert_base_name(base_name):
+    """Expand a base string into a regular expression pattern.
+
+    Args:
+        base_name (str): Input base string to be converted, e.g. ``"NAY"``.
+
+    Returns:
+        str: Regular expression pattern equivalent to the input, e.g.
+        ``"[ACGT]A[CT]"``.
+    """
+    pattern = ""
+    for base in base_name:
+        pattern += _MERGE_BASES.get(base, base)
+    return pattern

denseclass-0.1.0/denseclass/cli.py

@@ -0,0 +1,76 @@
+"""Command-line namespace for signal classification.
+
+``argparser()`` builds the subcommand tree for introspection and library use;
+``main()`` is the console entry point. Both share the same leaf registration,
+and ``main`` mirrors DenseCall's two-level layout (leaves hang directly off the
+top parser) so that ``denseclass <cmd> --help`` shows the leaf's help.
+"""
+
+from argparse import ArgumentParser, ArgumentDefaultsHelpFormatter
+
+__version__ = '0.1.0'
+
+subcommands = [
+    'label', 'split', 'gendata', 'train', 'predict',
+    'precision', 'evaluation', 'comparison'
+]
+
+__all__ = ['argparser', 'main', 'subcommands', '__version__']
+
+_DESCRIPTION = ('Signal classification: label map -> split -> gendata -> '
+                'train -> predict -> evaluate')
+
+
+def _leaves():
+    """Yield (name, module) for each subcommand."""
+    for name in subcommands:
+        mod = __import__(f"denseclass.{name}", fromlist=['argparser', 'main'])
+        yield name, mod
+
+
+def _add_subparsers(parser):
+    """Attach every subcommand to ``parser`` as a real subparser."""
+    sub = parser.add_subparsers(
+        title='subcommands', description='valid commands',
+        help='additional help', dest='subcommand'
+    )
+    sub.required = True
+    for name, mod in _leaves():
+        p = sub.add_parser(name, parents=[mod.argparser()])
+        p.set_defaults(func=mod.main)
+    return sub
+
+
+def argparser():
+    """The subcommand namespace on its own (``add_help=False``, since each leaf
+    carries its own ``-h``)."""
+    parser = ArgumentParser(
+        "denseclass",
+        formatter_class=ArgumentDefaultsHelpFormatter,
+        description=_DESCRIPTION,
+        add_help=False,
+    )
+    parser.add_argument(
+        '-v', '--version', action='version',
+        version='%(prog)s {}'.format(__version__)
+    )
+    _add_subparsers(parser)
+    return parser
+
+
+def main(args=None):
+    """Console entry point: leaves hang off the top parser so
+    ``denseclass <cmd> --help`` reaches the leaf."""
+    parser = ArgumentParser(
+        'denseclass',
+        formatter_class=ArgumentDefaultsHelpFormatter,
+        description=_DESCRIPTION,
+    )
+    parser.add_argument(
+        '-v', '--version', action='version',
+        version='%(prog)s {}'.format(__version__)
+    )
+    _add_subparsers(parser)
+
+    parsed = parser.parse_args(args)
+    parsed.func(parsed)