topoppi-affinity 3.0.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- topoppi_affinity-3.0.0/LICENSE +21 -0
- topoppi_affinity-3.0.0/MANIFEST.in +11 -0
- topoppi_affinity-3.0.0/PKG-INFO +137 -0
- topoppi_affinity-3.0.0/README.md +107 -0
- topoppi_affinity-3.0.0/docs/affinity_external_methods.md +44 -0
- topoppi_affinity-3.0.0/docs/api.md +72 -0
- topoppi_affinity-3.0.0/docs/evaluation.md +15 -0
- topoppi_affinity-3.0.0/docs/migration.md +29 -0
- topoppi_affinity-3.0.0/docs/models.md +60 -0
- topoppi_affinity-3.0.0/docs/workflow.md +87 -0
- topoppi_affinity-3.0.0/examples/README.md +32 -0
- topoppi_affinity-3.0.0/examples/tiny_complex.pdb +15 -0
- topoppi_affinity-3.0.0/examples/variants.csv +5 -0
- topoppi_affinity-3.0.0/pyproject.toml +58 -0
- topoppi_affinity-3.0.0/setup.cfg +4 -0
- topoppi_affinity-3.0.0/tests/conftest.py +19 -0
- topoppi_affinity-3.0.0/tests/fixtures/1bvk.pdb +6076 -0
- topoppi_affinity-3.0.0/tests/fixtures/tiny_complex.pdb +15 -0
- topoppi_affinity-3.0.0/tests/test_affinity_analytic_curvature.py +86 -0
- topoppi_affinity-3.0.0/tests/test_affinity_artifacts.py +37 -0
- topoppi_affinity-3.0.0/tests/test_affinity_attribution.py +82 -0
- topoppi_affinity-3.0.0/tests/test_affinity_author_references.py +57 -0
- topoppi_affinity-3.0.0/tests/test_affinity_ba_cycle.py +39 -0
- topoppi_affinity-3.0.0/tests/test_affinity_benchmark_data.py +127 -0
- topoppi_affinity-3.0.0/tests/test_affinity_benchmark_models.py +175 -0
- topoppi_affinity-3.0.0/tests/test_affinity_benchmark_reporting.py +183 -0
- topoppi_affinity-3.0.0/tests/test_affinity_bilinear_features.py +45 -0
- topoppi_affinity-3.0.0/tests/test_affinity_cached_author_references.py +98 -0
- topoppi_affinity-3.0.0/tests/test_affinity_comparison.py +43 -0
- topoppi_affinity-3.0.0/tests/test_affinity_data.py +82 -0
- topoppi_affinity-3.0.0/tests/test_affinity_embedding_baselines.py +112 -0
- topoppi_affinity-3.0.0/tests/test_affinity_epistasis.py +96 -0
- topoppi_affinity-3.0.0/tests/test_affinity_external_absolute.py +156 -0
- topoppi_affinity-3.0.0/tests/test_affinity_external_inputs.py +70 -0
- topoppi_affinity-3.0.0/tests/test_affinity_features.py +91 -0
- topoppi_affinity-3.0.0/tests/test_affinity_footprint_controls.py +20 -0
- topoppi_affinity-3.0.0/tests/test_affinity_frozen_structure.py +39 -0
- topoppi_affinity-3.0.0/tests/test_affinity_geometric_scattering.py +21 -0
- topoppi_affinity-3.0.0/tests/test_affinity_graph_dataset.py +87 -0
- topoppi_affinity-3.0.0/tests/test_affinity_graph_features.py +61 -0
- topoppi_affinity-3.0.0/tests/test_affinity_graph_models.py +160 -0
- topoppi_affinity-3.0.0/tests/test_affinity_group_dro.py +34 -0
- topoppi_affinity-3.0.0/tests/test_affinity_joint.py +94 -0
- topoppi_affinity-3.0.0/tests/test_affinity_legacy_antisymmetry.py +20 -0
- topoppi_affinity-3.0.0/tests/test_affinity_legacy_kernel.py +53 -0
- topoppi_affinity-3.0.0/tests/test_affinity_models.py +59 -0
- topoppi_affinity-3.0.0/tests/test_affinity_mutation_ensemble.py +57 -0
- topoppi_affinity-3.0.0/tests/test_affinity_next_protocols.py +131 -0
- topoppi_affinity-3.0.0/tests/test_affinity_paired_embeddings.py +32 -0
- topoppi_affinity-3.0.0/tests/test_affinity_residual_artifacts.py +62 -0
- topoppi_affinity-3.0.0/tests/test_affinity_residual_baselines.py +41 -0
- topoppi_affinity-3.0.0/tests/test_affinity_sequence_baselines.py +118 -0
- topoppi_affinity-3.0.0/tests/test_affinity_sequence_embeddings.py +104 -0
- topoppi_affinity-3.0.0/tests/test_affinity_state_kernel.py +28 -0
- topoppi_affinity-3.0.0/tests/test_affinity_structure_features.py +84 -0
- topoppi_affinity-3.0.0/tests/test_affinity_surface_diffusion.py +60 -0
- topoppi_affinity-3.0.0/tests/test_affinity_surface_transport.py +30 -0
- topoppi_affinity-3.0.0/tests/test_affinity_uv_layout.py +99 -0
- topoppi_affinity-3.0.0/tests/test_affinity_variant_augmentation.py +19 -0
- topoppi_affinity-3.0.0/tests/test_analysis_workflow.py +103 -0
- topoppi_affinity-3.0.0/tests/test_atlas_review.py +52 -0
- topoppi_affinity-3.0.0/tests/test_cancellation_semantics.py +161 -0
- topoppi_affinity-3.0.0/tests/test_downstream_journeys.py +179 -0
- topoppi_affinity-3.0.0/tests/test_explicit_fitting.py +69 -0
- topoppi_affinity-3.0.0/tests/test_gui_usability.py +1129 -0
- topoppi_affinity-3.0.0/tests/test_host_results.py +471 -0
- topoppi_affinity-3.0.0/tests/test_inference_representations.py +79 -0
- topoppi_affinity-3.0.0/tests/test_installer.py +454 -0
- topoppi_affinity-3.0.0/tests/test_integration.py +56 -0
- topoppi_affinity-3.0.0/tests/test_panel_keyboard.py +167 -0
- topoppi_affinity-3.0.0/tests/test_plugin_capability.py +75 -0
- topoppi_affinity-3.0.0/tests/test_production_models.py +96 -0
- topoppi_affinity-3.0.0/tests/test_public_model_metadata.py +57 -0
- topoppi_affinity-3.0.0/tests/test_resources.py +257 -0
- topoppi_affinity-3.0.0/tests/test_usability_workflow.py +256 -0
- topoppi_affinity-3.0.0/tools/README.md +10 -0
- topoppi_affinity-3.0.0/tools/__init__.py +6 -0
- topoppi_affinity-3.0.0/tools/features/__init__.py +1 -0
- topoppi_affinity-3.0.0/tools/features/extract_analytic_features.py +52 -0
- topoppi_affinity-3.0.0/tools/features/extract_features.py +113 -0
- topoppi_affinity-3.0.0/tools/features/extract_graph_features.py +78 -0
- topoppi_affinity-3.0.0/tools/features/extract_prospective_sasa.py +51 -0
- topoppi_affinity-3.0.0/tools/features/extract_sequence_embeddings.py +22 -0
- topoppi_affinity-3.0.0/tools/features/pool_manifest_embeddings.py +45 -0
- topoppi_affinity-3.0.0/tools/features/prepare_analytic_mutation_inputs.py +15 -0
- topoppi_affinity-3.0.0/tools/features/refine_graph_curvature.py +63 -0
- topoppi_affinity-3.0.0/tools/models/__init__.py +1 -0
- topoppi_affinity-3.0.0/tools/models/bundle_mutation_ensemble.py +17 -0
- topoppi_affinity-3.0.0/tools/models/fit_absolute_model.py +48 -0
- topoppi_affinity-3.0.0/tools/models/predict_absolute_model.py +27 -0
- topoppi_affinity-3.0.0/tools/models/predict_attribution.py +35 -0
- topoppi_affinity-3.0.0/tools/models/predict_frozen_affinity.py +17 -0
- topoppi_affinity-3.0.0/tools/models/predict_mutation_ensemble.py +26 -0
- topoppi_affinity-3.0.0/tools/models/predict_residual_affinity.py +23 -0
- topoppi_affinity-3.0.0/tools/models/refit_frozen_model.py +29 -0
- topoppi_affinity-3.0.0/tools/models/refit_residual_model.py +29 -0
- topoppi_affinity-3.0.0/topoppi_affinity/__init__.py +6 -0
- topoppi_affinity-3.0.0/topoppi_affinity/__main__.py +4 -0
- topoppi_affinity-3.0.0/topoppi_affinity/analytic_curvature.py +143 -0
- topoppi_affinity-3.0.0/topoppi_affinity/analytic_preprocessing.py +82 -0
- topoppi_affinity-3.0.0/topoppi_affinity/artifacts.py +66 -0
- topoppi_affinity-3.0.0/topoppi_affinity/atlas_review/__init__.py +1 -0
- topoppi_affinity-3.0.0/topoppi_affinity/atlas_review/comparison.py +209 -0
- topoppi_affinity-3.0.0/topoppi_affinity/atlas_review/context.py +117 -0
- topoppi_affinity-3.0.0/topoppi_affinity/atlas_review/gui.py +459 -0
- topoppi_affinity-3.0.0/topoppi_affinity/atlas_review/paired.py +173 -0
- topoppi_affinity-3.0.0/topoppi_affinity/atlas_review/session.py +111 -0
- topoppi_affinity-3.0.0/topoppi_affinity/attribution_features.py +220 -0
- topoppi_affinity-3.0.0/topoppi_affinity/author_references.py +207 -0
- topoppi_affinity-3.0.0/topoppi_affinity/ba_cycle_prior.py +224 -0
- topoppi_affinity-3.0.0/topoppi_affinity/benchmark_data.py +243 -0
- topoppi_affinity-3.0.0/topoppi_affinity/benchmark_features.py +271 -0
- topoppi_affinity-3.0.0/topoppi_affinity/benchmark_models.py +433 -0
- topoppi_affinity-3.0.0/topoppi_affinity/benchmark_reporting.py +382 -0
- topoppi_affinity-3.0.0/topoppi_affinity/bilinear_features.py +54 -0
- topoppi_affinity-3.0.0/topoppi_affinity/bilinear_kernel.py +15 -0
- topoppi_affinity-3.0.0/topoppi_affinity/bindpred_baseline.py +169 -0
- topoppi_affinity-3.0.0/topoppi_affinity/cached_author_references.py +388 -0
- topoppi_affinity-3.0.0/topoppi_affinity/capabilities.py +30 -0
- topoppi_affinity-3.0.0/topoppi_affinity/cath_protocol.py +82 -0
- topoppi_affinity-3.0.0/topoppi_affinity/cli.py +323 -0
- topoppi_affinity-3.0.0/topoppi_affinity/comparison.py +130 -0
- topoppi_affinity-3.0.0/topoppi_affinity/data/example/1bvk.pdb +6076 -0
- topoppi_affinity-3.0.0/topoppi_affinity/data/example/README.md +22 -0
- topoppi_affinity-3.0.0/topoppi_affinity/data/example/variants.csv +3 -0
- topoppi_affinity-3.0.0/topoppi_affinity/data/model_catalog.json +83 -0
- topoppi_affinity-3.0.0/topoppi_affinity/data/production/MODEL_CARD.md +40 -0
- topoppi_affinity-3.0.0/topoppi_affinity/data/production/absolute/model.json +515 -0
- topoppi_affinity-3.0.0/topoppi_affinity/data/production/absolute/weights.npz +0 -0
- topoppi_affinity-3.0.0/topoppi_affinity/data/production/mutation/model.json +470 -0
- topoppi_affinity-3.0.0/topoppi_affinity/data/production/mutation/weights.npz +0 -0
- topoppi_affinity-3.0.0/topoppi_affinity/data.py +102 -0
- topoppi_affinity-3.0.0/topoppi_affinity/embedding_baselines.py +189 -0
- topoppi_affinity-3.0.0/topoppi_affinity/epistasis.py +232 -0
- topoppi_affinity-3.0.0/topoppi_affinity/evaluation.py +56 -0
- topoppi_affinity-3.0.0/topoppi_affinity/expanded_references.py +259 -0
- topoppi_affinity-3.0.0/topoppi_affinity/external_absolute.py +419 -0
- topoppi_affinity-3.0.0/topoppi_affinity/external_energy.py +103 -0
- topoppi_affinity-3.0.0/topoppi_affinity/external_inputs.py +104 -0
- topoppi_affinity-3.0.0/topoppi_affinity/external_mutation.py +255 -0
- topoppi_affinity-3.0.0/topoppi_affinity/features.py +327 -0
- topoppi_affinity-3.0.0/topoppi_affinity/footprint_controls.py +17 -0
- topoppi_affinity-3.0.0/topoppi_affinity/frozen_probes.py +23 -0
- topoppi_affinity-3.0.0/topoppi_affinity/frozen_structure.py +199 -0
- topoppi_affinity-3.0.0/topoppi_affinity/geometric_scattering.py +79 -0
- topoppi_affinity-3.0.0/topoppi_affinity/graph_dataset.py +138 -0
- topoppi_affinity-3.0.0/topoppi_affinity/graph_features.py +304 -0
- topoppi_affinity-3.0.0/topoppi_affinity/graph_models.py +161 -0
- topoppi_affinity-3.0.0/topoppi_affinity/graph_training.py +71 -0
- topoppi_affinity-3.0.0/topoppi_affinity/group_dro_baselines.py +102 -0
- topoppi_affinity-3.0.0/topoppi_affinity/grouped_fitting.py +105 -0
- topoppi_affinity-3.0.0/topoppi_affinity/gui.py +1676 -0
- topoppi_affinity-3.0.0/topoppi_affinity/inference.py +273 -0
- topoppi_affinity-3.0.0/topoppi_affinity/installer.py +551 -0
- topoppi_affinity-3.0.0/topoppi_affinity/integration.py +408 -0
- topoppi_affinity-3.0.0/topoppi_affinity/joint_training.py +177 -0
- topoppi_affinity-3.0.0/topoppi_affinity/legacy_antisymmetry.py +30 -0
- topoppi_affinity-3.0.0/topoppi_affinity/legacy_kernel.py +84 -0
- topoppi_affinity-3.0.0/topoppi_affinity/mint_embeddings.py +39 -0
- topoppi_affinity-3.0.0/topoppi_affinity/model_metadata.py +91 -0
- topoppi_affinity-3.0.0/topoppi_affinity/models.py +108 -0
- topoppi_affinity-3.0.0/topoppi_affinity/multipoint.py +27 -0
- topoppi_affinity-3.0.0/topoppi_affinity/mutation_ensemble.py +113 -0
- topoppi_affinity-3.0.0/topoppi_affinity/mutation_physics.py +159 -0
- topoppi_affinity-3.0.0/topoppi_affinity/paired_embeddings.py +86 -0
- topoppi_affinity-3.0.0/topoppi_affinity/plugin.py +20 -0
- topoppi_affinity-3.0.0/topoppi_affinity/ppb_protocol.py +234 -0
- topoppi_affinity-3.0.0/topoppi_affinity/ppiformer_finetune.py +185 -0
- topoppi_affinity-3.0.0/topoppi_affinity/proaffinity_inputs.py +306 -0
- topoppi_affinity-3.0.0/topoppi_affinity/production.py +101 -0
- topoppi_affinity-3.0.0/topoppi_affinity/representation_controls.py +124 -0
- topoppi_affinity-3.0.0/topoppi_affinity/residual_artifacts.py +138 -0
- topoppi_affinity-3.0.0/topoppi_affinity/residual_baselines.py +139 -0
- topoppi_affinity-3.0.0/topoppi_affinity/resources.py +333 -0
- topoppi_affinity-3.0.0/topoppi_affinity/runtime.py +31 -0
- topoppi_affinity-3.0.0/topoppi_affinity/sequence_baselines.py +244 -0
- topoppi_affinity-3.0.0/topoppi_affinity/sequence_embeddings.py +232 -0
- topoppi_affinity-3.0.0/topoppi_affinity/splits.py +197 -0
- topoppi_affinity-3.0.0/topoppi_affinity/state_kernel.py +82 -0
- topoppi_affinity-3.0.0/topoppi_affinity/structure_features.py +79 -0
- topoppi_affinity-3.0.0/topoppi_affinity/surface_diffusion.py +180 -0
- topoppi_affinity-3.0.0/topoppi_affinity/surface_transport.py +84 -0
- topoppi_affinity-3.0.0/topoppi_affinity/thermodynamics.py +42 -0
- topoppi_affinity-3.0.0/topoppi_affinity/uv_layout_features.py +348 -0
- topoppi_affinity-3.0.0/topoppi_affinity/variant_augmentation.py +56 -0
- topoppi_affinity-3.0.0/topoppi_affinity/workflow.py +612 -0
- topoppi_affinity-3.0.0/topoppi_affinity.egg-info/PKG-INFO +137 -0
- topoppi_affinity-3.0.0/topoppi_affinity.egg-info/SOURCES.txt +190 -0
- topoppi_affinity-3.0.0/topoppi_affinity.egg-info/dependency_links.txt +1 -0
- topoppi_affinity-3.0.0/topoppi_affinity.egg-info/entry_points.txt +5 -0
- topoppi_affinity-3.0.0/topoppi_affinity.egg-info/requires.txt +21 -0
- topoppi_affinity-3.0.0/topoppi_affinity.egg-info/top_level.txt +2 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Shuyu Zhong
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
include README.md LICENSE
|
|
2
|
+
recursive-include docs *.md
|
|
3
|
+
recursive-include examples *.pdb *.csv *.json *.md
|
|
4
|
+
recursive-include tools *.py *.md
|
|
5
|
+
recursive-include tests *.py *.pdb
|
|
6
|
+
prune build
|
|
7
|
+
prune dist
|
|
8
|
+
global-exclude __pycache__ *.py[cod]
|
|
9
|
+
prune .internal
|
|
10
|
+
|
|
11
|
+
recursive-include topoppi_affinity/data/production *.json *.npz *.md
|
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: topoppi-affinity
|
|
3
|
+
Version: 3.0.0
|
|
4
|
+
Summary: Affinity modelling using interface descriptors produced by the TopoPPI workflow
|
|
5
|
+
License-Expression: MIT
|
|
6
|
+
Project-URL: Documentation, https://github.com/GeraltZeroZhong/TopoPPI/blob/HEAD/plugins/affinity/README.md
|
|
7
|
+
Project-URL: Repository, https://github.com/GeraltZeroZhong/TopoPPI
|
|
8
|
+
Project-URL: Issues, https://github.com/GeraltZeroZhong/TopoPPI/issues
|
|
9
|
+
Requires-Python: <3.11,>=3.10
|
|
10
|
+
Description-Content-Type: text/markdown
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Requires-Dist: topoppi[representation]<3.1,>=3.0.0
|
|
13
|
+
Requires-Dist: scikit-learn<1.8,>=1.6
|
|
14
|
+
Requires-Dist: pandas>=2.0
|
|
15
|
+
Requires-Dist: joblib<1.6,>=1.5
|
|
16
|
+
Requires-Dist: openpyxl>=3.1
|
|
17
|
+
Provides-Extra: models
|
|
18
|
+
Requires-Dist: torch>=2.2; extra == "models"
|
|
19
|
+
Requires-Dist: torch-geometric>=2.5; extra == "models"
|
|
20
|
+
Requires-Dist: esm==3.2.1.post1; extra == "models"
|
|
21
|
+
Requires-Dist: transformers<4.48.2,>=4.38; extra == "models"
|
|
22
|
+
Requires-Dist: numpy<2,>=1.26; (sys_platform == "darwin" and platform_machine == "x86_64") and extra == "models"
|
|
23
|
+
Provides-Extra: dev
|
|
24
|
+
Requires-Dist: pytest>=8; extra == "dev"
|
|
25
|
+
Requires-Dist: build>=1; extra == "dev"
|
|
26
|
+
Requires-Dist: ruff>=0.4; extra == "dev"
|
|
27
|
+
Requires-Dist: POT>=0.9; extra == "dev"
|
|
28
|
+
Requires-Dist: catboost>=1.2; extra == "dev"
|
|
29
|
+
Dynamic: license-file
|
|
30
|
+
|
|
31
|
+
# TopoPPI Affinity
|
|
32
|
+
|
|
33
|
+
TopoPPI Affinity adds affinity modelling and linked interface review to [TopoPPI](https://github.com/GeraltZeroZhong/TopoPPI/blob/HEAD/README.md). It extracts native interface descriptors and includes CPU models for binding affinity (pKd) and mutation effects (ΔΔG). Users can fit regression models to supplied data or load custom models, then review saved predictions alongside the corresponding residues and contacts.
|
|
34
|
+
|
|
35
|
+
## Installation
|
|
36
|
+
|
|
37
|
+
Install TopoPPI Affinity from PyPI with Python 3.10.
|
|
38
|
+
|
|
39
|
+
```sh
|
|
40
|
+
python -m pip install topoppi-affinity
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
For development, install Core, the plugin and its test dependencies from the repository root.
|
|
44
|
+
|
|
45
|
+
```sh
|
|
46
|
+
python -m pip install -e . -e './plugins/affinity[dev]'
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
The optional `models` extra supplies neural representation dependencies. Install it when using a model that requires them. Tk is required for the optional GUI. OptCuts is required for atlas generation. Native geometry and prediction run independently of atlas generation.
|
|
50
|
+
|
|
51
|
+
## Platform capability
|
|
52
|
+
|
|
53
|
+
Installation registers `affinity.predict`, `topoppi affinity ...`, and the
|
|
54
|
+
optional GUI integration through `topoppi.plugins`. Model dependencies load when
|
|
55
|
+
needed for prediction. New analyses can share a Core geometry object:
|
|
56
|
+
|
|
57
|
+
```python
|
|
58
|
+
import topoppi
|
|
59
|
+
|
|
60
|
+
geometry = topoppi.compute_geometry(
|
|
61
|
+
topoppi.get_interface(topoppi.load_structure("complex.pdb"), "A", "B")
|
|
62
|
+
)
|
|
63
|
+
result = topoppi.run("affinity.predict", geometry, task="absolute", output="results")
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
The capability reuses selected atoms and native surfaces without reopening the
|
|
67
|
+
input. `workflow.analyze` and the standalone CLI also accept structure paths.
|
|
68
|
+
Namespaced defaults use `ExecutionContext.plugin_config["affinity"]`; explicit
|
|
69
|
+
arguments take precedence.
|
|
70
|
+
|
|
71
|
+
The Core GUI lists **Binding affinity** and **Mutation effects** in the shared
|
|
72
|
+
**Binding analysis** navigation, alongside Hotspot ranking when that plugin is
|
|
73
|
+
installed. The prediction panel has two scientific tasks: whole-complex pKd and
|
|
74
|
+
mutation ΔΔG. Keep **Prepared task model** to use the bundled physical model.
|
|
75
|
+
Advanced known/unseen ensembles retain their separately documented training
|
|
76
|
+
scope; **Local model file** selects a compatible custom estimator.
|
|
77
|
+
|
|
78
|
+
Selecting a local model reads its target and declared scope. A later task or
|
|
79
|
+
scope mismatch is reported before computation. Variant drafts remain available
|
|
80
|
+
when switching tasks; absolute-affinity prediction uses the unmodified complex.
|
|
81
|
+
Selected interface residues can be sent to the mutation editor as separate
|
|
82
|
+
single-substitution variants or one variant containing multiple substitutions.
|
|
83
|
+
Adding variants appends rows, retains existing edits and resolves duplicate row
|
|
84
|
+
identifiers. An existing
|
|
85
|
+
draft for another structure or partner grouping must be switched explicitly.
|
|
86
|
+
|
|
87
|
+
Task UI and resource setup live in `topoppi_affinity.integration` and
|
|
88
|
+
`topoppi_affinity.installer`. The old `topoppi-install-affinity` command is a
|
|
89
|
+
deprecated forwarding adapter and requires the plugin to be installed first.
|
|
90
|
+
|
|
91
|
+
## Synthetic quick start
|
|
92
|
+
|
|
93
|
+
This example converts a dissociation constant to pKd and back:
|
|
94
|
+
|
|
95
|
+
```python
|
|
96
|
+
from topoppi_affinity.thermodynamics import kd_to_pkd, pkd_to_kd
|
|
97
|
+
|
|
98
|
+
assert float(kd_to_pkd(1e-8)) == 8.0
|
|
99
|
+
assert float(pkd_to_kd(8.0)) == 1e-8
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
The `examples/tiny_complex.pdb` fixture contains independently constructed toy coordinates. Its variant CSV exercises alternative substitutions, a variant containing multiple substitutions and an absent residue. Use it to check input handling and row-error reporting.
|
|
103
|
+
|
|
104
|
+
## Structure example and prediction
|
|
105
|
+
|
|
106
|
+
The installed example contains the documented [PDB 1BVK structure](https://www.rcsb.org/structure/1BVK) and example variants. It illustrates the antibody–lysozyme interface. Export it with:
|
|
107
|
+
|
|
108
|
+
```sh
|
|
109
|
+
topoppi-affinity example --output affinity-demo
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
Analyze it with the bundled affinity model:
|
|
113
|
+
|
|
114
|
+
```sh
|
|
115
|
+
topoppi-affinity analyze --structure affinity-demo/1bvk.pdb \
|
|
116
|
+
--chains-a A,B --chains-b C --task absolute \
|
|
117
|
+
--output affinity-demo/results
|
|
118
|
+
topoppi-affinity inspect affinity-demo/results
|
|
119
|
+
topoppi-affinity gui affinity-demo/results
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
The plugin contains one default model per task, including fitted preprocessing
|
|
123
|
+
and feature definitions. For mutation effects, use `--task mutation` and provide
|
|
124
|
+
`--mutations` or `--variants`. Default prediction runs on CPU without model
|
|
125
|
+
downloads. See [models](https://github.com/GeraltZeroZhong/TopoPPI/blob/HEAD/plugins/affinity/docs/models.md) and the [workflow](https://github.com/GeraltZeroZhong/TopoPPI/blob/HEAD/plugins/affinity/docs/workflow.md).
|
|
126
|
+
|
|
127
|
+
## Inputs and outputs
|
|
128
|
+
|
|
129
|
+
Supply PDB or mmCIF structures and complete partner chain groups. Mutation input uses `variant_id,mutations` CSV records or structured residue fields. Affinity targets are pKd or mutation ΔΔG in kcal/mol; positive ΔΔG means weaker binding. Temperature is in kelvin and the dissociation constant Kd is in molar units.
|
|
130
|
+
|
|
131
|
+
Saved analyses contain a JSON report, prediction tables, the native interface and any requested layout results. Prediction rows retain their identifiers, status and error messages. The report records model scope and separate prediction/layout status. Models determine their feature requirements and applicability; review their training metadata before interpreting predictions.
|
|
132
|
+
|
|
133
|
+
Run `topoppi-affinity --help` for CLI commands. See the [workflow guide](https://github.com/GeraltZeroZhong/TopoPPI/blob/HEAD/plugins/affinity/docs/workflow.md), [model interfaces](https://github.com/GeraltZeroZhong/TopoPPI/blob/HEAD/plugins/affinity/docs/models.md), [evaluation primitives](https://github.com/GeraltZeroZhong/TopoPPI/blob/HEAD/plugins/affinity/docs/evaluation.md), [feature tools](https://github.com/GeraltZeroZhong/TopoPPI/blob/HEAD/plugins/affinity/tools/README.md) and [test instructions](https://github.com/GeraltZeroZhong/TopoPPI/blob/HEAD/plugins/affinity/tests/README.md).
|
|
134
|
+
|
|
135
|
+
## Contributing
|
|
136
|
+
|
|
137
|
+
Use independently constructed fixtures for unit tests, preserve target units and row identities, and add coverage for changed public behavior. Run the affinity test suite together with affected core tests. Public interfaces are listed in the [API guide](https://github.com/GeraltZeroZhong/TopoPPI/blob/HEAD/plugins/affinity/docs/api.md).
|
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
# TopoPPI Affinity
|
|
2
|
+
|
|
3
|
+
TopoPPI Affinity adds affinity modelling and linked interface review to [TopoPPI](https://github.com/GeraltZeroZhong/TopoPPI/blob/HEAD/README.md). It extracts native interface descriptors and includes CPU models for binding affinity (pKd) and mutation effects (ΔΔG). Users can fit regression models to supplied data or load custom models, then review saved predictions alongside the corresponding residues and contacts.
|
|
4
|
+
|
|
5
|
+
## Installation
|
|
6
|
+
|
|
7
|
+
Install TopoPPI Affinity from PyPI with Python 3.10.
|
|
8
|
+
|
|
9
|
+
```sh
|
|
10
|
+
python -m pip install topoppi-affinity
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
For development, install Core, the plugin and its test dependencies from the repository root.
|
|
14
|
+
|
|
15
|
+
```sh
|
|
16
|
+
python -m pip install -e . -e './plugins/affinity[dev]'
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
The optional `models` extra supplies neural representation dependencies. Install it when using a model that requires them. Tk is required for the optional GUI. OptCuts is required for atlas generation. Native geometry and prediction run independently of atlas generation.
|
|
20
|
+
|
|
21
|
+
## Platform capability
|
|
22
|
+
|
|
23
|
+
Installation registers `affinity.predict`, `topoppi affinity ...`, and the
|
|
24
|
+
optional GUI integration through `topoppi.plugins`. Model dependencies load when
|
|
25
|
+
needed for prediction. New analyses can share a Core geometry object:
|
|
26
|
+
|
|
27
|
+
```python
|
|
28
|
+
import topoppi
|
|
29
|
+
|
|
30
|
+
geometry = topoppi.compute_geometry(
|
|
31
|
+
topoppi.get_interface(topoppi.load_structure("complex.pdb"), "A", "B")
|
|
32
|
+
)
|
|
33
|
+
result = topoppi.run("affinity.predict", geometry, task="absolute", output="results")
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
The capability reuses selected atoms and native surfaces without reopening the
|
|
37
|
+
input. `workflow.analyze` and the standalone CLI also accept structure paths.
|
|
38
|
+
Namespaced defaults use `ExecutionContext.plugin_config["affinity"]`; explicit
|
|
39
|
+
arguments take precedence.
|
|
40
|
+
|
|
41
|
+
The Core GUI lists **Binding affinity** and **Mutation effects** in the shared
|
|
42
|
+
**Binding analysis** navigation, alongside Hotspot ranking when that plugin is
|
|
43
|
+
installed. The prediction panel has two scientific tasks: whole-complex pKd and
|
|
44
|
+
mutation ΔΔG. Keep **Prepared task model** to use the bundled physical model.
|
|
45
|
+
Advanced known/unseen ensembles retain their separately documented training
|
|
46
|
+
scope; **Local model file** selects a compatible custom estimator.
|
|
47
|
+
|
|
48
|
+
Selecting a local model reads its target and declared scope. A later task or
|
|
49
|
+
scope mismatch is reported before computation. Variant drafts remain available
|
|
50
|
+
when switching tasks; absolute-affinity prediction uses the unmodified complex.
|
|
51
|
+
Selected interface residues can be sent to the mutation editor as separate
|
|
52
|
+
single-substitution variants or one variant containing multiple substitutions.
|
|
53
|
+
Adding variants appends rows, retains existing edits and resolves duplicate row
|
|
54
|
+
identifiers. An existing
|
|
55
|
+
draft for another structure or partner grouping must be switched explicitly.
|
|
56
|
+
|
|
57
|
+
Task UI and resource setup live in `topoppi_affinity.integration` and
|
|
58
|
+
`topoppi_affinity.installer`. The old `topoppi-install-affinity` command is a
|
|
59
|
+
deprecated forwarding adapter and requires the plugin to be installed first.
|
|
60
|
+
|
|
61
|
+
## Synthetic quick start
|
|
62
|
+
|
|
63
|
+
This example converts a dissociation constant to pKd and back:
|
|
64
|
+
|
|
65
|
+
```python
|
|
66
|
+
from topoppi_affinity.thermodynamics import kd_to_pkd, pkd_to_kd
|
|
67
|
+
|
|
68
|
+
assert float(kd_to_pkd(1e-8)) == 8.0
|
|
69
|
+
assert float(pkd_to_kd(8.0)) == 1e-8
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
The `examples/tiny_complex.pdb` fixture contains independently constructed toy coordinates. Its variant CSV exercises alternative substitutions, a variant containing multiple substitutions and an absent residue. Use it to check input handling and row-error reporting.
|
|
73
|
+
|
|
74
|
+
## Structure example and prediction
|
|
75
|
+
|
|
76
|
+
The installed example contains the documented [PDB 1BVK structure](https://www.rcsb.org/structure/1BVK) and example variants. It illustrates the antibody–lysozyme interface. Export it with:
|
|
77
|
+
|
|
78
|
+
```sh
|
|
79
|
+
topoppi-affinity example --output affinity-demo
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
Analyze it with the bundled affinity model:
|
|
83
|
+
|
|
84
|
+
```sh
|
|
85
|
+
topoppi-affinity analyze --structure affinity-demo/1bvk.pdb \
|
|
86
|
+
--chains-a A,B --chains-b C --task absolute \
|
|
87
|
+
--output affinity-demo/results
|
|
88
|
+
topoppi-affinity inspect affinity-demo/results
|
|
89
|
+
topoppi-affinity gui affinity-demo/results
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
The plugin contains one default model per task, including fitted preprocessing
|
|
93
|
+
and feature definitions. For mutation effects, use `--task mutation` and provide
|
|
94
|
+
`--mutations` or `--variants`. Default prediction runs on CPU without model
|
|
95
|
+
downloads. See [models](https://github.com/GeraltZeroZhong/TopoPPI/blob/HEAD/plugins/affinity/docs/models.md) and the [workflow](https://github.com/GeraltZeroZhong/TopoPPI/blob/HEAD/plugins/affinity/docs/workflow.md).
|
|
96
|
+
|
|
97
|
+
## Inputs and outputs
|
|
98
|
+
|
|
99
|
+
Supply PDB or mmCIF structures and complete partner chain groups. Mutation input uses `variant_id,mutations` CSV records or structured residue fields. Affinity targets are pKd or mutation ΔΔG in kcal/mol; positive ΔΔG means weaker binding. Temperature is in kelvin and the dissociation constant Kd is in molar units.
|
|
100
|
+
|
|
101
|
+
Saved analyses contain a JSON report, prediction tables, the native interface and any requested layout results. Prediction rows retain their identifiers, status and error messages. The report records model scope and separate prediction/layout status. Models determine their feature requirements and applicability; review their training metadata before interpreting predictions.
|
|
102
|
+
|
|
103
|
+
Run `topoppi-affinity --help` for CLI commands. See the [workflow guide](https://github.com/GeraltZeroZhong/TopoPPI/blob/HEAD/plugins/affinity/docs/workflow.md), [model interfaces](https://github.com/GeraltZeroZhong/TopoPPI/blob/HEAD/plugins/affinity/docs/models.md), [evaluation primitives](https://github.com/GeraltZeroZhong/TopoPPI/blob/HEAD/plugins/affinity/docs/evaluation.md), [feature tools](https://github.com/GeraltZeroZhong/TopoPPI/blob/HEAD/plugins/affinity/tools/README.md) and [test instructions](https://github.com/GeraltZeroZhong/TopoPPI/blob/HEAD/plugins/affinity/tests/README.md).
|
|
104
|
+
|
|
105
|
+
## Contributing
|
|
106
|
+
|
|
107
|
+
Use independently constructed fixtures for unit tests, preserve target units and row identities, and add coverage for changed public behavior. Run the affinity test suite together with affected core tests. Public interfaces are listed in the [API guide](https://github.com/GeraltZeroZhong/TopoPPI/blob/HEAD/plugins/affinity/docs/api.md).
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
# External prediction adapters
|
|
2
|
+
|
|
3
|
+
The optional adapters run upstream methods using explicit input manifests, source repositories and model resources. Each upstream package retains its installation requirements, model license and input conventions. Run adapters in a compatible environment and keep the source revision and checkpoint identity with the output.
|
|
4
|
+
|
|
5
|
+
## Absolute affinity
|
|
6
|
+
|
|
7
|
+
| Module and interface | Method | Required inputs |
|
|
8
|
+
| --- | --- | --- |
|
|
9
|
+
| `external_absolute.run_prodigy` | PRODIGY | Structure manifest, output directory and upstream resource directory |
|
|
10
|
+
| `external_absolute.run_mirage` | MIRAGE | Structure manifest, upstream source/model directory and sequence-embedding resources |
|
|
11
|
+
| `author_references.run_bindpred_features` | BindPred | Input manifest, named embedding features and fitted checkpoint |
|
|
12
|
+
| `author_references.run_proaffinity_graphs` | ProAffinity-GNN | Structure manifest, prepared graphs and their partner index, upstream repository and checkpoint |
|
|
13
|
+
|
|
14
|
+
The structure manifest identifies `sample_id`, `pdb_id`, `structure_path`, `chains_a` and `chains_b`. Supply complete partner chain groups. Energy-based outputs are converted to pKd using the method's stated sign convention and gas constant. `external_absolute.native_dg_to_pkd` exposes this conversion directly.
|
|
15
|
+
|
|
16
|
+
PRODIGY and MIRAGE process all supplied rows by default (`subset="all"`).
|
|
17
|
+
To select a held-out partition, set `subset="heldout"` and provide
|
|
18
|
+
`split_complex` and `split_sequence` columns. This selects rows marked `test`
|
|
19
|
+
in either column.
|
|
20
|
+
|
|
21
|
+
For ProAffinity-GNN, pass `graph_root` and `partner_index` for your prepared graphs.
|
|
22
|
+
The index records the two partner chain groups for each graph; they must match
|
|
23
|
+
the manifest. Each tab-separated line contains the graph key and two
|
|
24
|
+
semicolon-separated partner groups, with commas separating chains within a group.
|
|
25
|
+
|
|
26
|
+
## Mutation effects
|
|
27
|
+
|
|
28
|
+
| Module and interface | Method | Required inputs |
|
|
29
|
+
| --- | --- | --- |
|
|
30
|
+
| `external_mutation.run_rde` | RDE-Net | Mutation input table and upstream repository/checkpoints |
|
|
31
|
+
| `external_mutation.run_stabddg` | StaB-ddG | Mutation input table, upstream repository and chosen checkpoint |
|
|
32
|
+
| `expanded_references.run_mutation_reference` | PPIformer, Pythia-PPI, SAAMBE-3D | Mutation manifest, repository and method identifier |
|
|
33
|
+
| `cached_author_references.run_cached_reference` | DDAffinity, GearBind | Mutation manifest, compatible author cache, repository and checkpoint |
|
|
34
|
+
| `external_energy.run_evoef` | EvoEF1 | Mutation manifest and the upstream executable |
|
|
35
|
+
|
|
36
|
+
Mutation adapters preserve complete partner groups, wild-type residue identities and chain-renumbering maps. Outputs use ΔΔG in kcal/mol with positive values indicating weaker mutant binding. Supported substitution scope and missing structural inputs are recorded per row. A checkpoint's training provenance remains relevant when interpreting its predictions.
|
|
37
|
+
|
|
38
|
+
## Input and output records
|
|
39
|
+
|
|
40
|
+
Prediction tables expose sample identity, prediction, target, method and execution status. Mutation tables use the common fields `sample_id,predicted,target,method,status,error`; additional columns retain method-specific information. The output metadata records the selected software and model resources.
|
|
41
|
+
|
|
42
|
+
Pass explicit input tables to run the intended samples. The RDE and StaB-ddG adapters accept `records_frame` for in-memory records. Select checkpoints according to their documented applicability, and use matched successful sample IDs when comparing predictions from different methods.
|
|
43
|
+
|
|
44
|
+
For normal TopoPPI prediction, see the [workflow guide](workflow.md). For metric definitions and grouped fitting, see [evaluation](evaluation.md).
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
# Affinity Python API
|
|
2
|
+
|
|
3
|
+
TopoPPI Affinity provides structure analysis, prediction from named features, model fitting and review of predictions alongside interface residues and contacts. Structural identifiers retain author chain IDs, residue numbers and insertion codes.
|
|
4
|
+
|
|
5
|
+
## Predict from a structure
|
|
6
|
+
|
|
7
|
+
The bundled CPU models predict binding affinity and mutation effects. Choose the task and provide the structure and partner chain groups:
|
|
8
|
+
|
|
9
|
+
```python
|
|
10
|
+
from topoppi_affinity.workflow import analyze, load_analysis
|
|
11
|
+
|
|
12
|
+
report = analyze(
|
|
13
|
+
"complex.pdb", "A", "B",
|
|
14
|
+
task="absolute", output="affinity_result", device="cpu",
|
|
15
|
+
)
|
|
16
|
+
affinity = load_analysis("affinity_result").predictions
|
|
17
|
+
print(affinity)
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
For a substitution, supply the wild-type complex. Prediction uses its fixed coordinates:
|
|
21
|
+
|
|
22
|
+
```python
|
|
23
|
+
report = analyze(
|
|
24
|
+
"complex.pdb", "A", "B",
|
|
25
|
+
task="mutation", mutations=["A:G42V"],
|
|
26
|
+
output="mutation_result", device="cpu",
|
|
27
|
+
)
|
|
28
|
+
mutation_effects = load_analysis("mutation_result").predictions
|
|
29
|
+
print(mutation_effects)
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
Replace `A:G42V` with a substitution matching your structure's chain ID, author residue number, insertion code if present and wild-type amino acid. Each list entry describes one variant; comma-separated substitutions in one entry form a variant with multiple substitutions. Results include prediction units and row-specific status. The returned report records the saved files and overall prediction status. Supply `model=` to use a custom model.
|
|
33
|
+
|
|
34
|
+
## Reuse Core geometry
|
|
35
|
+
|
|
36
|
+
Pass a prepared Core `GeometryRepresentation` to the registered capability:
|
|
37
|
+
|
|
38
|
+
```python
|
|
39
|
+
import topoppi
|
|
40
|
+
|
|
41
|
+
structure = topoppi.load_structure("complex.pdb")
|
|
42
|
+
interface = topoppi.get_interface(structure, "A,B", "C")
|
|
43
|
+
geometry = topoppi.compute_geometry(interface)
|
|
44
|
+
result = topoppi.run(
|
|
45
|
+
"affinity.predict", geometry,
|
|
46
|
+
task="absolute", output="shared_geometry_result",
|
|
47
|
+
)
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
The capability reuses the selected atoms and compatible geometry. Use `task="mutation"` with `mutations=["A:G42V"]` for mutation effects, or supply `model="fitted_model.joblib"` for a custom model. The model determines its required features. See the [workflow guide](workflow.md) for saved results and linked review.
|
|
51
|
+
|
|
52
|
+
## Scientific interfaces
|
|
53
|
+
|
|
54
|
+
| Module | Interface | Purpose |
|
|
55
|
+
| --- | --- | --- |
|
|
56
|
+
| `features` | `extract_complex_features`, `mutation_features` | Conventional interface descriptors and mutation features |
|
|
57
|
+
| `data` | `parse_mutations`, `canonical_mutations`, `read_structure` | Mutation notation and structural identities |
|
|
58
|
+
| `thermodynamics` | `kd_to_pkd`, `pkd_to_kd`, `ddg_from_kd` | Affinity units and temperature-dependent conversion |
|
|
59
|
+
| `inference` | `model_info`, `predict_features` | Inspect a loaded model bundle or predict from named feature files |
|
|
60
|
+
| `artifacts` | `fit_frozen`, `predict_frozen` | Fit and use a fixed-configuration named-feature regressor |
|
|
61
|
+
| `legacy_kernel` | `fit_legacy_bundle`, `predict_legacy_kernel` | Two-block kernel fitting and prediction |
|
|
62
|
+
| `residual_artifacts` | `fit_residual_model`, `predict_residual` | Fit or apply a scalar-prior residual model |
|
|
63
|
+
| `grouped_fitting` | `fit_nested` | Select model parameters within supplied training groups |
|
|
64
|
+
| `evaluation` | `regression_metrics` | Row-weighted and equal-complex regression summaries |
|
|
65
|
+
|
|
66
|
+
Absolute-affinity predictions use pKd = −log10(Kd/M). Mutation effects use ΔΔG in kcal/mol, with positive values indicating weaker mutant binding. Conversion from pKd to binding free energy uses the supplied temperature, which defaults to 298.15 K.
|
|
67
|
+
|
|
68
|
+
## Feature and model contracts
|
|
69
|
+
|
|
70
|
+
Named feature NPZ files contain `sample_ids`, `X` and `feature_names`. Fitting aligns rows by sample ID and stores the ordered feature schema with the fitted model. The two-block kernel additionally requires descriptor `feature_groups`. Prediction checks the feature order against that stored schema.
|
|
71
|
+
|
|
72
|
+
Fitting functions take explicit observations and feature inputs. Models retain their fitted preprocessing, units and training metadata. Use model files from a trusted source because joblib deserialization reconstructs Python objects. See [model interfaces](models.md), [evaluation](evaluation.md) and [migration notes](migration.md).
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
# Evaluation primitives
|
|
2
|
+
|
|
3
|
+
The plugin provides grouped regression metrics, deterministic partitioning, feature ablations and reusable fitting APIs. Supply observations, groups and model parameters explicitly. Fit preprocessing within each training partition. Compare predictors on matching successful rows and retain prediction coverage alongside the scores.
|
|
4
|
+
|
|
5
|
+
Absolute affinity uses pKd, the negative base-10 logarithm of molar Kd. Mutation effects use the change in binding free energy, ΔΔG, in kcal/mol, with positive values denoting weaker binding. Complex-level summaries give each complex equal weight; row-level summaries describe all observations.
|
|
6
|
+
|
|
7
|
+
## Grouped fitting and prediction
|
|
8
|
+
|
|
9
|
+
`topoppi_affinity.grouped_fitting.fit_nested` selects parameters using grouped inner folds. `learning_subset` constructs nested subsets of whole families. `evaluation.regression_metrics` computes regression summaries; `splits` and `benchmark_data` provide grouping and partitioning utilities for supplied tables.
|
|
10
|
+
|
|
11
|
+
`artifacts.fit_frozen` fits an explicit configuration to a training table and a feature NPZ. The table contains `sample_id`, `complex_id`, `family_group` and the selected target. Feature files contain `sample_ids`, `X` and `feature_names`. Rows are matched by sample ID, and the model stores its fitted preprocessing and ordered feature names.
|
|
12
|
+
|
|
13
|
+
`residual_artifacts.fit_residual_model` additionally accepts a prior prediction table containing `sample_id,predicted,target,method,status,error`. It selects radial basis function (RBF) kernel parameters within two training folds grouped by mutation or family. The saved model applies the same feature definition and prior method during inference.
|
|
14
|
+
|
|
15
|
+
Use held-out predictions to assess predictive performance. A model refitted for application carries its training metadata separately from the evaluation results. The synthetic test suite checks numerical invariants, training-only preprocessing, row alignment and serialization.
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# Migration to TopoPPI 3.0
|
|
2
|
+
|
|
3
|
+
Affinity is an optional distribution named `topoppi-affinity`. Install it alongside TopoPPI 3.0 to use prediction and linked result review. Scientific tasks are available through the shared **Binding analysis** navigation.
|
|
4
|
+
|
|
5
|
+
## Shared geometry and saved results
|
|
6
|
+
|
|
7
|
+
`topoppi.run("affinity.predict", geometry, ...)` accepts an existing Core `GeometryRepresentation`. Path-based callers can continue to use `topoppi_affinity.workflow.analyze`. Core continues to read saved atlas geometry and its annotations independently of the prediction plugin.
|
|
8
|
+
|
|
9
|
+
Fitted estimator classes, feature names, units and serialized fields retain their numerical contracts. Existing model keys such as `legacy_feature_names` continue to identify their stored feature block.
|
|
10
|
+
|
|
11
|
+
## Installation and launch commands
|
|
12
|
+
|
|
13
|
+
`topoppi_affinity.installer` manages Affinity resources. The `topoppi-install-affinity` command forwards to the installed plugin; explicit imports of `topoppi.install_affinity` emit a deprecation warning. The old `topoppi-gui --affinity` and `--affinity-setup` options remain deprecated aliases of plugin launch options.
|
|
14
|
+
|
|
15
|
+
## Explicit fitting inputs
|
|
16
|
+
|
|
17
|
+
The feature and model tools accept the files required by each operation:
|
|
18
|
+
|
|
19
|
+
- `fit_absolute_model`: `--training-table`, `--sequence-features`, `--descriptor-features` and `--output`.
|
|
20
|
+
- `refit_frozen_model`: `--training-table`, `--features`, `--output` and the model configuration. `--antisymmetric` makes predictions change sign when the signs of the mutation features are reversed.
|
|
21
|
+
- `refit_residual_model`: `--training-table`, `--features`, `--prior`, `--output` and the grouping task.
|
|
22
|
+
- `pool_manifest_embeddings`: `--graphs`, `--sequences`, `--manifest`, `--output` and `--target`.
|
|
23
|
+
- `extract_analytic_features`: `--manifest`, `--graphs`, `--features`, `--output` and `--target`.
|
|
24
|
+
|
|
25
|
+
The former `--root`, `--development-only` and `--auxiliary-features` options for these tools are replaced by explicit input files. Concatenate intended training pools before fitting, retain unique sample IDs, and construct evaluation splits independently of the refit.
|
|
26
|
+
|
|
27
|
+
## Preparation metadata
|
|
28
|
+
|
|
29
|
+
`cath_protocol.prepare_cath_protocol` reports target differences as `target_mean_absolute_difference_from_reported_temperature`. The temperature-derived values remain in `ddg_at_reported_temperature`.
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
# Model interfaces
|
|
2
|
+
|
|
3
|
+
TopoPPI Affinity 3.0 includes two official CPU inference models: whole-complex
|
|
4
|
+
binding affinity (pKd) and mutation effects (ΔΔG in kcal/mol). The models,
|
|
5
|
+
fitted preprocessing and ordered feature definitions are installed with the
|
|
6
|
+
plugin. Each task uses one final fitted estimator. Model details are in the
|
|
7
|
+
[default model card](../topoppi_affinity/data/production/MODEL_CARD.md).
|
|
8
|
+
|
|
9
|
+
## Default models
|
|
10
|
+
|
|
11
|
+
The affinity model uses linear ridge regression on 477 physicochemical descriptors.
|
|
12
|
+
The mutation model uses kernel ridge regression with a radial basis function (RBF)
|
|
13
|
+
kernel. Its physicochemical inputs comprise 263 descriptors of the native
|
|
14
|
+
interface and substitutions and 167 atomic
|
|
15
|
+
solvent-accessible surface area (SASA) descriptors, plus temperature divided by
|
|
16
|
+
298.15 K. Both use median imputation, missingness indicators and standardization.
|
|
17
|
+
Model parameters were selected by mean absolute error averaged equally across
|
|
18
|
+
groups and then across inner-validation splits.
|
|
19
|
+
Final fits use all eligible training samples with inverse similarity-group
|
|
20
|
+
weights. The affinity model stores regression coefficients and an intercept;
|
|
21
|
+
the mutation model stores standardized training vectors and dual coefficients.
|
|
22
|
+
Both include fitted preprocessing parameters. Cross-validation performance is
|
|
23
|
+
estimated from separate held-out predictions.
|
|
24
|
+
|
|
25
|
+
```sh
|
|
26
|
+
topoppi-affinity analyze --structure complex.pdb --chains-a A --chains-b B \
|
|
27
|
+
--task absolute --output affinity-result
|
|
28
|
+
topoppi-affinity analyze --structure complex.pdb --chains-a A --chains-b B \
|
|
29
|
+
--task mutation --mutations A:G42V --output mutation-result
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
`models status` uses local files to report model availability. The default
|
|
33
|
+
models require CPU computation and the installed scientific dependencies. Optional
|
|
34
|
+
2D atlas generation additionally requires OptCuts.
|
|
35
|
+
|
|
36
|
+
## Applicability
|
|
37
|
+
|
|
38
|
+
Provide a prepared protein complex and the complete interacting chain groups.
|
|
39
|
+
The affinity output is pKd = −log10(Kd/M). Positive mutation ΔΔG indicates weaker
|
|
40
|
+
mutant binding. Mutation predictions describe single or multiple substitutions on
|
|
41
|
+
the fixed wild-type structure; the atomic SASA context is calculated
|
|
42
|
+
from that structure. Review sequence identity, missing residues and conformation
|
|
43
|
+
when interpreting predictions. Per-prediction confidence intervals are unavailable.
|
|
44
|
+
|
|
45
|
+
## Custom models and upstream resources
|
|
46
|
+
|
|
47
|
+
Use `--model` with a compatible `model.json` or `.joblib` artifact. Load joblib
|
|
48
|
+
models from trusted sources. `AffinityRegressor` stores an estimator, named feature
|
|
49
|
+
schema, target and training metadata. Dictionary bundles support named-feature
|
|
50
|
+
regressors, sequence/descriptor kernels and mutation ensembles with declared priors.
|
|
51
|
+
`inference.model_info` describes the required representation and target.
|
|
52
|
+
|
|
53
|
+
Custom neural models use the plugin's `models` extra. ESMC and upstream priors
|
|
54
|
+
retain their source locations, revisions and license information in the resource
|
|
55
|
+
catalog. For advanced known/unseen ensembles, provide an explicit catalog using
|
|
56
|
+
`models download --catalog CATALOG.json`, or select a compatible local model.
|
|
57
|
+
These identifiers describe training-system applicability. Select them according
|
|
58
|
+
to the estimator's documented training scope. `--cache-dir` chooses the resource
|
|
59
|
+
cache. The default physical models use descriptors calculated from the supplied
|
|
60
|
+
structure.
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
# Prediction and interface review
|
|
2
|
+
|
|
3
|
+
## Install and prepare
|
|
4
|
+
|
|
5
|
+
Install the core and affinity plugin in Python 3.10 as described in the [README](../README.md). The plugin includes default CPU models for binding affinity and mutation effects. Use `--model` for a custom estimator; neural models require the `models` extra and their declared resources. Inspect current resource availability with `topoppi-affinity models status` or `doctor`. An explicit model catalog can be supplied to `models download --catalog`.
|
|
6
|
+
|
|
7
|
+
## Run the included example
|
|
8
|
+
|
|
9
|
+
Export the documented 1BVK antibody–lysozyme example with
|
|
10
|
+
`topoppi-affinity example --output affinity-demo`. The complete partner groups
|
|
11
|
+
are A,B and C. In the Affinity window, select **Try 1BVK example...**, retain the
|
|
12
|
+
default task model and select **Predict**. The `example --run` shortcut performs
|
|
13
|
+
an affinity prediction with the bundled CPU model and saves its outputs.
|
|
14
|
+
|
|
15
|
+
**Local model file** selects a compatible custom model. Models with an explicit
|
|
16
|
+
download source can use **Prepare and predict**. **Open saved result...** reads
|
|
17
|
+
saved predictions and geometry independently of the model resources.
|
|
18
|
+
|
|
19
|
+
## Choose a scientific task
|
|
20
|
+
|
|
21
|
+
The Core **Binding analysis** navigation opens **Binding affinity**, **Mutation
|
|
22
|
+
effects**, or **Rank hotspots**. Affinity and mutation effects share a
|
|
23
|
+
prediction editor. Its task selector offers whole-complex pKd and
|
|
24
|
+
ΔΔG for specified substitutions; model applicability and model source have separate
|
|
25
|
+
controls.
|
|
26
|
+
|
|
27
|
+
The default mutation model supports substitutions on the supplied wild-type (WT)
|
|
28
|
+
complex. Advanced **known** and **unseen** ensembles describe training-system applicability.
|
|
29
|
+
A local model's declared target and scope are read when it is selected. Changing
|
|
30
|
+
tasks retains the variant draft and checks model compatibility before prediction.
|
|
31
|
+
Closing and reopening the prediction window also retains the draft and its
|
|
32
|
+
model, applicability and thermodynamic settings within the current TopoPPI
|
|
33
|
+
session. To continue after exiting the application, choose **Save setup...**
|
|
34
|
+
above the setup tabs and save a prediction setup JSON file. **Open setup...**
|
|
35
|
+
replaces the editable form with that file. Saving preserves incomplete variant
|
|
36
|
+
rows and model settings as entered. Setup files contain paths and settings only;
|
|
37
|
+
keep the referenced structure and model files available. Saving a setup is
|
|
38
|
+
independent of model loading and the displayed result. Review paths and finish
|
|
39
|
+
the draft before predicting.
|
|
40
|
+
|
|
41
|
+
Selected interface residues can open the shared variant composer. Choose
|
|
42
|
+
separate single substitutions for a scan, or combine multiple substitutions
|
|
43
|
+
in one variant row. Appending keeps existing rows, adds suffixes to duplicate identifiers and preserves the selected model settings.
|
|
44
|
+
If the mutation draft belongs to another structure or partner grouping, save
|
|
45
|
+
any rows you need and switch those inputs before appending. An
|
|
46
|
+
active prediction must finish or be cancelled before the draft can change.
|
|
47
|
+
|
|
48
|
+
## Analyze your structure
|
|
49
|
+
|
|
50
|
+
```sh
|
|
51
|
+
topoppi-affinity analyze --structure complex.pdb --chains-a A --chains-b B \
|
|
52
|
+
--task absolute --output results --device cpu
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
The unified command is `topoppi affinity analyze`. `--output-dir` is an alias for `--output`. Add `--json` to receive a JSON summary on standard output; progress messages go to standard error.
|
|
56
|
+
|
|
57
|
+
For scripted `analyze --layout` runs, exit code 0 confirms prediction success; check `layout_status` in the JSON summary for atlas completion, or use the separate `layout` command and its exit code.
|
|
58
|
+
|
|
59
|
+
Use `--check-only` to validate inputs before geometry calculation or prediction, `--layout` to request atlases and `--optcuts-bin` to select OptCuts. Each run creates its own result directory; `--retry` reuses a compatible saved interface in a new sibling directory.
|
|
60
|
+
|
|
61
|
+
## Variant input
|
|
62
|
+
|
|
63
|
+
A CSV can contain `variant_id,mutations`, with comma-separated substitutions quoted in one field, or structured `variant_id,chain,position,wt,mt` columns and optional insertion codes. A substitution such as `A:G1W` changes the glycine at chain A, residue 1 to tryptophan. Each repeated `--mutations` flag describes one variant; commas join changes in the same variant. Invalid rows retain their identifiers and error messages.
|
|
64
|
+
|
|
65
|
+
In the prediction editor, CSV import defaults to **Append rows**. Choose
|
|
66
|
+
**Replace draft** when the file should become the whole draft. Imported sample
|
|
67
|
+
IDs are preserved; resolve conflicting IDs before appending. Ctrl+Z reverses
|
|
68
|
+
the most recent import in one step.
|
|
69
|
+
|
|
70
|
+
For the default mutation model, use `--task mutation` and provide substitutions. Advanced known/unseen ensembles use `--mutation-context known` or `unseen` with the basis recorded in `--scope-note`. An optional measured `--wt-kd` in molar units anchors a mutation prediction to an absolute affinity using `--temperature` in kelvin.
|
|
71
|
+
|
|
72
|
+
## Review, export and retry
|
|
73
|
+
|
|
74
|
+
```sh
|
|
75
|
+
topoppi-affinity inspect results --json
|
|
76
|
+
topoppi-affinity review results --view contacts
|
|
77
|
+
topoppi-affinity render results --view surface --output surface.png
|
|
78
|
+
topoppi-affinity layout results --optcuts-bin /path/to/OptCuts_bin
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
Review commands use the predictions and geometry stored in saved results. Structure, contact and atlas selections refer to the same author residue identifiers. Layout errors remain separate from prediction results.
|
|
82
|
+
|
|
83
|
+
In the Affinity window, select **Open saved result...** and choose `analysis.json`. Select a prediction row and binding partner to inspect the 3D interface. Use **Show in main window** to place that selection on the main canvas, **Export predictions...** to share the table, or **Reuse inputs** to start another run. The **Activity** tab and **Show result details** control provide progress messages, units, row errors and saved model context. Failed or missing predictions display **Unavailable** in the table.
|
|
84
|
+
|
|
85
|
+
## Custom models
|
|
86
|
+
|
|
87
|
+
Named-feature inference uses NPZ arrays `X`, `sample_ids` and `feature_names`. Select `predict --features`, `--plm-features`, or `--descriptor-features` according to the model schema. A prior CSV identifies rows by `sample_id`. The [model guide](models.md) describes supported fitted objects and the [tools guide](../tools/README.md) lists explicit feature extraction and fitting commands.
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
# Example inputs
|
|
2
|
+
|
|
3
|
+
## Antibody–lysozyme example
|
|
4
|
+
|
|
5
|
+
The installed plugin includes PDB structure 1BVK and a CSV with two mutation sets. Follow the [installation guide](../docs/workflow.md#install-and-prepare), then export the example:
|
|
6
|
+
|
|
7
|
+
```sh
|
|
8
|
+
topoppi-affinity example --output affinity-demo
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
Run the bundled affinity model and open the result:
|
|
12
|
+
|
|
13
|
+
```sh
|
|
14
|
+
topoppi-affinity example --output affinity-demo --run
|
|
15
|
+
topoppi-affinity gui affinity-demo/results
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
The example uses antibody chains A,B against lysozyme chain C. Repeated runs save results in a new directory and print its path. Native-surface review is available immediately; OptCuts adds optional atlases. The [model guide](../docs/models.md#applicability) describes model scope, and the [workflow guide](../docs/workflow.md#variant-input) explains mutation input.
|
|
19
|
+
|
|
20
|
+
For a desktop start, select **Try 1BVK example...**, choose a folder and select **Predict** to use the bundled model. Advanced settings allow a compatible local model or a task model prepared from an explicit download catalog. The panel fills the absolute task and both partner groups. Reuse preserves previous results; edited example files can be analyzed directly or kept while a fresh copy is exported elsewhere.
|
|
21
|
+
|
|
22
|
+
## Synthetic row-error fixture
|
|
23
|
+
|
|
24
|
+
`tiny_complex.pdb` is a small synthetic structure shared with the core tests. Its `variants.csv` contains two alternative substitutions at one site, a variant with substitutions in both partners and an absent position. Use it to exercise valid and invalid rows with the bundled mutation model:
|
|
25
|
+
|
|
26
|
+
```sh
|
|
27
|
+
topoppi-affinity analyze --structure tiny_complex.pdb --chains-a A --chains-b B \
|
|
28
|
+
--task mutation --variants variants.csv --output software-fixture
|
|
29
|
+
topoppi-affinity gui software-fixture
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
Run these commands from this directory. The absent position produces a row error and exit code 2; valid predictions remain in the result. Add `--model` to use a compatible [custom model](../docs/workflow.md#custom-models).
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
ATOM 1 N GLY A 1 0.000 0.000 0.000 1.00 20.00 N
|
|
2
|
+
ATOM 2 CA GLY A 1 1.000 0.000 0.000 1.00 20.00 C
|
|
3
|
+
ATOM 3 C GLY A 1 1.000 1.000 0.000 1.00 20.00 C
|
|
4
|
+
ATOM 4 O GLY A 1 1.000 1.500 0.000 1.00 20.00 O
|
|
5
|
+
ATOM 5 N ALA A 2 2.000 1.000 0.000 1.00 20.00 N
|
|
6
|
+
ATOM 6 CA ALA A 2 2.500 1.500 0.000 1.00 20.00 C
|
|
7
|
+
HETATM 7 O HOH A 3 9.000 9.000 9.000 1.00 20.00 O
|
|
8
|
+
ATOM 8 N GLY B 1 3.000 0.000 0.000 1.00 20.00 N
|
|
9
|
+
ATOM 9 CA GLY B 1 4.000 0.000 0.000 1.00 20.00 C
|
|
10
|
+
ATOM 10 C GLY B 1 4.000 1.000 0.000 1.00 20.00 C
|
|
11
|
+
ATOM 11 O GLY B 1 4.000 1.500 0.000 1.00 20.00 O
|
|
12
|
+
ATOM 12 N ALA B 2 5.000 1.000 0.000 1.00 20.00 N
|
|
13
|
+
ATOM 13 CA ALA B 2 5.500 1.500 0.000 1.00 20.00 C
|
|
14
|
+
TER
|
|
15
|
+
END
|