topoppi-hotspot 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 (75) hide show
  1. topoppi_hotspot-3.0.0/LICENSE +21 -0
  2. topoppi_hotspot-3.0.0/MANIFEST.in +8 -0
  3. topoppi_hotspot-3.0.0/PKG-INFO +210 -0
  4. topoppi_hotspot-3.0.0/README.md +189 -0
  5. topoppi_hotspot-3.0.0/examples/synthetic_ranking.py +18 -0
  6. topoppi_hotspot-3.0.0/pyproject.toml +31 -0
  7. topoppi_hotspot-3.0.0/setup.cfg +4 -0
  8. topoppi_hotspot-3.0.0/tests/fixtures/README.md +3 -0
  9. topoppi_hotspot-3.0.0/tests/fixtures/tiny_complex.pdb +15 -0
  10. topoppi_hotspot-3.0.0/tests/test_block_ranking.py +82 -0
  11. topoppi_hotspot-3.0.0/tests/test_core_contract.py +114 -0
  12. topoppi_hotspot-3.0.0/tests/test_evaluation.py +43 -0
  13. topoppi_hotspot-3.0.0/tests/test_feature_controls.py +69 -0
  14. topoppi_hotspot-3.0.0/tests/test_features.py +66 -0
  15. topoppi_hotspot-3.0.0/tests/test_footprint_diffusion.py +163 -0
  16. topoppi_hotspot-3.0.0/tests/test_graph_operators.py +48 -0
  17. topoppi_hotspot-3.0.0/tests/test_graph_ranking.py +144 -0
  18. topoppi_hotspot-3.0.0/tests/test_gui.py +526 -0
  19. topoppi_hotspot-3.0.0/tests/test_gui_workflow.py +159 -0
  20. topoppi_hotspot-3.0.0/tests/test_inference.py +432 -0
  21. topoppi_hotspot-3.0.0/tests/test_mesh_diffusion.py +77 -0
  22. topoppi_hotspot-3.0.0/tests/test_mutation_model.py +55 -0
  23. topoppi_hotspot-3.0.0/tests/test_nonlinear_ranking.py +124 -0
  24. topoppi_hotspot-3.0.0/tests/test_organization.py +128 -0
  25. topoppi_hotspot-3.0.0/tests/test_paired_surface_features.py +35 -0
  26. topoppi_hotspot-3.0.0/tests/test_partner_features.py +46 -0
  27. topoppi_hotspot-3.0.0/tests/test_production_model.py +271 -0
  28. topoppi_hotspot-3.0.0/tests/test_rank_fusion.py +20 -0
  29. topoppi_hotspot-3.0.0/tests/test_ranking_metrics.py +115 -0
  30. topoppi_hotspot-3.0.0/tests/test_ranking_models.py +91 -0
  31. topoppi_hotspot-3.0.0/tests/test_relative_features.py +100 -0
  32. topoppi_hotspot-3.0.0/tests/test_solvent_accessibility.py +48 -0
  33. topoppi_hotspot-3.0.0/tests/test_surface_rim.py +50 -0
  34. topoppi_hotspot-3.0.0/topoppi_hotspot/__init__.py +3 -0
  35. topoppi_hotspot-3.0.0/topoppi_hotspot/__main__.py +3 -0
  36. topoppi_hotspot-3.0.0/topoppi_hotspot/block_ranking.py +152 -0
  37. topoppi_hotspot-3.0.0/topoppi_hotspot/cli.py +68 -0
  38. topoppi_hotspot-3.0.0/topoppi_hotspot/data/mutation_surface/MODEL_CARD.md +84 -0
  39. topoppi_hotspot-3.0.0/topoppi_hotspot/data/mutation_surface/model.json +1199 -0
  40. topoppi_hotspot-3.0.0/topoppi_hotspot/data/mutation_surface/weights.npz +0 -0
  41. topoppi_hotspot-3.0.0/topoppi_hotspot/evaluation.py +181 -0
  42. topoppi_hotspot-3.0.0/topoppi_hotspot/feature_controls.py +77 -0
  43. topoppi_hotspot-3.0.0/topoppi_hotspot/features.py +211 -0
  44. topoppi_hotspot-3.0.0/topoppi_hotspot/footprint_diffusion.py +244 -0
  45. topoppi_hotspot-3.0.0/topoppi_hotspot/graph_io.py +18 -0
  46. topoppi_hotspot-3.0.0/topoppi_hotspot/graph_operators.py +96 -0
  47. topoppi_hotspot-3.0.0/topoppi_hotspot/graph_ranking.py +228 -0
  48. topoppi_hotspot-3.0.0/topoppi_hotspot/gui.py +501 -0
  49. topoppi_hotspot-3.0.0/topoppi_hotspot/gui_workflow.py +141 -0
  50. topoppi_hotspot-3.0.0/topoppi_hotspot/inference.py +436 -0
  51. topoppi_hotspot-3.0.0/topoppi_hotspot/mesh_diffusion.py +223 -0
  52. topoppi_hotspot-3.0.0/topoppi_hotspot/model_io.py +36 -0
  53. topoppi_hotspot-3.0.0/topoppi_hotspot/mutation_inference.py +126 -0
  54. topoppi_hotspot-3.0.0/topoppi_hotspot/mutation_model.py +52 -0
  55. topoppi_hotspot-3.0.0/topoppi_hotspot/nonlinear_ranking.py +257 -0
  56. topoppi_hotspot-3.0.0/topoppi_hotspot/organization.py +276 -0
  57. topoppi_hotspot-3.0.0/topoppi_hotspot/paired_surface_features.py +113 -0
  58. topoppi_hotspot-3.0.0/topoppi_hotspot/partner_features.py +101 -0
  59. topoppi_hotspot-3.0.0/topoppi_hotspot/physical_features.py +102 -0
  60. topoppi_hotspot-3.0.0/topoppi_hotspot/plugin.py +21 -0
  61. topoppi_hotspot-3.0.0/topoppi_hotspot/rank_fusion.py +26 -0
  62. topoppi_hotspot-3.0.0/topoppi_hotspot/ranking_metrics.py +179 -0
  63. topoppi_hotspot-3.0.0/topoppi_hotspot/ranking_models.py +152 -0
  64. topoppi_hotspot-3.0.0/topoppi_hotspot/relative_features.py +123 -0
  65. topoppi_hotspot-3.0.0/topoppi_hotspot/representations.py +50 -0
  66. topoppi_hotspot-3.0.0/topoppi_hotspot/resources.py +15 -0
  67. topoppi_hotspot-3.0.0/topoppi_hotspot/sequence_embeddings.py +108 -0
  68. topoppi_hotspot-3.0.0/topoppi_hotspot/solvent_accessibility.py +60 -0
  69. topoppi_hotspot-3.0.0/topoppi_hotspot/surface_rim.py +107 -0
  70. topoppi_hotspot-3.0.0/topoppi_hotspot.egg-info/PKG-INFO +210 -0
  71. topoppi_hotspot-3.0.0/topoppi_hotspot.egg-info/SOURCES.txt +73 -0
  72. topoppi_hotspot-3.0.0/topoppi_hotspot.egg-info/dependency_links.txt +1 -0
  73. topoppi_hotspot-3.0.0/topoppi_hotspot.egg-info/entry_points.txt +5 -0
  74. topoppi_hotspot-3.0.0/topoppi_hotspot.egg-info/requires.txt +14 -0
  75. topoppi_hotspot-3.0.0/topoppi_hotspot.egg-info/top_level.txt +1 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 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,8 @@
