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,
  • 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.20-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

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.

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,
  • count mode,
  • transparency,
  • default vs ChimeraX-derived arc colors,
  • chain order,
  • per-chain link visibility,
  • flips,
  • 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: