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.
Files changed (192) hide show
  1. topoppi_affinity-3.0.0/LICENSE +21 -0
  2. topoppi_affinity-3.0.0/MANIFEST.in +11 -0
  3. topoppi_affinity-3.0.0/PKG-INFO +137 -0
  4. topoppi_affinity-3.0.0/README.md +107 -0
  5. topoppi_affinity-3.0.0/docs/affinity_external_methods.md +44 -0
  6. topoppi_affinity-3.0.0/docs/api.md +72 -0
  7. topoppi_affinity-3.0.0/docs/evaluation.md +15 -0
  8. topoppi_affinity-3.0.0/docs/migration.md +29 -0
  9. topoppi_affinity-3.0.0/docs/models.md +60 -0
  10. topoppi_affinity-3.0.0/docs/workflow.md +87 -0
  11. topoppi_affinity-3.0.0/examples/README.md +32 -0
  12. topoppi_affinity-3.0.0/examples/tiny_complex.pdb +15 -0
  13. topoppi_affinity-3.0.0/examples/variants.csv +5 -0
  14. topoppi_affinity-3.0.0/pyproject.toml +58 -0
  15. topoppi_affinity-3.0.0/setup.cfg +4 -0
  16. topoppi_affinity-3.0.0/tests/conftest.py +19 -0
  17. topoppi_affinity-3.0.0/tests/fixtures/1bvk.pdb +6076 -0
  18. topoppi_affinity-3.0.0/tests/fixtures/tiny_complex.pdb +15 -0
  19. topoppi_affinity-3.0.0/tests/test_affinity_analytic_curvature.py +86 -0
  20. topoppi_affinity-3.0.0/tests/test_affinity_artifacts.py +37 -0
  21. topoppi_affinity-3.0.0/tests/test_affinity_attribution.py +82 -0
  22. topoppi_affinity-3.0.0/tests/test_affinity_author_references.py +57 -0
  23. topoppi_affinity-3.0.0/tests/test_affinity_ba_cycle.py +39 -0
  24. topoppi_affinity-3.0.0/tests/test_affinity_benchmark_data.py +127 -0
  25. topoppi_affinity-3.0.0/tests/test_affinity_benchmark_models.py +175 -0
  26. topoppi_affinity-3.0.0/tests/test_affinity_benchmark_reporting.py +183 -0
  27. topoppi_affinity-3.0.0/tests/test_affinity_bilinear_features.py +45 -0
  28. topoppi_affinity-3.0.0/tests/test_affinity_cached_author_references.py +98 -0
  29. topoppi_affinity-3.0.0/tests/test_affinity_comparison.py +43 -0
  30. topoppi_affinity-3.0.0/tests/test_affinity_data.py +82 -0
  31. topoppi_affinity-3.0.0/tests/test_affinity_embedding_baselines.py +112 -0
  32. topoppi_affinity-3.0.0/tests/test_affinity_epistasis.py +96 -0
  33. topoppi_affinity-3.0.0/tests/test_affinity_external_absolute.py +156 -0
  34. topoppi_affinity-3.0.0/tests/test_affinity_external_inputs.py +70 -0
  35. topoppi_affinity-3.0.0/tests/test_affinity_features.py +91 -0
  36. topoppi_affinity-3.0.0/tests/test_affinity_footprint_controls.py +20 -0
  37. topoppi_affinity-3.0.0/tests/test_affinity_frozen_structure.py +39 -0
  38. topoppi_affinity-3.0.0/tests/test_affinity_geometric_scattering.py +21 -0
  39. topoppi_affinity-3.0.0/tests/test_affinity_graph_dataset.py +87 -0
  40. topoppi_affinity-3.0.0/tests/test_affinity_graph_features.py +61 -0
  41. topoppi_affinity-3.0.0/tests/test_affinity_graph_models.py +160 -0
  42. topoppi_affinity-3.0.0/tests/test_affinity_group_dro.py +34 -0
  43. topoppi_affinity-3.0.0/tests/test_affinity_joint.py +94 -0
  44. topoppi_affinity-3.0.0/tests/test_affinity_legacy_antisymmetry.py +20 -0
  45. topoppi_affinity-3.0.0/tests/test_affinity_legacy_kernel.py +53 -0
  46. topoppi_affinity-3.0.0/tests/test_affinity_models.py +59 -0
  47. topoppi_affinity-3.0.0/tests/test_affinity_mutation_ensemble.py +57 -0
  48. topoppi_affinity-3.0.0/tests/test_affinity_next_protocols.py +131 -0
  49. topoppi_affinity-3.0.0/tests/test_affinity_paired_embeddings.py +32 -0
  50. topoppi_affinity-3.0.0/tests/test_affinity_residual_artifacts.py +62 -0
  51. topoppi_affinity-3.0.0/tests/test_affinity_residual_baselines.py +41 -0
  52. topoppi_affinity-3.0.0/tests/test_affinity_sequence_baselines.py +118 -0
  53. topoppi_affinity-3.0.0/tests/test_affinity_sequence_embeddings.py +104 -0
  54. topoppi_affinity-3.0.0/tests/test_affinity_state_kernel.py +28 -0
  55. topoppi_affinity-3.0.0/tests/test_affinity_structure_features.py +84 -0
  56. topoppi_affinity-3.0.0/tests/test_affinity_surface_diffusion.py +60 -0
  57. topoppi_affinity-3.0.0/tests/test_affinity_surface_transport.py +30 -0
  58. topoppi_affinity-3.0.0/tests/test_affinity_uv_layout.py +99 -0
  59. topoppi_affinity-3.0.0/tests/test_affinity_variant_augmentation.py +19 -0
  60. topoppi_affinity-3.0.0/tests/test_analysis_workflow.py +103 -0
  61. topoppi_affinity-3.0.0/tests/test_atlas_review.py +52 -0
  62. topoppi_affinity-3.0.0/tests/test_cancellation_semantics.py +161 -0
  63. topoppi_affinity-3.0.0/tests/test_downstream_journeys.py +179 -0
  64. topoppi_affinity-3.0.0/tests/test_explicit_fitting.py +69 -0
  65. topoppi_affinity-3.0.0/tests/test_gui_usability.py +1129 -0
  66. topoppi_affinity-3.0.0/tests/test_host_results.py +471 -0
  67. topoppi_affinity-3.0.0/tests/test_inference_representations.py +79 -0
  68. topoppi_affinity-3.0.0/tests/test_installer.py +454 -0
  69. topoppi_affinity-3.0.0/tests/test_integration.py +56 -0
  70. topoppi_affinity-3.0.0/tests/test_panel_keyboard.py +167 -0
  71. topoppi_affinity-3.0.0/tests/test_plugin_capability.py +75 -0
  72. topoppi_affinity-3.0.0/tests/test_production_models.py +96 -0
  73. topoppi_affinity-3.0.0/tests/test_public_model_metadata.py +57 -0
  74. topoppi_affinity-3.0.0/tests/test_resources.py +257 -0
  75. topoppi_affinity-3.0.0/tests/test_usability_workflow.py +256 -0
  76. topoppi_affinity-3.0.0/tools/README.md +10 -0
  77. topoppi_affinity-3.0.0/tools/__init__.py +6 -0
  78. topoppi_affinity-3.0.0/tools/features/__init__.py +1 -0
  79. topoppi_affinity-3.0.0/tools/features/extract_analytic_features.py +52 -0
  80. topoppi_affinity-3.0.0/tools/features/extract_features.py +113 -0
  81. topoppi_affinity-3.0.0/tools/features/extract_graph_features.py +78 -0
  82. topoppi_affinity-3.0.0/tools/features/extract_prospective_sasa.py +51 -0
  83. topoppi_affinity-3.0.0/tools/features/extract_sequence_embeddings.py +22 -0
  84. topoppi_affinity-3.0.0/tools/features/pool_manifest_embeddings.py +45 -0
  85. topoppi_affinity-3.0.0/tools/features/prepare_analytic_mutation_inputs.py +15 -0
  86. topoppi_affinity-3.0.0/tools/features/refine_graph_curvature.py +63 -0
  87. topoppi_affinity-3.0.0/tools/models/__init__.py +1 -0
  88. topoppi_affinity-3.0.0/tools/models/bundle_mutation_ensemble.py +17 -0
  89. topoppi_affinity-3.0.0/tools/models/fit_absolute_model.py +48 -0
  90. topoppi_affinity-3.0.0/tools/models/predict_absolute_model.py +27 -0
  91. topoppi_affinity-3.0.0/tools/models/predict_attribution.py +35 -0
  92. topoppi_affinity-3.0.0/tools/models/predict_frozen_affinity.py +17 -0
  93. topoppi_affinity-3.0.0/tools/models/predict_mutation_ensemble.py +26 -0
  94. topoppi_affinity-3.0.0/tools/models/predict_residual_affinity.py +23 -0
  95. topoppi_affinity-3.0.0/tools/models/refit_frozen_model.py +29 -0
  96. topoppi_affinity-3.0.0/tools/models/refit_residual_model.py +29 -0
  97. topoppi_affinity-3.0.0/topoppi_affinity/__init__.py +6 -0
  98. topoppi_affinity-3.0.0/topoppi_affinity/__main__.py +4 -0
  99. topoppi_affinity-3.0.0/topoppi_affinity/analytic_curvature.py +143 -0
  100. topoppi_affinity-3.0.0/topoppi_affinity/analytic_preprocessing.py +82 -0
  101. topoppi_affinity-3.0.0/topoppi_affinity/artifacts.py +66 -0
  102. topoppi_affinity-3.0.0/topoppi_affinity/atlas_review/__init__.py +1 -0
  103. topoppi_affinity-3.0.0/topoppi_affinity/atlas_review/comparison.py +209 -0
  104. topoppi_affinity-3.0.0/topoppi_affinity/atlas_review/context.py +117 -0
  105. topoppi_affinity-3.0.0/topoppi_affinity/atlas_review/gui.py +459 -0
  106. topoppi_affinity-3.0.0/topoppi_affinity/atlas_review/paired.py +173 -0
  107. topoppi_affinity-3.0.0/topoppi_affinity/atlas_review/session.py +111 -0
  108. topoppi_affinity-3.0.0/topoppi_affinity/attribution_features.py +220 -0
  109. topoppi_affinity-3.0.0/topoppi_affinity/author_references.py +207 -0
  110. topoppi_affinity-3.0.0/topoppi_affinity/ba_cycle_prior.py +224 -0
  111. topoppi_affinity-3.0.0/topoppi_affinity/benchmark_data.py +243 -0
  112. topoppi_affinity-3.0.0/topoppi_affinity/benchmark_features.py +271 -0
  113. topoppi_affinity-3.0.0/topoppi_affinity/benchmark_models.py +433 -0
  114. topoppi_affinity-3.0.0/topoppi_affinity/benchmark_reporting.py +382 -0
  115. topoppi_affinity-3.0.0/topoppi_affinity/bilinear_features.py +54 -0
  116. topoppi_affinity-3.0.0/topoppi_affinity/bilinear_kernel.py +15 -0
  117. topoppi_affinity-3.0.0/topoppi_affinity/bindpred_baseline.py +169 -0
  118. topoppi_affinity-3.0.0/topoppi_affinity/cached_author_references.py +388 -0
  119. topoppi_affinity-3.0.0/topoppi_affinity/capabilities.py +30 -0
  120. topoppi_affinity-3.0.0/topoppi_affinity/cath_protocol.py +82 -0
  121. topoppi_affinity-3.0.0/topoppi_affinity/cli.py +323 -0
  122. topoppi_affinity-3.0.0/topoppi_affinity/comparison.py +130 -0
  123. topoppi_affinity-3.0.0/topoppi_affinity/data/example/1bvk.pdb +6076 -0
  124. topoppi_affinity-3.0.0/topoppi_affinity/data/example/README.md +22 -0
  125. topoppi_affinity-3.0.0/topoppi_affinity/data/example/variants.csv +3 -0
  126. topoppi_affinity-3.0.0/topoppi_affinity/data/model_catalog.json +83 -0
  127. topoppi_affinity-3.0.0/topoppi_affinity/data/production/MODEL_CARD.md +40 -0
  128. topoppi_affinity-3.0.0/topoppi_affinity/data/production/absolute/model.json +515 -0
  129. topoppi_affinity-3.0.0/topoppi_affinity/data/production/absolute/weights.npz +0 -0
  130. topoppi_affinity-3.0.0/topoppi_affinity/data/production/mutation/model.json +470 -0
  131. topoppi_affinity-3.0.0/topoppi_affinity/data/production/mutation/weights.npz +0 -0
  132. topoppi_affinity-3.0.0/topoppi_affinity/data.py +102 -0
  133. topoppi_affinity-3.0.0/topoppi_affinity/embedding_baselines.py +189 -0
  134. topoppi_affinity-3.0.0/topoppi_affinity/epistasis.py +232 -0
  135. topoppi_affinity-3.0.0/topoppi_affinity/evaluation.py +56 -0
  136. topoppi_affinity-3.0.0/topoppi_affinity/expanded_references.py +259 -0
  137. topoppi_affinity-3.0.0/topoppi_affinity/external_absolute.py +419 -0
  138. topoppi_affinity-3.0.0/topoppi_affinity/external_energy.py +103 -0
  139. topoppi_affinity-3.0.0/topoppi_affinity/external_inputs.py +104 -0
  140. topoppi_affinity-3.0.0/topoppi_affinity/external_mutation.py +255 -0
  141. topoppi_affinity-3.0.0/topoppi_affinity/features.py +327 -0
  142. topoppi_affinity-3.0.0/topoppi_affinity/footprint_controls.py +17 -0
  143. topoppi_affinity-3.0.0/topoppi_affinity/frozen_probes.py +23 -0
  144. topoppi_affinity-3.0.0/topoppi_affinity/frozen_structure.py +199 -0
  145. topoppi_affinity-3.0.0/topoppi_affinity/geometric_scattering.py +79 -0
  146. topoppi_affinity-3.0.0/topoppi_affinity/graph_dataset.py +138 -0
  147. topoppi_affinity-3.0.0/topoppi_affinity/graph_features.py +304 -0
  148. topoppi_affinity-3.0.0/topoppi_affinity/graph_models.py +161 -0
  149. topoppi_affinity-3.0.0/topoppi_affinity/graph_training.py +71 -0
  150. topoppi_affinity-3.0.0/topoppi_affinity/group_dro_baselines.py +102 -0
  151. topoppi_affinity-3.0.0/topoppi_affinity/grouped_fitting.py +105 -0
  152. topoppi_affinity-3.0.0/topoppi_affinity/gui.py +1676 -0
  153. topoppi_affinity-3.0.0/topoppi_affinity/inference.py +273 -0
  154. topoppi_affinity-3.0.0/topoppi_affinity/installer.py +551 -0
  155. topoppi_affinity-3.0.0/topoppi_affinity/integration.py +408 -0
  156. topoppi_affinity-3.0.0/topoppi_affinity/joint_training.py +177 -0
  157. topoppi_affinity-3.0.0/topoppi_affinity/legacy_antisymmetry.py +30 -0
  158. topoppi_affinity-3.0.0/topoppi_affinity/legacy_kernel.py +84 -0
  159. topoppi_affinity-3.0.0/topoppi_affinity/mint_embeddings.py +39 -0
  160. topoppi_affinity-3.0.0/topoppi_affinity/model_metadata.py +91 -0
  161. topoppi_affinity-3.0.0/topoppi_affinity/models.py +108 -0
  162. topoppi_affinity-3.0.0/topoppi_affinity/multipoint.py +27 -0
  163. topoppi_affinity-3.0.0/topoppi_affinity/mutation_ensemble.py +113 -0
  164. topoppi_affinity-3.0.0/topoppi_affinity/mutation_physics.py +159 -0
  165. topoppi_affinity-3.0.0/topoppi_affinity/paired_embeddings.py +86 -0
  166. topoppi_affinity-3.0.0/topoppi_affinity/plugin.py +20 -0
  167. topoppi_affinity-3.0.0/topoppi_affinity/ppb_protocol.py +234 -0
  168. topoppi_affinity-3.0.0/topoppi_affinity/ppiformer_finetune.py +185 -0
  169. topoppi_affinity-3.0.0/topoppi_affinity/proaffinity_inputs.py +306 -0
  170. topoppi_affinity-3.0.0/topoppi_affinity/production.py +101 -0
  171. topoppi_affinity-3.0.0/topoppi_affinity/representation_controls.py +124 -0
  172. topoppi_affinity-3.0.0/topoppi_affinity/residual_artifacts.py +138 -0
  173. topoppi_affinity-3.0.0/topoppi_affinity/residual_baselines.py +139 -0
  174. topoppi_affinity-3.0.0/topoppi_affinity/resources.py +333 -0
  175. topoppi_affinity-3.0.0/topoppi_affinity/runtime.py +31 -0
  176. topoppi_affinity-3.0.0/topoppi_affinity/sequence_baselines.py +244 -0
  177. topoppi_affinity-3.0.0/topoppi_affinity/sequence_embeddings.py +232 -0
  178. topoppi_affinity-3.0.0/topoppi_affinity/splits.py +197 -0
  179. topoppi_affinity-3.0.0/topoppi_affinity/state_kernel.py +82 -0
  180. topoppi_affinity-3.0.0/topoppi_affinity/structure_features.py +79 -0
  181. topoppi_affinity-3.0.0/topoppi_affinity/surface_diffusion.py +180 -0
  182. topoppi_affinity-3.0.0/topoppi_affinity/surface_transport.py +84 -0
  183. topoppi_affinity-3.0.0/topoppi_affinity/thermodynamics.py +42 -0
  184. topoppi_affinity-3.0.0/topoppi_affinity/uv_layout_features.py +348 -0
  185. topoppi_affinity-3.0.0/topoppi_affinity/variant_augmentation.py +56 -0
  186. topoppi_affinity-3.0.0/topoppi_affinity/workflow.py +612 -0
  187. topoppi_affinity-3.0.0/topoppi_affinity.egg-info/PKG-INFO +137 -0
  188. topoppi_affinity-3.0.0/topoppi_affinity.egg-info/SOURCES.txt +190 -0
  189. topoppi_affinity-3.0.0/topoppi_affinity.egg-info/dependency_links.txt +1 -0
  190. topoppi_affinity-3.0.0/topoppi_affinity.egg-info/entry_points.txt +5 -0
  191. topoppi_affinity-3.0.0/topoppi_affinity.egg-info/requires.txt +21 -0
  192. 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