MtsslTrilaterate

Type	PyMOL Plugin
Download	plugins/mtsslTrilaterate.py
Author(s)	Dinar Abdullin
License	-
This code has been put under version control in the project Pymol-script-repo

mtsslTrilaterate

mtsslTrilaterate is a PyMOL plugin for the trilateration of objects based on distance restraints.

The mtsslTrilaterate program calculates the coordinates of an object which is defined by the distances from this object to several "reference" objects. The idea of the program is similar to the Global Positioning System (GPS) that can locate an object on the surface of the Earth by measuring distances to a number of GPS-satellites. Applied to biomolecules, this program can be used to localize paramagnetic metal ions in a biomolecular structure by measuring the distances between these ions and artificially attached spin labels.

The mtsslTrilaterate program is a python code and it works as a plugin for the PyMOL program. It is a part of the mtsslSuite package and is optimized to work in pair with the program mtsslWizard.
The program was tested on the 64-bit Windows 7 platform. Due to some problems with the wx library in PyMOL, the program temporarily does not work on the Mac platform.

Screen Shot

Installation

1. The program requires python 2.7 (or higher) to be installed. It can be downloaded free of charge from official web site http://www.python.org/.

2. The program also uses wx and numpy libraries. If the basic version of python does not contain these libraries, they should be installed subsequently (e.g. from http://www.lfd.uci.edu/~gohlke/pythonlibs/). Check if python can recognize these libraries (for this you could run "import wx" and "import numpy" commands in PyMOL: there should be no mistakes).

3. The program requires PyMOL version compatible with python 2.7 (or higher).

4. Save the mtsslTrilaterate.py file somewhere in your computer.

5. Run PyMOL. In the "Plugin menu" select "Plugin Manager". Then open the "Install New Plugin" page and click on "Choose file". Select the mtsslTrilaterate.py file. If installation is finished successfully, a message “Plugin Trilateration has been installed” would appear.

6. Run mtsslTrilaterate from the Plugin menu.

Operation Guidelines

The graphical user interface of mtsslTrilaterate is shown above. It consists of a small menu and a main working window. The main window contains two panels called "INPUT" and "OUTPUT", which display the input and output data of the program, correspondingly.

All input data is introduced into the table of the "INPUT" panel. Each row of this table corresponds to one of the spin labels (reference objects) attached to a biomolecule. The user-defined identifiers of these labels are listed in the first column of the table. The following three columns correspond to the Cartesian coordinates (x, y, z) of the labels in the coordinate frame of a biomolecule. The last two columns represent the mean value and the standard deviation of the distance between each label and a target.

The "OUTPUT" panel displays the calculated coordinates of the target and their standard errors.

In the following the step-by-step instruction of using the program is given:

• Load the structure or structural model of a biomolecule to PyMOL. It can be done either in PyMOL selecting "File" → "Open" or in mtsslTrilaterate selecting "PyMOL" → "Load structure to PyMOL".

• Load/create the models of spin labels (reference objects). The models of several commonly used EPR spin labels can be created by means of the mtsslWizad plugin (see http://pymolwiki.org/index.php/MtsslWizard).

• The coordinates of the created spin labels can be entered into mtsslTrilaterate in three different ways: 1) They can be typed manually into the "INPUT" table. 2) If MTSSL (or MTSL) is used as a spin label and if its model is created by means of the mtsslWizard plugin, the coordinates can imported into mtsslTrilaterate automatically by pushing the "Import from PyMOL" button, than choosing the label in the "List of labels" list and pressing the "Load" button. Note that MTSSL coordinates are averaged over all generated conformers when being imported into mtsslTrilaterate. While importing one label after another, a new row has to be selected each time in the "INPUT" table (the selected row is highlighted by orange color). 3) The coordinates can be also loaded from a data file by clicking the "Load coordinates" button and choosing the file which contains the coordinates of a spin label. This file should contain 3 columns corresponding to x, y, z coordinates. If there are several sets of the coordinates (several rows) in the data file chosen, an average coordinates will be calculated by mtssslTrilaterate.

• The distance between each spin label and the target can be entered manually to the corresponding fields of the "INPUT" table or uploaded from a data file by clicking the "Load distances" button. The latter procedure converts a distance distribution generated by the DeerAnalysis program (a file with the "fit" suffix) into a single-distance constraint.

• When all input data is entered, press "Accept" button. At this stage, the program checks if at least 4 spin labels were described completely (coordinates and distances are given). 4 spin labels is a minimal number of labels that allows to solve the trilateration problem.

• Click "Compute" button. After calculations, the coordinates of the target and their standard errors appear in the "OUTPUT" panel. The program also displays an obtained chi-squared value and a number of iterations which was required for an optimization algorithm to find a solution.

• To create a graphical representation of the trilateration solution within the biomolecular structure in the PyMOL graphical window , press the "Export to PyMOL" button. Two PyMOL objects, called "trilateration" and "target", will be created inside PyMOL (see figure above). The "trilateration" object represents a trilateration-spheres plotted around each used spin label. The radius of each sphere equals to the average distance between the corresponding spin label and the target. An area where all spheres intersect each other determines the location of the target. This area is depicted by the "target" ellipsoid. The center of the ellipsoid corresponds to the calculated most probable coordinates of the target, whereas the legths of its semi-principal axes equal to the standard errors of these coordinates. The scale of the semi-principal axes and, accordingly, the confidence level of the solution can be changed in "File" → "Preferences" → "Output data" → "Confidence level". The "Confidence level" of 1 corresponds to a 1σ error, the "Confidence level" of 2 - to a 2σ error, and so on.

• Using "File" → "Save As" and "File" → "Open" commands in mtsslTrilaterate, the user can save an input data and a trilateration result in one data file and open it latter, i.e. in another PyMOL session.

Reference

If you find this program useful, please cite this paper:

mtsslSuite: In silico spin labelling, trilateration and distance-constrained rigid body docking in PyMOL, G. Hagelueken, D. Abdullin, R. Ward, O. Schiemann, Mol. Phys. 2013, 111, 18-19.

It also contains detailed information about the program and examples of its application.

Contact

Dinar Abdullin

abdullin@pc.uni-bonn.de

Acknowledgement

Thanks to Jason Vertrees and Thomas Holder for some programming tips.