topoppi 1.1__tar.gz

topoppi-1.1/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to TopoPPI are documented here.
+
+## [Unreleased]
+
+## [1.1] - 2026-05-09
+
+- Improved GUI mode switching, sticky run controls, styling, run logs, validation, figure auto-save, manifests, and Matplotlib navigation.
+- Added benchmark `resume`/`new`/`overwrite` modes, worker selection, config fingerprints, and invalid-input reports.
+- Made benchmark preprocessing honor configured chain IDs consistently.
+- Added ProLIF metadata validation and richer single-run reproducibility manifests.
+- Hardened release packaging, PyPI metadata, and OptCuts installation checks.
+- Added the `topoppi-install-optcuts` downloader for Linux x86-64 GitHub release artifacts.
+
+## [1.0.0] - 2026-05-08
+
+- Initial public release of TopoPPI.

topoppi-1.1/CITATION.cff

@@ -0,0 +1,9 @@
+cff-version: 1.2.0
+message: "If you use TopoPPI in your research, please cite this software."
+title: "TopoPPI: a geometry-aware platform for visualization and low-distortion mapping of protein–protein interaction interfaces"
+version: "1.1"
+date-released: "2026-05-09"
+repository-code: "https://github.com/GeraltZeroZhong/TopoPPI"
+license: "MIT"
+authors:
+  - name: "Shuyu Zhong"

topoppi-1.1/CONTRIBUTING.md

@@ -0,0 +1,47 @@
+# Contributing
+
+## Development Setup
+
+```bash
+conda env create -f environment.yml
+conda activate bio3d
+pip install -e ".[dev,benchmark,interactions,meshio]"
+```
+
+Install OptCuts into the active environment when running the full pipeline:
+
+```bash
+bash tools/OptCuts/install_optcuts.sh
+which OptCuts_bin
+```
+
+## Tests
+
+Run the lightweight test suite:
+
+```bash
+PYTHONPATH=src python -m unittest discover -s tests
+```
+
+With pytest installed:
+
+```bash
+pytest
+```
+
+Tests that require the external OptCuts binary should be marked `requires_optcuts`.
+Slow or dataset-scale tests should be marked `slow` and must not be required for basic pull-request validation.
+
+## Code Style
+
+Use English for code, comments, commit messages, and project documentation inside the repository.
+Prefer small, reviewable changes and preserve core algorithm behavior unless a clear bug is identified.
+
+```bash
+ruff check src tests
+```
+
+## Fixture Policy
+
+Keep default fixtures small, synthetic, and redistributable.
+Do not add downloaded PDB datasets, generated benchmark outputs, or large binary artifacts to the repository.

topoppi-1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Shuyu Zhong
+
+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.

topoppi-1.1/MANIFEST.in

@@ -0,0 +1,21 @@
+include LICENSE
+include README.md
+include environment.yml
+include CHANGELOG.md
+include CITATION.cff
+include CONTRIBUTING.md
+recursive-include docs *.md
+recursive-include docs/assets *.png
+include tests/fixtures/1bvk.pdb
+include tests/fixtures/prolif_interactions.json
+include tests/fixtures/tiny_complex.pdb
+recursive-exclude .github *
+recursive-exclude dist *
+recursive-exclude build *
+recursive-exclude *.egg-info *
+recursive-exclude tools/OptCuts OptCuts_bin
+recursive-exclude tests/fixtures *_cutoff*_res*_sigma*_min*_*.png
+recursive-exclude tests/fixtures *_cutoff*_res*_sigma*_min*_*.topoppi.json
+global-exclude __pycache__
+global-exclude *.py[cod]
+global-exclude .DS_Store

topoppi-1.1/PKG-INFO

