PyMOL plugin brings protein circuit topology into the molecular viewer

A new open-source PyMOL plugin allows researchers to analyze the circuit topology of proteins directly inside a widely used molecular-visualization environment, eliminating much of the setup required by the original script-based ProteinCT workflow. Version 0.0.4 combines contact detection, topological classification, plotting and data export in a graphical interface, and its developers report exact agreement with the reference implementation for the structures tested. The software also adds batch processing, trajectory analysis, non-destructive coloring of three-dimensional structures and a published metric designed to characterize compaction in intrinsically disordered proteins.

The plugin translates a specialized mathematical description of protein architecture into an interactive workflow for selecting structures, setting contact criteria and examining results. Its three tabs correspond to local circuit topology, single-file analysis and multi-file analysis. Local analysis focuses on the contact pairs surrounding a selected residue; single-file mode classifies the topology of an entire molecular object; and multi-file mode processes a folder of structures or the frames of a molecular-dynamics trajectory. PDB and mmCIF structures can be imported through the interface, while objects already loaded into PyMOL can be analyzed without exporting them first.

At the center of the system is a contact-pair map constructed from geometric proximity. By default, the software detects contacts between heavy atoms, ignores hydrogen atoms, requires at least five atom-to-atom contacts within a residue pair, and excludes residues separated by no more than three positions along the chain. The 4.5-ångström distance threshold and both filters are adjustable, making explicit how apparently objective structural relationships depend on user-selected criteria. An optional ProteinCT-identical mode counts all atoms, including hydrogens, but the developers warn that this can reduce comparability between models with different hydrogen representations.

For a single chain, the plugin classifies relations between pairs of contacts according to the order of their endpoints along the protein sequence. Nested endpoints produce Parallel or Inverse Parallel relations, separated endpoints produce Series relations, and interleaved endpoints produce Cross relations. The program also handles concerted variants of these categories. A Cross relation describes sequence ordering only: it does not by itself establish a physical crossing, threaded segment or protein knot, because circuit topology is not a geometric knot measure. The relation matrix, circuit diagram, contact-length and contact-energy filters, and the fraction of Parallel-plus-Cross relations described by ProteinCT as entanglement statistics are inherited from the established method.

Multi-chain models require an expanded vocabulary. Contact detection spans all chains in the object, including inter-chain pairs, but the basic Series, Parallel and Cross labels are assigned only when both contacts lie within the same chain. Relations involving contacts between different chains are labeled Independent, Tandem or Loop according to the multi-chain scheme adapted by ProteinCT. Despite the whole-model contact search, residue coloring and the CT Folding Score are calculated separately for each chain using intrachain contacts. The software therefore distinguishes the scope of global relation analysis from chain-specific measures while leaving the underlying contact map available for inspection and tuning.

Among the additions beyond the original toolkit is a direct projection of topological participation onto the three-dimensional structure. For each selected relation type, the plugin counts the relations involving every contact pair and adds that count to both endpoint residues. These values are not numbers of a residue’s own contacts, but sums of its participation in topological relationships. The colors are divided into five levels and scaled separately for each map, so equal colors across different relation panels do not represent equal numerical values. Coloring is applied to a copy of the molecular object, preserving the deposited B factors of the original structure, and the three-dimensional visualization currently supports the basic Series, Parallel and Cross types rather than their concerted counterparts.

The release also implements the CT Folding Score proposed by Akulov and colleagues as a quantitative measure of compaction in intrinsically disordered protein chains. In the developers’ demonstration using hen egg-white lysozyme, PDB accession 1AKI, single-file analysis generated a color-coded relation matrix, a circuit plot, three-dimensional residue maps and CSV files containing the contact-pair map and relation matrix. The reported distribution for chain A was 57.4% Series, 31.0% Parallel and 11.6% Cross relations, with the Parallel total including concerted parallel categories and the Series total including concerted series, following the reference ProteinCT definition. The lysozyme structure contains no deposited hydrogen atoms, so the hydrogen setting did not affect this example.

Multi-file analysis was used to examine 205 frames from replica 3 of a molecular-dynamics trajectory of the AF1c S203P fragment of the glucocorticoid receptor, an intrinsically disordered protein. The source simulation used GROMACS, the amber99SBdisp force field, 150 mM sodium chloride, a temperature of 310 kelvin and a one-microsecond duration for each replica. When the default heavy-atom criterion was used, three frames contained no residue pair meeting the contact threshold; the plugin identified and skipped those frames, leaving 202 in the final time-resolved output. The numbers of Series, Parallel and Cross relations fluctuated, and an increase followed by a return toward baseline was consistent with transient compaction, rather than proving a specific folding transition. Separate analyses with and without hydrogens showed the same qualitative pattern.

Validation extends beyond visual demonstrations. Automated tests install PyMOL 3.1.6.1 on clean Windows Server 2025, Ubuntu 24.04 and macOS 15 systems, install the plugin through PyMOL’s Plugin Manager and run the complete suite inside that environment. Interactive use was also checked manually on Windows 10, Windows 11, Ubuntu Linux 24.04 and macOS 15. On Apple Silicon, the tested PyMOL application ran through Rosetta 2 because no native arm64 build was available. The project supplies a Docker-based reproducible capsule, a PyMOL script, an exactly pinned conda environment, platform-specific lockfiles and automated parity artifacts comparing the plugin with the reference method. The MIT-licensed release is openly available through GitHub, with permanent archives provided through Zenodo.

Several limits constrain interpretation and use. The plugin analyzes polymer components, automatically excluding and reporting waters, ions, ligands and other non-polymer atoms. Nucleic acids and unknown residues are removed, while modified residues deposited as heteroatom records can leave gaps even when they occupy backbone positions. At least two intrachain contact pairs are required for a relation to exist, so extremely small structures cannot be analyzed in this way. Contact-length and energy filters apply only to single-chain structures, and the energy filter recognizes the 20 standard amino acids. Memory use is modest for a small static structure but rises sharply when an entire trajectory is colored, reaching approximately 1.3 gigabytes for 200 frames of a small protein. The tool therefore makes protein circuit topology more accessible, but its classifications remain threshold-dependent descriptions of contact organization rather than direct measurements of binding strength or physical entanglement.

Subject of Research: A PyMOL plugin for analyzing and visualizing protein circuit topology.

Article Title: PyMOL plugin for protein circuit topology

Article References: Dimiņš, M., Bazba, A., Mogyorósi, Á., Kennon, E., Fiol, T. D., Hagen, L. A., Sheikhhassani, V., Akulov, V., & Mashaghi, A. (2026). PyMOL plugin for protein circuit topology. SoftwareX, 36, Article 103142. https://doi.org/10.1016/j.softx.2026.103142

Image Credits: AI Generated

DOI: 10.1016/j.softx.2026.103142

Keywords: PyMOL, protein topology, ProteinCT, structural biology, molecular visualization, protein contacts, intrinsically disordered proteins, molecular dynamics, open-source software, circuit topology, plugin, protein