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.
- topoppi_hotspot-3.0.0/LICENSE +21 -0
- topoppi_hotspot-3.0.0/MANIFEST.in +8 -0
- topoppi_hotspot-3.0.0/PKG-INFO +210 -0
- topoppi_hotspot-3.0.0/README.md +189 -0
- topoppi_hotspot-3.0.0/examples/synthetic_ranking.py +18 -0
- topoppi_hotspot-3.0.0/pyproject.toml +31 -0
- topoppi_hotspot-3.0.0/setup.cfg +4 -0
- topoppi_hotspot-3.0.0/tests/fixtures/README.md +3 -0
- topoppi_hotspot-3.0.0/tests/fixtures/tiny_complex.pdb +15 -0
- topoppi_hotspot-3.0.0/tests/test_block_ranking.py +82 -0
- topoppi_hotspot-3.0.0/tests/test_core_contract.py +114 -0
- topoppi_hotspot-3.0.0/tests/test_evaluation.py +43 -0
- topoppi_hotspot-3.0.0/tests/test_feature_controls.py +69 -0
- topoppi_hotspot-3.0.0/tests/test_features.py +66 -0
- topoppi_hotspot-3.0.0/tests/test_footprint_diffusion.py +163 -0
- topoppi_hotspot-3.0.0/tests/test_graph_operators.py +48 -0
- topoppi_hotspot-3.0.0/tests/test_graph_ranking.py +144 -0
- topoppi_hotspot-3.0.0/tests/test_gui.py +526 -0
- topoppi_hotspot-3.0.0/tests/test_gui_workflow.py +159 -0
- topoppi_hotspot-3.0.0/tests/test_inference.py +432 -0
- topoppi_hotspot-3.0.0/tests/test_mesh_diffusion.py +77 -0
- topoppi_hotspot-3.0.0/tests/test_mutation_model.py +55 -0
- topoppi_hotspot-3.0.0/tests/test_nonlinear_ranking.py +124 -0
- topoppi_hotspot-3.0.0/tests/test_organization.py +128 -0
- topoppi_hotspot-3.0.0/tests/test_paired_surface_features.py +35 -0
- topoppi_hotspot-3.0.0/tests/test_partner_features.py +46 -0
- topoppi_hotspot-3.0.0/tests/test_production_model.py +271 -0
- topoppi_hotspot-3.0.0/tests/test_rank_fusion.py +20 -0
- topoppi_hotspot-3.0.0/tests/test_ranking_metrics.py +115 -0
- topoppi_hotspot-3.0.0/tests/test_ranking_models.py +91 -0
- topoppi_hotspot-3.0.0/tests/test_relative_features.py +100 -0
- topoppi_hotspot-3.0.0/tests/test_solvent_accessibility.py +48 -0
- topoppi_hotspot-3.0.0/tests/test_surface_rim.py +50 -0
- topoppi_hotspot-3.0.0/topoppi_hotspot/__init__.py +3 -0
- topoppi_hotspot-3.0.0/topoppi_hotspot/__main__.py +3 -0
- topoppi_hotspot-3.0.0/topoppi_hotspot/block_ranking.py +152 -0
- topoppi_hotspot-3.0.0/topoppi_hotspot/cli.py +68 -0
- topoppi_hotspot-3.0.0/topoppi_hotspot/data/mutation_surface/MODEL_CARD.md +84 -0
- topoppi_hotspot-3.0.0/topoppi_hotspot/data/mutation_surface/model.json +1199 -0
- topoppi_hotspot-3.0.0/topoppi_hotspot/data/mutation_surface/weights.npz +0 -0
- topoppi_hotspot-3.0.0/topoppi_hotspot/evaluation.py +181 -0
- topoppi_hotspot-3.0.0/topoppi_hotspot/feature_controls.py +77 -0
- topoppi_hotspot-3.0.0/topoppi_hotspot/features.py +211 -0
- topoppi_hotspot-3.0.0/topoppi_hotspot/footprint_diffusion.py +244 -0
- topoppi_hotspot-3.0.0/topoppi_hotspot/graph_io.py +18 -0
- topoppi_hotspot-3.0.0/topoppi_hotspot/graph_operators.py +96 -0
- topoppi_hotspot-3.0.0/topoppi_hotspot/graph_ranking.py +228 -0
- topoppi_hotspot-3.0.0/topoppi_hotspot/gui.py +501 -0
- topoppi_hotspot-3.0.0/topoppi_hotspot/gui_workflow.py +141 -0
- topoppi_hotspot-3.0.0/topoppi_hotspot/inference.py +436 -0
- topoppi_hotspot-3.0.0/topoppi_hotspot/mesh_diffusion.py +223 -0
- topoppi_hotspot-3.0.0/topoppi_hotspot/model_io.py +36 -0
- topoppi_hotspot-3.0.0/topoppi_hotspot/mutation_inference.py +126 -0
- topoppi_hotspot-3.0.0/topoppi_hotspot/mutation_model.py +52 -0
- topoppi_hotspot-3.0.0/topoppi_hotspot/nonlinear_ranking.py +257 -0
- topoppi_hotspot-3.0.0/topoppi_hotspot/organization.py +276 -0
- topoppi_hotspot-3.0.0/topoppi_hotspot/paired_surface_features.py +113 -0
- topoppi_hotspot-3.0.0/topoppi_hotspot/partner_features.py +101 -0
- topoppi_hotspot-3.0.0/topoppi_hotspot/physical_features.py +102 -0
- topoppi_hotspot-3.0.0/topoppi_hotspot/plugin.py +21 -0
- topoppi_hotspot-3.0.0/topoppi_hotspot/rank_fusion.py +26 -0
- topoppi_hotspot-3.0.0/topoppi_hotspot/ranking_metrics.py +179 -0
- topoppi_hotspot-3.0.0/topoppi_hotspot/ranking_models.py +152 -0
- topoppi_hotspot-3.0.0/topoppi_hotspot/relative_features.py +123 -0
- topoppi_hotspot-3.0.0/topoppi_hotspot/representations.py +50 -0
- topoppi_hotspot-3.0.0/topoppi_hotspot/resources.py +15 -0
- topoppi_hotspot-3.0.0/topoppi_hotspot/sequence_embeddings.py +108 -0
- topoppi_hotspot-3.0.0/topoppi_hotspot/solvent_accessibility.py +60 -0
- topoppi_hotspot-3.0.0/topoppi_hotspot/surface_rim.py +107 -0
- topoppi_hotspot-3.0.0/topoppi_hotspot.egg-info/PKG-INFO +210 -0
- topoppi_hotspot-3.0.0/topoppi_hotspot.egg-info/SOURCES.txt +73 -0
- topoppi_hotspot-3.0.0/topoppi_hotspot.egg-info/dependency_links.txt +1 -0
- topoppi_hotspot-3.0.0/topoppi_hotspot.egg-info/entry_points.txt +5 -0
- topoppi_hotspot-3.0.0/topoppi_hotspot.egg-info/requires.txt +14 -0
- 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,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,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"])
|