PSNToolsGUI 1.0

PSNToolsGUI is free and open to all users and is distributed as a binary executable (recommended) and as source code which can be compiled on other platforms. Both the binary and the source code can be downloaded at the website of WebPSN server.

The binary executable has been tested to properly work out of the box using a fresh install of the latest two releases of the following, widely used, Linux distributions: Ubuntu, Fedora and Manjaro.

Compilation can be (very) long due to the large internal database of network parameters and requires a modern C++ compiler and toolchain and the following development libraries: Boost, Cereal, ZLib, Armadillo and BLAS/LAPACK libraries.

PSNToolsGUI uses the command line version of PSNTools and, for some calculation stages, Wordom, another software provided by the same research group. A statically compiled binary executable for Wordom is provided as well. To use PSNToolsGUI, PSNTools and Wordom you can download (or compile) the executable files and move them to an appropriate location in your filesystem. The only additional requirement to run PSNToolsGUI is a complete installation of the Python 2.7 programming language, which is already present by default in almost all linux distributions.

Finally, this is a list of additional recommended software that, while not strictly necessary, are however highly recommended: PyMol, VMD, Gnuplot, Graphviz.

Please, refer to your operating system manual and to the website of each software for more details about the installation process:

Thank you for using PSNToolsGUI, we really appreciate it.

Please, remember to cite at least one of the following papers in all published works which utilize this software:

NEW_PAPER_CITATION_HERE

Angelo Felline, Michele Seeber and Francesca Fanelli
webPSN v2.0: a webserver to infer fingerprints of structural communication in biomacromolecules
Nucleic Acids Res, Web Server Issue, 19 May 2020
https://doi.org/10.1093/nar/gkaa397

If you have any questions or if you encounter any problems with this sofware please do not hesitate to contact us at the following email addresses:

@ Prof. Francesca Fanelli
@ Angelo Felline

PSNToolsGUI is copyright 2017-2020 the University of Modena and Reggio Emilia (Italy).

PSNToolsGUI is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

PSNToolsGUI is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with Wordom. If not, see http://www.gnu.org/licenses

To calculate a Protein Structure Network from a single PDB file or a Gromacs (xtc) or CHARMM (dcd) trajectory file click on Calculate → PSN to calculate a new network. For detailed information on the theory behind this step, read the relevant section in the Appendices chapter.

the following new window will be opened:

Use Set Options menu to setup your calculation. Each menu entry is marked as Required or Optional, and all optional settings will be automatically adjusted for you depending on the situation.

Please, refer to the PSNTools user guide for more details about the meanings of these options.

To calculate your network click on Run → Calculate PSN. Finally, click on Exit to close this window.

Computation of consensus networks allows inferring common structural communication features in homologous systems sharing the same functionality or even only the fold. A consensus network is calculated by averaging the trajectory frequencies and interactions strengths of all hubs and links among the networks used to build the consensus. Once produced, the .psn file of a consensus network can be used as a normal network and can be analyzed using the methods present in Analyses menu.

Click on Calculate → Consensus to calculate a new consensus network.

As for the network calculation procedure you can setup the consensus calculation using the Set Options menu.

The only required option you have to provide is the list of psn files you want to use to calculate your consensus network. You have to select two or more psn files using Set Options → PSN Files menu (You have to hold your ctrl down while selecting multiple files).

When the calculation is finished you can close this window using Exit menu.

After the PSN calculation stage, you can use the produced .psn file to generate a network representation called Protein Structure Graph (PSG) clicking on Analyses → PSG Menu. Please remember that all optional values listed below will be automatically set for you to a reasonable default value.

The following options are available in the Set Options menu:

When all desired options has been set, you can calculate the PSG using Run → Calculate PSG menu. When the calculation is finished, the Outputs menu will be automatically activated:

Output files are grouped as follow:

Please, see First Run and Configuration section for more details.

The following output files will be available:

Finally, you can close this window using Exit menu.