1
+ include README.md pyproject.toml LICENSE
2
+ recursive-include topoppi_hotspot *.py
3
+ recursive-include examples *.py
4
+ recursive-include tests *.py *.pdb *.md
5
+ prune build
6
+ prune .internal
7
+
8
+ recursive-include topoppi_hotspot/data *.json *.npz *.md
@@ -0,0 +1,210 @@
1
+ Metadata-Version: 2.4
2
+ Name: topoppi-hotspot
3
+ Version: 3.0.0
4
+ Summary: Residue feature extraction and selected-partner ranking for TopoPPI.
5
+ License-Expression: MIT
6
+ Requires-Python: <3.11,>=3.10
7
+ Description-Content-Type: text/markdown
8
+ License-File: LICENSE
9
+ Requires-Dist: topoppi[representation]>=3.0.0
10
+ Requires-Dist: topoppi-affinity>=3.0.0
11
+ Requires-Dist: pandas>=2
12
+ Requires-Dist: scikit-learn>=1.3
13
+ Requires-Dist: joblib>=1.2
14
+ Provides-Extra: neural
15
+ Requires-Dist: torch>=2.2; extra == "neural"
16
+ Provides-Extra: sequence
17
+ Requires-Dist: esm>=3.2.1; extra == "sequence"
18
+ Provides-Extra: xgboost
19
+ Requires-Dist: xgboost>=3.2; extra == "xgboost"
20
+ Dynamic: license-file
21
+
22
+ # TopoPPI Hotspot
23
+
24
+ TopoPPI Hotspot ranks interface residues within a selected binding partner by predicting the binding free-energy change of each alanine substitution. Its bundled model combines physicochemical mutation descriptors with spatial descriptors recovered from a residue-aware UV representation. Inputs are a structure and the complete chain groups forming the two partners. You can also supply a compatible fitted model.
25
+
26
+ ## Installation
27
+
28
+ Install TopoPPI Hotspot from PyPI with Python 3.10.
29
+
30
+ ```sh
31
+ python -m pip install topoppi-hotspot
32
+ ```
33
+
34
+ For development, run this command from the repository root with Core installed.
35
+
36
+ ```bash
37
+ python -m pip install -e ./plugins/affinity -e ./plugins/hotspot
38
+ ```
39
+
40
+ Hotspot installs the Affinity package for shared mutation features and the Core `representation` extra for surface encoding. The bundled model also requires native OptCuts; follow the [platform installation instructions](https://github.com/GeraltZeroZhong/TopoPPI/blob/HEAD/README.md#optcuts-cannot-be-found). Published pip installations can use `topoppi-install-optcuts` on supported platforms. Set `TOPOPPI_OPTCUTS_BIN` to an existing executable, or pass `--optcuts-bin` to the ranking command. Once OptCuts and the Python dependencies are installed, prediction runs offline on CPU using the bundled weights.
41
+
42
+ The package uses NumPy, SciPy, pandas, Biopython, and scikit-learn through its dependencies. Optional extras enable PyTorch neural rankers (`neural`), XGBoost (`xgboost`), and ESMC embeddings (`sequence`). Embedding inference requires an explicit local checkpoint.
43
+
44
+ ## Desktop workflow
45
+
46
+ Start `topoppi-gui`, open **Binding analysis**, and choose **Rank hotspots**. The
47
+ Analysis menu and **Hotspot ranking** in **Plugins** also open the workspace directly. The structure and
48
+ partner chain groups are filled from the main window; **Use main selection**
49
+ refreshes them after a change.
50
+
51
+ 1. Choose the complete partner to rank. Leave **Custom model (optional)** empty to use the bundled model; select a folder containing `model.json` to use your own model.
52
+ 2. Choose a new results folder. Sequence models also use a prepared embedding registry under **Sequence model options**.
53
+ 3. Select **Rank residues**. The calculation runs on CPU, displays progress, and can be cancelled.
54
+ 4. Review the ranked table, select one or more residues, and choose **Show ranked surface** to color the native 3D interface in the main canvas. All selected residues with a native surface footprint are highlighted together; a residue without a footprint remains available in the table for variant creation.
55
+ 5. Export the full ranking table, or use **Export residue values...** for a `residue,value` annotation CSV that can color an existing Core atlas.
56
+ 6. Select one or more residues with Ctrl/Cmd-click or Shift-click and choose **Create variants...** to continue in Affinity. Choose separate single substitutions or one joint variant. The selected residues retain their author chain IDs, residue numbers, insertion codes, and wild-type identities. Review the prepared variants, then choose **Predict** in Affinity to run the prediction.
57
+
58
+ The shared task navigation connects hotspot ranking, binding affinity, and mutation
59
+ effects using the current structure and partner input fields. **Create variants...**
60
+ continues from the displayed ranking, using its saved structure and partner groups
61
+ even when the next ranking's input fields have been edited.
62
+ Variant creation requires Affinity to be enabled. Saved rankings can still be
63
+ reviewed and exported without it.
64
+
65
+ For the bundled model, higher predicted ΔΔG values rank first. Positive values
66
+ indicate weaker binding after alanine substitution. Predictions use a reference
67
+ temperature of 298.15 K. Native alanines remain part of the feature context.
68
+ The table shows tied ranks and coverage details where relevant; custom scores
69
+ follow the selected model's documented scope.
70
+
71
+ Compatible geometry from the main workspace is reused. The model's surface and
72
+ topology settings determine any additional geometry computation. Desktop runs
73
+ save `interface.npz` alongside the ranking files, so **Open saved ranking...**
74
+ can recover the table and surface after the original structure or model moves.
75
+ Earlier CLI output folders can still be opened as tables. Existing result files
76
+ are preserved; **New results folder** creates a fresh destination for another run.
77
+ Closing and reopening the Hotspot window in the same TopoPPI session retains
78
+ unfinished model, output and rank-partner settings, alongside the displayed
79
+ result and selected residues. The next ranking's settings remain separate from
80
+ the source and selected partner of the displayed result.
81
+
82
+ Custom sequence models use local fitted models and prepared embedding registries.
83
+ The Python and CLI interfaces also support explicit local ESMC checkpoints.
84
+
85
+ ## Synthetic quick start
86
+
87
+ From a source checkout, run the fitting example.
88
+
89
+ ```bash
90
+ python plugins/hotspot/examples/synthetic_ranking.py
91
+ python -m topoppi_hotspot --help
92
+ ```
93
+
94
+ The example constructs eight one-dimensional feature rows and two invented queries. It fits a pairwise ranker and prints within-query scores and average precision. Its labels follow the sign of the feature by construction; the output demonstrates the API.
95
+
96
+ ```python
97
+ import numpy as np
98
+ from topoppi_hotspot.ranking_models import PairwiseHotspotRanker
99
+
100
+ features = np.array([[-2.0], [-1.0], [1.0], [2.0]])
101
+ labels = np.array([0, 0, 1, 1])
102
+ queries = np.array(["toy"] * 4)
103
+ ranker = PairwiseHotspotRanker(alpha=0.1).fit(features, labels, queries)
104
+ scores = ranker.decision_function(features)
105
+ ```
106
+
107
+ ## Structure ranking
108
+
109
+ ```bash
110
+ python -m topoppi_hotspot rank-complex \
111
+ --structure input.pdb --chains-a A --chains-b B --partner A \
112
+ --output-dir ranking_output
113
+ ```
114
+
115
+ The unified command is `topoppi hotspot rank-complex`. `--output` is an alias for `--output-dir`. Add `--json` to receive the ranked residues, model information and saved-file locations as JSON on standard output; progress messages go to standard error.
116
+
117
+ Choose a new output directory for each ranking. The CLI preserves existing ranking files; an empty directory can be reused after a failed calculation.
118
+
119
+ `--partner` must match a complete input partner group. Comma-separated groups support multichain partners. The optional `--model-dir fitted_model` selects a custom model. Its directory contains `model.json` and the coefficient or estimator files described by that metadata. Supported kinds are `mutation_surface`, `linear`, `mlp`, `xgb`, `graph`, `block_linear`, and `fusion`. See the [official model card](https://github.com/GeraltZeroZhong/TopoPPI/blob/HEAD/plugins/hotspot/topoppi_hotspot/data/mutation_surface/MODEL_CARD.md) for the bundled model's training source, feature definitions, units and applicability.
120
+
121
+ Models that use sequence features additionally require `--embedding-registry` or `--esmc-checkpoint`. Fresh embedding inference defaults to CPU; `--device cuda` explicitly selects CUDA. The ESMC implementation uses the 600M architecture and limits observed chains to 1,000 residues.
122
+
123
+ The bundled model saves:
124
+
125
+ | File | Content |
126
+ | --- | --- |
127
+ | `rankings.csv` | Residue identity, alanine substitution, predicted ΔΔG in kcal/mol, ranking score, tied rank interval, within-partner percentile, footprint area, and coverage flags |
128
+ | `candidate_coverage.csv` | Structural, interface-context, candidate, and missing-feature counts |
129
+ | `metadata.json` | Input locations, feature protocol, model requirements, partner groups, and scoring semantics |
130
+ | `features.csv` | The bundled model's 552 inputs for each candidate |
131
+ | `representation.bin` | The encoded residue-aware UV representation used by the bundled model |
132
+ | `interface.npz` | Native geometry for reopening results and linked surface views |
133
+
134
+ Feature calculation uses both complete wild-type (WT) partners, including native alanines. Ranked candidates are standard non-alanine residues on the selected partner with a heavy atom within 6 Å of the other partner. The bundled radial basis function (RBF) kernel ridge regressor receives 430 physicochemical mutation descriptors, temperature divided by 298.15 K, and 121 spatial descriptors. Spatial features are computed after decoding a residue-aware UV representation with a byte budget equal to one quarter of the uncompressed native source size. `rank_score` equals `predicted_ddg_kcal_mol` for this model.
135
+
136
+ Mesh surface areas describe the Gaussian surface; solvent-accessible surface area (SASA) is calculated separately with the Shrake–Rupley algorithm. Custom models use the feature protocol and score meaning recorded in their metadata.
137
+
138
+ ## Python structure ranking
139
+
140
+ Use the bundled model directly from Python:
141
+
142
+ ```python
143
+ from topoppi_hotspot.inference import rank_complex
144
+
145
+ ranking, metadata = rank_complex(
146
+ "input.pdb", "A", "B", partner="A", output_dir="ranking_output",
147
+ )
148
+ print(ranking[["residue_key", "predicted_ddg_kcal_mol", "rank_min", "rank_max"]])
149
+ ```
150
+
151
+ `ranking` is a pandas DataFrame; `metadata` records the model, units and feature protocol. `output_dir` selects the folder for the saved results. Supply `optcuts_bin` to use a specific OptCuts executable, or `model_dir` to select a custom model.
152
+
153
+ ## Shared Core geometry
154
+
155
+ Installation registers `hotspot.rank`, the Hotspot desktop workspace, and the `topoppi hotspot` command through
156
+ `topoppi.plugins`. Existing `topoppi-hotspot` and `rank_complex` calls remain valid.
157
+ The object API reuses Core atoms, native surfaces, SASA input and sequence keys:
158
+
159
+ ```python
160
+ import topoppi
161
+ from topoppi_hotspot.inference import model_requirements
162
+
163
+ protocol = model_requirements()["feature_protocol"]
164
+ geometry = topoppi.compute_geometry(
165
+ topoppi.get_interface(topoppi.load_structure("input.cif"), "A", "B"),
166
+ surface=topoppi.SurfaceConfig(**protocol["surface"]),
167
+ topology=topoppi.TopologyConfig(**protocol["topology"]),
168
+ )
169
+ ranking, metadata = topoppi.run(
170
+ "hotspot.rank", geometry, partner="A", output_dir="shared_geometry_ranking",
171
+ )
172
+ ```
173
+
174
+ For a custom model, pass its directory to both `model_requirements` and `topoppi.run` using `model_dir=`.
175
+
176
+ The capability accepts `partner`, `model_dir`, `output_dir`, `embedding_registry`,
177
+ `esmc_checkpoint`, `optcuts_bin` and `device` from `ExecutionContext.plugin_config["hotspot"]`;
178
+ explicit non-None arguments take precedence. Output may also use the context's
179
+ `output_dir`. Geometry must contain both surfaces and match the fitted model's
180
+ protocol. Incompatible geometry raises an error; prepare geometry with the model's
181
+ settings before retrying. Fresh sequence registries use Core-selected atoms for
182
+ both PDB and mmCIF input.
183
+
184
+ ## Python modules
185
+
186
+ | Modules | Purpose |
187
+ | --- | --- |
188
+ | `features`, `partner_features`, `relative_features` | Residue chemistry, contacts, surface geometry, and interface-relative normalization |
189
+ | `mesh_diffusion`, `footprint_diffusion`, `surface_rim`, `paired_surface_features` | Mesh and graph diffusion, rim distances, and cross-partner context |
190
+ | `solvent_accessibility` | Isolated-partner, bound-complex, and buried residue SASA |
191
+ | `ranking_models`, `block_ranking`, `nonlinear_ranking`, `graph_ranking` | Trainable ranking estimators |
192
+ | `ranking_metrics`, `evaluation`, `organization` | Ranking metrics, grouped evaluation, and spatial organization |
193
+ | `graph_io`, `graph_operators`, `representations`, `feature_controls` | Array loading, graph alignment, normalization, and feature controls |
194
+ | `model_io`, `rank_fusion`, `inference`, `sequence_embeddings` | Model loading, rank aggregation, structure scoring, and explicit checkpoint inference |
195
+
196
+ The amino-acid tables in `features` use the Kyte-Doolittle hydropathy scale and Zamyatnin residue-volume values. Feature extraction uses these fixed reference descriptors. Pairwise training pairs positive and negative examples within each query and gives queries equal weight.
197
+
198
+ ## Development
199
+
200
+ Run the independent synthetic checks from the repository root:
201
+
202
+ ```bash
203
+ PYTHONPATH=src:plugins/affinity:plugins/hotspot python -m pytest plugins/hotspot/tests -q
204
+ ```
205
+
206
+ Tests construct small numerical arrays and use the bundled synthetic two-chain PDB fixture. They check graph alignment, conservation, invariance, scaling fitted on training data, serialization, normalization, and inference dispatch. Optional neural tests skip when PyTorch is unavailable. Contributions should preserve feature names, units, seeds, portable model formats, and meaningful synthetic assertions.
207
+
208
+ Import normalization from `representations`, partner-relative features from `partner_features`, graph mapping from `graph_operators`, and SASA from `solvent_accessibility`. Existing portable model kinds, metadata keys, feature names, and `rank-complex` arguments remain supported.
209
+
210
+ The distribution includes the MIT license, the bundled model and synthetic tests.
@@ -0,0 +1,189 @@
1
+ # TopoPPI Hotspot
2
+
3
+ TopoPPI Hotspot ranks interface residues within a selected binding partner by predicting the binding free-energy change of each alanine substitution. Its bundled model combines physicochemical mutation descriptors with spatial descriptors recovered from a residue-aware UV representation. Inputs are a structure and the complete chain groups forming the two partners. You can also supply a compatible fitted model.
4
+
5
+ ## Installation
6
+
7
+ Install TopoPPI Hotspot from PyPI with Python 3.10.
8
+
9
+ ```sh
10
+ python -m pip install topoppi-hotspot
11
+ ```
12
+
13
+ For development, run this command from the repository root with Core installed.
14
+
15
+ ```bash
16
+ python -m pip install -e ./plugins/affinity -e ./plugins/hotspot
17
+ ```
18
+
19
+ Hotspot installs the Affinity package for shared mutation features and the Core `representation` extra for surface encoding. The bundled model also requires native OptCuts; follow the [platform installation instructions](https://github.com/GeraltZeroZhong/TopoPPI/blob/HEAD/README.md#optcuts-cannot-be-found). Published pip installations can use `topoppi-install-optcuts` on supported platforms. Set `TOPOPPI_OPTCUTS_BIN` to an existing executable, or pass `--optcuts-bin` to the ranking command. Once OptCuts and the Python dependencies are installed, prediction runs offline on CPU using the bundled weights.
20
+
21
+ The package uses NumPy, SciPy, pandas, Biopython, and scikit-learn through its dependencies. Optional extras enable PyTorch neural rankers (`neural`), XGBoost (`xgboost`), and ESMC embeddings (`sequence`). Embedding inference requires an explicit local checkpoint.
22
+
23
+ ## Desktop workflow
24
+
25
+ Start `topoppi-gui`, open **Binding analysis**, and choose **Rank hotspots**. The
26
+ Analysis menu and **Hotspot ranking** in **Plugins** also open the workspace directly. The structure and
27
+ partner chain groups are filled from the main window; **Use main selection**
28
+ refreshes them after a change.
29
+
30
+ 1. Choose the complete partner to rank. Leave **Custom model (optional)** empty to use the bundled model; select a folder containing `model.json` to use your own model.
31
+ 2. Choose a new results folder. Sequence models also use a prepared embedding registry under **Sequence model options**.
32
+ 3. Select **Rank residues**. The calculation runs on CPU, displays progress, and can be cancelled.
33
+ 4. Review the ranked table, select one or more residues, and choose **Show ranked surface** to color the native 3D interface in the main canvas. All selected residues with a native surface footprint are highlighted together; a residue without a footprint remains available in the table for variant creation.
34
+ 5. Export the full ranking table, or use **Export residue values...** for a `residue,value` annotation CSV that can color an existing Core atlas.
35
+ 6. Select one or more residues with Ctrl/Cmd-click or Shift-click and choose **Create variants...** to continue in Affinity. Choose separate single substitutions or one joint variant. The selected residues retain their author chain IDs, residue numbers, insertion codes, and wild-type identities. Review the prepared variants, then choose **Predict** in Affinity to run the prediction.
36
+
37
+ The shared task navigation connects hotspot ranking, binding affinity, and mutation
38
+ effects using the current structure and partner input fields. **Create variants...**
39
+ continues from the displayed ranking, using its saved structure and partner groups
40
+ even when the next ranking's input fields have been edited.
41
+ Variant creation requires Affinity to be enabled. Saved rankings can still be
42
+ reviewed and exported without it.
43
+
44
+ For the bundled model, higher predicted ΔΔG values rank first. Positive values
45
+ indicate weaker binding after alanine substitution. Predictions use a reference
46
+ temperature of 298.15 K. Native alanines remain part of the feature context.
47
+ The table shows tied ranks and coverage details where relevant; custom scores
48
+ follow the selected model's documented scope.
49
+
50
+ Compatible geometry from the main workspace is reused. The model's surface and
51
+ topology settings determine any additional geometry computation. Desktop runs
52
+ save `interface.npz` alongside the ranking files, so **Open saved ranking...**
53
+ can recover the table and surface after the original structure or model moves.
54
+ Earlier CLI output folders can still be opened as tables. Existing result files
55
+ are preserved; **New results folder** creates a fresh destination for another run.
56
+ Closing and reopening the Hotspot window in the same TopoPPI session retains
57
+ unfinished model, output and rank-partner settings, alongside the displayed
58
+ result and selected residues. The next ranking's settings remain separate from
59
+ the source and selected partner of the displayed result.
60
+
61
+ Custom sequence models use local fitted models and prepared embedding registries.
62
+ The Python and CLI interfaces also support explicit local ESMC checkpoints.
63
+
64
+ ## Synthetic quick start
65
+
66
+ From a source checkout, run the fitting example.
67
+
68
+ ```bash
69
+ python plugins/hotspot/examples/synthetic_ranking.py
70
+ python -m topoppi_hotspot --help
71
+ ```
72
+
73
+ The example constructs eight one-dimensional feature rows and two invented queries. It fits a pairwise ranker and prints within-query scores and average precision. Its labels follow the sign of the feature by construction; the output demonstrates the API.
74
+
75
+ ```python
76
+ import numpy as np
77
+ from topoppi_hotspot.ranking_models import PairwiseHotspotRanker
78
+
79
+ features = np.array([[-2.0], [-1.0], [1.0], [2.0]])
80
+ labels = np.array([0, 0, 1, 1])
81
+ queries = np.array(["toy"] * 4)
82
+ ranker = PairwiseHotspotRanker(alpha=0.1).fit(features, labels, queries)
83
+ scores = ranker.decision_function(features)
84
+ ```
85
+
86
+ ## Structure ranking
87
+
88
+ ```bash
89
+ python -m topoppi_hotspot rank-complex \
90
+ --structure input.pdb --chains-a A --chains-b B --partner A \
91
+ --output-dir ranking_output
92
+ ```
93
+
94
+ The unified command is `topoppi hotspot rank-complex`. `--output` is an alias for `--output-dir`. Add `--json` to receive the ranked residues, model information and saved-file locations as JSON on standard output; progress messages go to standard error.
95
+
96
+ Choose a new output directory for each ranking. The CLI preserves existing ranking files; an empty directory can be reused after a failed calculation.
97
+
98
+ `--partner` must match a complete input partner group. Comma-separated groups support multichain partners. The optional `--model-dir fitted_model` selects a custom model. Its directory contains `model.json` and the coefficient or estimator files described by that metadata. Supported kinds are `mutation_surface`, `linear`, `mlp`, `xgb`, `graph`, `block_linear`, and `fusion`. See the [official model card](https://github.com/GeraltZeroZhong/TopoPPI/blob/HEAD/plugins/hotspot/topoppi_hotspot/data/mutation_surface/MODEL_CARD.md) for the bundled model's training source, feature definitions, units and applicability.
99
+
100
+ Models that use sequence features additionally require `--embedding-registry` or `--esmc-checkpoint`. Fresh embedding inference defaults to CPU; `--device cuda` explicitly selects CUDA. The ESMC implementation uses the 600M architecture and limits observed chains to 1,000 residues.
101
+
102
+ The bundled model saves:
103
+
104
+ | File | Content |
105
+ | --- | --- |
106
+ | `rankings.csv` | Residue identity, alanine substitution, predicted ΔΔG in kcal/mol, ranking score, tied rank interval, within-partner percentile, footprint area, and coverage flags |
107
+ | `candidate_coverage.csv` | Structural, interface-context, candidate, and missing-feature counts |
108
+ | `metadata.json` | Input locations, feature protocol, model requirements, partner groups, and scoring semantics |
109
+ | `features.csv` | The bundled model's 552 inputs for each candidate |
110
+ | `representation.bin` | The encoded residue-aware UV representation used by the bundled model |
111
+ | `interface.npz` | Native geometry for reopening results and linked surface views |
112
+
113
+ Feature calculation uses both complete wild-type (WT) partners, including native alanines. Ranked candidates are standard non-alanine residues on the selected partner with a heavy atom within 6 Å of the other partner. The bundled radial basis function (RBF) kernel ridge regressor receives 430 physicochemical mutation descriptors, temperature divided by 298.15 K, and 121 spatial descriptors. Spatial features are computed after decoding a residue-aware UV representation with a byte budget equal to one quarter of the uncompressed native source size. `rank_score` equals `predicted_ddg_kcal_mol` for this model.
114
+
115
+ Mesh surface areas describe the Gaussian surface; solvent-accessible surface area (SASA) is calculated separately with the Shrake–Rupley algorithm. Custom models use the feature protocol and score meaning recorded in their metadata.
116
+
117
+ ## Python structure ranking
118
+
119
+ Use the bundled model directly from Python:
120
+
121
+ ```python
122
+ from topoppi_hotspot.inference import rank_complex
123
+
124
+ ranking, metadata = rank_complex(
125
+ "input.pdb", "A", "B", partner="A", output_dir="ranking_output",
126
+ )
127
+ print(ranking[["residue_key", "predicted_ddg_kcal_mol", "rank_min", "rank_max"]])
128
+ ```
129
+
130
+ `ranking` is a pandas DataFrame; `metadata` records the model, units and feature protocol. `output_dir` selects the folder for the saved results. Supply `optcuts_bin` to use a specific OptCuts executable, or `model_dir` to select a custom model.
131
+
132
+ ## Shared Core geometry
133
+
134
+ Installation registers `hotspot.rank`, the Hotspot desktop workspace, and the `topoppi hotspot` command through
135
+ `topoppi.plugins`. Existing `topoppi-hotspot` and `rank_complex` calls remain valid.
136
+ The object API reuses Core atoms, native surfaces, SASA input and sequence keys:
137
+
138
+ ```python
139
+ import topoppi
140
+ from topoppi_hotspot.inference import model_requirements
141
+
142
+ protocol = model_requirements()["feature_protocol"]
143
+ geometry = topoppi.compute_geometry(
144
+ topoppi.get_interface(topoppi.load_structure("input.cif"), "A", "B"),
145
+ surface=topoppi.SurfaceConfig(**protocol["surface"]),
146
+ topology=topoppi.TopologyConfig(**protocol["topology"]),
147
+ )
148
+ ranking, metadata = topoppi.run(
149
+ "hotspot.rank", geometry, partner="A", output_dir="shared_geometry_ranking",
150
+ )
151
+ ```
152
+
153
+ For a custom model, pass its directory to both `model_requirements` and `topoppi.run` using `model_dir=`.
154
+
155
+ The capability accepts `partner`, `model_dir`, `output_dir`, `embedding_registry`,
156
+ `esmc_checkpoint`, `optcuts_bin` and `device` from `ExecutionContext.plugin_config["hotspot"]`;
157
+ explicit non-None arguments take precedence. Output may also use the context's
158
+ `output_dir`. Geometry must contain both surfaces and match the fitted model's
159
+ protocol. Incompatible geometry raises an error; prepare geometry with the model's
160
+ settings before retrying. Fresh sequence registries use Core-selected atoms for
161
+ both PDB and mmCIF input.
162
+
163
+ ## Python modules
164
+
165
+ | Modules | Purpose |
166
+ | --- | --- |
167
+ | `features`, `partner_features`, `relative_features` | Residue chemistry, contacts, surface geometry, and interface-relative normalization |
168
+ | `mesh_diffusion`, `footprint_diffusion`, `surface_rim`, `paired_surface_features` | Mesh and graph diffusion, rim distances, and cross-partner context |
169
+ | `solvent_accessibility` | Isolated-partner, bound-complex, and buried residue SASA |
170
+ | `ranking_models`, `block_ranking`, `nonlinear_ranking`, `graph_ranking` | Trainable ranking estimators |
171
+ | `ranking_metrics`, `evaluation`, `organization` | Ranking metrics, grouped evaluation, and spatial organization |
172
+ | `graph_io`, `graph_operators`, `representations`, `feature_controls` | Array loading, graph alignment, normalization, and feature controls |
173
+ | `model_io`, `rank_fusion`, `inference`, `sequence_embeddings` | Model loading, rank aggregation, structure scoring, and explicit checkpoint inference |
174
+
175
+ The amino-acid tables in `features` use the Kyte-Doolittle hydropathy scale and Zamyatnin residue-volume values. Feature extraction uses these fixed reference descriptors. Pairwise training pairs positive and negative examples within each query and gives queries equal weight.
176
+
177
+ ## Development
178
+
179
+ Run the independent synthetic checks from the repository root:
180
+
181
+ ```bash
182
+ PYTHONPATH=src:plugins/affinity:plugins/hotspot python -m pytest plugins/hotspot/tests -q
183
+ ```
184
+
185
+ Tests construct small numerical arrays and use the bundled synthetic two-chain PDB fixture. They check graph alignment, conservation, invariance, scaling fitted on training data, serialization, normalization, and inference dispatch. Optional neural tests skip when PyTorch is unavailable. Contributions should preserve feature names, units, seeds, portable model formats, and meaningful synthetic assertions.
186
+
187
+ Import normalization from `representations`, partner-relative features from `partner_features`, graph mapping from `graph_operators`, and SASA from `solvent_accessibility`. Existing portable model kinds, metadata keys, feature names, and `rank-complex` arguments remain supported.
188
+
189
+ The distribution includes the MIT license, the bundled model and synthetic tests.
@@ -0,0 +1,18 @@
1
+ """Fit and score two invented residue queries using an analytical toy feature.
2
+
3
+ The eight feature rows and labels are constructed here without structural or
4
+ experimental records. Each query has two positives and two negatives.
5
+ """
6
+ import numpy as np
7
+ from topoppi_hotspot.ranking_metrics import ranking_metrics
8
+ from topoppi_hotspot.ranking_models import PairwiseHotspotRanker
9
+
10
+ features = np.array([[-2.], [-1.], [1.], [2.], [-3.], [-1.], [1.], [3.]])
11
+ labels = np.array([0, 0, 1, 1, 0, 0, 1, 1])
12
+ queries = np.array(["toy_a"] * 4 + ["toy_b"] * 4)
13
+ model = PairwiseHotspotRanker(alpha=0.1).fit(features, labels, queries)
14
+ scores = model.decision_function(features)
15
+ for query in np.unique(queries):
16
+ selected = queries == query
17
+ values = ranking_metrics(labels[selected], scores[selected])
18
+ print(f"{query}: scores={scores[selected].round(3).tolist()}, AP={values['AP']:.1f}")
@@ -0,0 +1,31 @@
1
+ [build-system]
2
+ requires = ["setuptools>=77", "wheel"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "topoppi-hotspot"
7
+ version = "3.0.0"
8
+ description = "Residue feature extraction and selected-partner ranking for TopoPPI."
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ license-files = ["LICENSE"]
12
+ requires-python = ">=3.10,<3.11"
13
+ dependencies = ["topoppi[representation]>=3.0.0", "topoppi-affinity>=3.0.0", "pandas>=2", "scikit-learn>=1.3", "joblib>=1.2"]
14
+
15
+ [project.optional-dependencies]
16
+ neural = ["torch>=2.2"]
17
+ sequence = ["esm>=3.2.1"]
18
+ xgboost = ["xgboost>=3.2"]
19
+
20
+ [project.entry-points."topoppi.plugins"]
21
+ hotspot = "topoppi_hotspot.plugin:plugin"
22
+
23
+ [project.scripts]
24
+ topoppi-hotspot = "topoppi_hotspot.cli:main"
25
+
26
+ [tool.setuptools.packages.find]
27
+ where = ["."]
28
+ include = ["topoppi_hotspot*"]
29
+
30
+ [tool.setuptools.package-data]
31
+ topoppi_hotspot = ["data/mutation_surface/*.json", "data/mutation_surface/*.npz", "data/mutation_surface/*.md"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,3 @@
1
+ # Synthetic structure fixture
2
+
3
+ `tiny_complex.pdb` contains four manually constructed residues arranged on two toy chains. It is copied from the Core synthetic fixture for standalone package testing.
@@ -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
@@ -0,0 +1,82 @@
1
+ import numpy as np
2
+ import pytest
3
+ from sklearn.base import clone
4
+ from topoppi_hotspot.block_ranking import BlockPairwiseRanker
5
+
6
+
7
+ def _data():
8
+ geometry = np.array([[-2., 1.], [2., 1.], [-1., 4.], [3., 4.], [20., -2.]])
9
+ embedding = np.array([[-3., 1., 0.], [3., -1., 0.], [-2., 1., 0.], [2., -1., 0.], [0., 0., 0.]])
10
+ return geometry, embedding, np.array([0, 1, 0, 1, 1]), np.array(["a", "a", "b", "b", "single"])
11
+
12
+
13
+ def test_train_only_scaling_has_declared_block_norms_and_ignores_prediction_data():
14
+ geometry, embedding, y, queries = _data()
15
+ model = BlockPairwiseRanker().fit(geometry, embedding, y, queries)
16
+ np.testing.assert_allclose(model.geometry_scaler_.mean_, geometry.mean(axis=0))
17
+ assert model.embedding_scale_ == pytest.approx(np.sqrt(np.mean(np.sum(embedding ** 2, axis=1))))
18
+ transformed = model._transform(geometry, embedding)
19
+ assert np.mean(np.sum(transformed[:, :2] ** 2, axis=1)) == pytest.approx(1.)
20
+ assert np.mean(np.sum(transformed[:, 2:] ** 2, axis=1)) == pytest.approx(1.)
21
+ assert model.training_summary_["n_training_nodes"] == len(y)
22
+ assert model.training_summary_["n_informative_queries"] == 2
23
+ before = model.decision_function(geometry, embedding)
24
+ model.decision_function(geometry * 10000, embedding * 10000)
25
+ np.testing.assert_array_equal(model.decision_function(geometry, embedding), before)
26
+ assert clone(model).get_params() == model.get_params()
27
+
28
+
29
+ def test_embedding_units_and_node_order_do_not_change_the_fitted_function():
30
+ geometry, embedding, y, queries = _data()
31
+ model = BlockPairwiseRanker().fit(geometry, embedding, y, queries)
32
+ rescaled = clone(model).fit(geometry, embedding * 1000, y, queries)
33
+ scores = model.decision_function(geometry, embedding)
34
+ np.testing.assert_allclose(rescaled.decision_function(geometry, embedding * 1000), scores, atol=1e-10)
35
+ order = np.array([4, 2, 1, 3, 0])
36
+ np.testing.assert_allclose(model.decision_function(geometry[order], embedding[order]), scores[order])
37
+ reordered = clone(model).fit(geometry[order], embedding[order], y[order], queries[order])
38
+ np.testing.assert_allclose(reordered.decision_function(geometry, embedding), scores, atol=1e-8)
39
+
40
+
41
+ def test_exact_equal_query_objective_and_optimum_gradient():
42
+ # One positive-negative pair in query a, six in query b, and an excluded
43
+ # single-class query. Reconstruct the independently weighted objective.
44
+ embedding = np.array([[-2., 1.], [2., -1.], [-1., 0.], [-2., -1.], [1., 2.], [2., 1.], [3., 0.], [20., -4.]])
45
+ y = np.array([0, 1, 0, 0, 1, 1, 1, 1])
46
+ queries = np.array(["a", "a", "b", "b", "b", "b", "b", "single"])
47
+ model = BlockPairwiseRanker(alpha=.2, tol=1e-12).fit(np.empty((8, 0)), embedding, y, queries)
48
+ standardized = embedding / model.embedding_scale_
49
+
50
+ def objective(coefficient):
51
+ scores = standardized @ coefficient
52
+ first = np.logaddexp(0., scores[0] - scores[1])
53
+ second = np.logaddexp(0., scores[2:4, None] - scores[None, 4:7]).mean()
54
+ return (first + second) / 2 + .2 / 2 * np.dot(coefficient, coefficient)
55
+
56
+ coefficient = model.coef_.ravel()
57
+ assert model.training_summary_["objective"] == pytest.approx(objective(coefficient), abs=1e-12)
58
+ steps = np.eye(len(coefficient)) * 1e-5
59
+ gradient = [(objective(coefficient + step) - objective(coefficient - step)) / 2e-5 for step in steps]
60
+ np.testing.assert_allclose(gradient, 0., atol=1e-7)
61
+
62
+
63
+ @pytest.mark.parametrize("geometry_dimension", [0, 2])
64
+ def test_portable_roundtrip_with_and_without_geometry(tmp_path, geometry_dimension):
65
+ geometry, embedding, y, queries = _data()
66
+ geometry = geometry[:, :geometry_dimension]
67
+ model = BlockPairwiseRanker().fit(geometry, embedding, y, queries)
68
+ model.save(tmp_path)
69
+ restored = BlockPairwiseRanker.load(tmp_path)
70
+ np.testing.assert_array_equal(restored.decision_function(geometry, embedding),
71
+ model.decision_function(geometry, embedding))
72
+ assert restored.get_params() == model.get_params()
73
+ assert restored.training_summary_ == model.training_summary_
74
+
75
+
76
+ def test_zero_embedding_block_is_finite_and_single_class_queries_do_not_cross_pair():
77
+ geometry, embedding, y, queries = _data()
78
+ model = BlockPairwiseRanker().fit(geometry, np.zeros_like(embedding), y, queries)
79
+ assert model.embedding_scale_ == 1.
80
+ assert np.isfinite(model.decision_function(geometry, np.zeros_like(embedding))).all()
81
+ with pytest.raises(ValueError, match="both binary classes"):
82
+ BlockPairwiseRanker().fit(geometry, embedding, y, ["negative", "positive", "negative", "positive", "positive"])