ChimeraX Command

Syntax

circoscontacts [objects] [restrict <spec>] [outputDir <path>] [title <text>] \
               [interModel true|false] [intramol true|false] \
               [dnaMismatches <N>] [dnaMode auto|merge|split] \
               [af3FullData true|false] [useplddt true|false] \
               [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.

When the source spec is narrower than the full model, such as sel or a residue range, the generated plot keeps the source chains visible and makes partner chains available for display. Chains that do not participate in the filtered result are available in the HTML but are omitted from Chain Presence/Order by default.

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.

AlphaFold3 Full Data

af3FullData true enables optional parsing of matching AlphaFold3 full-data JSON files.

For each model CIF, the plugin looks in the same directory for the matching file:

  • fold_name_model_0.cif -> fold_name_full_data_0.json
  • fold_name_model_0.um.cif -> fold_name_full_data_0.json
  • fold_name_model_0.amber-relaxed.cif -> fold_name_full_data_0.json

When found, the JSON contact_probs matrix is sampled for each ChimeraX contact residue pair. The resulting HTML adds a Minimum AF3 contact probability slider that filters on mean contact probability across the processed models, with models lacking that displayed ChimeraX contact contributing zero; contact-link hover text reports both mean and maximum contact probability.

useplddt true uses atom_plddts from the same JSON files to modulate chromosome arc saturation. High-confidence residues retain the normal arc color; low-confidence residues become gray.

This is disabled by default because loading the full matrices can be expensive for large models or ensembles. If AF3 full data is requested but any matching JSON file is missing, the command fails with an error in the ChimeraX log.

Chain Sequence Warnings

The plot aggregates contacts by chain ID and residue number. If two open models contain a protein chain with the same chain ID but different sequence or residue set, circoscontacts emits a warning.

The plot is still generated, but interpretation should be cautious because a displayed chain position may not represent the same residue identity in every model.

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

Include AF3 contact probabilities

circoscontacts af3FullData true

Desaturate arcs by AF3 pLDDT

circoscontacts useplddt true

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.