MolBatch

MolBatch is an integrated toolkit for quantitative macromolecular structure comparison, batch analysis, structure search, and reproducible PyMOL/ChimeraX visualization. It turns one-off scripts into a configurable Python and command-line workflow.

Highlights

• Batch discovery of .cif, .mmcif, and .pdb files
• Native pairwise comparison with sequence-guided Cα correspondence and Kabsch superposition
• Reference-batch ranking and all-against-all similarity matrices
• RMSD, reference/mobile-normalized TM-score, GDT-TS, GDT-HA, Cα-lDDT, sequence identity, coverage, and aligned-core statistics
• Optional US-align comparison and Foldseek database/folder search integrations
• Dual backends:
  • PyMOL script generation (.pml)
  • ChimeraX command generation (.cxc)
• Configuration via YAML, JSON, or TOML
• CLI subcommands for config initialization, validation, scanning, plan inspection, script generation, execution, preset listing, backend listing, and environment diagnostics
• Reference-based alignment planning
• Chain filtering, hiding, removing, and object-specific coloring
• Background color, reference surface, transparency, and image/session export controls
• Optional object labeling for presentation-style scenes
• Plugin-style Python hook support with pre-command and post-command injection
• Markdown, JSON, CSV, and normalized plan reports
• Cross-platform path handling for Windows, macOS, and Linux
• Project-ready repository layout with docs, tests, examples, and packaging files

Installation

pip install -e .

For development:

python -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install -e .[dev]
pytest

Quick start

Create a starter configuration:

molbatch init-config --format yaml --out examples/demo.yaml

Validate the configuration:

molbatch validate --config examples/demo.yaml

Scan matching inputs:

molbatch scan --config examples/demo.yaml

Inspect a normalized execution plan:

molbatch plan --config examples/demo.yaml --backend pymol

Generate a PyMOL script:

molbatch generate --config examples/demo.yaml --backend pymol --out out/scene.pml

Generate a ChimeraX script:

molbatch generate --config examples/demo.yaml --backend chimerax --out out/scene.cxc

Run with a local installation:

molbatch run --config examples/demo.yaml --backend pymol --out out/scene.pml

Check local viewer availability:

molbatch doctor

Quantitatively compare two structures without a config file:

molbatch compare reference.cif model.cif --chain A

Rank every configured structure against the reference and write JSON/CSV/Markdown reports:

molbatch analyze --config examples/demo.yaml

Create an all-against-all TM-score matrix:

molbatch matrix --config examples/demo.yaml --metric tm_score

Use the optional high-sensitivity engines when installed:

molbatch analyze --config examples/demo.yaml --engine usalign
molbatch foldseek-search query.cif structure_db --out hits.tsv --tmp-dir .foldseek-tmp

Project layout

molbatch/
├─ docs/
├─ examples/
├─ src/molbatch/
│  ├─ backends/
│  ├─ core/
│  ├─ plugins/
│  └─ utils/
└─ tests/

Core concepts

1. Config loading normalizes YAML/JSON/TOML into a shared internal model.
2. Scanning discovers files with include patterns, exclude patterns, sorting, and optional limits.
3. Planning resolves a reference structure, applies presets, and assigns colors.
4. Analysis performs native metrics or delegates to US-align and writes machine-readable reports.
5. Search can delegate large collection queries to Foldseek.
6. Backend rendering turns the plan into a PyMOL or ChimeraX script.
7. Runtime execution can optionally launch an external viewer using configurable command templates.
8. Hooks let users inject custom Python logic and plain backend commands before or after script generation.

Choosing an engine

• native is dependency-contained and ideal for same or homologous protein chains. It uses a global sequence alignment to establish residue correspondence before superposition.
• usalign is recommended for sequence-independent alignment, nucleic acids, complexes, circular permutations, and publication-grade TM-align/US-align results.
• foldseek-search is intended for fast searches across large structure collections.

See scientific methods for metric definitions, limitations, and primary references.

Presets

Available built-in presets:

• comparison
• ligand-focus
• presentation
• minimal
• publication
• screening

List them from the CLI:

molbatch list-presets

Example use cases

• Align many predicted structures to a reference chain
• Keep only selected core chains in the reference while showing ligand chains in every model
• Generate reproducible sessions and figures for manuscripts or slides
• Batch-prepare viewer scripts without editing commands manually
• Pre-scan large directories and archive reports for screening workflows

License

Apache-2.0. See LICENSE.