igfold2d

IgFold2D widget API

The widget exposes a single global IgFold2D (also a CommonJS export). It has no dependencies — drop the script and call render().

Loading

Browser, drop-in

<script src="src/igfold2d.js"></script>
<script>
  IgFold2D.render({ container: '#map', template, assignment, sources });
</script>

CommonJS / Node.js / bundlers

const IgFold2D = require('igfold2d');
// or:  import IgFold2D from 'igfold2d';

IgFold2D.render(config) → widget

Renders the proteomap into config.container and returns a handle.

config

field	type	required	description
container	string | Element	yes	CSS selector or DOM node where the SVG is mounted
template	object	yes	The template JSON (load from templates/*.json)
assignment	array	yes	Residue list (load from assignments/*.json or compute from PDB)
sources	object	no	{ uniprot, pdb, alphafold } source metadata
options	object	no	See Options below

options

field	type	default	description
displayMode	string	'residue'	What to show in numbered cells: 'residue', 'igstrand', 'uniprot', 'pdb', 'excel'
showChain	bool	true	Show the dashed chain trace and direction chevrons
templateId	string	'IgV-split-AAprime'	Used to look up template-specific overrides (border hides, label moves)

Returned handle

const widget = IgFold2D.render({...});

widget.registry        // The CellRegistry (see below)
widget.highlight(addr) // Highlight a cell by any address; pass null to clear
widget.setOptions(opts)// Re-render with new options
widget._bindEvents()   // Re-bind interactivity (call after setOptions)

Cell registry

The registry holds every grid cell, indexed by multiple keys.

widget.registry.get('L10')        // by Excel address
widget.registry.get('9,11')       // by row,col
widget.registry.get(2550)         // by IgStrand number
widget.registry.getByUniProt(119) // by UniProt position
widget.registry.getByPDB(98)      // by PDB position
widget.registry.cells             // all 504 cells (for the IgV template)
widget.registry.residuesInChainOrder()  // residues sorted by IgStrand value

Cell object shape

Every cell carries the same shape, with fields that may be null when not applicable:

{
  row: 19, col: 11,
  excel_address: "L20",
  kind: "cell",
  fill: "#0432FF",
  borders: { left: "thick", right: "thick" },
  value: null,
  igstrand: 4550,
  residue: "L",
  uniprot:   { id: "P01732", version: 1, pos: 92, url: "..." },
  pdb:       { id: "1CD8", chain: "A", pos: 71, url: "..." },
  alphafold: { id: "AF-P01732-F1", version: 4, pos: 92, url: "..." },
  strand: "C'",
  is_lace: true,           // part of the drawn lace (colored or bordered)
  is_placeholder: false,   // empty cell (future insertion site)
  is_extensible: false,    // marked '…' for insertions
  is_anchor: true,         // xx50 position
  features: {}             // user-defined feature overlays
}

Events

The container fires custom events:

event	detail	when
cellhover	{ cell, event }	mouse enters a cell
cellleave	{ event }	mouse leaves the SVG
cellclick	{ cell, event }	a cell is clicked
cellhighlight	cell or null	widget.highlight() was called

Example:

document.getElementById('map').addEventListener('cellclick', e => {
  const cell = e.detail.cell;
  if (cell.igstrand) console.log(`Clicked ${cell.residue} (IgStrand ${cell.igstrand})`);
});

Bidirectional sync with external views

Use widget.highlight() to drive the widget from another view (sequence, 3D viewer, etc.), and listen to cellhover/cellclick to drive the other view from the widget.

// Highlight a cell from outside the widget
widget.highlight(2550);            // by IgStrand number
widget.highlight('L10');           // by Excel address
widget.highlight('9,11');          // by row,col

// Find the cell for a UniProt position (then optionally highlight or read data)
const cell = widget.registry.getByUniProt(119);
if (cell) widget.highlight(cell.igstrand);

Static export

IgFold2D.render() mounts an SVG into the container. The DOM is regular SVG you can serialize:

const svgEl = document.querySelector('#map svg');
const svgString = new XMLSerializer().serializeToString(svgEl);
// Save as .svg or convert to PNG via canvas

A pre-rendered standalone SVG with all data attributes (IgFold2D-CD8a.svg) is also published in releases for use as a publication figure or external reference.

Utilities

IgFold2D.version              // "0.1.0"
IgFold2D.excelAddress(r, c)   // → "L10"
IgFold2D.strandFromIgStrand(n)// → "C'" for 4550, "A'" for 1850, etc.
IgFold2D.createRegistry(template, assignment, sources)  // build a registry without rendering

This site is open source. Improve this page.