Network difference is used to highlight the differences between two PSGs in terms of their links, hubs and links mediated by at least one hub. This analysis is particularly useful to identify commonalties and differences in the structural communication of two functionally different states of the same system. Please remember that you need to pass one or two labels files if the two networks have a different primary sequence or even they have the same sequence but different chains and/or segments in the passed pdb files. Please see Labels File section for more details. Please remember that all optional values listed below will be automatically set for you to a reasonable default value.

The following options are available in the Set Options menu:

When all desired options has been set, you can calculate the PSG Difference using Run → Calculate PSG Difference menu. When the calculation is finished, the following outputs menus will be automatically activated:

Output files are grouped as follow:

Please, see First Run and Configuration section for more details.

The outputs accessible in 3D Outputs menu are divided in PyMol and VMD groups and then in Net1 vs Net2 and Net2 vs Net1.

The outputs accessible in Plots menu are:

Finally, use Exit menu to close this window.

After the PSN calculation stage, you can use the produced .psn file to calculate the correlated shortest communication path(s) between two or more nodes clicking on Analyses → Shortest Paths. As for the previous commands, remember that all optional values listed below will be automatically set for you to a reasonable default value.

As for the the other analyses provided by PSNToolsGUI you can setup all required and optional settings using Set Options menu.

When all desired options has been set, you can calculate the PSG Difference using Run → Calculate Shortest Paths menu. When the calculation is finished, Outputs menu will be automatically activated giving access to the following outputs:

Finally, you can close this window using Exit menu.

This analysis is used to perform and compare the results of shortest paths analysis of two networks. Most of the options accepted by this command are the same of those accepted by Shortest Paths analysis and their values can be conveniently applied to both networks.. As always, all non used options will be set to reasonable default values.

As for the the other analyses provided by PSNToolsGUI you can setup all required and optional settings using Set Options menu.

When all desired options has been set, you can calculate the PSG Difference using Run → Calculate Shortest Paths Difference menu. When the calculation is finished, Outputs menu will be automatically activated giving access to the following outputs:

Finally, you can close this window using Exit menu.

This analysis is used to highlight the relevance of each link in a given metapath by iteratively removing each link from the network and then recalculating the resulting metapath. The effect of link removal on the formation of the native metapath is then expressed as a percentage of native metapath links missing in the perturbed metapath. Finally, the most relevant links are also iteratively combined and removed to test their synergistic effect.

This analysis accepts all the same options accepted by Shortest Communication Paths analysis, please refer to that table for a detailed description of their meanings. Please note that this is a very cpu intensive analysis and setting a relatively high value to the Number Of Threads option can drastically reduce the computation time.

As for the the other analyses provided by PSNToolsGUI you can setup all required and optional settings using Set Options menu.

This command will produce the same output files produced by Shortest Communication Paths analysis and the following specific file present in the Data Files group of Outputs menu:

Finally, you can close this window using Exit menu.

This analysis is used to generate two different types of plots of network statistics obtained during the network calculation stage. Despite being available also for networks generated from a single .pdb file, the primary target of this command are networks generated from a trajectory file.

To run this analysis click on Analyses → Trajectory Plots.

For a detailed list of available network statistics see the corresponding table in Miscellaneous → PSN Info section.

For each distribution and surface plots the following output files will be produced:

Where {Stat} and {StatsPair} are the network statistic and the pair of network statistics selected while adding the distribution and the surface plots, respectively.

Where {Stat} and {StatsPair} are the network statistic and the pair of network statistics selected while adding the distribution and the surface plots, respectively.

Finally, you can close this window using Exit menu.

This analysis is similar to Plots Of Trajectory Network Statistics and is used to calculate the difference in the trajectory network statistics of two different .psn files. To start this analysis click on Analyses → Trajectory Difference Plots menu. The only difference in the setting stage is that you have to provide two psn files. Please refer to Plots Of Trajectory Network Statistics section for more details about the setting and calculation stages.

After the calculation stage, in the Outputs menu, the following outputs will be available:

For each distribution and surface plots the following output files will be produced:

Where {Stat} and {StatsPair} are the network statistic and the pair of network statistics selected while adding the distribution and the surface plots, respectively.

Where {Stat} and {StatsPair} are the network statistic and the pair of network statistics selected while adding the distribution and the surface plots, respectively.

Finally, you can close this window using Exit menu.

With this method, labels files are generated from a labels definition file generated by the user. Click on Labels → Generate Labels and enter a new file name when prompted. A new window of selected text editor will be opened with a detailed description of the file format and an example. When finished, close the text editor window and PSNToolsGUI will generate the corresponding labels file for you.

The following table summarize the labels definition file format:

This is an example labels definition that can be used to label the chain A residues of the 3LNX pdb:

This function is accessible via Labels → MSA To Labels menu and provides an alternative way to produce multiple labels files at the same time from a multi sequence alignment (MSA) in fasta format. All you have to do is select the desired multi sequence alignment file when prompted to.

As for the previous method, PSNToolsGUI needs to access to a pdb file corresponding to the each sequence listed in the msa file. To match sequences and the corresponding pdb files, please change the sequence definition line, i.e. the line after ">" character, with the full disk path of the corresponding pdb file as in the following example:

The easiest way to generate a labels file is to use the corresponding tool provided by WebPSN, the web server version of PSNToolsGUI.

PSNToolsGUI uses the residue type field (4^th column) of passed pdb file to assign the correct network parameter to each node during PSN calculation. These three-letters codes are (almost) standardized, nonetheless some molecular simulation programs, like CHARMM or Gromacs, use some codes with an alternative meanings, like HSD, HSE and HSP to identify different protonation state for the histidines. It is a good practice, before a Network Calculation, to check for non standard aminoacids/nucleotides present in your pdb file and to see to which molecule and network parameter they are associated to in the internal database.

To access this function click on Miscellaneous → Check PDB Parameters menu and select a pdb file when prompted.

This command will show you a table with each non standard aminoacids/nucleotides present in passed pdb and their associated molecule name and formula, as well as, their network parameter. If a molecule is not present in the internal database, it will be parametrized on the fly on the basis of its atomic coordinates.

This is the message that this function will show you when the chain A of PDB Code 1U19 is passed:

As seen in the previous Analyses sections, if you do not set the network name option, all output files will be named according to the internal network name of passed psn file. If you want to change the internal network name of a psn file, this little function can modify it for you, all you have to do is to select the desired psn file and set a new name when prompted.

This function shows several information listed in the table below about passed .psn file.

Open the PDF version of this user guide in your browser (needs a working internet connection).

Open the web version of this user guide in your browser (needs a working internet connection).

Show a message with the current version of installed PSNTools and PSNToolsGUI.

Checks if a new version of PSNTools and PSNToolsGUI are available (needs a working internet connection).

Shows the about window.

PSN analysis is a product of graph theory applied to protein and nucleic acid structures. A graph is defined by a set of vertices (nodes) and connections (edges) between them. In a PSN, each amino acid residue is represented as a node and these nodes are connected by edges based on the strength of non-covalent interactions between residues. The strength of interaction between residues i and j (I_ij) is evaluated as a percentage given by the following equation:

where n_ij is the number of atom-atom pairs between the side chains of residues i and j within a distance cutoff of 4.5 Å. N_i and N_j are normalization factors for residue types i and j, which account for the differences in size of the amino acid side chains and their propensity to make the maximum number of contacts with other amino acids in protein structures. Glycines, are now included in the PSN analysis. The PSNTools has an internal database with the normalization factors for the 20 standard amino acids and the 8 standard nucleotides (i.e. dA, dG, dC, dT, A, G, C, and U), as well as for more than 30,000 biologically relevant molecules and ions (ligands, lipids, sugars, etc) from the PDB. Additionally, the server automatically identifies un-parametrized molecules in passed PDB files and automatically calculates their normalization factors transparently.

