{"id":25167169,"url":"https://github.com/biocomputingup/ring-pymol","last_synced_at":"2025-04-30T22:02:50.135Z","repository":{"id":65488430,"uuid":"407498086","full_name":"BioComputingUP/ring-pymol","owner":"BioComputingUP","description":"This is the public repository for the RING PyMOL plugin developed by the BioComputing UP laboratory at the University of Padua","archived":false,"fork":false,"pushed_at":"2025-02-04T13:30:32.000Z","size":10063,"stargazers_count":23,"open_issues_count":2,"forks_count":5,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-02-04T14:34:20.715Z","etag":null,"topics":["bioinformatics","plugin","pymol"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BioComputingUP.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-09-17T10:24:15.000Z","updated_at":"2025-02-04T13:30:37.000Z","dependencies_parsed_at":"2024-01-29T16:37:46.225Z","dependency_job_id":null,"html_url":"https://github.com/BioComputingUP/ring-pymol","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BioComputingUP%2Fring-pymol","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BioComputingUP%2Fring-pymol/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BioComputingUP%2Fring-pymol/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BioComputingUP%2Fring-pymol/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BioComputingUP","download_url":"https://codeload.github.com/BioComputingUP/ring-pymol/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237911253,"owners_count":19386040,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bioinformatics","plugin","pymol"],"created_at":"2025-02-09T06:19:47.665Z","updated_at":"2025-02-09T06:19:48.815Z","avatar_url":"https://github.com/BioComputingUP.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# RING PyMOL plugin\n\n\u003c!-- TOC --\u003e\n* [RING PyMOL plugin](#ring-pymol-plugin)\n  * [Install](#install)\n    * [Installation of PyMOL and python dependencies](#installation-of-pymol-and-python-dependencies)\n      * [Installation of PyMOL with apt](#installation-of-pymol-with-apt)\n      * [Installation of PyMOL with Conda from yml file (RECOMMENDED)](#installation-of-pymol-with-conda-from-yml-file--recommended-)\n      * [Installation of PyMOL with Conda](#installation-of-pymol-with-conda)\n    * [NOTE](#note)\n    * [Install the RING plugin](#install-the-ring-plugin)\n    * [Singularity container](#singularity-container)\n* [Usage Instructions](#usage-instructions)\n  * [Configuration](#configuration)\n    * [RING](#ring)\n    * [Visualization](#visualization)\n  * [Executing RING and visualize the edges](#executing-ring-and-visualize-the-edges)\n    * [Filtering the results](#filtering-the-results)\n  * [Nodes](#nodes)\n    * [Pairwise interaction plot](#pairwise-interaction-plot)\n    * [Nodes interaction table](#nodes-interaction-table)\n    * [Color nodes by interaction frequency](#color-nodes-by-interaction-frequency)\n  * [Edges](#edges)\n    * [Interaction plots](#interaction-plots)\n      * [Chain interactions](#chain-interactions)\n      * [Secondary structure interactions](#secondary-structure-interactions)\n    * [Probabilistic interchain residue contact map](#probabilistic-interchain-residue-contact-map)\n    * [Pairwise interaction correlation analysis](#pairwise-interaction-correlation-analysis)\n  * [Clustering](#clustering)\n    * [Calculation of the hierarchical clustering](#calculation-of-the-hierarchical-clustering)\n    * [Clustering visualizations](#clustering-visualizations)\n    * [Create object](#create-object)\n  * [Example](#example)\n\u003c!-- TOC --\u003e\n\n## Install\n\n### Installation of PyMOL and python dependencies\n\n#### Installation of PyMOL with apt\n\n- `sudo apt install pymol python3-pip python3-tk`\n- `pip install pmw networkx numpy scipy seaborn pandas qt-material biopython requests tqdm`\n\n#### Installation of PyMOL with Conda from yml file (RECOMMENDED)\n\n- Install conda, following the instructions on their website\n- Download the environment.yml file from this repository\n- Create the environment with `conda env create -f environment-open-source.yml`\n  - To install the schrodinger version of PyMOL use the `environment-schrodinger.yml` file\n- Activate the environment with `conda activate ring-pymol`\n\n#### Installation of PyMOL with Conda\n\n- Install conda, following the instructions on their website\n- Create a new environment and switch to it\n    - `conda create -n myenv`\n    - `conda activate myenv`\n- Install PyMOL in the new environment\n    - `conda install -c conda-forge -c schrodinger pymol-bundle` (schrodinger version)\n    - `conda install -c conda-forge pymol-open-source` (open-source version)\n- Install python dependencies for the plugin\n    - `conda install networkx numpy scipy seaborn pandas requests biopython tqdm`\n    - `pip install qt-material` (This will be installed in the conda environment)\n\n### NOTE\n\nPlease check that the PyMOL executable that you are running is the one for which you installed all the dependencies.\nE.g.\n`which pymol` should return something like `/opt/miniconda3/envs/myenv/bin/pymol` if installed with the recommended\nconda installation.\n\n### Install the RING plugin\n\n- Open PyMOL and go to Plugin \u003e Plugin Manager \u003e Install New Plugin \u003e Install from Repository \u003e Add..\n    - Add https://biocomputingup.it/shared/ring-plugin/\n- Click on ring-plugin.zip in the right panel and then Install\n- Set the installation directory\n-\n- The plugin should now appear on the Plugin menu of PyMOL\n\n### Singularity container\n\nAnother option for installing the plugin is to use the singularity container definition file provided in this\nrepository.\nTo create the image file you can follow these steps:\n\n- `sudo singularity build -F ring-pymol-plugin.sif singularity.def` (this will create the image file)\n- `singularity shell --cleanenv --writable-tmpfs -B ~/.Xauthority ring-pymol-plugin.sif` (this will open a shell in the\n  container).\n  Note that the -B option is needed to allow the container to access the X server of the host machine for displaying the\n  GUI.\n- Start PyMOL with `pymol`\n- Add a new directory where to find new plugins\n    - Plugin \u003e Plugin Manager \u003e Settings \u003e Add new directory...\n    - Add `/opt`\n- Restart PyMOL\n- The plugin should now appear on the Plugin menu of PyMOL\n\n# Usage Instructions\n\n## Configuration\n\n### RING\n\nIn the configuration tab you can configure the settings for the RING software\n\n- If you want to execute RING locally or on a remote server using the RING WS APIs (https://ring.biocomputingup.it).\n- The location of the RING executable, if it is placed on the default location it will be picked up automatically\n- The options for the edge filtering\n    - Multi: Computes multiple edges for a pair of nodes, filtering out connections triangular connections like the one\n      showed in the image below. It retains the connection with the lower distance computed between the interacting\n      atoms.\n\n    - One:Return only the most valuable connection between two residues.\n\n    - All: Return all the connections found.\n- Sequence separation, the minimum distance that is required between two residues in the sequence to compute the\n  interactions between them.\n- Distance thresholds, the maximum distance that can exist between two atoms (or residues) to have a specific\n  interaction\n- Re-execute RING every time: use this checkbox if you want to override the save function for the RING results of the\n  plugin and re-execute the software each time instead of filtering the stored result. Use this if you modified the\n  object or if you loaded a different version of the same object.\n\n### Visualization\n\nThis tab is reserved for settings of the CGO (the edges) and we can find settings regarding\n\n- The width of the edge\n- The transparency of the edge\n- The color of the edge associated to each type of interaction calculated by RING\n\n## Executing RING and visualize the edges\n\nTo run RING on a structure you can fetch a PDB structure from the PDB repository with the command `fetch PDB_ID`. Then\nopen the plugin and at the top check that the object you fetched is selected in the drop-down menu.\n\nTo run RING on that object press the `Execute RING` button. The RING software will be executed on the selected object.\nYou can see the execution progress on the progress bar that appears when the object is exported and loaded into RING.\n\nThe drawing of the computed edges is automatic and they will be filtered in compliance with the selected filters.\n\nThe edges are loaded as Compiled Graphic Objects (CGO) in PyMOL grouped by interaction type `obj_interactionType` and\nfinally all the interactions for that objects are placed in a group called `obj_edges`.\n\nThe shown interactions are shown state-by-state, meaning that the interactions are shown for a specific state. If you\nnavigate to different states the interactions will change showing the interactions for that particular state.\n\nIn the same way a selection for the nodes involved in a interaction is created, and all the selected nodes are placed in\na group called `obj_nodes`.\n\n### Filtering the results\n\nUse the switches and controls in the top bar to filter the edges computed by the RING software. If the analyzed object\nhas multiple states then you can filter the interactions by their frequency, setting a minimum and maximum frequency.\nInteractions that have a frequency that is not in that range will be filtered out from the visualization.\n\nTo visualize the results click on the `Show` button if RING was already launched, or `Execute RING` on the object.\n\n## Nodes\n\n### Pairwise interaction plot\n\nBy creating a selection of exactly two residues, and selecting the selection in the top bar, it is possible to produce a\nplot showing the interaction occurring during an MD simulation (or in a multi-state structure) between the two residues.\nIn this plot different series represent different types of interaction occurring. In the $x$ axis the number of states\nis represented, while in the $y$ axis there is the distance of interaction.\n\n### Nodes interaction table\n\nClicking on this button will open a new window containing a table where all the residues of the selected structure that\nare interacting are listed, with their frequency of interaction for each type of possible interaction. This is useful\nto see for example if a residue is involved in a certain type of interaction, and the frequency of this interaction\n(when the structure has multiple states).\n\nThe rows of the table can be selected in order to create a new selection (`sele_rows`) in PyMOL with the selected\nresidues.\nThe selection can be expanded by clicking on multiple rows. To reset the selection one can delete it\nfrom PyMOL and then restart to select new rows.\n\n### Color nodes by interaction frequency\n\nThis option lets you color the residues of the selected object based on the frequency of interaction of a certain type.\nThe coloring is done using a heatmap, where the residues with the highest frequency are colored in blue, while the\nresidues with the lowest frequency are colored in white.\nThe frequency is computed on the number of states that a residue present the selected type of interaction over the\ntotal number of states.\n\nSelect the interaction of interest and then click on `Color nodes` to color the nodes in the structure.\n\n## Edges\n\n### Interaction plots\n\nThe following two graphs are intended for giving a quick overview of the interactions occurring in the structure.\n\n#### Chain interactions\n\nThis graph shows the interactions occurring between the different chains of the structure. The nodes of the graph are\nthe chains, while the edges are the interactions between the chains.\n\n#### Secondary structure interactions\n\nThis graph shows the interactions occurring between the different secondary structure elements of the protein.\nThe nodes of the graph are the secondary structure elements, identified with $\\alpha$ helices and $\\beta$ strands.\nThe numbering of these elements is given starting from the N-terminus of the protein.\nThe edges are the interactions between the secondary structure elements.\n\n### Probabilistic interchain residue contact map\n\nThis heatmap represents the probability of interaction between residues of different chains. The probability is computed\nas the number of states in which the two residues are interacting over the total number of states.\nThe user can select different types of interactions using the drop-down menu. Showing `all` interactions will also show\nintrachain interactions probabilities. Moreover, with `all` interactions, the probability of interaction between two\nresidues is computed as the number of any type of interaction between the two residues over the total number of states.\nThe heatmap can be zoomed and panned using the controls in the top bar, this can be useful to concentrate the plot in a\nspecific region (e.g. chain A interactions with chain B).\n\n### Pairwise interaction correlation analysis\n\nCorrelation analysis can be performed by the plugin on the results of RING, to study correlations between contacts found\nin a multi-state structure. Indeed, the correlation that the plugin computes is a correlation of the contacts over the\ntime variable. It is interesting to see if some contacts are in correlation over time because this can be a clear signal\nof an allostery mechanism that is present in the protein of study, especially if the two contacts are located in\ndifferent regions in the protein.\n\nWith correlation one can see if two contacts are present in the structure at the same time for a repeated number of\ntimes, or, if they anti-correlate, they are present most of the times alternatively. The plugin computes the correlation\nmatrix given the contact maps produced by RING, and produce a table that summarize the results.\n\nFor this analysis different settings for the creation and filter of the correlation matrix are available. One important\nthing is to limit the number of spurious contacts by setting a minimum frequency of contact, and at the same time\nremoving the ones that are constantly present in the structure. This limits the number of results that would have small\nsignificance. Once the correlation matrix is produced more filters can be applied to it, removing points where the\ncorrelation coefficient is not high or low enough, or filtering on the p-value of the correlation. For further reading\non how the coefficient is computed and what the p-value is please refer\nto https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.pearsonr.html\n\nThe results of the calculation is a table composed by various column, from left to right we find:\n\n- The first edge composed by the two residue in contact\n- The frequency of the first edge in the multi-state structure, for the indicated type\n- The type of interaction of the first **and** second edge, when the interaction type is *ALL* this means that all the\n  interactions between the two edges were taken in consideration to compute the correlation value and p-value.\n- The second edge composed by the two residue in contact\n- The frequency of the second edge in the multi-state structure, for the indicated type\n- The correlation value of the two edges\n- The p-value of the two edges\n\nRows of the table can be filtered on all the columns, multiple additive filters can be set using the space as separator.\nSo if one wants to filter on rows that contains as part of edge_1 or edge_2 the chain A and have a correlation value of\n0.8 for HBOND interactions can write: `A/ 0.8 HBOND`\n\nRows can also be selected (with multi-selection active, with `↑Shift` or `ctrl` ), and by pressing on\nthe `Visualize selected` button the two selected edges (if only one row selected) will be created in the PyMOL\ninterface, and two selections will be created containing the residues of edge_1 and edge_2. This has been done to\nhighlight the correlating interactions, that can be further analyzed with other features of the plugin, such as the\nresidue pair interaction plot on the two edges to confirm that the correlation or anti-correlation is present.\n\n## Clustering\n\nWhen dealing with large multi-state structures like molecular dynamics simulations it can be helpful to reduce the\nnumber of states in the structure to better analyze some feature of the simulation. Moreover, with clustering one can\nsee if there is some kind of pattern in the simulation, and some interesting to study conformational states are emerging\nduring the simulation.\n\n### Calculation of the hierarchical clustering\n\nThe plugin provides a simple way to perform clustering analysis on the structures loaded into PyMOL. The clustering that\nthe plugin provides is a hierarchical clustering based on RMSD distances calculated between all the states ( $n\\times\nn$ ). By default the clustering is done only on the C $\\alpha$ atoms, so it can be faster to compute, but if it is\nnecessary one can change it taking in consideration all the atoms in the structure.\n\nThe clustering method to compute the linkage matrix can be changed, and it can be one of the ones described\nhere: https://docs.scipy.org/doc/scipy/reference/generated/scipy.cluster.hierarchy.linkage.html\n\nThe clustering will be computed on demand, when the user wants to get one of the two plots to visualize the clustering\nor wants to generate a new object with the representative states of the clustering. Once the hierarchical clustering is\ncomputed, the hierarchical tree can be cut in two ways, by RMSD value or by number of desired clusters. Different cuts\nproduce different results, that can be confronted with the two proposed visualizations.\n\n### Clustering visualizations\n\nTwo different plots can be produced with the results of the clustering, giving the user an idea of the distribution of\nthe clusters, their densities and separations.\n\nThe first plot is the Hierarchical Clustering Plot, which shows the hierarchical tree of the computed clustering,\nrelative to the cut that the user selected. In the **x** axis the labels are composed by **cluster representative -(#\nstates in cluster)**, where the cluster representative is the state that has the lower sum of distances between all the\nother states in the same cluster.\n\nThe second plot represent each state individually as a cell, and a color is assigned to it based on the membership\ncluster. This can show if there are stable conformation during the simulation, and if some conformation is repeated\nduring time. Moreover, each cluster is represented by a color, and to that color the representative state of that\ncluster is associated. The user can interact with plot by positioning the mouse over a cell, and a label will appear,\nshowing the state number of the selected cell and the relative cluster representative.\n\nOnce the appropriate number of cluster is selected (via RMSD or explicitly), the user can press the \"Create object\"\nbutton. This will extract the representative cluster states and stitch them together in a new PyMOL object. This new\nobject can be used for further analysis with other features of the plugin.\n\n### Create object\n\nClicking on this button will apply the previously selected clustering and will create a new object with only the\nclustering representative states of the original object.\n\n## Example\n\nThe plugin can be tested with the following example:\n\n1. Download the multi-state structure 2H9R from PDBe-KB\n    - Type `fetch 2h9r` in the PyMOL command line\n2. Load the plugin in PyMOL\n    - `Plugin` $\\rightarrow$ `Ring plugin` or type in the command line `ring_plugin`\n3. Now the plugin should be loaded, and in its top bar there should be already selected the PyMOL object 2h9r, the\n   structure that you previously loaded.\n4. Now you can execute RING with the button `Execute RING`\n    - This will run the RING executable (if present) on the selected object, or it will try to execute RING on the\n      selected structure on a web server using the APIs.\n5. Once the results are ready they will be parsed and visualized on the structure in the PyMOL interface.\n\n\u003cp align=\"center\"\u003e\n    \u003cimg height=\"400\" src=\"doc_imgs/edges.png\" width=\"650\"/\u003e\n\u003c/p\u003e\n\n6. Now the edges can be filtered based on the type of interaction, frequency, and all the various tools can be used.\n   E.g. we can see the `probabilistic interchain residue contact map` of the $\\pi-\\pi$ stack interactions:\n\n   \u003cp align=\"center\"\u003e\n       \u003cimg height=\"400\" src=\"doc_imgs/contact_map.png\" width=\"650\"/\u003e\n   \u003c/p\u003e\n\n7. Finally, we can also try to cluster a multi-state object, with a RMSD-based clustering. We can for example set a\n   threshold criterion on the RMSD value for cutting the hierarchical clustering, yielding a certain number of clusters.\n   Otherwise, one can select the exact number of clusters, and the RMSD value for the cut will be calculated\n   automatically. One example is the following, were we set a RMSD cut value of 3.5 $\\AA$, yielding 5 different\n   clusters:\n\n   \u003cp align=\"center\"\u003e\n       \u003cimg height=\"400\" src=\"doc_imgs/clusters.png\" width=\"650\"/\u003e\n   \u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbiocomputingup%2Fring-pymol","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbiocomputingup%2Fring-pymol","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbiocomputingup%2Fring-pymol/lists"}