Troubleshooting

The browser opens but the plot seems empty

Check the most common causes first:

  • threshold is too high
  • the relevant chains were removed from Chain Presence/Order
  • the per-chain link checkbox is off for one or both participating chains
  • Residue mode is selected when you expected dense Atom-mode links

The HTML says Render status: pending

Use a current build.

Older intermediate builds had a generated-JavaScript error that could prevent the page from initializing.

I do not see an AF3 contact probability slider

The slider appears only when all of these are true:

  • the command used af3FullData true,
  • at least one matching full_data_*.json file was found next to the source CIF,
  • at least one ChimeraX contact residue pair could be mapped to AF3 token_chain_ids and token_res_ids.

For a model named fold_example_model_0.um.cif, the expected JSON name is fold_example_full_data_0.json.

fold_example_model_0.amber-relaxed.cif is matched the same way.

af3FullData or useplddt fails before HTML is created

When AF3 full data is requested, every processed model must have a matching full_data_*.json file. Partial availability is treated as an error so that the plot is not silently filtered or colored from incomplete data.

Either add the missing JSON files or rerun without the AF3 option.

The DNA arc does not look right

Possible causes:

  • DNA merge detection did not match the input layout
  • a split/nicked duplex needs dnaMismatches adjusted
  • you may want dnaMode split for diagnosis

Try rerunning with:

circoscontacts dnaMode split

If that looks correct, the issue is in merge interpretation rather than missing chains.

Clicking a contact arc does not select what I expected

Remember:

  • the copied ChimeraX command is based on the real contributing source residues,
  • merged DNA display arcs do not copy as a pseudo-chain,
  • the actual strand/base residues are used when available.

Default colors is disabled

This means the HTML was created without usable ChimeraX ribbon colors.

Current plugin behavior reads ribbon/cartoon colors, not arbitrary other coloring sources.

If you want arc and contact-link colors to follow the structure view:

  1. apply ribbon colors in ChimeraX first
  2. then run circoscontacts

Those schemes are only captured if they end up as ribbon/cartoon colors on residues.

They are not currently read from:

  • surface-only colors
  • atom-only colors
  • map data by itself

Session JSON will not load

Use a session file produced by the current tool.

Current accepted schemas:

  • contacts-circos-session-v1
  • contacts-circos-session-v2

Invalid or unrelated JSON files will be rejected.

Saved HTML opens, but I want to know exactly how it was created

Use the Info button in the HTML.

It shows:

  • tool version
  • timestamp
  • invocation string
  • source model metadata

ChimeraX Colors does not recolor the residues I expected

Check:

  • threshold at export time
  • chain order / chain inclusion
  • per-chain link checkbox state
  • count mode
  • whether the structure currently loaded in ChimeraX matches the original chain IDs and residue numbering