igfold2d

IgFold2D

2D proteomaps for Ig-fold protein domains.

A small, dependency-free JavaScript widget that renders a folded-lace 2D map of an immunoglobulin domain, with residues placed at canonical positions on a grid indexed by the IgStrand universal numbering scheme (Tawfeeq et al., PLOS Comput Biol 2025).

CD8α IgV domain. Each cell is addressable by Excel coordinate, IgStrand number, UniProt position, and PDB position. The dashed trace follows the chain N→C through anchor positions xx50 (yellow row).

---

Try it

• Live demo: vizomics.org/proteomaps — CD8α with bidirectional sequence ↔ proteomap sync
• Standalone HTML demo: clone the repo and open examples/browser-widget/index.html directly in a browser, no install
• Static figure SVG: a pre-rendered, clickable, data-rich SVG is shipped with releases (IgFold2D-CD8a.svg)

---

For iCn3D maintainers

👉 Start here: docs/icn3d-integration.md — three integration paths from “just add a link” to “full bidirectional 3D↔2D sync”.

The widget consumes the JSON output of iCn3D’s refnum.js (Ig domain detection + reference numbering) through a small adapter. No iCn3D internals are touched.

---

What it is

An Ig Proteomap is an explicit 2D projection of a 3D Ig-fold (β-sandwich) topology that preserves residue-residue contacts while making the sequential chain order visible.

Each cell of the 2D grid is multi-addressable:

• Excel coordinate (e.g. L10)
• (row, col) pair
• IgStrand number (e.g. 2550 for the B-strand anchor)
• UniProt / PDB / AlphaFold position

The widget supports:

• 5 display modes (residue letter, IgStrand #, UniProt #, PDB #, Excel address)
• Click and hover interactivity with a complete cell info panel
• Dashed chain trace following the IgStrand sequence A → G with direction chevrons
• Bidirectional highlight between linear sequence view and 2D proteomap
• Extensible feature vector per cell (conservation, contacts, SASA, mutations, …)

Quick start

Browser, drop-in

<div id="map"></div>
<script src="src/igfold2d.js"></script>
<script>
  Promise.all([
    fetch('templates/IgV-split-AAprime.json').then(r => r.json()),
    fetch('assignments/CD8a-P01732.json').then(r => r.json())
  ]).then(([template, assignment]) => {
    IgFold2D.render({
      container: '#map',
      template,
      assignment,
      sources: {
        uniprot:   { id: 'P01732', version: 1 },
        pdb:       { id: '1CD8', chain: 'A' },
        alphafold: { id: 'AF-P01732-F1', version: 4 }
      }
    });
  });
</script>

NPM (planned)

npm install igfold2d

import IgFold2D from 'igfold2d';

Repository layout

src/
  igfold2d.js              Widget core (~430 lines, ~13 KB minified, no deps)
templates/                 JSON template files (one per Ig variant)
  IgV-split-AAprime.json   IgV split A/A' (CD8-like) — 9 strands
assignments/               Pre-computed residue → IgStrand mappings
  CD8a-P01732.json         CD8α IgV domain (107 residues, hand-curated)
examples/
  browser-widget/          Standalone HTML demo (no server, no install)
website/                   The vizomics.org/proteomaps page
docs/
  icn3d-integration.md     ← How to integrate into iCn3D
  topology-rules.md        Fold construction rules
  igstrand-spec.md         IgStrand numbering reference
  api.md                   Widget API reference

The folding rules (short version)

Full reference in docs/topology-rules.md. Highlights:

Rule	Description
No crossing	The lace never visually crosses itself on colored cells
Turns at strand ends	90° turns happen above or below strands, never mid-loop
Minimize bends	Each strand-to-strand transition uses the minimum number of right-angle turns
Anchor alignment	All xx50 positions sit on one horizontal line
Passes-behind	Where a 3D chain crosses behind another, the 2D trace may visibly cross (dashed) or break (gap)
Placeholder traversal	Empty cells can be traversed as bridges; future residue insertions may land there

IgStrand numbering

4-digit codes ijxx:

• i (thousands): strand id — A=1, B=2, C=3, C’=4, C”=5, D=6, E=7, F=8, G=9
• j (hundreds): 5 for canonical strands; 8 for A’ (split case)
• xx: position centered on 50 (the anchor)
• Insertions: A−=14xx, A++=13xx, A+=16xx, G+=96xx, etc.

Full spec in docs/igstrand-spec.md.

Status & roadmap

Version	Status	Scope
v0.1	✅ shipped	Hand-curated CD8α template, browser widget, sequence↔map sync
v0.2	🚧 planned	More templates: IgC1, IgC2, IgI, FN3
v0.3	🚧 planned	Live IgStrand assignment via iCn3D refnum.js
v0.4	🚧 planned	Feature overlays: conservation, contacts, SASA, mutations
v0.5	🚧 planned	Multi-domain view with inter-domain contacts

License

MIT — see LICENSE.

Citation

If you use IgFold2D in your research, please cite the underlying numbering scheme:

Tawfeeq M, et al. (2025) A universal residue numbering scheme for the Immunoglobulin-fold (Ig-fold). PLOS Comput Biol 21(4): e1012813. doi:10.1371/journal.pcbi.1012813

Acknowledgments

Developed by Philippe Youkharibache and contributors at vizomics.org. The lace-folding concept extends prior work by the ISMB-2021 hackathon team (Manfredi, Patel, Cachau, Byrum) — see hackathonismb/2D-Maps-for-Ig-domains-and-for-RBDs. iCn3D integration consultation: NCBI Structure team.

This site is open source. Improve this page.