ChimeraX CircosContacts

circoscontacts is a ChimeraX command plugin for summarizing contacts across one or more open models as an interactive circos-style HTML plot.

It is designed for workflows where you want to:

  • aggregate contacts across a model ensemble,
  • treat dsDNA as one logical track when appropriate,
  • optionally combine ChimeraX contacts with AlphaFold3 contact_probs,
  • inspect recurrent contacts interactively,
  • annotate regions and sequences,
  • export a figure (.svg), a ChimeraX coloring script (.cxc), or a reusable session (.json).

What The Plugin Does

From ChimeraX, circoscontacts:

  1. identifies the requested models,
  2. runs ChimeraX contacts on each structure,
  3. aggregates the resulting contact files,
  4. builds an interactive contacts_circos.html,
  5. opens that HTML in your default web browser.

The HTML is the main analysis surface. Most filtering, annotation, and export actions happen there.

Install

Most users should install through the ChimeraX Toolshed UI:

  1. In ChimeraX, open More Tools...
  2. This opens the Toolshed browser inside ChimeraX.
  3. Search for CircosContacts.
  4. Install the tool from there.

You can also install from the ChimeraX command line:

toolshed install /path/to/chimerax_circoscontacts-0.4.31-py3-none-any.whl

For local development:

devel install /path/to/tools/chimerax_circoscontacts

After installation, confirm the command exists:

usage circoscontacts

Quick Start

Basic use

  1. Open one or more models in ChimeraX.
  2. Run:
circoscontacts
  1. Wait for the browser window to open.
  2. In the HTML view, adjust threshold, ordering, and contact mode.
  3. Export what you need:
  4. Download SVG
  5. ChimeraX Colors
  6. Save Session
  7. Save HTML

Typical defaults

If you simply run circoscontacts with no arguments:

  • all open atomic structures are used,
  • contacts are computed per model,
  • source contacts are restricted to protein on one side,
  • interModel false
  • intramol false
  • AF3 full-data JSON parsing is off unless af3FullData true or useplddt true is supplied

This avoids trivial DNA-DNA self-contact clutter and emphasizes protein-involving contacts.

Main Concepts

Chains and arcs

Each displayed chain becomes a circos arc.

  • protein chains are shown individually,
  • DNA chains may be merged into one logical DNA arc,
  • split/nicked dsDNA can also be detected and merged when it matches the expected geometry.

Each displayed link is an aggregated contact between two displayed residue positions.

Direction is ignored:

  • A:55 ↔ B:28
  • B:28 ↔ A:55

are treated as the same displayed link.

Atom mode vs Residue mode

The HTML provides two count modes:

  • Atom: count every atom–atom contact row.
  • Residue: count each displayed contact arc at most once per model.

Residue mode is usually the better measure of recurrence across an ensemble.

AF3 contact probability mode

If the command is run with af3FullData true, the plugin searches for matching AlphaFold3 full-data JSON files next to the model CIF files and maps contact_probs values onto displayed contact links.

The HTML then provides a separate Minimum AF3 contact probability slider. This filter uses the mean AF3 contact probability across the processed models, with models lacking that displayed ChimeraX contact contributing zero, and is independent of the normal contact-count threshold. Contact-link hover text reports both mean and maximum AF3 contact probability.

If the command is run with useplddt true, residue pLDDT values from the same full-data JSON files desaturate the chromosome arcs: high-confidence residues retain the normal arc color, while low-confidence residues approach gray.

When AF3 full data is requested, every processed model must have a matching JSON file or the command fails before producing HTML.

Files and Outputs

The plugin writes a browser-facing HTML file and supporting temporary artifacts.

From the HTML view you can export:

  • contacts_circos.svg: static figure export
  • contacts_circos_colors.cxc: recolor matching residues in ChimeraX
  • contacts_circos_session.json: reusable interactive state
  • contacts_circos.html: full standalone HTML snapshot

What Is Preserved

Save Session

Save Session stores interactive state such as:

  • threshold,
  • AF3 contact-probability threshold when present,
  • count mode,
  • transparency,
  • default vs ChimeraX-derived chromosome/contact colors,
  • chain order,
  • per-chain link visibility,
  • flips,
  • single-chain or adjacent-chain junction bottom lock,
  • selections,
  • callouts,
  • callout positions and sizes.

This is intended for reapplying the same view logic.

Save HTML

Save HTML stores the entire current page state in a standalone HTML file.

That saved HTML remains interactive when reopened and also contains provenance information available under the Info button:

  • tool version,
  • timestamp,
  • invocation string,
  • model names / filenames,
  • original paths when available.

Learn The Interface

Start here: