STRUCTURE.md

Structure comparison in Arbor 1.3

Choose Structure or Linked views beside Tree + alignment. The structure view uses the same pinned Mol* 5.11.0 runtime and compact viewport setup as EvoOnline, bundled locally. Rotate, pan, zoom, reset, screenshot and full-screen remain available through the viewport. The structure controls expose EvoOnline-style Show/Map, cartoon, atoms, molecular surface, and per-chain or global surface opacity.

Give the structure more room

The viewer fills the available height, and its controls occupy a 280 px sidebar by default. Drag the divider to widen or narrow the controls, or click Hide controls. Source loading and reference/query selectors live in that sidebar. Chain controls reflow into cards at narrow widths instead of requiring horizontal scrolling.

Click Maximize structure for a nearly full-window molecular view. Restore layout or Escape restores the previous layout. In Linked views, drag the horizontal tree/structure divider to allocate more height to either pane. The residue inspection panel starts collapsed; expand its summary and drag the divider above it to change its height. All these choices are included in Save session. Native Mol* screenshot/fullscreen controls remain available.

Load, map and compare

1. Load your existing alignment through Arbor's alignment controls. Set the sequence type correctly: protein or nucleotide. Full sequence headers are preserved.
2. Load a local PDB or mmCIF file (50 MiB maximum). Alternatively enter a four-character PDB ID and click Fetch PDB. Only this explicit fetch contacts RCSB; no alignment is transmitted. Local structure files and both analysis engines work without external services.
3. For nucleotide data, open Profile alignment settings and select the correct reading frame and genetic code (standard or vertebrate mitochondrial). Input must be a codon alignment. Frame 1 groups alignment columns 1–3, 4–6, etc.; frame 2 starts at column 2, and frame 3 at column 3. Partial-gap or ambiguous codons become unknown; gaps never silently shift the frame. Terminal partial codons are excluded. Warnings report partial gaps, stops and discarded leading/trailing columns.
4. Choose Reference and Query from the alignment. You can also select exactly one taxon in the tree/alignment, then use Selected taxon → reference/query. Swap reverses the pair.
5. Credible profile matches automatically display as opaque mapped surfaces. Weak matches stay hidden. Enable Show to retain a neutral context chain; enable Map to apply the comparison colors. Mapping weak matches is allowed but clearly flagged for review.
6. Change colors or representations freely. The query/reference pair and colors update without repeating profile alignment. Atoms + Cartoon shows side-chain heavy atoms only: backbone atoms and bonds are excluded, including Cα and terminal backbone oxygen aliases. Atoms with Cartoon off shows the complete chain (hydrogens remain hidden). This is decided independently for each chain and also applies to exported scenes and reopened sessions. Glycine has no side-chain heavy atoms. Surface opacity can be overridden globally without overwriting per-chain values; Use per-chain restores those values.

Show ligands (including glycans) is enabled by default under Structure chains & representations. It shows small-molecule ligands, carbohydrate/branched entities and ions as ball-and-stick atoms, independently of the protein-chain switches. The Mol* ligand selector excludes glycans and ions, so both are explicitly included. Water is excluded. These context atoms are not assigned reference/query difference colors. The toggle is preserved in sessions and exported MolViewSpec scenes.

The original chain mapping remains tied to the complete loaded MSA, even if Arbor is showing only selected taxa or disjoint regions. Color displayed alignment regions only controls a visual mask; it does not alter the mapping. For codons, a site is in the mask if any of its three original nucleotide columns is displayed.

Difference semantics

The map compares reference against query, not either sequence against the structure. Structure residues are anchors used to place alignment positions in 3D.

• Amino-acid differences is the default: unequal standard amino acids are red (editable). Synonymous codon changes are identical under this mode.
• Any nucleotide difference per codon is available for nucleotide alignments: any unequal unambiguous bases in a mapped codon make that residue red, including synonymous differences. U and T are treated as equivalent. The mapping still uses a translated protein profile.
• Count a residue ↔ gap as a difference is on by default. Query deletions and insertions are identified separately in the audit/export, while sharing the configurable difference color. Turn this off to treat those sites as missing rather than red.
• Gaps in both rows, ambiguous amino acids, and incomplete observations are neutral unknowns, not evidence of identity. Protein-mode stop symbols are unknown. Nucleotide mode can compare an unambiguous stop codon's literal bases, but stop codons do not contribute to the protein mapping profile.
• Identical, unknown, unmapped, context, and background colors are separately configurable.

