diffbio 0.1.0__tar.gz → 0.1.2__tar.gz

{diffbio-0.1.0 → diffbio-0.1.2}/.gitignore

@@ -217,3 +217,11 @@ CLAUDE.md
 # Benchmark results (generated)
 benchmarks/results/
 data/
+
+# Local tracer-bullet tickets and scratch work
+.scratch/
+
+# Private working notes and per-editor assistant configuration. Local only.
+.claude/
+.cursor/
+AGENTS.md

{diffbio-0.1.0 → diffbio-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: diffbio
-Version: 0.1.0
+Version: 0.1.2
 Summary: DiffBio: End-to-end differentiable bioinformatics pipelines built on Datarax, Artifex, Opifex, and Calibrax
 Project-URL: Bug Tracker, https://github.com/avitai/DiffBio/issues
 Project-URL: Documentation, https://diffbio.readthedocs.io
@@ -35,40 +35,38 @@ Classifier: Intended Audience :: Education
 Classifier: Intended Audience :: Science/Research
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
 Classifier: Topic :: Software Development
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Python: >=3.11
+Requires-Python: <3.14,>=3.12
 Requires-Dist: anndata>=0.9.1
-Requires-Dist: avitai-artifex>=0.1.0
+Requires-Dist: avitai-artifex>=0.1.5
 Requires-Dist: beartype>=0.14.1
 Requires-Dist: biopython>=1.81
-Requires-Dist: calibrax>=0.1.1
+Requires-Dist: calibrax>=0.1.5
 Requires-Dist: chex>=0.1.7
-Requires-Dist: datarax>=0.1.3
-Requires-Dist: flax>=0.12.0
+Requires-Dist: datarax>=0.1.6
+Requires-Dist: flax>=0.12.9
 Requires-Dist: h5py>=3.7
 Requires-Dist: jax-md>=0.2.27
-Requires-Dist: jax>=0.6.1
+Requires-Dist: jax>=0.11.1
 Requires-Dist: jaxtyping>=0.2.20
 Requires-Dist: numpy>=1.24
-Requires-Dist: opifex>=0.1.0
-Requires-Dist: optax>=0.1.4
-Requires-Dist: orbax-checkpoint>=0.11.10
-Requires-Dist: pre-commit>=4.3.0
-Requires-Dist: rdkit>=2025.9.3
-Requires-Dist: ruff>=0.1.5
+Requires-Dist: opifex>=0.2.2
+Requires-Dist: optax>=0.2.8
 Requires-Dist: scipy>=1.10
+Requires-Dist: substrax>=0.1.5
 Provides-Extra: all
 Requires-Dist: bandit[toml]>=1.8.6; extra == 'all'
 Requires-Dist: beartype>=0.14.1; extra == 'all'
 Requires-Dist: build>=1.0.3; extra == 'all'
 Requires-Dist: coverage>=7; extra == 'all'
+Requires-Dist: datasets>=2.14; extra == 'all'
 Requires-Dist: deepchem>=2.8.0; extra == 'all'
 Requires-Dist: flake8-functions-names>=0.4; extra == 'all'
 Requires-Dist: flake8>=7.0; extra == 'all'
@@ -76,8 +74,7 @@ Requires-Dist: griffe>=1.7.3; extra == 'all'
 Requires-Dist: import-linter>=2.5; extra == 'all'
 Requires-Dist: interrogate>=1.7.0; extra == 'all'
 Requires-Dist: ipykernel>=6.29.5; extra == 'all'
-Requires-Dist: jax[cuda12]>=0.6.1; extra == 'all'
-Requires-Dist: jaxlib>=0.6.1; extra == 'all'
+Requires-Dist: jax[cuda12]>=0.11.1; extra == 'all'
 Requires-Dist: lineax>=0.0.8; extra == 'all'
 Requires-Dist: matplotlib>=3.7; extra == 'all'
 Requires-Dist: mkdocs-include-exclude-files>=0.1; extra == 'all'
@@ -105,6 +102,7 @@ Requires-Dist: pytest-xdist>=3.6; extra == 'all'
 Requires-Dist: pytest>=8.3.5; extra == 'all'
 Requires-Dist: python-dotenv>=1; extra == 'all'
 Requires-Dist: radon>=6.0.1; extra == 'all'
+Requires-Dist: rdkit>=2025.9.3; extra == 'all'
 Requires-Dist: ruff>=0.1.5; extra == 'all'
 Requires-Dist: scib-metrics>=0.5; extra == 'all'
 Requires-Dist: shellcheck-py>=0.10.0.1; extra == 'all'
@@ -113,6 +111,7 @@ Requires-Dist: tabulate>=0.9; extra == 'all'
 Requires-Dist: torch>=1.13.0; extra == 'all'
 Requires-Dist: wemake-python-styleguide>=1.0; extra == 'all'
 Provides-Extra: benchmark
+Requires-Dist: datasets>=2.14; extra == 'benchmark'
 Requires-Dist: deepchem>=2.8.0; extra == 'benchmark'
 Requires-Dist: matplotlib>=3.7; extra == 'benchmark'
 Requires-Dist: pandas>=2.0; extra == 'benchmark'
@@ -120,6 +119,8 @@ Requires-Dist: pynndescent>=0.5; extra == 'benchmark'
 Requires-Dist: scib-metrics>=0.5; extra == 'benchmark'
 Requires-Dist: squidpy>=1.4; extra == 'benchmark'
 Requires-Dist: tabulate>=0.9; extra == 'benchmark'
+Provides-Extra: chem
+Requires-Dist: rdkit>=2025.9.3; extra == 'chem'
 Provides-Extra: cuda-dev
 Requires-Dist: bandit[toml]>=1.8.6; extra == 'cuda-dev'
 Requires-Dist: build>=1.0.3; extra == 'cuda-dev'
@@ -129,8 +130,7 @@ Requires-Dist: flake8>=7.0; extra == 'cuda-dev'
 Requires-Dist: import-linter>=2.5; extra == 'cuda-dev'
 Requires-Dist: interrogate>=1.7.0; extra == 'cuda-dev'
 Requires-Dist: ipykernel>=6.29.5; extra == 'cuda-dev'
-Requires-Dist: jax[cuda12]>=0.6.1; extra == 'cuda-dev'
-Requires-Dist: jaxlib>=0.6.1; extra == 'cuda-dev'
+Requires-Dist: jax[cuda12]>=0.11.1; extra == 'cuda-dev'
 Requires-Dist: pylint>=3.3.8; extra == 'cuda-dev'
 Requires-Dist: pyright>=1.1.336; extra == 'cuda-dev'
 Requires-Dist: pytest-asyncio>=0.23; extra == 'cuda-dev'
@@ -147,6 +147,8 @@ Requires-Dist: radon>=6.0.1; extra == 'cuda-dev'
 Requires-Dist: ruff>=0.1.5; extra == 'cuda-dev'
 Requires-Dist: shellcheck-py>=0.10.0.1; extra == 'cuda-dev'
 Requires-Dist: wemake-python-styleguide>=1.0; extra == 'cuda-dev'
+Provides-Extra: cuda12
+Requires-Dist: jax[cuda12]>=0.11.1; extra == 'cuda12'
 Provides-Extra: dev
 Requires-Dist: bandit[toml]>=1.8.6; extra == 'dev'
 Requires-Dist: build>=1.0.3; extra == 'dev'
@@ -183,9 +185,6 @@ Requires-Dist: pymdown-extensions>=10.14.3; extra == 'docs'
 Provides-Extra: genomics
 Requires-Dist: pyfaidx>=0.8.0; extra == 'genomics'
 Requires-Dist: pysam>=0.22.0; extra == 'genomics'
-Provides-Extra: gpu
-Requires-Dist: jax[cuda12]>=0.6.1; extra == 'gpu'
-Requires-Dist: jaxlib>=0.6.1; extra == 'gpu'
 Provides-Extra: soft-ops-advanced
 Requires-Dist: lineax>=0.0.8; extra == 'soft-ops-advanced'
 Requires-Dist: optimistix>=0.0.9; extra == 'soft-ops-advanced'
@@ -211,7 +210,7 @@ Description-Content-Type: text/markdown
 # DiffBio
 
 <p align="center">
-  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.11+-blue.svg" alt="Python 3.11+"></a>
+  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.12+-blue.svg" alt="Python 3.12+"></a>
   <a href="https://jax.readthedocs.io/"><img src="https://img.shields.io/badge/JAX-0.6.1+-green.svg" alt="JAX"></a>
   <a href="https://flax.readthedocs.io/"><img src="https://img.shields.io/badge/Flax-0.12+-orange.svg" alt="Flax"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
@@ -222,11 +221,28 @@ Description-Content-Type: text/markdown
 </p>
 
 <p align="center">
-  Built on <a href="https://github.com/avitai/datarax">Datarax</a>, <a href="https://github.com/avitai/artifex">Artifex</a>, <a href="https://github.com/avitai/Opifex">Opifex</a>, and <a href="https://github.com/avitai/calibrax">Calibrax</a> | Powered by <a href="https://jax.readthedocs.io/">JAX</a> & <a href="https://flax.readthedocs.io/">Flax NNX</a>
+  Built on <a href="https://github.com/avitai/datarax">Datarax</a>, <a href="https://github.com/avitai/artifex">Artifex</a>, <a href="https://github.com/avitai/opifex">Opifex</a>, and <a href="https://github.com/avitai/calibrax">Calibrax</a> | Powered by <a href="https://jax.readthedocs.io/">JAX</a> & <a href="https://flax.readthedocs.io/">Flax NNX</a>
 </p>
 
 ---
 
+> **Research preview.** DiffBio is under rapid iteration and the API will change while we iterate
+> toward v1.0. What that means concretely:
+>
+> | Area | Status | Impact |
+> |------|--------|--------|
+> | **API** | 🔄 Unstable | Breaking changes are expected. Public interfaces may change without deprecation warnings. Pin to specific commits if stability is required. |
+> | **Tests** | 🔄 In Flux | Test suite is being expanded. Some tests may fail or be skipped. Coverage metrics are improving but not yet full. |
+> | **Documentation** | 🔄 Evolving | Docs may not reflect current implementation. Code examples might be outdated. Refer to source code and tests for accurate usage. |
+>
+> Pin a version if you need stability, and do not put it in production yet. For research and
+> experimentation it is ready to use today, with the understanding that APIs will evolve.
+>
+> This is public this early on purpose. Issues, questions and pull requests genuinely steer
+> what gets built next, and a star tells us which layer to push on.
+
+---
+
 ## Overview
 
 DiffBio is a framework for building **end-to-end differentiable bioinformatics
@@ -258,17 +274,18 @@ This enables learning optimal pipeline parameters directly from data, rather tha
 - **Composable Architecture** built on the Datarax, Artifex, Opifex, and Calibrax stack
 - **Training Utilities** with gradient clipping, custom loss functions, and synthetic data generation
 
-For complete operator and pipeline listings, see the [Operators Overview](https://docs.avitai.bio/diffbio/user-guide/operators/overview/) and [Pipelines Overview](https://docs.avitai.bio/diffbio/user-guide/pipelines/overview/) in the documentation.
+For complete operator and pipeline listings, see the [Operators Overview](https://diffbio.readthedocs.io/en/latest/user-guide/operators/overview/) and [Pipelines Overview](https://diffbio.readthedocs.io/en/latest/user-guide/pipelines/overview/) in the documentation.
 
 ## Installation
 
 ```bash
-# Clone the repository
+# From PyPI
+uv add diffbio          # or: pip install diffbio
+
+# From source
 git clone https://github.com/avitai/DiffBio.git
 cd DiffBio
-
-# Install with uv
-uv sync
+./setup.sh              # detects the backend and syncs the extras
 ```
 
 ## Quick Start
@@ -280,24 +297,22 @@ import jax
 import jax.numpy as jnp
 from flax import nnx
 
-from diffbio.operators import DifferentiableQualityFilter
-from diffbio.operators.variant.pileup import DifferentiablePileup
-from diffbio.operators.alignment.smith_waterman import SmoothSmithWaterman
+from diffbio.operators import DifferentiableQualityFilter, QualityFilterConfig
 
-# Quality filtering with learnable threshold
+# Quality filtering with learnable threshold (default initial_threshold=20.0)
 quality_filter = DifferentiableQualityFilter(
-    threshold=20.0,
-    temperature=1.0,
+    QualityFilterConfig(initial_threshold=20.0),
     rngs=nnx.Rngs(0),
 )
 
-# Apply to reads
+# Apply to a one-hot encoded sequence with per-position quality scores
 quality_scores = jnp.array([35.0, 15.0, 28.0, 10.0])
-reads = jax.nn.one_hot(jnp.array([[0, 1, 2, 3]] * 4), 4)
-data = {"reads": reads, "quality": quality_scores}
+sequence = jax.nn.one_hot(jnp.array([0, 1, 2, 3]), 4)  # (length, alphabet=4)
+data = {"sequence": sequence, "quality_scores": quality_scores}
 
 filtered_data, _, _ = quality_filter.apply(data, {}, None)
-# filtered_data["weights"] contains soft weights for each read
+# filtered_data["sequence"]        - sequence with low-quality positions softly suppressed
+# filtered_data["quality_scores"]  - pass-through quality values
 ```
 
 ### Using the Variant Calling Pipeline
@@ -386,9 +401,12 @@ DiffBio sits on a layered ecosystem rather than standing alone:
 |---|---|---|
 | Execution contracts | [Datarax](https://github.com/avitai/datarax) | Operator, data-source, and pipeline contracts |
 | Modeling substrate | [Artifex](https://github.com/avitai/artifex) | Reusable transformer and generative-model components |
-| Scientific ML substrate | [Opifex](https://github.com/avitai/Opifex) | Scientific optimization, operator learning, and advanced training methods |
+| Scientific ML substrate | [Opifex](https://github.com/avitai/opifex) | Scientific optimization, operator learning, and advanced training methods |
 | Evaluation substrate | [Calibrax](https://github.com/avitai/calibrax) | Metrics, benchmarking, comparison, profiling, and regression checks |
-| Biology-specific layer | DiffBio | Differentiable biological operators and domain compositions |
+
+DiffBio itself sits on top of these as the biology-specific layer: differentiable
+biological operators and end-to-end pipeline compositions (alignment, variant
+calling, single-cell analysis, drug discovery, structural biology, multi-omics).
 
 Each DiffBio operator inherits from Datarax's `OperatorModule` and implements:
 
@@ -403,18 +421,31 @@ This enables:
 
 ### Operator Composition
 
-Operators are chained by threading the `(data, state, metadata)` triple
-returned by `apply()` into the next operator:
+`apply()` runs an operator on a single element (no batch dimension). Operators
+are chained by threading the `(data, state, metadata)` triple returned by
+`apply()` into the next operator:
 
 ```python
-data, state, metadata = quality_filter.apply(batch_data, {}, None)
+data, state, metadata = quality_filter.apply(element_data, {}, None)
 data, state, metadata = pileup.apply(data, state, metadata)
 data, state, metadata = classifier.apply(data, state, metadata)
 
-# `data` is a dict of JAX arrays — read out the per-position predictions
+# `data` is a dict of JAX arrays - read out the per-position predictions
 predictions = data["logits"]
 ```
 
+For batched data wrapped in a Datarax `Batch`, call the operator directly
+(or use `apply_batch()`); both delegate to the same code path:
+
+```python
+from datarax import Batch
+
+batch = Batch.from_parts(...)        # construct from a list of elements
+batch = quality_filter(batch)         # equivalent to quality_filter.apply_batch(batch)
+batch = pileup(batch)
+batch = classifier(batch)
+```
+
 ## Testing
 
 ```bash
@@ -435,35 +466,49 @@ uv run pytest tests/integration/ -vv
 ```
 DiffBio/
 ├── src/diffbio/
-│   ├── core/               # Base operators, graph utils, soft ops
-│   ├── operators/           # 35+ differentiable operators
+│   ├── core/                # Base operators, graph utils, soft ops, neural components
+│   ├── operators/           # 40+ differentiable operators
 │   │   ├── alignment/       # Smith-Waterman, profile HMM, soft MSA
-│   │   ├── variant/         # Pileup, classifiers, CNV segmentation
-│   │   ├── singlecell/      # Clustering, trajectory, velocity, GRN, ...
-│   │   ├── drug_discovery/  # Fingerprints, property prediction, ADMET
-│   │   ├── epigenomics/     # Peak calling, chromatin state
-│   │   ├── normalization/   # VAE normalizer, UMAP, PHATE
+│   │   ├── assembly/        # GNN assembly, metagenomic binning
+│   │   ├── crispr/          # Guide RNA scoring
+│   │   ├── drug_discovery/  # Fingerprints, ADMET, AttentiveFP, MACCS keys
+│   │   ├── epigenomics/     # Peak calling, chromatin state, contextual epigenomics
+│   │   ├── foundation_models/ # Geneformer/scGPT adapters, transformer encoders
+│   │   ├── mapping/         # Neural read mapping
+│   │   ├── metabolomics/    # Spectral similarity
+│   │   ├── molecular_dynamics/ # Force fields, MD integrators
+│   │   ├── multiomics/      # Hi-C, spatial deconvolution, multi-omics VAE
+│   │   ├── normalization/   # VAE normalizer, UMAP, PHATE, embeddings
+│   │   ├── population/      # Ancestry estimation
+│   │   ├── preprocessing/   # Adapter removal, duplicate weighting, error correction
+│   │   ├── protein/         # Secondary structure
+│   │   ├── rna_structure/   # RNA folding
+│   │   ├── rnaseq/          # Splicing PSI, motif discovery
+│   │   ├── singlecell/      # Clustering, trajectory, velocity, GRN, batch correction, ...
 │   │   ├── statistical/     # HMM, NB GLM, EM quantification
-│   │   ├── multiomics/      # Hi-C, spatial deconvolution
-│   │   └── ...              # preprocessing, protein, RNA, assembly, ...
-│   ├── pipelines/           # End-to-end pipelines
-│   ├── losses/              # Alignment, single-cell, statistical losses
-│   ├── sources/             # Data loaders (FASTA, BAM, MolNet, ...)
-│   ├── splitters/           # Dataset splitting strategies
-│   └── utils/               # Training utilities
+│   │   └── variant/         # Pileup, classifiers, CNV segmentation
+│   ├── pipelines/           # 6 end-to-end pipelines
+│   ├── losses/              # Alignment, biological-regularization, single-cell, statistical, metric
+│   ├── sources/             # Data loaders (FASTA, BAM, AnnData, MoleculeNet, indexed views)
+│   ├── splitters/           # Random, stratified, scaffold, Tanimoto, sequence-identity
+│   ├── samplers/            # Perturbation samplers
+│   ├── sequences/           # DNA / RNA encoding utilities
+│   ├── evaluation/          # Evaluation runner and graders
+│   └── utils/               # Training utilities, dependency-runtime checks
 ├── tests/                   # Unit, integration, and benchmark tests
 ├── benchmarks/              # Domain benchmarks with training + baselines
+├── examples/                # Runnable example scripts paired with notebooks
 └── docs/                    # MkDocs documentation
 ```
 
 ## Requirements
 
-- Python 3.11+
+- Python 3.12+
 - JAX 0.6.1+
 - Flax 0.12+
 - Optax 0.1.4+
 - jaxtyping 0.2.20+
-- Datarax, Artifex, Opifex, and Calibrax (installed automatically from PyPI)
+- Datarax, Artifex, Opifex, Calibrax and Substrax (installed automatically from PyPI)
 
 ## License
 
@@ -472,9 +517,8 @@ MIT License. See [LICENSE](LICENSE) for details.
 ## Acknowledgments
 
 DiffBio builds on ideas from:
-- [SMURF](https://www.biorxiv.org/content/10.1101/2021.10.23.465204): Differentiable Smith-Waterman for end-to-end MSA learning
 - [Datarax](https://github.com/avitai/datarax): Composable data processing framework
 - [Artifex](https://github.com/avitai/artifex): Generative-model and transformer substrate
-- [Opifex](https://github.com/avitai/Opifex): Scientific ML and advanced optimization substrate
+- [Opifex](https://github.com/avitai/opifex): Scientific ML and advanced optimization substrate
 - [Calibrax](https://github.com/avitai/calibrax): Benchmarking, comparison, and regression substrate
 - [Flax NNX](https://flax.readthedocs.io/): Neural network library for JAX

{diffbio-0.1.0 → diffbio-0.1.2}/README.md

@@ -1,7 +1,7 @@
 # DiffBio
 
 <p align="center">
-  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.11+-blue.svg" alt="Python 3.11+"></a>
+  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.12+-blue.svg" alt="Python 3.12+"></a>
   <a href="https://jax.readthedocs.io/"><img src="https://img.shields.io/badge/JAX-0.6.1+-green.svg" alt="JAX"></a>
   <a href="https://flax.readthedocs.io/"><img src="https://img.shields.io/badge/Flax-0.12+-orange.svg" alt="Flax"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
@@ -12,11 +12,28 @@
 </p>
 
 <p align="center">
-  Built on <a href="https://github.com/avitai/datarax">Datarax</a>, <a href="https://github.com/avitai/artifex">Artifex</a>, <a href="https://github.com/avitai/Opifex">Opifex</a>, and <a href="https://github.com/avitai/calibrax">Calibrax</a> | Powered by <a href="https://jax.readthedocs.io/">JAX</a> & <a href="https://flax.readthedocs.io/">Flax NNX</a>
+  Built on <a href="https://github.com/avitai/datarax">Datarax</a>, <a href="https://github.com/avitai/artifex">Artifex</a>, <a href="https://github.com/avitai/opifex">Opifex</a>, and <a href="https://github.com/avitai/calibrax">Calibrax</a> | Powered by <a href="https://jax.readthedocs.io/">JAX</a> & <a href="https://flax.readthedocs.io/">Flax NNX</a>
 </p>
 
 ---
 
+> **Research preview.** DiffBio is under rapid iteration and the API will change while we iterate
+> toward v1.0. What that means concretely:
+>
+> | Area | Status | Impact |
+> |------|--------|--------|
+> | **API** | 🔄 Unstable | Breaking changes are expected. Public interfaces may change without deprecation warnings. Pin to specific commits if stability is required. |
+> | **Tests** | 🔄 In Flux | Test suite is being expanded. Some tests may fail or be skipped. Coverage metrics are improving but not yet full. |
+> | **Documentation** | 🔄 Evolving | Docs may not reflect current implementation. Code examples might be outdated. Refer to source code and tests for accurate usage. |
+>
+> Pin a version if you need stability, and do not put it in production yet. For research and
+> experimentation it is ready to use today, with the understanding that APIs will evolve.
+>
+> This is public this early on purpose. Issues, questions and pull requests genuinely steer
+> what gets built next, and a star tells us which layer to push on.
+
+---
+
 ## Overview
 
 DiffBio is a framework for building **end-to-end differentiable bioinformatics
@@ -48,17 +65,18 @@ This enables learning optimal pipeline parameters directly from data, rather tha
 - **Composable Architecture** built on the Datarax, Artifex, Opifex, and Calibrax stack
 - **Training Utilities** with gradient clipping, custom loss functions, and synthetic data generation
 
-For complete operator and pipeline listings, see the [Operators Overview](https://docs.avitai.bio/diffbio/user-guide/operators/overview/) and [Pipelines Overview](https://docs.avitai.bio/diffbio/user-guide/pipelines/overview/) in the documentation.
+For complete operator and pipeline listings, see the [Operators Overview](https://diffbio.readthedocs.io/en/latest/user-guide/operators/overview/) and [Pipelines Overview](https://diffbio.readthedocs.io/en/latest/user-guide/pipelines/overview/) in the documentation.
 
 ## Installation
 
 ```bash
-# Clone the repository
+# From PyPI
+uv add diffbio          # or: pip install diffbio
+
+# From source
 git clone https://github.com/avitai/DiffBio.git
 cd DiffBio
-
-# Install with uv
-uv sync
+./setup.sh              # detects the backend and syncs the extras
 ```
 
 ## Quick Start
@@ -70,24 +88,22 @@ import jax
 import jax.numpy as jnp
 from flax import nnx
 
-from diffbio.operators import DifferentiableQualityFilter
-from diffbio.operators.variant.pileup import DifferentiablePileup
-from diffbio.operators.alignment.smith_waterman import SmoothSmithWaterman
+from diffbio.operators import DifferentiableQualityFilter, QualityFilterConfig
 
-# Quality filtering with learnable threshold
+# Quality filtering with learnable threshold (default initial_threshold=20.0)
 quality_filter = DifferentiableQualityFilter(
-    threshold=20.0,
-    temperature=1.0,
+    QualityFilterConfig(initial_threshold=20.0),
     rngs=nnx.Rngs(0),
 )
 
-# Apply to reads
+# Apply to a one-hot encoded sequence with per-position quality scores
 quality_scores = jnp.array([35.0, 15.0, 28.0, 10.0])
-reads = jax.nn.one_hot(jnp.array([[0, 1, 2, 3]] * 4), 4)
-data = {"reads": reads, "quality": quality_scores}
+sequence = jax.nn.one_hot(jnp.array([0, 1, 2, 3]), 4)  # (length, alphabet=4)
+data = {"sequence": sequence, "quality_scores": quality_scores}
 
 filtered_data, _, _ = quality_filter.apply(data, {}, None)
-# filtered_data["weights"] contains soft weights for each read
+# filtered_data["sequence"]        - sequence with low-quality positions softly suppressed
+# filtered_data["quality_scores"]  - pass-through quality values
 ```
 
 ### Using the Variant Calling Pipeline
@@ -176,9 +192,12 @@ DiffBio sits on a layered ecosystem rather than standing alone:
 |---|---|---|
 | Execution contracts | [Datarax](https://github.com/avitai/datarax) | Operator, data-source, and pipeline contracts |
 | Modeling substrate | [Artifex](https://github.com/avitai/artifex) | Reusable transformer and generative-model components |
-| Scientific ML substrate | [Opifex](https://github.com/avitai/Opifex) | Scientific optimization, operator learning, and advanced training methods |
+| Scientific ML substrate | [Opifex](https://github.com/avitai/opifex) | Scientific optimization, operator learning, and advanced training methods |
 | Evaluation substrate | [Calibrax](https://github.com/avitai/calibrax) | Metrics, benchmarking, comparison, profiling, and regression checks |
-| Biology-specific layer | DiffBio | Differentiable biological operators and domain compositions |
+
+DiffBio itself sits on top of these as the biology-specific layer: differentiable
+biological operators and end-to-end pipeline compositions (alignment, variant
+calling, single-cell analysis, drug discovery, structural biology, multi-omics).
 
 Each DiffBio operator inherits from Datarax's `OperatorModule` and implements:
 
@@ -193,18 +212,31 @@ This enables:
 
 ### Operator Composition
 
-Operators are chained by threading the `(data, state, metadata)` triple
-returned by `apply()` into the next operator:
+`apply()` runs an operator on a single element (no batch dimension). Operators
+are chained by threading the `(data, state, metadata)` triple returned by
+`apply()` into the next operator:
 
 ```python
-data, state, metadata = quality_filter.apply(batch_data, {}, None)
+data, state, metadata = quality_filter.apply(element_data, {}, None)
 data, state, metadata = pileup.apply(data, state, metadata)
 data, state, metadata = classifier.apply(data, state, metadata)
 
-# `data` is a dict of JAX arrays — read out the per-position predictions
+# `data` is a dict of JAX arrays - read out the per-position predictions
 predictions = data["logits"]
 ```
 
+For batched data wrapped in a Datarax `Batch`, call the operator directly
+(or use `apply_batch()`); both delegate to the same code path:
+
+```python
+from datarax import Batch
+
+batch = Batch.from_parts(...)        # construct from a list of elements
+batch = quality_filter(batch)         # equivalent to quality_filter.apply_batch(batch)
+batch = pileup(batch)
+batch = classifier(batch)
+```
+
 ## Testing
 
 ```bash
@@ -225,35 +257,49 @@ uv run pytest tests/integration/ -vv
 ```
 DiffBio/
 ├── src/diffbio/
-│   ├── core/               # Base operators, graph utils, soft ops
-│   ├── operators/           # 35+ differentiable operators
+│   ├── core/                # Base operators, graph utils, soft ops, neural components
+│   ├── operators/           # 40+ differentiable operators
 │   │   ├── alignment/       # Smith-Waterman, profile HMM, soft MSA
-│   │   ├── variant/         # Pileup, classifiers, CNV segmentation
-│   │   ├── singlecell/      # Clustering, trajectory, velocity, GRN, ...
-│   │   ├── drug_discovery/  # Fingerprints, property prediction, ADMET
-│   │   ├── epigenomics/     # Peak calling, chromatin state
-│   │   ├── normalization/   # VAE normalizer, UMAP, PHATE
+│   │   ├── assembly/        # GNN assembly, metagenomic binning
+│   │   ├── crispr/          # Guide RNA scoring
+│   │   ├── drug_discovery/  # Fingerprints, ADMET, AttentiveFP, MACCS keys
+│   │   ├── epigenomics/     # Peak calling, chromatin state, contextual epigenomics
+│   │   ├── foundation_models/ # Geneformer/scGPT adapters, transformer encoders
+│   │   ├── mapping/         # Neural read mapping
+│   │   ├── metabolomics/    # Spectral similarity
+│   │   ├── molecular_dynamics/ # Force fields, MD integrators
+│   │   ├── multiomics/      # Hi-C, spatial deconvolution, multi-omics VAE
+│   │   ├── normalization/   # VAE normalizer, UMAP, PHATE, embeddings
+│   │   ├── population/      # Ancestry estimation
+│   │   ├── preprocessing/   # Adapter removal, duplicate weighting, error correction
+│   │   ├── protein/         # Secondary structure
+│   │   ├── rna_structure/   # RNA folding
+│   │   ├── rnaseq/          # Splicing PSI, motif discovery
+│   │   ├── singlecell/      # Clustering, trajectory, velocity, GRN, batch correction, ...
 │   │   ├── statistical/     # HMM, NB GLM, EM quantification
-│   │   ├── multiomics/      # Hi-C, spatial deconvolution
-│   │   └── ...              # preprocessing, protein, RNA, assembly, ...
-│   ├── pipelines/           # End-to-end pipelines
-│   ├── losses/              # Alignment, single-cell, statistical losses
-│   ├── sources/             # Data loaders (FASTA, BAM, MolNet, ...)
-│   ├── splitters/           # Dataset splitting strategies
-│   └── utils/               # Training utilities
+│   │   └── variant/         # Pileup, classifiers, CNV segmentation
+│   ├── pipelines/           # 6 end-to-end pipelines
+│   ├── losses/              # Alignment, biological-regularization, single-cell, statistical, metric
+│   ├── sources/             # Data loaders (FASTA, BAM, AnnData, MoleculeNet, indexed views)
+│   ├── splitters/           # Random, stratified, scaffold, Tanimoto, sequence-identity
+│   ├── samplers/            # Perturbation samplers
+│   ├── sequences/           # DNA / RNA encoding utilities
+│   ├── evaluation/          # Evaluation runner and graders
+│   └── utils/               # Training utilities, dependency-runtime checks
 ├── tests/                   # Unit, integration, and benchmark tests
 ├── benchmarks/              # Domain benchmarks with training + baselines
+├── examples/                # Runnable example scripts paired with notebooks
 └── docs/                    # MkDocs documentation
 ```
 
 ## Requirements
 
-- Python 3.11+
+- Python 3.12+
 - JAX 0.6.1+
 - Flax 0.12+
 - Optax 0.1.4+
 - jaxtyping 0.2.20+
-- Datarax, Artifex, Opifex, and Calibrax (installed automatically from PyPI)
+- Datarax, Artifex, Opifex, Calibrax and Substrax (installed automatically from PyPI)
 
 ## License
 
@@ -262,9 +308,8 @@ MIT License. See [LICENSE](LICENSE) for details.
 ## Acknowledgments
 
 DiffBio builds on ideas from:
-- [SMURF](https://www.biorxiv.org/content/10.1101/2021.10.23.465204): Differentiable Smith-Waterman for end-to-end MSA learning
 - [Datarax](https://github.com/avitai/datarax): Composable data processing framework
 - [Artifex](https://github.com/avitai/artifex): Generative-model and transformer substrate
-- [Opifex](https://github.com/avitai/Opifex): Scientific ML and advanced optimization substrate
+- [Opifex](https://github.com/avitai/opifex): Scientific ML and advanced optimization substrate
 - [Calibrax](https://github.com/avitai/calibrax): Benchmarking, comparison, and regression substrate
 - [Flax NNX](https://flax.readthedocs.io/): Neural network library for JAX