I_ij are calculated for all node pairs. At a given interaction strength cutoff, I_min, any residue pair ij for which I_ij ≥ I_min is considered to be interacting and hence is connected. Node interconnectivity is used to highlight node clusters, where a cluster is a set of connected nodes in a graph. Cluster size, i.e., the number of nodes constituting a cluster, varies as a function of the I_min, and the size of the largest cluster is used to calculate the I_critic value. The latter is defined as the I_min, at which the size of the largest cluster is half the size of the largest cluster at I_min = 0.0%. Studies by Vishveshwara’s [16] group found that optimal I_min corresponds to the one at which the largest cluster undergoes a transition. All resulting clusters can then be iteratively connected by the link(s) with the highest sub-I_critic interaction strength to compensate, at least in part, for the lack of side chain fluctuations.

Residues making four or more edges are referred to as hubs at that particular I_min. Such cutoff for hub definition relates to the intrinsic limit in the possible number of non covalent connections made by an amino acid in protein structures due to steric constraints. The cutoff 4 is close to the upper limit. The majority of amino acid hubs indeed make from 4 to 6 links, with 4 being the most frequent value. Finally, links are then used to highlight network communities, which are sets of highly interconnected nodes such that nodes belonging to the same community are densely linked to each other and poorly connected to nodes outside the community. Communities can be considered as fairly independent compartments of a graph. They are identified using a variant of the clique percolation method, by finding all the k=3-cliques, i.e. sets of three fully interconnected nodes, and then merging all those cliques sharing at least one node.

The search for all shortest paths relies on Dijkstra’s algorithm. The method first finds all possible communication paths between all node pairs and then filters the results according to cross-correlation of atomic motions, as derived from ENM-NMA or LMI analysis for networks calculated from a single .pdb file or from a molecular dynamics simulation, respectively.

Filtering consists in retaining only those shortest paths that contain only residues with a correlation ≥ of a given cutoff with at least one of the two path extremities (i.e. the first and last amino acids in the path). The default values for these cutoffs are 0.7 and 0.8 for networks calculated from a single .pdb file or from a molecular dynamics simulation, respectively and are based on benchmarks tested against experimental data.

Finally, filtered paths were used to build the global meta path, which is made of the most recurrent links, i.e. those links present in a number paths ≥ 10% or 20% for networks calculated from a single .pdb file or from a molecular dynamics simulation, respectively of the number of paths in which the most recurrent link in present. Such meta path represents a coarse/global picture of the structural communication in the considered system. The user can also filter those paths that begin and end at a given residue pair or that pass through a residue. Such a path filtering provides a novel metapath and is particularly recommended when some information on residues involved in structural communication is available.

The combination between a coarse grained representation of a protein structure (e.g. ENM) and Normal Mode Analysis (NMA) is ever increasingly used to study the collective dynamics of complex systems. ENM-NMA is a coarse grained normal mode analysis technique able to describe the vibrational dynamics of protein systems around an energy minimum. With this technique, each protein/nucleic acid structure is described by a reduced subset of atoms corresponding to the C_α atoms, for standard amino acids, and the atom nearest to the geometric center for all other molecules.

The interactions between particle pairs are given by a single term Hookean harmonic potential. The total energy of the system is thus described by the simple Hamiltonian:

where d_ij and d_ij⁰ are the instantaneous and equilibrium distances between particle i and j, respectively, whereas k_ij is a force constant, defined as:

where C is constant (with a default value of 40 Kcal/mol ·Å²).

The cross-correlations of motions for path filtering are obtained from the covariance matrix C [17]:

where C_ij denotes the correlation between particles i and j, M is the number of modes considered for computation (the first 10 non-zero frequency modes), v_xy and λ_y are, respectively, the x^th element and the associated eigenvalue of the y^th mode.

where i and j ar residues, C_ij is the pair-covariance matrix, and C_i and C_j are marginal covariance matrices. LMI correlation values can vary from 0.0 to 1.0, which indicate completely uncorrelated and completely correlated displacements, respectively.