An insertion without a coordinate-bearing structure residue cannot be painted onto that structure. The summary reports sequence differences separately from differences with shown mapped coordinates. The reference/query comparison can also differ at sites where the structure has a third amino acid; the 3D color still denotes the selected pair's comparison.

Mapping strategy from the attachment

The implementation ports makeProfile and alignProfile from the supplied interfacer.html:

1. Build standard-amino-acid frequencies for each full-MSA column (or translated codon column). Ambiguous residues, stops and gaps do not contribute.
2. Omit profile columns with no standard-amino-acid observations, retaining their original coordinate indices.
3. Score each structure residue against each active profile column using the frequency-weighted expected BLOSUM62 score.
4. Perform local Smith–Waterman dynamic programming with affine gaps, default opening penalty 10 and extension penalty 0.5.
5. Trace back from the best local endpoint to map coordinate-bearing chain residues to the original alignment columns. Missing coordinate segments can create gaps; mappings are never inferred from PDB residue numbers alone.

The attachment's weak-match heuristic is retained: fewer than min(20, chain length) mapped residues, less than 50% chain coverage, or score per mapped residue below 1. These are heuristic review flags, not homology probabilities. Identity shown is agreement with the profile consensus; coverage is the fraction of the coordinate-bearing chain that maps. The mapping runs in a dedicated cancellable worker with an 80-million-DP-cell guard per chain. All-gap profile positions are not counted in the DP width.

Unlike a consensus-only alignment, the profile uses frequencies across every alignment row. Switching reference or query therefore changes only the comparison, not the chain mapping.

Mol* parses structures and provides the first model's atomic hierarchy. The app extracts protein polymer residues, preserves label and author chain IDs, preserves insertion codes, and deduplicates alternate atom conformations at residue level. Modified residues follow the attachment's conventional amino-acid normalization (for example MSE→M, SEC→C). Biological assemblies, ensemble model switching and non-protein structures are not mapped; this view uses the first model's asymmetric unit.

Inspect, export and restore

• Hover over a residue for its author residue number, insertion code, original alignment coordinates and reference→query difference. Click a mapped residue to jump to the linked alignment.
• Reference / query / chain alignment shows the profile consensus, selected pair and coordinate-bearing chain in 120-site pages. It retains alignment coordinates, and every cell can jump to the linked alignment.
• Show difference sites in alignment displays all differing positions as potentially disjoint regions.
• Residue mapping + differences TSV includes all protein chains, author/label IDs, insertion codes, original 1-based alignment columns, pair residues, classification, and the weak-match flag. Chain Show/Map settings control the view; the TSV intentionally preserves mappings for all chains.
• MolViewSpec scene JSON is self-contained: coordinates are embedded as a data URL alongside current representations/colors. The viewport's native screenshot control exports the 3D view. Arbor's existing SVG/PNG buttons still export tree/alignment graphics, not 3D geometry.
• Save session stores structure bytes (including fetched PDB coordinates), sequence choices, mapping parameters, all structure checkboxes, chain settings, colors, the camera snapshot, inspected chain, inspection page and scroll position. Mappings are recomputed from the restored alignment and source when the Structure/Linked view is opened. No refetch or re-upload is needed. New sessions use format version 2; legacy version 1 sessions remain readable. Camera restoration also works when reopening a session with the same structure already loaded.

Validation and practical limits

The test suite checks exact algorithm parity against the attachment; actual Mol* PDB/mmCIF parsing; author/label IDs and insertion codes; MolViewSpec scene schema; protein/codon comparisons; synonymous/gap/unknown handling; per-chain/global settings; the complete controller flow; stale-worker rejection; and session/export data. Surface configuration is validated with the actual Mol* schema. Tests use a headless parser and stub the WebGL viewport: they do not validate GPU raster output, browser-specific transparency, native screenshots, or interactive mouse behavior. No cross-browser visual QA or live Pages deployment was performed.

Large molecular surfaces can be expensive to compute. Use cartoons for initial navigation, hide unnecessary chains, and reduce the loaded structure if the browser runs out of memory. Source files are limited to 50 MiB; this is a guardrail, not a promise that every structure below that size will render on every GPU. Mapping cancellation terminates the profile worker; a Mol* representation update already running completes before the latest queued update is applied.