Skip to content

Commit 1f1651e

Browse files
jbenjosephjbenjoseph
committed
feat: add HER2 antibody design notebook to examples
1 parent 2b5f6ed commit 1f1651e

2 files changed

Lines changed: 232 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -96,6 +96,7 @@ The `examples/` directory includes runnable notebooks:
9696
- `refua_folding.ipynb`
9797
- `refua_antibody_design.ipynb`
9898
- `refua_antibody_design_pd_l1.ipynb`
99+
- `refua_antibody_design_her2.ipynb`
99100
- `refua_peptide_design_mdm2.ipynb`
100101
- `refua_peptide_design_glp1r.ipynb`
101102
- `refua_peptide_design_integrin_avb3.ipynb`

‎examples/refua_antibody_design_her2.ipynb‎

Lines changed: 231 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,231 @@
1+
{
2+
"cells": [
3+
{
4+
"cell_type": "markdown",
5+
"metadata": {},
6+
"source": [
7+
"# Refua Antibody Design Notebook: HER2 Domain IV\n",
8+
"\n",
9+
"> **Audience:** anyone new to antibody design workflows. \n",
10+
"> **Goal:** generate epitope-focused antibody candidates against a clinically important HER2 surface region.\n",
11+
"\n",
12+
"## Why this target is interesting (with sources)\n",
13+
"- **Biology and disease relevance:** HER2 is implicated in aggressive cancers; classic HER2 structural literature reports overexpression in 20-30% of breast cancers and links it to poorer prognosis.\n",
14+
"- **Clinical signal remains current:** on **November 20, 2024**, FDA granted accelerated approval to **zanidatamab-hrii**, a HER2-directed bispecific antibody, for previously treated unresectable/metastatic HER2-positive biliary tract cancer.\n",
15+
"- **Structure-guided design is practical:** PDB **1N8Z** resolves human HER2 extracellular domain in complex with Herceptin (trastuzumab) Fab, which supports domain- and epitope-focused design setups.\n",
16+
"\n",
17+
"## Workflow\n",
18+
"1. Define a HER2 domain IV antigen and a trastuzumab-facing window.\n",
19+
"2. Generate heavy/light antibody templates with explicit CDR length controls.\n",
20+
"3. Run one design/fold pass and inspect candidate specs for triage.\n"
21+
]
22+
},
23+
{
24+
"cell_type": "code",
25+
"execution_count": null,
26+
"metadata": {},
27+
"outputs": [],
28+
"source": [
29+
"%load_ext refua_notebook\n",
30+
"import refua_notebook\n",
31+
"\n",
32+
"refua_notebook.activate()\n"
33+
]
34+
},
35+
{
36+
"cell_type": "code",
37+
"execution_count": null,
38+
"metadata": {},
39+
"outputs": [],
40+
"source": [
41+
"from refua import BinderDesigns, Complex, Protein\n"
42+
]
43+
},
44+
{
45+
"cell_type": "markdown",
46+
"metadata": {},
47+
"source": [
48+
"## Biological setup (plain language)\n",
49+
"\n",
50+
"This notebook uses a HER2 domain IV segment from PDB 1N8Z (chain C, juxtamembrane region), where trastuzumab-class antibodies bind.\n",
51+
"\n",
52+
"| Design input | Choice in this notebook | Why |\n",
53+
"|---|---|---|\n",
54+
"| Target chain | 1N8Z HER2 domain IV segment (119 aa) | Compact structural region that includes the Herceptin-facing surface |\n",
55+
"| Binding hotspot | `38..110` | Broadly spans the central trastuzumab-contact neighborhood for focused exploration |\n",
56+
"| Candidate style | De novo heavy/light pair with CDR constraints | Standard early-stage antibody exploration pattern |\n"
57+
]
58+
},
59+
{
60+
"cell_type": "code",
61+
"execution_count": null,
62+
"metadata": {},
63+
"outputs": [],
64+
"source": [
65+
"HER2_DOMAIN_IV_1N8Z = (\n",
66+
" \"CHQLCARGHCWGPGPTQCVNCSQFLRGQECVEECRVLQGLPREYVNARHCLPCHPECQPQNGSVTCFGPEADQCVACAHYKDPPFCVARCPSGVKPDLSYMPIWKFPDEEGACQPCPIN\"\n",
67+
")\n",
68+
"\n",
69+
"# Reference therapeutic binder sequences from PDB 1N8Z (trastuzumab / Herceptin Fab).\n",
70+
"TRASTUZUMAB_HEAVY_1N8Z = (\n",
71+
" \"EVQLVESGGGLVQPGGSLRLSCAASGFNIKDTYIHWVRQAPGKGLEWVARIYPTNGYTRYADSVKGRFTISADTSKNTAYLQMNSLRAEDTAVYYCSRWGGDGFYAMDYWGQGTLVTVSSASTKGPSVFPLAPSSKSTSGGTAALGCLVKDYFPEPVTVSWNSGALTSGVHTFPAVLQSSGLYSLSSVVTVPSSSLGTQTYICNVNHKPSNTKVDKKVEP\"\n",
72+
")\n",
73+
"TRASTUZUMAB_LIGHT_1N8Z = (\n",
74+
" \"DIQMTQSPSSLSASVGDRVTITCRASQDVNTAVAWYQQKPGKAPKLLIYSASFLYSGVPSRFSGSRSGTDFTLTISSLQPEDFATYYCQQHYTTPPTFGQGTKVEIKRTVAAPSVFIFPPSDEQLKSGTASVVCLLNNFYPREAKVQWKVDNALQSGNSQESVTEQDSKDSTYSLSSTLTLSKADYEKHKVYACEVTHQGLSSPVTKSFNRGEC\"\n",
75+
")\n",
76+
"\n",
77+
"HER2_BINDING_WINDOW = \"38..110\"\n",
78+
"\n",
79+
"HEAVY_CDR_LENGTHS = (12, 10, 13)\n",
80+
"LIGHT_CDR_LENGTHS = (10, 9, 9)\n"
81+
]
82+
},
83+
{
84+
"cell_type": "markdown",
85+
"metadata": {},
86+
"source": [
87+
"## Build antibody design spec\n",
88+
"\n",
89+
"This cell composes:\n",
90+
"- the antigen (`A`)\n",
91+
"- a generated heavy chain (`H`)\n",
92+
"- a generated light chain (`L`)\n",
93+
"\n",
94+
"into one `Complex` object named `her2_domain4_antibody_design`.\n",
95+
"\n",
96+
"Think of `design_spec` as a reusable recipe you can rerun across nearby windows and alternate CDR settings.\n"
97+
]
98+
},
99+
{
100+
"cell_type": "code",
101+
"execution_count": null,
102+
"metadata": {},
103+
"outputs": [],
104+
"source": [
105+
"antigen = Protein(\n",
106+
" HER2_DOMAIN_IV_1N8Z,\n",
107+
" ids=\"A\",\n",
108+
" binding_types={\"binding\": HER2_BINDING_WINDOW},\n",
109+
")\n",
110+
"\n",
111+
"binder_pair = BinderDesigns.antibody(\n",
112+
" heavy_cdr_lengths=HEAVY_CDR_LENGTHS,\n",
113+
" light_cdr_lengths=LIGHT_CDR_LENGTHS,\n",
114+
" heavy_id=\"H\",\n",
115+
" light_id=\"L\",\n",
116+
")\n",
117+
"\n",
118+
"design_spec = Complex([antigen, *binder_pair], name=\"her2_domain4_antibody_design\")\n"
119+
]
120+
},
121+
{
122+
"cell_type": "code",
123+
"execution_count": null,
124+
"metadata": {},
125+
"outputs": [],
126+
"source": [
127+
"{\n",
128+
" \"heavy_spec\": binder_pair.heavy.sequence,\n",
129+
" \"light_spec\": binder_pair.light.sequence,\n",
130+
" \"trastuzumab_ref_heavy_1n8z\": TRASTUZUMAB_HEAVY_1N8Z,\n",
131+
" \"trastuzumab_ref_light_1n8z\": TRASTUZUMAB_LIGHT_1N8Z,\n",
132+
"}\n"
133+
]
134+
},
135+
{
136+
"cell_type": "markdown",
137+
"metadata": {},
138+
"source": [
139+
"## Design narrative: from intent to candidates\n",
140+
"\n",
141+
"This is an **early discovery pass** to generate structured antibody hypotheses for ranking and follow-up.\n",
142+
"\n",
143+
"### What each output means\n",
144+
"| Output | What it is | How to use it |\n",
145+
"|---|---|---|\n",
146+
"| `result.binder_specs` | Heavy/light candidate specifications | Compare sequence hypotheses across CDR settings |\n",
147+
"| `result.chain_design_summary()` | Per-chain summary of fixed vs designable regions | Check whether constraints match your intent |\n",
148+
"| `result.features` | Model-level features for downstream ranking workflows | Save for reproducibility and triage pipelines |\n",
149+
"\n",
150+
"> Practical strategy: run multiple nearby hotspot windows and keep candidates that remain stable across settings.\n"
151+
]
152+
},
153+
{
154+
"cell_type": "markdown",
155+
"metadata": {},
156+
"source": [
157+
"## Run a design pass\n",
158+
"\n",
159+
"`design_spec.fold()` executes the design/fold workflow for this setup.\n",
160+
"\n",
161+
"Interpretation guardrails:\n",
162+
"- Generated binders are **computational candidates**, not validated therapeutics.\n",
163+
"- Use these outputs for prioritization and shortlist generation.\n",
164+
"- Confirm top candidates experimentally (binding, function, developability, safety).\n"
165+
]
166+
},
167+
{
168+
"cell_type": "code",
169+
"execution_count": null,
170+
"metadata": {},
171+
"outputs": [],
172+
"source": [
173+
"result = design_spec.fold()\n",
174+
"\n",
175+
"result\n"
176+
]
177+
},
178+
{
179+
"cell_type": "code",
180+
"execution_count": null,
181+
"metadata": {},
182+
"outputs": [],
183+
"source": [
184+
"result.binder_specs\n"
185+
]
186+
},
187+
{
188+
"cell_type": "code",
189+
"execution_count": null,
190+
"metadata": {},
191+
"outputs": [],
192+
"source": [
193+
"result.chain_design_summary()\n"
194+
]
195+
},
196+
{
197+
"cell_type": "markdown",
198+
"metadata": {},
199+
"source": [
200+
"## Science references\n",
201+
"\n",
202+
"- FDA (November 20, 2024), accelerated approval of HER2-directed bispecific antibody zanidatamab-hrii in HER2+ BTC: https://www.fda.gov/drugs/resources-information-approved-drugs/fda-grants-accelerated-approval-zanidatamab-hrii-previously-treated-unresectable-or-metastatic-her2\n",
203+
"- RCSB PDB 1N8Z (human HER2 extracellular domain in complex with Herceptin Fab): https://www.rcsb.org/structure/1N8Z\n",
204+
"- RCSB FASTA 1N8Z (exact chain sequences): https://www.rcsb.org/fasta/entry/1N8Z/display\n",
205+
"- Cho et al., *Nature* (2003), HER2 extracellular structure + Herceptin Fab (PMID: 12610629): https://pubmed.ncbi.nlm.nih.gov/12610629/\n",
206+
"- FDA preclinical research basics (why computational designs require experimental validation): https://www.fda.gov/patients/drug-development-process/step-2-preclinical-research\n"
207+
]
208+
}
209+
],
210+
"metadata": {
211+
"kernelspec": {
212+
"display_name": "Python 3 (ipykernel)",
213+
"language": "python",
214+
"name": "python3"
215+
},
216+
"language_info": {
217+
"codemirror_mode": {
218+
"name": "ipython",
219+
"version": 3
220+
},
221+
"file_extension": ".py",
222+
"mimetype": "text/x-python",
223+
"name": "python",
224+
"nbconvert_exporter": "python",
225+
"pygments_lexer": "ipython3",
226+
"version": "3.12.12"
227+
}
228+
},
229+
"nbformat": 4,
230+
"nbformat_minor": 5
231+
}

0 commit comments

Comments
 (0)