Workflows

1. First-Time Use

Use this if you are starting from scratch.

  1. Open the relevant models in ChimeraX.
  2. Run:
circoscontacts
  1. In the browser:
  2. set Contact mode to Residue for ensemble recurrence
  3. raise the threshold until noisy links disappear
  4. reorder or hide chains if needed
  5. Export:
  6. Save Session for later editing
  7. Download SVG for figures

2. Ensemble Summary With DNA Merge

Use this when protein contacts to dsDNA are the main target.

  1. Open the full model set.
  2. Run:
circoscontacts title "Protein–DNA ensemble contacts"
  1. Confirm the DNA arc is merged as expected.
  2. Switch between:
  3. Atom mode for dense contact detail
  4. Residue mode for per-model recurrence
  5. Use thresholding to find persistent contacts.

3. Restrict Contacts To A Source Window

Use the plugin the way you would use ChimeraX contacts with a source and a target.

Example:

circoscontacts #1,2/S,T:100-120 restrict /S,T,C interModel false intramol false

Recommended follow-up in the HTML:

  • inspect active masked arc regions to confirm the input window,
  • use shift-click residue isolation to inspect specific sites,
  • use Contacts @ threshold in the selection menu to copy back only the currently supported contacts.

4. Match Arc Colors To Structure Colors

If your ChimeraX ribbons are already colored meaningfully:

  1. color ribbons in ChimeraX first
  2. run circoscontacts
  3. in the HTML, uncheck Default colors

The arcs will switch to the captured ChimeraX ribbon colors.

This is useful when you want the circos arc colors to match the structure view.

5. Build An Annotated Figure

  1. Choose final threshold and contact mode.
  2. Set chain order and optional bottom lock.
  3. Add selections for motifs or domains.
  4. Create sequence or comment callouts.
  5. Adjust callout placement and size.
  6. Export SVG.

Recommended discipline:

  • Save Session before major annotation changes
  • Save HTML once the figure state is stable

6. Send Selections Back To ChimeraX

There are two useful routes.

Click a visible contact arc.

This copies a ChimeraX select command for the actual contributing residues.

From a selected region

Use the selection popup:

  • All models: select the whole region across all models
  • Contacts @ threshold: select only the residues supporting visible contacts at the current threshold

This is useful for jumping back from the circos view to structural inspection.

7. Recolor Structures To Match The Plot

After tuning the visible links in the HTML:

  1. click ChimeraX Colors
  2. in ChimeraX, run:
open /path/to/contacts_circos_colors.cxc

This recolors residues corresponding to the currently visible links.

8. Preserve Provenance

When you need the output to remain self-describing:

  • use Save HTML
  • use the Info popup to verify the embedded metadata

Stored provenance includes:

  • version
  • timestamp
  • invocation
  • model names
  • file names / paths when available