@@ -0,0 +1,486 @@
+Metadata-Version: 2.4
+Name: topoppi
+Version: 1.1
+Summary: Protein-protein interaction interface mapping from 3D structures to 2D UV atlases.
+Author: TopoPPI contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/GeraltZeroZhong/TopoPPI
+Project-URL: Repository, https://github.com/GeraltZeroZhong/TopoPPI
+Project-URL: Issues, https://github.com/GeraltZeroZhong/TopoPPI/issues
+Keywords: protein-protein interaction,bioinformatics,surface mesh,uv atlas,computational biology
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: <3.11,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.21
+Requires-Dist: scipy>=1.8
+Requires-Dist: biopython>=1.79
+Requires-Dist: scikit-image>=0.19
+Requires-Dist: matplotlib>=3.5
+Requires-Dist: trimesh>=3.10
+Requires-Dist: networkx>=2.8
+Requires-Dist: pillow>=9.0
+Requires-Dist: rtree>=1.0
+Requires-Dist: shapely>=1.8
+Requires-Dist: libigl<2.7,>=2.6
+Provides-Extra: benchmark
+Requires-Dist: psutil>=5.9; extra == "benchmark"
+Requires-Dist: tqdm>=4.60; extra == "benchmark"
+Provides-Extra: interactions
+Requires-Dist: MDAnalysis>=2.0; extra == "interactions"
+Requires-Dist: prolif>=2.0; extra == "interactions"
+Requires-Dist: rdkit>=2023.9; extra == "interactions"
+Provides-Extra: meshio
+Requires-Dist: meshio>=5.0; extra == "meshio"
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Provides-Extra: all
+Requires-Dist: psutil>=5.9; extra == "all"
+Requires-Dist: tqdm>=4.60; extra == "all"
+Requires-Dist: MDAnalysis>=2.0; extra == "all"
+Requires-Dist: prolif>=2.0; extra == "all"
+Requires-Dist: rdkit>=2023.9; extra == "all"
+Requires-Dist: meshio>=5.0; extra == "all"
+Dynamic: license-file
+
+# TopoPPI
+
+> **Release:** This README targets `topoppi 1.1`. The matching GitHub release tag is `v1.1`.
+
+TopoPPI maps **protein-protein interaction (PPI) interfaces** from 3D structures into annotated 2D UV atlases. It is built for interactive inspection, reproducible figure export, and benchmark-style evaluation across structure sets.
+
+The toolkit includes:
+
+- a **Basic/Advanced Tkinter GUI** for single-structure analysis, interaction styling, benchmark launching, and reproducible export,
+- a **command-line pipeline** for one-shot interface map generation,
+- a **benchmark framework** for multi-structure evaluation with JSON/CSV reports,
+- optional typed interaction annotation through ProLIF, with geometric fallback when no ProLIF data is available.
+
+The pipeline loads protein chains from PDB/mmCIF files, builds a receptor surface, extracts interface patches against a partner chain, flattens patches to UV space, optimizes UVs with [**OptCuts**](https://github.com/liminchen/OptCuts), and renders annotated interface maps.
+
+<img width="1920" height="1032" alt="TopoPPI GUI showing the Basic workflow and interface map" src="https://raw.githubusercontent.com/GeraltZeroZhong/TopoPPI/v1.1/docs/assets/3ff22687bd403a67cd66caeacc95baee.png" />
+
+---
+
+## Quick Start (GUI, ~5 minutes)
+
+If you only want to launch the GUI and run your first structure quickly:
+
+1. Create and activate the Conda environment:
+
+```bash
+conda env create -f environment.yml
+conda activate bio3d
+```
+
+2. Install TopoPPI in editable mode:
+
+```bash
+pip install -e ".[benchmark,interactions,meshio]"
+```
+
+3. Install OptCuts into the active Conda environment:
+
+```bash
+topoppi-install-optcuts
+which OptCuts_bin
+```
+
+   Source checkout users can also install the bundled binary directly:
+
+```bash
+bash tools/OptCuts/install_optcuts.sh
+```
+
+4. Launch GUI:
+
+```bash
+topoppi-gui
+```
+
+5. In the GUI:
+   - Use **Basic** to load a `.pdb`/`.cif` structure file,
+   - Review detected chains and use **Swap A/B** if the surface/partner assignment is reversed,
+   - Choose which interaction types to display and adjust colors if needed,
+   - Click **Run Single Analysis** to generate and auto-save the interface map.
+
+> Note: [OptCuts](https://github.com/liminchen/OptCuts) is required by the current pipeline. Running without OptCuts is intentionally unsupported.
+> PyPI wheels do not include the OptCuts binary, but the `topoppi-install-optcuts` command downloads the Linux x86-64 binary from the matching GitHub release and installs it into your active Conda environment or `~/.local/bin`.
+
+---
+
+## Project Overview
+
+### Core workflow
+
+1. **Load structure data** for Chain A (receptor/surface chain) and Chain B (ligand chain).
+2. **Generate molecular surface** for Chain A.
+3. **Extract interface patches** using a distance cutoff to Chain B atoms.
+4. **Parameterize patches** with LSCM.
+5. **Optimize UV patches** with OptCuts (required in current pipeline).
+6. **Visualize and export** annotated 2D interface maps.
+
+### Main entry points
+
+- `topoppi`: installed command-line pipeline.
+- `topoppi-gui`: installed Tkinter GUI.
+- `topoppi-install-optcuts`: download and install the Linux x86-64 OptCuts binary from the matching GitHub release.
+- `topoppi.pipeline.run_interface_mapping`: importable single-structure API.
+- `topoppi.benchmarking`: benchmark engine, metrics, aggregation, and CSV/JSON reporting.
+
+All user-facing defaults live in `topoppi.config`.
+
+---
+
+## Installation & Requirements
+
+### System requirements
+
+- Python **3.10** (recommended via Conda)
+- OS with Tk support (for GUI mode)
+- **libigl Python bindings 2.6.x** (package: `igl`)
+- **ProLIF + MDAnalysis are recommended** for automatic typed interaction generation; the GUI can leave ProLIF blank and fall back to geometric heuristics if generation is unavailable
+- **OptCuts binary (`OptCuts_bin`) must be installed** and available in your PATH (or passed via `--optcuts-bin`)
+
+### Create environment from a source checkout
+
+```bash
+conda env create -f environment.yml
+conda activate bio3d
+pip install -e ".[benchmark,interactions,meshio]"
+```
+
+The repository includes `pyproject.toml` for standard Python packaging and PyPI publication.
+
+### Install from PyPI
+
+```bash
+conda create -n topoppi python=3.10
+conda activate topoppi
+pip install "topoppi[benchmark,interactions,meshio]"
+topoppi-install-optcuts
+which OptCuts_bin
+```
+
+For this release, `topoppi-install-optcuts` downloads from the matching GitHub release tag, for example `v1.1`. It currently supports Linux x86-64 release artifacts. On other platforms, build OptCuts manually and set `TOPOPPI_OPTCUTS_BIN=/absolute/path/to/OptCuts_bin`.
+
+### Install [OptCuts](https://github.com/liminchen/OptCuts) binary
+
+For PyPI installs, use the installed downloader:
+
+```bash
+topoppi-install-optcuts
+```
+
+From a source checkout, the repository also includes a helper script that installs `tools/OptCuts/OptCuts_bin` into your active Conda environment:
+
+```bash
+bash tools/OptCuts/install_optcuts.sh
+```
+
+After installation, verify:
+
+```bash
+which OptCuts_bin
+```
+
+> Required: the current pipeline does **not** support running without [OptCuts](https://github.com/liminchen/OptCuts). You can also set `TOPOPPI_OPTCUTS_BIN=/absolute/path/to/OptCuts_bin`.
+> PyPI source and wheel distributions intentionally do not include `tools/OptCuts`; `topoppi-install-optcuts` downloads the release-provided binary artifact instead.
+
+### Python dependencies
+
+See `environment.yml` and `pyproject.toml` for the authoritative lists.
+The full Conda environment includes ProLIF/MDAnalysis for automatic interaction generation.
+
+Main dependencies include:
+
+- `numpy`, `scipy`, `matplotlib`
+- `biopython`, `scikit-image`, `trimesh`, `igl` (**2.6.x**)
+- `networkx`, `rtree`, `shapely`, `pillow`
+- optional interaction extras: `MDAnalysis`, `prolif`, `rdkit`
+
+---
+
+## Usage
+
+### 1) GUI mode
+
+Launch the desktop app:
+
+```bash
+topoppi-gui
+```
+
+GUI supports:
+
+- Basic single-file analysis with structure loading, chain preview, A/B swapping, interaction filters, and color controls,
+- Advanced controls for chain IDs, cutoffs, surface parameters, OptCuts export, labels, layout, and output directories,
+- folder-level benchmark runs with explicit `resume`, `new`, and `overwrite` modes,
+- interaction-type filtering, custom colors, and style presets (`Exploration`, `Publication`, `High contrast`),
+- recent input/output path pickers,
+- inline validation before launching a run,
+- staged progress (`Load`, `Surface`, `Patch`, `OptCuts`, `Render`) and cooperative cancellation,
+- optional OptCuts frame export,
+- auto-saved figures and sidecar manifests for reproducibility.
+
+### 2) Command-line mode
+
+Run the full pipeline on a single PDB/mmCIF structure:
+
+```bash
+topoppi <input.pdb|input.cif> [options]
+```
+
+Example:
+
+```bash
+topoppi ./data/1abc.pdb -A A -B B -o interface_map.png --cutoff 9.0 --res 1.0 --sigma 1.5
+```
+
+### 3) Benchmark mode (via GUI workflow)
+
+Select **Benchmark**, choose a folder containing `.pdb` files, select a run mode, and run **Run Benchmark** in GUI.
+Benchmark preprocessing uses the configured surface/partner chain IDs for every file.
+Outputs are written under:
+
+- `benchmark_report.json`
+- `benchmark_summary.csv`
+- `benchmark_checkpoint.json` (resume support)
+
+### 4) Output artifacts (what gets written)
+
+#### Single-run CLI / GUI outputs
+
+- Main rendered interface image (default: `interface_map.png`, or your `-o/--output` value)
+- GUI single runs auto-save a figure to the selected save directory and write a `<figure>.topoppi.json` sidecar manifest
+- Auto-generated ProLIF JSON when `--prolif` is not provided (saved as `<input_basename>.<chain_a>-<chain_b>.prolif.json` beside the input file)
+
+#### Benchmark outputs
+
+- `benchmark_report.json`: full structured report with runtime worker count and config fingerprint
+- `benchmark_summary.csv`: tabular summary for all processed structures
+- `benchmark_checkpoint.json`: resume/checkpoint state
+
+---
+
+## Configuration
+
+### Command-line options (`topoppi`)
+
+- `pdb_file`: input structure file (`.pdb` or `.cif`)
+- `-A, --chain-a`: receptor/surface chain ID
+- `-B, --chain-b`: ligand chain ID
+- `--prolif` (`--arpeggio` alias): optional ProLIF JSON path
+- `--cutoff`: interface distance cutoff (Å)
+- `--res`: surface grid resolution (Å)
+- `--sigma`: Gaussian smoothing sigma
+- `-o, --output` (default `interface_map.png`): output image path
+- `--optcuts-bin` (default `OptCuts_bin`): OptCuts executable path/name
+- `--patch-gap`: minimum spacing between charts in global UV atlas
+- `--show`: display the Matplotlib figure after saving
+- `-v, --verbose`: verbose logging
+
+CLI defaults are read from `topoppi.config.DEFAULT_RUN_CONFIG`.
+
+### Benchmark configuration (`BenchmarkConfig`)
+
+`topoppi.config.BenchmarkConfig` defines reusable benchmark settings, including:
+
+- input/output roots,
+- chain IDs,
+- nested surface/topology/parameterization/OptCuts configuration,
+- parallelism (`max_workers`),
+- resume behavior (`resume`),
+- minimum patch validity thresholds.
+
+### ProLIF behavior
+
+If `--prolif` is not provided (or the GUI ProLIF field is left blank), TopoPPI tries to auto-generate `<input_basename>.<chain_a>-<chain_b>.prolif.json` using MDAnalysis + ProLIF. If generation is unavailable or fails, visualization falls back to geometric interaction heuristics.
+
+---
+
+## Examples
+
+### Test fixture: 1BVK
+
+The repository includes `tests/fixtures/1bvk.pdb` for smoke tests and reproducible examples.
+
+```bash
+topoppi tests/fixtures/1bvk.pdb -A A -B C -o 1bvk_interface.png
+```
+
+### CLI: basic run
+
+```bash
+topoppi ./data/complex.pdb -A A -B B -o complex_interface.png
+```
+
+### CLI: custom OptCuts binary and tighter patch gap
+
+```bash
+topoppi ./data/complex.pdb -A A -B C \
+  --optcuts-bin /usr/local/bin/OptCuts_bin \
+  --patch-gap 0.05 \
+  --output complex_interface_optcuts.png
+```
+
+### CLI: use existing ProLIF interactions
+
+```bash
+topoppi ./data/complex.pdb -A A -B B \
+  --prolif ./data/complex.prolif.json \
+  --output complex_with_prolif.png
+```
+
+### Python: run one interface map programmatically
+
+```python
+from topoppi.config import TopoPPIRunConfig
+from topoppi.pipeline import run_interface_mapping
+
+result = run_interface_mapping(
+    TopoPPIRunConfig(
+        pdb_file="./data/complex.pdb",
+        chain_a="A",
+        chain_b="B",
+        output_file="complex_interface.png",
+    )
+)
+print(result.to_dict())
+```
+
+### Python: run benchmark programmatically
+
+```python
+from dataclasses import replace
+
+from topoppi.config import BenchmarkConfig, DEFAULT_RUN_CONFIG
+from topoppi.benchmarking import BenchmarkRunner
+
+config = BenchmarkConfig(
+    input_folder="./dataset",
+    output_root="./benchmark_results",
+    chain_a="A",
+    chain_b="B",
+    surface=replace(DEFAULT_RUN_CONFIG.surface, grid_resolution=1.0, sigma=1.0),
+    topology=replace(DEFAULT_RUN_CONFIG.topology, distance_cutoff=9.0),
+    optcuts=replace(DEFAULT_RUN_CONFIG.optcuts, optcuts_bin="OptCuts_bin").for_headless(),
+    resume=True,
+)
+
+runner = BenchmarkRunner(config=config, log_fn=print)
+report = runner.run()
+print(report["summary"])
+```
+
+---
+
+## Project Structure
+
+```text
+TopoPPI/
+├─ pyproject.toml                 # Python package metadata and console scripts
+├─ environment.yml                # Conda environment definition
+├─ docs/                          # Release and reproducibility notes
+├─ tests/                         # Lightweight smoke/unit tests
+├─ tools/
+│  └─ OptCuts/
+│     ├─ OptCuts_bin              # Source-checkout convenience executable
+│     ├─ install_optcuts.sh       # Installer script for Conda env
+│     ├─ NOTICE.md                # Binary provenance and packaging policy
+│     └─ LICENSE.txt              # OptCuts license
+└─ src/
+	   └─ topoppi/
+	      ├─ cli.py                   # CLI entry point
+	      ├─ config.py                # Central runtime, benchmark, GUI, and OptCuts configuration
+	      ├─ install_optcuts.py       # Release artifact downloader for OptCuts
+	      ├─ pipeline.py              # Importable single-run API
+      ├─ io/                      # PDB/mmCIF loading and chain extraction
+      ├─ mesh/                    # Surface generation, topology, parameterization
+      ├─ optimization/            # OptCuts-based UV optimization
+      ├─ interactions/            # ProLIF integration and interaction normalization
+      ├─ visualization/           # 2D interface rendering
+      ├─ atlas/                   # Atlas metrics
+      ├─ gui_app/                 # GUI mixins and application orchestration
+      └─ benchmarking/            # Benchmark runner, metrics, reporting
+```
+
+---
+
+## Troubleshooting
+
+### `OptCuts_bin` not found
+
+Symptoms:
+- CLI/GUI fails when entering optimization stage
+- `which OptCuts_bin` returns empty
+
+Fix:
+
+```bash
+topoppi-install-optcuts
+which OptCuts_bin
+```
+
+From a source checkout, this also works:
+
+```bash
+bash tools/OptCuts/install_optcuts.sh
+which OptCuts_bin
+```
+
+If still missing, pass an explicit binary path:
+
+```bash
+topoppi <input.pdb|input.cif> -A <chainA> -B <chainB> --optcuts-bin /absolute/path/to/OptCuts_bin
+```
+
+### ProLIF/MDAnalysis import errors
+
+Symptoms:
+- Import errors for `prolif` or `MDAnalysis`
+
+Fix:
+- Recreate environment from `environment.yml`
+- Confirm packages are installed in the active env
+
+```bash
+conda env create -f environment.yml
+conda activate bio3d
+python -c "import MDAnalysis, prolif; print('ok')"
+```
+
+### `igl` / libigl compatibility issues
+
+Symptoms:
+- Import failures or runtime issues in geometry/parameterization stages
+
+Fix:
+- Use the project environment and keep `igl` in the documented `2.6.x` range.
+
+---
+
+## Changelog
+
+- **v1.1** adds improved GUI workflows, benchmark reporting, reproducibility manifests, PyPI packaging, and one-command Linux x86-64 OptCuts installation.
+- **v1.0.0** is the initial public release of TopoPPI.
+
+See [CHANGELOG.md](./CHANGELOG.md) for release history.
+
+---
+
+## License
+
+This project is distributed under the terms of the **MIT License**. See [LICENSE](./LICENSE).
+
+The source checkout includes a Linux x86-64 OptCuts binary for convenience. It is not included in the Python package distribution; see [`tools/OptCuts/NOTICE.md`](./tools/OptCuts/NOTICE.md) and [`tools/OptCuts/LICENSE.txt`](./tools/OptCuts/LICENSE.txt) before redistributing binary artifacts.