📖 Table of Contents

• Overview
• Installation
• Quick start
• Subcommands
• Training modes
• Examples
• Relationship to densecall
• 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 and now stands alone — see Relationship to densecall.

📦 Installation

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:

conda install -c nvidia cuda-toolkit=12.8

🚀 Quick start

denseclass --help
denseclass label --help

🎯 Subcommands

🧪 Training modes

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

# 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)

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:

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:

All flags are unchanged.

🛠 Development

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

# 1. bump __version__ in denseclass/cli.py
python -m build
twine check dist/* && twine upload dist/*

📄 License

MIT — see LICENCE.txt.