topoppi-affinity 3.0.0__py3-none-any.whl

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 (117) hide show
  1. topoppi_affinity/__init__.py +6 -0
  2. topoppi_affinity/__main__.py +4 -0
  3. topoppi_affinity/analytic_curvature.py +143 -0
  4. topoppi_affinity/analytic_preprocessing.py +82 -0
  5. topoppi_affinity/artifacts.py +66 -0
  6. topoppi_affinity/atlas_review/__init__.py +1 -0
  7. topoppi_affinity/atlas_review/comparison.py +209 -0
  8. topoppi_affinity/atlas_review/context.py +117 -0
  9. topoppi_affinity/atlas_review/gui.py +459 -0
  10. topoppi_affinity/atlas_review/paired.py +173 -0
  11. topoppi_affinity/atlas_review/session.py +111 -0
  12. topoppi_affinity/attribution_features.py +220 -0
  13. topoppi_affinity/author_references.py +207 -0
  14. topoppi_affinity/ba_cycle_prior.py +224 -0
  15. topoppi_affinity/benchmark_data.py +243 -0
  16. topoppi_affinity/benchmark_features.py +271 -0
  17. topoppi_affinity/benchmark_models.py +433 -0
  18. topoppi_affinity/benchmark_reporting.py +382 -0
  19. topoppi_affinity/bilinear_features.py +54 -0
  20. topoppi_affinity/bilinear_kernel.py +15 -0
  21. topoppi_affinity/bindpred_baseline.py +169 -0
  22. topoppi_affinity/cached_author_references.py +388 -0
  23. topoppi_affinity/capabilities.py +30 -0
  24. topoppi_affinity/cath_protocol.py +82 -0
  25. topoppi_affinity/cli.py +323 -0
  26. topoppi_affinity/comparison.py +130 -0
  27. topoppi_affinity/data/example/1bvk.pdb +6076 -0
  28. topoppi_affinity/data/example/README.md +22 -0
  29. topoppi_affinity/data/example/variants.csv +3 -0
  30. topoppi_affinity/data/model_catalog.json +83 -0
  31. topoppi_affinity/data/production/MODEL_CARD.md +40 -0
  32. topoppi_affinity/data/production/absolute/model.json +515 -0
  33. topoppi_affinity/data/production/absolute/weights.npz +0 -0
  34. topoppi_affinity/data/production/mutation/model.json +470 -0
  35. topoppi_affinity/data/production/mutation/weights.npz +0 -0
  36. topoppi_affinity/data.py +102 -0
  37. topoppi_affinity/embedding_baselines.py +189 -0
  38. topoppi_affinity/epistasis.py +232 -0
  39. topoppi_affinity/evaluation.py +56 -0
  40. topoppi_affinity/expanded_references.py +259 -0
  41. topoppi_affinity/external_absolute.py +419 -0
  42. topoppi_affinity/external_energy.py +103 -0
  43. topoppi_affinity/external_inputs.py +104 -0
  44. topoppi_affinity/external_mutation.py +255 -0
  45. topoppi_affinity/features.py +327 -0
  46. topoppi_affinity/footprint_controls.py +17 -0
  47. topoppi_affinity/frozen_probes.py +23 -0
  48. topoppi_affinity/frozen_structure.py +199 -0
  49. topoppi_affinity/geometric_scattering.py +79 -0
  50. topoppi_affinity/graph_dataset.py +138 -0
  51. topoppi_affinity/graph_features.py +304 -0
  52. topoppi_affinity/graph_models.py +161 -0
  53. topoppi_affinity/graph_training.py +71 -0
  54. topoppi_affinity/group_dro_baselines.py +102 -0
  55. topoppi_affinity/grouped_fitting.py +105 -0
  56. topoppi_affinity/gui.py +1676 -0
  57. topoppi_affinity/inference.py +273 -0
  58. topoppi_affinity/installer.py +551 -0
  59. topoppi_affinity/integration.py +408 -0
  60. topoppi_affinity/joint_training.py +177 -0
  61. topoppi_affinity/legacy_antisymmetry.py +30 -0
  62. topoppi_affinity/legacy_kernel.py +84 -0
  63. topoppi_affinity/mint_embeddings.py +39 -0
  64. topoppi_affinity/model_metadata.py +91 -0
  65. topoppi_affinity/models.py +108 -0
  66. topoppi_affinity/multipoint.py +27 -0
  67. topoppi_affinity/mutation_ensemble.py +113 -0
  68. topoppi_affinity/mutation_physics.py +159 -0
  69. topoppi_affinity/paired_embeddings.py +86 -0
  70. topoppi_affinity/plugin.py +20 -0
  71. topoppi_affinity/ppb_protocol.py +234 -0
  72. topoppi_affinity/ppiformer_finetune.py +185 -0
  73. topoppi_affinity/proaffinity_inputs.py +306 -0
  74. topoppi_affinity/production.py +101 -0
  75. topoppi_affinity/representation_controls.py +124 -0
  76. topoppi_affinity/residual_artifacts.py +138 -0
  77. topoppi_affinity/residual_baselines.py +139 -0
  78. topoppi_affinity/resources.py +333 -0
  79. topoppi_affinity/runtime.py +31 -0
  80. topoppi_affinity/sequence_baselines.py +244 -0
  81. topoppi_affinity/sequence_embeddings.py +232 -0
  82. topoppi_affinity/splits.py +197 -0
  83. topoppi_affinity/state_kernel.py +82 -0
  84. topoppi_affinity/structure_features.py +79 -0
  85. topoppi_affinity/surface_diffusion.py +180 -0
  86. topoppi_affinity/surface_transport.py +84 -0
  87. topoppi_affinity/thermodynamics.py +42 -0
  88. topoppi_affinity/uv_layout_features.py +348 -0
  89. topoppi_affinity/variant_augmentation.py +56 -0
  90. topoppi_affinity/workflow.py +612 -0
  91. topoppi_affinity-3.0.0.dist-info/METADATA +137 -0
  92. topoppi_affinity-3.0.0.dist-info/RECORD +117 -0
  93. topoppi_affinity-3.0.0.dist-info/WHEEL +5 -0
  94. topoppi_affinity-3.0.0.dist-info/entry_points.txt +5 -0
  95. topoppi_affinity-3.0.0.dist-info/licenses/LICENSE +21 -0
  96. topoppi_affinity-3.0.0.dist-info/top_level.txt +2 -0
  97. topoppi_affinity_tools/README.md +10 -0
  98. topoppi_affinity_tools/__init__.py +6 -0
  99. topoppi_affinity_tools/features/__init__.py +1 -0
  100. topoppi_affinity_tools/features/extract_analytic_features.py +52 -0
  101. topoppi_affinity_tools/features/extract_features.py +113 -0
  102. topoppi_affinity_tools/features/extract_graph_features.py +78 -0
  103. topoppi_affinity_tools/features/extract_prospective_sasa.py +51 -0
  104. topoppi_affinity_tools/features/extract_sequence_embeddings.py +22 -0
  105. topoppi_affinity_tools/features/pool_manifest_embeddings.py +45 -0
  106. topoppi_affinity_tools/features/prepare_analytic_mutation_inputs.py +15 -0
  107. topoppi_affinity_tools/features/refine_graph_curvature.py +63 -0
  108. topoppi_affinity_tools/models/__init__.py +1 -0
  109. topoppi_affinity_tools/models/bundle_mutation_ensemble.py +17 -0
  110. topoppi_affinity_tools/models/fit_absolute_model.py +48 -0
  111. topoppi_affinity_tools/models/predict_absolute_model.py +27 -0
  112. topoppi_affinity_tools/models/predict_attribution.py +35 -0
  113. topoppi_affinity_tools/models/predict_frozen_affinity.py +17 -0
  114. topoppi_affinity_tools/models/predict_mutation_ensemble.py +26 -0
  115. topoppi_affinity_tools/models/predict_residual_affinity.py +23 -0
  116. topoppi_affinity_tools/models/refit_frozen_model.py +29 -0
  117. topoppi_affinity_tools/models/refit_residual_model.py +29 -0
