ChimeraX Command

Syntax

circoscontacts [objects] [restrict <spec>] [outputDir <path>] [title <text>] \
               [interModel true|false] [intramol true|false] \
               [dnaMismatches <N>] [dnaMode auto|merge|split] \
               [openHtml true|false] [keepTemp true|false]

Run usage circoscontacts inside ChimeraX for the exact installed signature.

How It Uses contacts

The plugin is intentionally built around ChimeraX contacts semantics.

Internally it runs contacts once per selected structure, saves those contact files, then aggregates them into the circos plot.

Default source behavior

If you run:

circoscontacts

then for each open structure the plugin conceptually does:

contacts <model-spec> & protein interModel false intramol false saveFile <...>

This means:

  • contacts must involve protein on one side,
  • inter-model contacts are off by default,
  • intramolecular contacts are off by default.

That default is deliberate: it suppresses uninformative DNA-along-DNA contact clutter.

objects

If you provide an object specification, that becomes the source spec, intersected per structure.

Example:

circoscontacts #1,3,4 & protein

This limits processing to the matching subset of the open models.

restrict

restrict is passed through in the same style as ChimeraX contacts.

Example:

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

This means:

  • the source side is residues 100–120 of chains S,T in models #1,#2,
  • the target side is limited to chains S,T,C,
  • normal contacts rules still apply to self/intramolecular handling.

Important Aggregation Rules

Canonicalization

Displayed links are canonicalized:

  • endpoint order does not matter,
  • the same contact found in different models contributes to one displayed link.

Count modes

The HTML can display counts two ways:

  • Atom: every atom–atom contact row counts,
  • Residue: each displayed residue-pair arc counts at most once per model.

For merged DNA arcs, Residue mode avoids overcounting a single model just because both nucleotides of a base pair contact the same protein residue.

DNA Handling

The plugin can merge DNA chains into one logical DNA arc.

dnaMode

  • auto: detect mergeable DNA layouts automatically
  • merge: force merged behavior when possible
  • split: keep DNA chains separate

dnaMismatches

Used when detecting split/nicked dsDNA where reverse-complement matching is required.

  • 0: exact match
  • N > 0: allow up to N mismatches

Output Options

outputDir

Write the generated HTML and intermediate files to a specific directory.

circoscontacts outputDir /tmp/circos_run

openHtml

If true, open the generated HTML automatically in the default browser.

keepTemp

If outputDir is not given, the plugin writes to a temporary directory. keepTemp controls whether those artifacts are retained.

Examples

All open structures

circoscontacts

Selected models only

circoscontacts #1,3,4 & protein

Restrict contacts to a window against defined chains

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

Force split DNA display

circoscontacts dnaMode split

Keep generated files in a stable directory

circoscontacts outputDir ~/Desktop/circos_run title "SPO11 ensemble"

Provenance Stored In HTML

The generated HTML stores:

  • plugin version,
  • timestamp,
  • reconstructed circoscontacts invocation,
  • model names,
  • model filenames and paths when available.

This information is accessible from the HTML Info button.