Skip to content

Commit 39e2b49

Browse files
xnaclyxnacly
committed
align documentation with other blocks
1 parent b10ac0b commit 39e2b49

3 files changed

Lines changed: 80 additions & 40 deletions

File tree

‎README.md‎

Lines changed: 41 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,46 @@
11
# 3D Structure-Based Liabilities
22

3-
Per-clonotype structural developability analysis for therapeutic antibody candidates. Consumes PDB structures from the [3D Structure Prediction block](https://github.com/platforma-open/3d-structure-prediction) and reproduces [Raybould 2019 TAP](https://doi.org/10.1073/pnas.1810576116) (paired Fv: surface hydrophobicity / positive-charge patches / negative-charge patches / Fv charge symmetry) and [Gordon 2025 TNP](https://github.com/oxpig/TNP) (VHH: same metrics with type-restricted charge patches plus CDRH3 compactness), with **region-aware per-residue confidence gating** using ImmuneBuilder B-factor as predicted error.
4-
5-
Sequence-only liability scanners (see our sister [antibody-sequence-liabilities](https://github.com/platforma-open/antibody-sequence-liabilities) block) flag every regex match without knowing whether the chemically reactive atom is solvent-exposed. This block adds 3D context: filters motif hits by rSASA, weights each hit by region (CDR3 > CDR1/2 > FR), gates low-confidence regions, and adds structural-only signals (surface charge / hydrophobicity patches, free-Cys state, CDR3 compactness).
6-
7-
## Inputs
8-
9-
`PlDatasetSelector` over `pl7.app/structure/pdb` anchor PColumns. Optional clonotype filter (Boolean/Int subset PColumn, e.g. `predictionSuccessful`, `confident`). Settings: numbering scheme (IMGT default), heavy / light chain overrides (auto-detected from REMARK 99), FR / CDR confidence thresholds (defaults 4.0 / 6.0 Å for ImmuneBuilder).
10-
11-
## Outputs
12-
13-
Per-clonotype scalar PColumns keyed on `pl7.app/vdj/scClonotypeKey`, bundled in the `scoresData` PFrame with `pl7.app/blockId` domain. Composite cost (`structuralDevelopabilityScore`) plus categorical risks (`structuralDevelopabilityRisk`, `structuralIntegrityRisk`); per-metric raw values + threshold flags (None / Medium / High); cysteine and motif counts; per-metric low-confidence-residue fractions. Mode-specific columns (`sfvcsp` for Fv, `cdrh3Compactness` for VHH). Full list with annotations in `workflow/src/specs.lib.tengo`.
14-
15-
## UI
16-
17-
- **Main**: `PlAgDataTableV2` with default-visible columns; row double-click opens a `PlSlideModal` with `PlStructureViewer` (Mol\*, `initialColorScheme="uncertainty"`). Cluster badge surfaces when the 3D Structure Clustering block is upstream.
18-
- **Five distribution pages**: hydrophobicity, positive charge patches, negative charge patches, mode-specific (Fv charge symmetry or CDRH3 compactness), developability cost, via graph-maker with Raybould / Gordon threshold lines.
19-
- **Run-summary alert** fires when more than 25% of clonotypes have at least one confidence-gated motif.
3+
Per-clonotype structural developability analysis for antibody candidates.
4+
Consumes per-clonotype PDB files from the [3D Structure
5+
Prediction](https://github.com/platforma-open/3d-structure-prediction) block
6+
upstream and emits per-clonotype liability calls, surface developability
7+
metrics, and a composite developability cost that downstream blocks (Lead
8+
Selection) can rank candidates on.
9+
10+
Sequence-only liability scanners (see our sister [Antibody Sequence
11+
Liabilities](https://github.com/platforma-open/antibody-sequence-liabilities)
12+
block) flag every regex match without knowing whether the chemically reactive
13+
atom is solvent-exposed. This block adds 3D context: filters motif hits by
14+
relative solvent-accessible surface area (rSASA), weights each hit by region
15+
(CDR3 > CDR1/2 > FR), gates low-confidence residues using the per-residue
16+
predicted error emitted by ImmuneBuilder, and adds structural-only signals
17+
(surface hydrophobicity / charge patches, free-Cys state, CDR-H3 compactness).
18+
19+
Surface metrics follow [Raybould 2019
20+
TAP](https://doi.org/10.1073/pnas.1810576116) verbatim for paired Fv (surface
21+
hydrophobicity, positive-charge patches, negative-charge patches, Fv charge
22+
symmetry) and [Gordon 2025 TNP](https://github.com/oxpig/TNP) for VHH (same
23+
metrics with type-restricted charge patches plus CDR-H3 compactness). SASA is
24+
computed with [FreeSASA](https://freesasa.github.io/) under the Shrake-Rupley
25+
algorithm at a 1.4 Å probe radius, the configuration both calibration cohorts
26+
use. Threshold bands are pinned to the literature cohorts: cohortSize 242 for
27+
Fv (Raybould 2019 Table 2), cohortSize 36 for VHH (Gordon 2025
28+
`assign_flag()`).
29+
30+
> Raybould MIJ, Marks C, Krawczyk K, Taddese B, Nowak J, Lewis AP, Bujotzek A,
31+
> Shi J, Deane CM. _Five computational developability guidelines for
32+
> therapeutic antibody profiling._ PNAS 116(10), 4025–4030 (2019).
33+
> [https://doi.org/10.1073/pnas.1810576116](https://doi.org/10.1073/pnas.1810576116)
34+
35+
> Gordon GL, Raybould MIJ, Deane CM. _TAP 2.0: a refined platform for assessing
36+
> the developability of nanobodies (in silico)._ bioRxiv (2025).
37+
> [https://doi.org/10.1101/2025.08.11.669635](https://doi.org/10.1101/2025.08.11.669635)
38+
39+
SASA computation uses [FreeSASA](https://freesasa.github.io/). Please cite:
40+
41+
> Mitternacht S. _FreeSASA: An open source C library for solvent accessible
42+
> surface area calculations._ F1000Research, 5:189 (2016).
43+
> [https://doi.org/10.12688/f1000research.7931.1](https://doi.org/10.12688/f1000research.7931.1)
2044
2145
## See Also
2246

‎block/package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@
2727
"logo": "file:../logos/block-logo.png",
2828
"url": "https://github.com/platforma-open/3D-Structure-Based-Liabilities",
2929
"support": "mailto:support@milaboratories.com",
30-
"description": "Identifying potential liabilities in therapeutic antibody candidates using 3D structure analysis. Takes a protein structure in PDB format through preprocessing and liability detection to flag developability risks.",
30+
"description": "Per-clonotype structural developability analysis for antibody candidates.",
3131
"longDescription": "file:../docs/description.md",
3232
"changelog": "file:../CHANGELOG.md",
3333
"tags": [

‎docs/description.md‎

Lines changed: 38 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,43 @@
11
# Overview
22

3-
Per-clonotype structural developability analysis for antibody candidates. Consumes per-clonotype PDB files from the [3D Structure Prediction](https://github.com/platforma-open/3d-structure-prediction) block upstream and emits per-clonotype liability calls, surface developability metrics, and a composite developability cost that downstream blocks (Lead Selection) can rank candidates on.
4-
5-
Sequence-only liability scanners (see our sister [Antibody Sequence Liabilities](https://github.com/platforma-open/antibody-sequence-liabilities) block) flag every regex match without knowing whether the chemically reactive atom is solvent-exposed. This block adds 3D context: filters motif hits by relative solvent-accessible surface area (rSASA), weights each hit by region (CDR3 > CDR1/2 > FR), gates low-confidence residues using the per-residue predicted error emitted by ImmuneBuilder, and adds structural-only signals (surface hydrophobicity / charge patches, free-Cys state, CDR-H3 compactness).
6-
7-
Surface metrics follow [Raybould 2019 TAP](https://doi.org/10.1073/pnas.1810576116) verbatim for paired Fv (surface hydrophobicity, positive-charge patches, negative-charge patches, Fv charge symmetry) and [Gordon 2025 TNP](https://github.com/oxpig/TNP) for VHH (same metrics with type-restricted charge patches plus CDR-H3 compactness). SASA is computed with [FreeSASA](https://freesasa.github.io/) under the Shrake-Rupley algorithm at a 1.4 Å probe radius, the configuration both calibration cohorts use. Threshold bands are pinned to the literature cohorts: cohortSize 242 for Fv (Raybould 2019 Table 2), cohortSize 36 for VHH (Gordon 2025 `assign_flag()`).
8-
9-
Outputs are per-clonotype scalar `PColumn`s keyed on `pl7.app/vdj/scClonotypeKey`. The composite cost `structuralDevelopabilityScore` aggregates motif risk (`fixabilityWeight × regionWeight × exposure`), per-metric threshold-flag bumps, and cysteine penalties. Two categorical risks ride alongside: `structuralDevelopabilityRisk` (None / Low / Medium / High) and `structuralIntegrityRisk` (None / Present, for broken or missing canonical disulfides, exposed extra cysteines, and structural-tier motifs). Per-metric raw values + None/Medium/High threshold flags are exported, with `<metric>LowConfidenceResidueFraction` columns letting users discount metrics dominated by low-confidence regions of the prediction.
10-
11-
## UI
12-
13-
The Main page renders a per-clonotype results table with default-visible columns (developability cost, risk levels, per-metric flags, cysteine counts) and a "Columns" toggle that reveals raw metric values and low-confidence fractions. Double-clicking a row opens a Mol\*-based 3D structure viewer for that clonotype with confidence-coloured per-residue rendering. Five distribution pages (surface hydrophobicity, positive-charge patches, negative-charge patches, mode-specific Fv-charge-symmetry / CDR-H3 compactness, and developability cost) render the Raybould / Gordon threshold lines so each candidate's standing against the literature thresholds is visible without leaving the chart. A run-summary alert fires when more than 25% of clonotypes have at least one confidence-gated motif.
14-
15-
## Honest scope
16-
17-
Flags reflect the **predicted apo conformation**. CDR-H3 in particular can rearrange on antigen binding, so a residue buried in the apo prediction may be exposed in the bound state. The value-prop is "removes apo-state-buried false positives", not "removes all false positives". The per-metric low-confidence-residue fraction lets users discount metrics dominated by uncertain regions of the prediction.
18-
19-
## References
20-
21-
> Raybould MIJ, Marks C, Krawczyk K, Taddese B, Nowak J, Lewis AP, Bujotzek A, Shi J, Deane CM. *Five computational developability guidelines for therapeutic antibody profiling.* PNAS 116(10), 4025–4030 (2019). [https://doi.org/10.1073/pnas.1810576116](https://doi.org/10.1073/pnas.1810576116)
22-
23-
> Gordon GL, Raybould MIJ, Deane CM. *TAP 2.0: a refined platform for assessing the developability of nanobodies (in silico).* bioRxiv (2025). [https://doi.org/10.1101/2025.08.11.669635](https://doi.org/10.1101/2025.08.11.669635)
3+
Per-clonotype structural developability analysis for antibody candidates.
4+
Consumes per-clonotype PDB files from the [3D Structure
5+
Prediction](https://github.com/platforma-open/3d-structure-prediction) block
6+
upstream and emits per-clonotype liability calls, surface developability
7+
metrics, and a composite developability cost that downstream blocks (Lead
8+
Selection) can rank candidates on.
9+
10+
Sequence-only liability scanners (see our sister [Antibody Sequence
11+
Liabilities](https://github.com/platforma-open/antibody-sequence-liabilities)
12+
block) flag every regex match without knowing whether the chemically reactive
13+
atom is solvent-exposed. This block adds 3D context: filters motif hits by
14+
relative solvent-accessible surface area (rSASA), weights each hit by region
15+
(CDR3 > CDR1/2 > FR), gates low-confidence residues using the per-residue
16+
predicted error emitted by ImmuneBuilder, and adds structural-only signals
17+
(surface hydrophobicity / charge patches, free-Cys state, CDR-H3 compactness).
18+
19+
Surface metrics follow [Raybould 2019
20+
TAP](https://doi.org/10.1073/pnas.1810576116) verbatim for paired Fv (surface
21+
hydrophobicity, positive-charge patches, negative-charge patches, Fv charge
22+
symmetry) and [Gordon 2025 TNP](https://github.com/oxpig/TNP) for VHH (same
23+
metrics with type-restricted charge patches plus CDR-H3 compactness). SASA is
24+
computed with [FreeSASA](https://freesasa.github.io/) under the Shrake-Rupley
25+
algorithm at a 1.4 Å probe radius, the configuration both calibration cohorts
26+
use. Threshold bands are pinned to the literature cohorts: cohortSize 242 for
27+
Fv (Raybould 2019 Table 2), cohortSize 36 for VHH (Gordon 2025
28+
`assign_flag()`).
29+
30+
> Raybould MIJ, Marks C, Krawczyk K, Taddese B, Nowak J, Lewis AP, Bujotzek A,
31+
> Shi J, Deane CM. _Five computational developability guidelines for
32+
> therapeutic antibody profiling._ PNAS 116(10), 4025–4030 (2019).
33+
> [https://doi.org/10.1073/pnas.1810576116](https://doi.org/10.1073/pnas.1810576116)
34+
35+
> Gordon GL, Raybould MIJ, Deane CM. _TAP 2.0: a refined platform for assessing
36+
> the developability of nanobodies (in silico)._ bioRxiv (2025).
37+
> [https://doi.org/10.1101/2025.08.11.669635](https://doi.org/10.1101/2025.08.11.669635)
2438
2539
SASA computation uses [FreeSASA](https://freesasa.github.io/). Please cite:
2640

27-
> Mitternacht S. *FreeSASA: An open source C library for solvent accessible surface area calculations.* F1000Research, 5:189 (2016). [https://doi.org/10.12688/f1000research.7931.1](https://doi.org/10.12688/f1000research.7931.1)
41+
> Mitternacht S. _FreeSASA: An open source C library for solvent accessible
42+
> surface area calculations._ F1000Research, 5:189 (2016).
43+
> [https://doi.org/10.12688/f1000research.7931.1](https://doi.org/10.12688/f1000research.7931.1)

0 commit comments

Comments
 (0)