@@ -0,0 +1,6 @@
1
+ """Optional affinity modelling using interface descriptors from the TopoPPI workflow.
2
+
3
+ Importing this package does not load models, weights or GPU dependencies.
4
+ """
5
+
6
+ __version__ = "3.0.0"
@@ -0,0 +1,4 @@
1
+ from topoppi_affinity.cli import main
2
+
3
+ raise SystemExit(main())
4
+
@@ -0,0 +1,143 @@
1
+ """Existing implicit-surface curvature formulas for TopoPPI Gaussian fields.
2
+
3
+ Gaussian derivatives are analytic; atom neighborhoods use the same axis-aligned
4
+ four-sigma truncation as SurfaceGenerator. Goldman (2005), equations 4.1/4.2,
5
+ provide Gaussian/mean curvature at the mesh sample positions. No curvature
6
+ clipping, triangle-area denominator, or change to the cached mesh is applied.
7
+ """
8
+ from __future__ import annotations
9
+
10
+ import json
11
+
12
+ import numpy as np
13
+ from scipy.spatial import cKDTree
14
+
15
+ CURVATURE_PROTOCOL = "analytic_unit_peak_gaussian_box4_v1"
16
+ GRAPH_PROTOCOL = "native_residue_surface_graph_analytic_gaussian_v1"
17
+
18
+
19
+ def gaussian_derivatives(points, atom_coords, *, sigma=1., truncate_sigma=4., chunk_size=2048):
20
+ """Density, gradient, Hessian from sparse nearby atom-point pairs.
21
+
22
+ The native truncation is a box, not a Euclidean ball. Derivatives describe the
23
+ smooth Gaussian terms active locally; the numerical hard cutoff itself has
24
+ discontinuous boundaries. This distinction and mesh interpolation error are
25
+ recorded in the protocol rather than hidden by a fitted curvature transform.
26
+ """
27
+ points, atom_coords = np.asarray(points, dtype=np.float64), np.asarray(atom_coords, dtype=np.float64)
28
+ tree = cKDTree(atom_coords)
29
+ density = np.empty(len(points), dtype=np.float64)
30
+ gradient = np.empty((len(points), 3), dtype=np.float64)
31
+ hessian = np.empty((len(points), 3, 3), dtype=np.float64)
32
+ for start in range(0, len(points), chunk_size):
33
+ query = points[start:start + chunk_size]
34
+ neighbors = tree.query_ball_point(query, truncate_sigma * sigma, p=np.inf)
35
+ counts = np.fromiter((len(items) for items in neighbors), dtype=np.int64)
36
+ rows = np.repeat(np.arange(len(query)), counts)
37
+ columns = np.concatenate(neighbors).astype(np.int64)
38
+ delta = query[rows] - atom_coords[columns]
39
+ phi = np.exp(-np.einsum("ij,ij->i", delta, delta) / (2. * sigma**2))
40
+ total = np.bincount(rows, weights=phi, minlength=len(query))
41
+ density[start:start + len(query)] = total
42
+ for axis in range(3):
43
+ gradient[start:start + len(query), axis] = np.bincount(
44
+ rows, weights=-phi * delta[:, axis] / sigma**2, minlength=len(query))
45
+ for other in range(axis, 3):
46
+ values = np.bincount(rows, weights=phi * delta[:, axis] * delta[:, other] / sigma**4,
47
+ minlength=len(query))
48
+ if axis == other:
49
+ values -= total / sigma**2
50
+ hessian[start:start + len(query), axis, other] = values
51
+ hessian[start:start + len(query), other, axis] = values
52
+ return density, gradient, hessian
53
+
54
+
55
+ def implicit_curvatures(gradient, hessian):
56
+ """Goldman Gaussian and signed mean curvature, without Hessian inversion."""
57
+ cofactors = np.stack([np.cross(hessian[:, 1], hessian[:, 2]),
58
+ np.cross(hessian[:, 2], hessian[:, 0]),
59
+ np.cross(hessian[:, 0], hessian[:, 1])], axis=1)
60
+ norm2 = np.einsum("ij,ij->i", gradient, gradient)
61
+ if np.any(norm2 == 0):
62
+ raise ValueError("Implicit curvature is undefined at zero-gradient points")
63
+ gaussian = np.einsum("ni,nij,nj->n", gradient, cofactors, gradient) / norm2**2
64
+ mean = (np.einsum("ni,nij,nj->n", gradient, hessian, gradient)
65
+ - norm2 * np.trace(hessian, axis1=1, axis2=2)) / (2. * norm2**1.5)
66
+ return gaussian, mean
67
+
68
+
69
+ def gaussian_curvature(points, atom_coords, *, sigma=1., truncate_sigma=4.):
70
+ density, gradient, hessian = gaussian_derivatives(points, atom_coords, sigma=sigma, truncate_sigma=truncate_sigma)
71
+ gaussian, _ = implicit_curvatures(gradient, hessian)
72
+ return gaussian, {"protocol": CURVATURE_PROTOCOL, "sigma_angstrom": sigma,
73
+ "truncate_sigma_box": truncate_sigma, "gradient_norm_min": float(np.linalg.norm(gradient, axis=1).min()),
74
+ "density_min": float(density.min()), "density_max": float(density.max()),
75
+ "gaussian_min": float(gaussian.min()), "gaussian_max": float(gaussian.max()),
76
+ "sampling": "native mesh vertices; no level-set projection or clipping"}
77
+
78
+
79
+ def replace_graph_curvature(graph, structure_path):
80
+ """Replace only the two Gaussian-curvature columns on a supplied WT/MT graph."""
81
+ from topoppi.atlas.footprints import mesh_vertex_residue_labels, source_atom_residue_labels
82
+ from topoppi.config import SurfaceConfig
83
+ from topoppi.io.io_loader import PDBLoader
84
+ from topoppi.mesh.surface import SurfaceGenerator
85
+
86
+ from topoppi_affinity.features import _group_data
87
+ from topoppi_affinity.graph_features import FEATURE_NAMES, _vertex_mass
88
+
89
+ result = {key: value.copy() for key, value in graph.items()}
90
+ mean_column = FEATURE_NAMES.index("surface.gaussian_curvature_mean")
91
+ std_column = FEATURE_NAMES.index("surface.gaussian_curvature_std")
92
+ result["x"][:, [mean_column, std_column]] = 0.
93
+ lookup = {str(key): index for index, key in enumerate(graph["residue_key"])}
94
+ loader = PDBLoader(str(structure_path))
95
+ reports = []
96
+ for partner in (0, 1):
97
+ chains = tuple(np.unique(graph["chain"][graph["side"] == partner]).tolist())
98
+ coordinates, atoms = _group_data(loader, chains)
99
+ config = SurfaceConfig()
100
+ mesh = SurfaceGenerator(coordinates, config=config).generate_mesh()
101
+ if mesh is None:
102
+ raise ValueError(f"Cannot reconstruct native side {partner} mesh for analytic curvature")
103
+ mass = _vertex_mass(mesh)
104
+ labels = mesh_vertex_residue_labels(mesh, source_atom_residue_labels(atoms))
105
+ nodes = np.asarray([lookup[str(label)] for label in labels], dtype=np.int64)
106
+ curvature, report = gaussian_curvature(mesh.vertices, coordinates, sigma=config.sigma)
107
+ for node in np.unique(nodes):
108
+ selected = nodes == node
109
+ weights, values = mass[selected], curvature[selected]
110
+ if not weights.sum():
111
+ continue
112
+ mean = np.average(values, weights=weights)
113
+ result["x"][node, mean_column] = mean
114
+ result["x"][node, std_column] = np.sqrt(np.average((values - mean)**2, weights=weights))
115
+ reports.append(report)
116
+ metadata = json.loads(str(graph["metadata_json"]))
117
+ metadata.update(protocol=GRAPH_PROTOCOL, curvature_method="analytic_gaussian", analytic_curvature=reports,
118
+ replaced_columns=[FEATURE_NAMES[mean_column], FEATURE_NAMES[std_column]])
119
+ result["metadata_json"] = np.asarray(json.dumps(metadata))
120
+ return result
121
+
122
+
123
+ def update_pooled_curvature(vector, names, graph, *, target, mutations=""):
124
+ """Change exactly the pooled slots affected by the two replaced graph columns."""
125
+ from topoppi_affinity.graph_features import mutant_node_features
126
+
127
+ result = np.asarray(vector).copy()
128
+ lookup = {str(name): index for index, name in enumerate(names)}
129
+ curvature = graph["x"][:, 34:36].astype(np.float64)
130
+ if target == "pkd":
131
+ for statistic in ("mean", "sum", "std"):
132
+ left, right = [getattr(curvature[graph["side"] == partner], statistic)(axis=0) for partner in (0, 1)]
133
+ values = np.concatenate([left + right, np.abs(left - right)])
134
+ for index, value in zip((4, 5, 19, 20), values, strict=True):
135
+ result[lookup[f"surface.{statistic}.sum_absdiff.{index}"]] = value
136
+ else:
137
+ mutant, _, mask = mutant_node_features(graph, mutations)
138
+ delta = mutant[mask, :26].astype(np.float64) - graph["x"][mask, :26].astype(np.float64)
139
+ products = np.einsum("ni,nj->ij", delta, curvature[mask])
140
+ for chemical in range(26):
141
+ for column in range(2):
142
+ result[lookup[f"surface.chemical_delta_context.{chemical * 15 + 4 + column}"]] = products[chemical, column]
143
+ return result
@@ -0,0 +1,82 @@
1
+ """Analytic-curvature feature preprocessing for supplied structures."""
2
+ from __future__ import annotations
3
+
4
+ import json
5
+ import subprocess
6
+ import sys
7
+ from functools import lru_cache
8
+ from pathlib import Path
9
+
10
+ import numpy as np
11
+ import pandas as pd
12
+ from topoppi_affinity_tools import tool_file
13
+
14
+ from topoppi_affinity.analytic_curvature import update_pooled_curvature
15
+ from topoppi_affinity.embedding_baselines import zero_surface_slots
16
+ from topoppi_affinity.frozen_probes import load_features
17
+ from topoppi_affinity.graph_features import load_graph
18
+
19
+ CURVATURE = "analytic_Gaussian_Goldman"
20
+ PREPROCESSING = {
21
+ "curvature": CURVATURE,
22
+ "field": "native unit-peak Gaussian sum; sigma=1 Angstrom; active axis-aligned 4-sigma atom support",
23
+ "geometry": "same native unsmoothed mesh, vertex area and residue footprint identity",
24
+ "derivatives": "analytic gradient and Hessian; Goldman implicit Gaussian curvature formula",
25
+ "replaced_graph_columns": ["surface.gaussian_curvature_mean", "surface.gaussian_curvature_std"],
26
+ "pooled_readout": "replace curvature entries in surface.chemical_delta_context; keep all ESM-C and other slots",
27
+ "command": "python -m topoppi_affinity_tools.features.prepare_analytic_mutation_inputs --input INPUT.csv --graph-manifest GRAPHS.csv --features ORIGINAL_SURFACE.npz --contact-features ORIGINAL_CONTACT.npz --output OUTPUT_DIRECTORY",
28
+ "model_input": "OUTPUT_DIRECTORY/ddg_plm_analytic.npz; original discrete-curvature surface vectors are a different protocol",
29
+ }
30
+
31
+
32
+ def prepare_analytic_mutation_inputs(input_manifest, graph_manifest, features, contact_features, output):
33
+ """Only structure/mutation identity and unlabeled pooled vectors are read."""
34
+ output = Path(output)
35
+ output.mkdir(parents=True, exist_ok=True)
36
+ frame = pd.read_csv(input_manifest, usecols=["sample_id", "source", "complex_id", "mutations"], keep_default_na=False)
37
+ graphs = pd.read_csv(graph_manifest, keep_default_na=False)
38
+ graphs = frame[["source", "complex_id"]].drop_duplicates().merge(
39
+ graphs, on=["source", "complex_id"], validate="one_to_one")
40
+ graphs.to_csv(output / "input_graphs.csv", index=False)
41
+ subprocess.run([sys.executable, tool_file('features/refine_graph_curvature.py'), "--manifest",
42
+ str(output / "input_graphs.csv"), "--output", str(output / "graphs"), "--workers", "2"], check=True)
43
+ refined = pd.read_csv(output / "graphs/manifest.csv", keep_default_na=False)
44
+ paths = {(row.source, row.complex_id): row.graph_path for row in refined.itertuples() if row.status == "ok"}
45
+ original, names = load_features(features, frame)
46
+ contact, contact_names = load_features(contact_features, frame)
47
+ if not np.array_equal(names, contact_names):
48
+ raise ValueError("Supplied original surface/contact schemas differ")
49
+
50
+ @lru_cache(maxsize=16)
51
+ def graph(key):
52
+ return load_graph(paths[key])
53
+
54
+ values, selected, coverage = [], [], []
55
+ for index, row in enumerate(frame.itertuples()):
56
+ record = {"sample_id": row.sample_id, "source": row.source, "complex_id": row.complex_id}
57
+ try:
58
+ values.append(update_pooled_curvature(original[index], names, graph((row.source, row.complex_id)),
59
+ target="ddg", mutations=row.mutations))
60
+ selected.append(index)
61
+ record.update(status="ok", error="")
62
+ except (ValueError, KeyError, OSError) as error:
63
+ record.update(status="error", error=f"{type(error).__name__}: {error}")
64
+ coverage.append(record)
65
+ matrix = np.asarray(values)
66
+ difference = float(np.max(np.abs(zero_surface_slots(matrix, names) - contact[selected])))
67
+ if difference != 0.:
68
+ raise ValueError("Analytic curvature changed the original contact control")
69
+ np.savez_compressed(output / "ddg_plm_analytic.npz", X=matrix,
70
+ sample_ids=frame.iloc[selected].sample_id.to_numpy(dtype=str),
71
+ feature_names=names, curvature_protocol=np.asarray(CURVATURE))
72
+ pd.DataFrame(coverage).to_csv(output / "coverage.csv", index=False)
73
+ report = {**PREPROCESSING, "input_manifest": str(input_manifest), "original_surface_features": str(features),
74
+ "n_graphs": len(graphs), "successful_graphs": len(paths), "n_rows": len(frame),
75
+ "successful_rows": len(selected), "dimension": matrix.shape[1],
76
+ "changed_pooled_columns": int(np.any(original[selected] != matrix, axis=0).sum()),
77
+ "contact_max_absolute_difference": difference, "labels_read": False, "model_prediction_run": False}
78
+ (output / "protocol.json").write_text(json.dumps(report, indent=2) + "\n")
79
+ print(json.dumps(report, indent=2), flush=True)
80
+ return report
81
+
82
+
@@ -0,0 +1,66 @@
1
+ """Fit named-feature regressors and apply their saved preprocessing."""
2
+ from __future__ import annotations
3
+
4
+ import json
5
+ from pathlib import Path
6
+
7
+ import joblib
8
+ import numpy as np
9
+ import pandas as pd
10
+ from threadpoolctl import threadpool_limits
11
+
12
+ from topoppi_affinity.embedding_baselines import fit_frozen_regressor
13
+ from topoppi_affinity.frozen_probes import load_features
14
+ from topoppi_affinity.thermodynamics import REFERENCE_TEMPERATURE_K, pkd_to_dg, pkd_to_kd
15
+
16
+
17
+ def fit_frozen(training, features, output, *, target, representation, family,
18
+ parameters, antisymmetric=False):
19
+ """Fit a fixed configuration on an explicit table and feature NPZ.
20
+
21
+ The training table supplies sample_id, complex_id, family_group and target.
22
+ Feature rows are aligned by sample_id; preprocessing is fitted on these rows.
23
+ """
24
+ frame = training.copy() if isinstance(training, pd.DataFrame) else pd.read_csv(
25
+ training, keep_default_na=False, dtype={'sample_id': str})
26
+ if target not in ('pkd', 'ddg'):
27
+ raise ValueError('Target must be pkd or ddg')
28
+ if frame.sample_id.duplicated().any():
29
+ raise ValueError('Training sample IDs must be unique')
30
+ matrix, names = load_features(features, frame)
31
+ with threadpool_limits(limits=2):
32
+ model = fit_frozen_regressor(matrix, frame[target], frame.complex_id,
33
+ family=family, params=parameters, antisymmetric=antisymmetric)
34
+ report = {'target': target, 'representation': representation, 'family': family,
35
+ 'parameters': parameters, 'antisymmetric': antisymmetric,
36
+ 'n_train': len(frame), 'n_complexes': frame.complex_id.nunique(),
37
+ 'n_families': frame.family_group.nunique(), 'n_features': matrix.shape[1],
38
+ 'train_sample_ids': frame.sample_id.tolist(),
39
+ 'train_family_groups': sorted(frame.family_group.unique()),
40
+ 'selection': 'Caller-specified fixed configuration',
41
+ 'affinity_units': 'pKd=-log10(Kd/M)' if target == 'pkd' else 'kcal/mol; mutant minus WT'}
42
+ output = Path(output)
43
+ output.parent.mkdir(parents=True, exist_ok=True)
44
+ joblib.dump({'model': model, 'feature_names': names, 'report': report}, output)
45
+ output.with_suffix('.json').write_text(json.dumps(report, indent=2) + '\n')
46
+ return report
47
+
48
+
49
+ def predict_frozen(artifact, features, *, temperature_K=REFERENCE_TEMPERATURE_K):
50
+ """Feature NPZ only needs sample_ids, X and feature_names, with no target."""
51
+ bundle = joblib.load(artifact)
52
+ with np.load(features, allow_pickle=False) as source:
53
+ if not np.array_equal(source['feature_names'], bundle['feature_names']):
54
+ raise ValueError('Input feature columns differ from the fitted model')
55
+ with threadpool_limits(limits=2):
56
+ prediction = bundle['model'].predict(source['X'])
57
+ frame = pd.DataFrame({'sample_id': source['sample_ids'].astype(str), 'predicted': prediction})
58
+ target = bundle['report']['target']
59
+ if target == 'pkd':
60
+ frame['predicted_pkd'] = prediction
61
+ frame['predicted_kd_M'] = pkd_to_kd(prediction)
62
+ frame['predicted_dg_at_reference_kcal_mol'] = pkd_to_dg(prediction, temperature_K)
63
+ frame['reference_temperature_K'] = temperature_K
64
+ else:
65
+ frame['predicted_ddg_kcal_mol'] = prediction
66
+ return frame
@@ -0,0 +1 @@
1
+ """Identity-linked native structure, contact graph and atlas review."""
@@ -0,0 +1,209 @@
1
+ """Observed-sequence correspondence and mapped native contact differences."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import argparse
6
+ import itertools
7
+ import json
8
+ from pathlib import Path
9
+
10
+ import numpy as np
11
+ import pandas as pd
12
+ from Bio.SeqUtils import seq1
13
+ from topoppi.atlas.footprints import source_atom_residue_labels
14
+ from topoppi.io.io_loader import PDBLoader
15
+ from topoppi.sequence_alignment import align_protein_sequences
16
+
17
+ from topoppi_affinity.features import _chains, _group_data
18
+
19
+ from .context import atom_context
20
+
21
+
22
+ def observed(row):
23
+ loader = PDBLoader(row["structure_path"])
24
+ groups = sorted((_chains(row["chains_a"]), _chains(row["chains_b"])))
25
+ chains = {}
26
+ for chain in sum((list(g) for g in groups), []):
27
+ xyz, atoms = loader.get_chain_data(chain)
28
+ keys = list(dict.fromkeys(map(str, source_atom_residue_labels(atoms))))
29
+ chains[chain] = ("".join(seq1(k.split(":")[1]) for k in keys), keys)
30
+ residues, edges = atom_context([_group_data(loader, g) for g in groups])
31
+ return groups, chains, residues, edges
32
+
33
+
34
+ def map_structures(left, right):
35
+ ga, ca, _, _ = left
36
+ gb, cb, _, _ = right
37
+ matches = {}
38
+ failures = []
39
+ for a, (sa, _ka) in ca.items():
40
+ for b, (sb, _kb) in cb.items():
41
+ if min(len(sa), len(sb)) / max(len(sa), len(sb)) < 0.8:
42
+ continue
43
+ try:
44
+ pairs, metrics = align_protein_sequences(sa, sb)
45
+ except ValueError as exc:
46
+ failures.append(str(exc))
47
+ continue
48
+ if (
49
+ metrics["alignment_identity"] >= 0.3
50
+ and min(metrics["reference_coverage"], metrics["mobile_coverage"]) >= 0.8
51
+ ):
52
+ matches[a, b] = (pairs, metrics)
53
+ assignments = []
54
+ for orientation in ((0, 1), (1, 0)):
55
+ if any(len(ga[s]) != len(gb[orientation[s]]) for s in (0, 1)):
56
+ continue
57
+ choices = []
58
+ for side in (0, 1):
59
+ choices.append(
60
+ [
61
+ list(zip(ga[side], perm, strict=True))
62
+ for perm in itertools.permutations(gb[orientation[side]])
63
+ if all((a, b) in matches for a, b in zip(ga[side], perm, strict=True))
64
+ ]
65
+ )
66
+ for first, second in itertools.product(*choices):
67
+ assignments.append(first + second)
68
+ if len(assignments) != 1:
69
+ return None, dict(
70
+ status="ambiguous_chain_assignment" if assignments else "no_complete_mapping",
71
+ assignments=len(assignments),
72
+ alignment_failures=len(failures),
73
+ )
74
+ records = []
75
+ for a, b in assignments[0]:
76
+ pairs, metrics = matches[a, b]
77
+ if metrics["selected_pair_consensus_fraction"] != 1:
78
+ return None, dict(status="ambiguous_residue_alignment", chain_a=a, chain_b=b)
79
+ for i, j in pairs:
80
+ records.append(
81
+ dict(
82
+ reference_key=ca[a][1][i],
83
+ mobile_key=cb[b][1][j],
84
+ reference_chain=a,
85
+ mobile_chain=b,
86
+ identity=metrics["alignment_identity"],
87
+ reference_coverage=metrics["reference_coverage"],
88
+ mobile_coverage=metrics["mobile_coverage"],
89
+ )
90
+ )
91
+ return records, dict(status="automatic_mapping", independent_review="not_performed", assignments=1, mapped_residues=len(records))
92
+
93
+
94
+ def contact_delta(mapping, left_edges, right_edges, cutoff=6.0):
95
+ lookup = {r["reference_key"]: r["mobile_key"] for r in mapping}
96
+ reverse = {v: k for k, v in lookup.items()}
97
+ left = {
98
+ tuple(sorted((e["source"], e["target"]))): e["min_distance"]
99
+ for e in left_edges
100
+ if e["source"] in lookup and e["target"] in lookup
101
+ }
102
+ right = {
103
+ tuple(sorted((reverse[e["source"]], reverse[e["target"]]))): e["min_distance"]
104
+ for e in right_edges
105
+ if e["source"] in reverse and e["target"] in reverse
106
+ }
107
+ rows = []
108
+ for edge in sorted(set(left) | set(right)):
109
+ a, b = left.get(edge, float("inf")), right.get(edge, float("inf"))
110
+ if min(a, b) > cutoff:
111
+ continue
112
+ status = "shared" if max(a, b) <= cutoff else "reference_only" if a <= cutoff else "mobile_only"
113
+ rows.append(
114
+ dict(
115
+ reference_source=edge[0],
116
+ reference_target=edge[1],
117
+ mobile_source=lookup[edge[0]],
118
+ mobile_target=lookup[edge[1]],
119
+ reference_min_distance=a if np.isfinite(a) else None,
120
+ mobile_min_distance=b if np.isfinite(b) else None,
121
+ distance_missing_meaning="above exported 6.5 A distance limit",
122
+ cutoff_A=cutoff,
123
+ status=status,
124
+ )
125
+ )
126
+ return rows
127
+
128
+
129
+ def run(manifest, output, target=24):
130
+ output = Path(output)
131
+ output.mkdir(parents=True, exist_ok=True)
132
+ frame = pd.read_csv(manifest, keep_default_na=False).drop_duplicates("complex_id")
133
+ rng = np.random.default_rng(20260926)
134
+ families = sorted(frame.family_group.unique())
135
+ rng.shuffle(families)
136
+ cache = {}
137
+ registry = []
138
+ pairs = []
139
+ for family in families:
140
+ group = frame[frame.family_group == family].sort_values("sample_id").to_dict("records")
141
+ if len(group) < 2:
142
+ continue
143
+ candidates = list(itertools.combinations(range(len(group)), 2))
144
+ rng.shuffle(candidates)
145
+ for i, j in candidates:
146
+ a, b = group[i], group[j]
147
+ if a["pdb_id"] == b["pdb_id"]:
148
+ continue
149
+ try:
150
+ for row in (a, b):
151
+ if row["sample_id"] not in cache:
152
+ cache[row["sample_id"]] = observed(row)
153
+ left, right = cache[a["sample_id"]], cache[b["sample_id"]]
154
+ mapping, report = map_structures(left, right)
155
+ except (ValueError, KeyError, OSError) as exc:
156
+ mapping = None
157
+ report = dict(status="source_error", error=str(exc))
158
+ record = dict(reference=a["sample_id"], mobile=b["sample_id"], family_group=family, **report)
159
+ registry.append(record)
160
+ if mapping is None:
161
+ continue
162
+ pair_id = f"pair_{len(pairs) + 1:03d}"
163
+ folder = output / pair_id
164
+ folder.mkdir(exist_ok=True)
165
+ pd.DataFrame(mapping).to_csv(folder / "correspondence.csv", index=False)
166
+ deltas = [r for cutoff in (5.5, 6.0, 6.5) for r in contact_delta(mapping, left[3], right[3], cutoff)]
167
+ pd.DataFrame(deltas).to_csv(folder / "contact_differences.csv", index=False)
168
+ for label, row, structure in [("reference", a, left), ("mobile", b, right)]:
169
+ (folder / f"{label}.json").write_text(
170
+ json.dumps(dict(source=row, groups=structure[0], residues=structure[2], contacts=structure[3]))
171
+ + "\n"
172
+ )
173
+ pairs.append(
174
+ dict(
175
+ pair_id=pair_id,
176
+ **record,
177
+ reference_structure=a["structure_path"],
178
+ mobile_structure=b["structure_path"],
179
+ )
180
+ )
181
+ print(f"{pair_id}: {a['pdb_id']} / {b['pdb_id']}, {family}", flush=True)
182
+ break # One pair per candidate family; source structures never reused.
183
+ if len(pairs) >= target:
184
+ break
185
+ pd.DataFrame(registry).to_csv(output / "candidate_registry.csv", index=False)
186
+ pd.DataFrame(pairs).to_csv(output / "pairs.csv", index=False)
187
+ (output / "status.json").write_text(
188
+ json.dumps(
189
+ dict(
190
+ automatically_mapped_pairs=len(pairs),
191
+ independent_candidate_families=len(pairs),
192
+ reviewed_pairs=0,
193
+ human_performance_observations=0,
194
+ selection="seed 20260926; random family/pair order; first eligible pair per family; stop at target",
195
+ target_pairs=target,
196
+ ),
197
+ indent=2,
198
+ )
199
+ + "\n"
200
+ )
201
+
202
+
203
+ if __name__ == "__main__":
204
+ p = argparse.ArgumentParser()
205
+ p.add_argument("manifest")
206
+ p.add_argument("output")
207
+ p.add_argument("--target", type=int, default=24)
208
+ a = p.parse_args()
209
+ run(a.manifest, a.output, a.target)
@@ -0,0 +1,117 @@
1
+ """Native residue context shared by all review conditions."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import argparse
6
+ import json
7
+ from concurrent.futures import ProcessPoolExecutor
8
+ from pathlib import Path
9
+
10
+ import numpy as np
11
+ import pandas as pd
12
+ from scipy.spatial import cKDTree
13
+ from topoppi.atlas.footprints import source_atom_residue_labels
14
+ from topoppi.io.io_loader import PDBLoader
15
+
16
+ from topoppi_affinity.features import _chains, _group_data
17
+
18
+
19
+ def atom_context(groups, cutoff=6.5):
20
+ coords = [g[0] for g in groups]
21
+ labels = [source_atom_residue_labels(g[1]).astype(str) for g in groups]
22
+ distances, counts = {}, {}
23
+ for i, indices in enumerate(cKDTree(coords[1]).query_ball_point(coords[0], cutoff)):
24
+ for j in indices:
25
+ key = (str(labels[0][i]), str(labels[1][j]))
26
+ d = float(np.linalg.norm(coords[0][i] - coords[1][j]))
27
+ distances[key] = min(d, distances.get(key, float("inf")))
28
+ if d <= 6.0:
29
+ counts[key] = counts.get(key, 0) + 1
30
+ residues = []
31
+ for side in (0, 1):
32
+ for key in sorted(set(labels[side])):
33
+ xyz = coords[side][labels[side] == key].mean(axis=0)
34
+ residues.append(dict(residue_key=key, side=side, x=float(xyz[0]), y=float(xyz[1]), z=float(xyz[2])))
35
+ edges = [
36
+ dict(source=a, target=b, min_distance=d, atom_pair_count_6A=counts.get((a, b), 0))
37
+ for (a, b), d in sorted(distances.items())
38
+ ]
39
+ return residues, edges
40
+
41
+
42
+ def export_job(args):
43
+ row, output = args
44
+ loader = PDBLoader(row["structure_path"])
45
+ groups = sorted((_chains(row["chains_a"]), _chains(row["chains_b"])))
46
+ residue, edges = atom_context([_group_data(loader, g) for g in groups])
47
+ obj = dict(
48
+ sample_id=row["sample_id"],
49
+ structure_path=row["structure_path"],
50
+ groups=groups,
51
+ family_group=row.get("family_group"),
52
+ residues=residue,
53
+ contacts=edges,
54
+ contact_cutoff_A=6.0,
55
+ exported_distance_limit_A=6.5,
56
+ )
57
+ path = Path(output) / (row["sample_id"].replace(":", "_") + ".json")
58
+ path.write_text(json.dumps(obj) + "\n")
59
+ contact = [e for e in edges if e["min_distance"] <= 6.0]
60
+ return dict(
61
+ sample_id=row["sample_id"],
62
+ contact_count=len(contact),
63
+ chain_count=sum(map(len, groups)),
64
+ contacting_residues=len({e[k] for e in contact for k in ("source", "target")}),
65
+ context=str(path),
66
+ )
67
+
68
+
69
+ def run(manifest, output, workers=4):
70
+ output = Path(output)
71
+ output.mkdir(parents=True, exist_ok=True)
72
+ frame = pd.read_csv(manifest, keep_default_na=False).drop_duplicates("sample_id")
73
+ with ProcessPoolExecutor(workers) as pool:
74
+ rows = list(pool.map(export_job, [(r, str(output)) for r in frame.to_dict("records")]))
75
+ pd.DataFrame(rows).to_csv(output / "native_covariates.csv", index=False)
76
+ print(f"Exported native context for {len(rows)} structures")
77
+
78
+
79
+ if __name__ == "__main__":
80
+ p = argparse.ArgumentParser()
81
+ p.add_argument("manifest")
82
+ p.add_argument("output")
83
+ p.add_argument("--workers", type=int, default=4)
84
+ a = p.parse_args()
85
+ run(a.manifest, a.output, a.workers)
86
+
87
+
88
+ def independent_contact_sets(structure_path, groups, cutoff=6.0):
89
+ """Answer-key reference: original atoms, explicit identities, dense distances.
90
+
91
+ This path does not read the saved contact map or the display's graph.
92
+ """
93
+ from scipy.spatial.distance import cdist
94
+
95
+ loader = PDBLoader(structure_path)
96
+ coordinates = []
97
+ identities = []
98
+ for group in groups:
99
+ xyz, atoms = _group_data(loader, group)
100
+ coordinates.append(xyz)
101
+ identities.append(
102
+ np.array(
103
+ [
104
+ f"{a.get_parent().get_parent().id}:{a.get_parent().resname.strip()}:{a.get_parent().id[1]}{a.get_parent().id[2].strip()}"
105
+ for a in atoms
106
+ ]
107
+ )
108
+ )
109
+ result = {key: set() for labels in identities for key in set(labels)}
110
+ # Blocked dense evaluation bounds memory while retaining a separate distance path.
111
+ for start in range(0, len(coordinates[0]), 256):
112
+ a, b = np.nonzero(cdist(coordinates[0][start : start + 256], coordinates[1]) <= cutoff)
113
+ for i, j in zip(a + start, b, strict=True):
114
+ left, right = str(identities[0][i]), str(identities[1][j])
115
+ result[left].add(right)
116
+ result[right].add(left)
117
+ return result