py2Dmol, embedded

The div is yours, the canvas inside it is the library's. PDB or mmCIF, told apart by looking at the text, so you do not have to say which you have.

The frame around the canvas is on by default. box: false takes it off.

Getting the text. show takes a string, so it is yours to fetch, read from a file input, or write into the page. For the two public archives there is a helper that knows the URLs:

const text = await py2Dmol.fetch('1UBQ');    // four characters: the PDB
const text = await py2Dmol.fetch('P01308');  // anything else: AlphaFold
py2Dmol.show('mol', text);

It is separate from show and hands back text rather than a viewer, so a download that fails — offline, a wrong id, a slow server — is yours to catch, and show stays something that either works or throws immediately.

Biological assemblies are built by default. A crystal structure file holds the asymmetric unit, which for anything symmetric is a fraction of the real molecule — one protomer of a trimer, a sixtieth of a capsid — along with the operations that make the rest. Those are applied unless you say otherwise:

py2Dmol.show('mol', text, { biounit: false });   // the deposited coordinates

A file with no assembly records is drawn exactly as it is, which is most files, so the default costs a search that finds nothing.

Pass it to show as style, or change it later with setStyle. Both take the same four names.

3d comes up on a black page, since solid shaded geometry is meant to be seen on one. bg: 'white' overrides that.

auto · chain · rainbow · plddt · deepmind · ss · hydrophobicity. A name it does not know throws, rather than leaving the picture unchanged and letting you wonder.

hydrophobicity is Kyte & Doolittle in five buckets rather than a ramp, orange for the core and blue for the surface, so you can point at a band and name it. py2Dmol.hydrophobicityBands is the same five, in order, for a legend.

plddt reads the B-factor column, which in a crystal structure is a real B-factor rather than a confidence.

This is the selector, and everything else on the page takes the same one. A bare string is a chain, {range} is half open, and {residues} is the numbering in the file.

Colours accumulate: a range and then a chain leaves both in place. To start again, set a mode.

select adds, unselect takes away, and unselect() with nothing to take away clears.

Clicking the canvas selects too: a click takes a residue, shift-click adds another, double-click takes the whole chain, and a click on the background clears. select: false turns that off for a viewer meant only to be looked at.

hide takes residues off, show puts them back, and resetVisibility() returns to everything. To draw one thing and nothing else, reset first and hide the rest: v.resetVisibility(); v.hide({not: sel});

What is hidden is hidden to everything else too: it cannot be clicked, and it does not pull the camera when you orient.

{type} is what a position is: 'L' ligand, 'P' protein, 'N' nucleic. You do not need to know what the ligand is called.

{near} is everything within 5 Å of another selector, measured atom to atom. That is a contact shell — a hydrogen bond is under 3.5 and a salt bridge under 4. {angstroms} changes it.

The ligand is part of site, since it is within 5 Å of itself. {not: {type: 'L'}} would leave it out.

hideSidechains takes them away again.

setSidechainColor takes a colour or a whole colour mode, and the same selector as everything else. It is a second colour, not a replacement: a side chain nobody spoke for follows its residue, so recolouring the main chain carries it along, and one given a colour of its own stays put. That is what lets a backbone say plddt while its side chains say hydrophobicity — two questions on one picture. v.setSidechainColor(null) hands them back.

They arrive coloured by element — carbon in the residue's own colour, oxygen red, nitrogen blue — and so does a ligand. That is on by default, since those are the atoms with an element worth reading; v.hideElements(sel) turns it off for a flat colour, and v.showElements(sel) puts it back.

This needs a structure that carries side-chain atoms — a C-alpha trace has none, and asking for them throws rather than quietly doing nothing. The file here keeps every C-alpha, and all the atoms of the residues nearest the ligand.

With no selector it frames the selection, or everything visible if nothing is selected.

{animate: false} jumps instead of flying. On load it never animates, and orient: false keeps the file's own orientation for a structure that already sits the way you want it.

The slab is as thick as the selection is deep, and refits as you turn, so it stays over the site rather than at a fixed depth. Drag it and watch.

To cut deeper, clip to less: v.clip({type: 'L'}) keeps a thinner slice than v.clip(site). There is no separate thickness setting — the selector is it.

v.clip() with no selector turns it off.

A file with more than one model gets a player; a single structure stays a bare canvas. play: false refuses it, play: true insists.

The player is the library's: play, a slider, a counter and a speed control. You can also step frames from code with v.setFrame(i).

Bases are drawn as plates on the backbone. Nothing asks for that either — a structure holding protein and nucleic is drawn as both.

Within one structure an end is either a position or a chain and residue number: [5, 60, 1.0] or ['A', 12, 'B', 34, 1.0].

An empty list clears them. Contacts belong to the structure, so loading over it replaces them.

Names are yours to choose. They are deliberately not A and B here, which is what the chains inside a structure are called.

The camera widens to take in a structure it has not framed before. Hiding one and showing it again leaves the camera where it is.

A contact can join two different structures. Each end names its own, and the contact belongs to the viewer rather than to either one, so you pass no name.

The canvas is looked up inside its own container, so the containers are what must be distinct. Everything the library creates inside them is scoped and may repeat.

The two viewers are independent: a selection, a style or a camera in one does not touch the other.

Style, Capture and every slider, plus Orient and Rotate. Off by default: most embeds want a picture and nothing else.

And the selection panel, which arrives with it: click a residue and it slides in with the website's own controls — colour (a PyMOL palette or a scheme, on the main chain and the side chains separately), Show/Hide per part, element colours, base plates, a secondary-structure override, contacts between a pair, Find interactions, and Copy / Cut / Delete. Pass select: false to keep the chrome and turn picking and the panel off. Align is the one row that does not travel: it needs align/align.js, which can never be bundled, so the row hides itself here.

Its styling is scoped to your container, so it cannot reach your page's own dropdowns or buttons.

It stays inside the box you give it. On a fixed height the panel scrolls; in a container too narrow for the panel beside the canvas, it wraps underneath.

The bundle carries the panel; your page carries the box — a #heatmapContainer holding a #heatmapCanvas (the older #paeContainer / #paeCanvas still work). controls: true is not optional: it selects the shell that mounts the panels.

A map describes itself. vmin/vmax are the values the bytes are encoded against, colors is a list of stops, and xlabel/ylabel caption the axes — all of them beating the panel's built-in scale for that key. The tab is named by the key, so two maps in one frame are two tabs.

Numbered slots, the same tabs over each. The viewer's box is slot 1 and this one is slot 2; each shows the structure, a map or the scatter plot, each can be dragged to size, and picking in one what another shows swaps them. With no coordinates yet the map takes the first, and full screen is slot 1's. slots: ['contact'] in the options, or v.setSlots(['pae', 'structure']) later, chooses from code — one name per slot, in order, and a short list leaves the rest alone.

Dragging a box on the plot selects those residues in the structure, and a box is stored in residues — so it means the same thing on every map, whatever each one's resolution.