Documentation

Installation

Precompiled Package

Precompiled binaries are found in the Download section.

From Source

  1. Download and install the open source Qt SDK version 5.15 from https://www.qt.io
  2. Download and install the Eigen 3 library from https://eigen.tuxfamily.org/
  3. Download the latest APL@Voro repository and unpack the archive or use git to clone the repository.
  4. Go into the src directory.
  5. Execute qmake in the source directory.
    >> qmake aplvoro.pro
    To change the installation path of APL@Voro, use option PREFIX=<the install path>. PREFIX = /usr is deault and will install APL@Voro in usr/bin
    On OSX: Use option OSX_BUNDLE=bundle
  6. Execute make in the source directory.
    >> make
  7. Execute make install In the source directory to install a binary in the default /usr/bin or the directory you defined previously.
    >> sudo make install

Manual

Main Window

APL@Voro’s main window with two opened simulations.

1 Main Menu

File Menu:

  • Add a new simulation to the session
  • Save the current session
  • Open a previously saved session
  • Close APL@Voro

Help Menu:

  • Show the manual
  • Show the about page

2 Simulation Handler

When a new simulation is loaded a simulation handler appears in the sidebar on the left. It contains the name of the simulation, a red X button to close the simulation, three buttons to open views in the docking area and two spin boxes to synchronize different simulations. The three buttons from left to right open a new Voronoi view, 2D plotting area and averages table in the docking area. The two spin boxes represent the first and last frame respectively along which all simulations will be synchronized.

3 Docking Area

New views are placed in this area where they can be arranged as desired.

4 Simulation Control

The user can play and pause the simulation using the appropriate buttons. Simulation frames can be selected by dragging the top slider or by using the spin box on the right. The bottom slider changes the speed of the playback.

Loading a New Simulation

To add a new simulation to the current session click File -> new or press Ctl + N. This will open the setup wizard that guides the user through the process.

Base Parameters

The first page of the setup wizard is used to define what simulation data is used, which frames are loaded from the simulation and which algorithms are used.

The name is used during a session to refer to this particular simulation. If this field is left empty then the model file name is used. The name does not have to be unique, but it is recommended.

The box dimensions define the size of the simulation box used for the model file. This information is usually contained within the file and is used by checking “detect by CRYST1 record”.

The periodic boundary condition (PBC) cutoff distance defines how much of the membrane is duplicated during the creation of the Voronoi diagram. This value is given as a percentage of the membrane size. When this value is too small then the calculated area for the lipids on the edge of the membrane will be too large. A large value will slow down the loading process. This value may be smaller for large membranes, but it needs to be larger when a large average area per lipid is to be expected.

The frame selection limits the frames loaded from the trajectory. When you want to load the trajectory to its last frame then set it to -1. A stride of n means that only every nth frame is loaded.

APL@Voro uses up to three files to set up a simulation. The model file in the pdb format is mandatory. It will be interpreted as the first frame in the simulation and is used to obtain residue names, residue numbers , atom names and atom numbers. The index file is used to define non-lipid molecules that enter the membrane, usually proteins. The trajectory file can be in the trr and xtc format.

When an index file is defined the next page will be the protein selection page, else it will be the key atom selection page.

Protein Selection

On this page the user selects non-lipid atoms that might be inserted into the membrane and an offset that controls when these atoms are actually inserted. Non-lipid atoms are included based on the triangular prism insertion method (TPIM). The three closest key atoms to a non-lipid atom form a triangular prism. When a non-lipid atom is within the volume of such a prism then it is inserted as a new site into the membrane. The height of the triangular prism can then be increased by choosing a TPIM offset method. The prism height is increased by the van der Waals radius of the key atoms by default.

Key Atom Selection

Expand the nodes for the lipid names and select the key atoms you want to include. The auto select button will select the first phosphorus atom in each lipid. Selecting multiple key atoms per lipid will create multiple Voronoi cells accordingly and will lead to a smaller average area for these lipids. This might be desirable for more complex lipids. For now APL@Voro has no built in function to combine partial lipid areas. To obtain the area for the whole lipid use the export function and use a script to add up all the partial areas of a lipid.

Once all key atoms are selected press the Finish button to load the simulation. This might take a while.

Voronoi View

The Voronoi view visualizes a membrane leaflet as a Voronoi diagram where a Voronoi cell represents a lipid or a non-lipid atom. The visualization is done in the rendering area on the right. The sidebar on the left provides additional information and control.

The sidebar contains various means of making selections, detailed information on each lipid and averages for the current frame and the current selection.

One method to make a selection from the sidebar is the selection editor. Click on the “New selection model” button to open it. The first text box is used to give the selection a name. The drop menu below that decides whether all or only one of the selection criteria needs to be met for a lipid to be selected. After that you can add as many selection criteria based on residue names, area per lipid, thickness and neighbourhood. Once you click “okay” the selection will be available in the drop down box at the top of the sidebar.

Details to all lipids are organized in a tree structure, ordered by lipid type. Single lipids can be selected by clicking an entry which will be highlighted in blue. Dragging the cursor over the list while holding left click will select all elements the cursor passes over. Holding Ctl will add to the current selection. Using shift and select all consecutive entries between the currently and previously clicked entry. Setting the check box next to a lipid name will select all lipids of that type. Left clicking a top level element will open a colour select dialogue where you can set a colour for a lipid type that is used when colouring the Voronoi graph by residue.

At the bottom of the sidebar is information on the average APL and thickness including standard deviation for both the whole leaflet and the current selection.

Rendering Area

The rendering area is where a leaflet is visualized as a Voronoi diagram. Each lipid and non-lipid atom is represented by a cell in the diagram. The cells can be coloured to map area, thickness, number of neighbours and lipid type. Non-lipid atoms are always white. The legend for the colour mapping can be found on the top left. Additional information on the visualized leaflet are at the top right. From top to bottom that information is:

  • Name of the simulation.
  • Currently shown leaflet.
  • Zoom level (useful to set zoom to the same level on several views).
  • Current time.
  • Current frame number.
  • Average area per lipid.
  • Average thickness.

Hovering the cursor over a Voronoi cell will show lipid type, area and thickness for that cell.

Cells can be selected by either clicking them or by box selection. Holding Ctl will add to the existing selection.

Right-click anywhere within the rendering area to open the context menu. From here you can:

  • Open the settings dialogue.
  • Change the active leaflet.
  • Select the metric which will be used for colour mapping.
  • Toggle the grid.
  • Toggle the legend.
  • Export the rendering area as an image. What you see is what you get.
  • Export the simulation data as txt or xml file. The exported data can be limited to a selection.
  • Center the view on the Voronoi diagram.

The settings dialogue lets you change the colour of various elements in the rendering area. Additionally you can change the grid spacing and the margins for the colour mapping. Global margins will take the maximum and minimum across all opened simulations into account. Local margins will use the maximum and minimum of this single simulation.

2D Plots

Area per lipid and thickness can be plotted over time. To add a new plot click on the + button. This will open the new plot dialogue. The options from top to bottom are:

  • The simulation from which the data will be taken
  • The leaflet
  • Which metric will be used (area per lipid or thickness)
  • Limit the data to a selection
  • The colour of the plot
  • The name of the plot

Once all parameters are set click on “Save” to finish the process. To delete a plot select it in the tree list on the left and click the – Button.

The buttons on the toolbar offer additional functionality. From left to right:

  • Zoom.
  • Reset zoom.
  • Change the coloring scheme of the plot.
  • Add a marker to the plot that indicates the current time of the simulation.
  • Export a plot as xvg file. A plot needs to be selected in the tree list.
  • Export the plot as an image.

Averages Table

The averages table provides an overview of the average area per lipid and thickness by lipid type over all loaded frames.

Algorithms

The algorithms section contains excerpts from “APL@Voro: A Voronoi-Based Membrane Analysis Tool for GROMACS Trajectories”.

Leaflet detection

One approach for detecting membrane leaflets is to check the orientation of each lipid. The orientation-based algorithm iterates through each lipid atom and compares the z coordinate between the first atom and all other atoms. Depending on how many atoms are above or below the lipid is assigned to the upper or lower leaflet. This algorithm handles flat membranes very well, as long as the lipids are well aligned, but might run into problems with curved membranes. This implementation assumes that the first lipid atom that is encountered will always be part of the headgroup, which is not necessarily true.

The newly added position-based approach uses a best fit surface to assign lipids to leaflets based on their position relative to that surface. The best fit surface is found using polynomial regression. This algorithm is a bit slower than the orientation-based approach, but it has proven more reliable. Caution should be taken when choosing the degree for the polynomial regression, as it tends to become unstable for high degrees (>7).

Area per lipid

After the leaflets are detected key atoms are temporarily duplicated to account for the periodic boundary condition. A Voronoi diagram is created for the set of key atoms, including duplicates, for each leaflet. The duplicate key atoms and the corresponding Voronoi cells are then discarded. The area a lipid occupies is the area of its Voronoi cell.

Thickness

Pandit et al. proposed an algorithm based on a Voronoi tessellation to calculate the bilayer thickness and provide thickness data for single lipids. In APL@Voro, Voronoi diagrams are already used for the calculation of the area per lipid and thus can be reused for the calculation of the bilayer thickness. The proposed algorithm is based on finding a vertical neighbour phosphorus atom in one leaflet for a phosphorus atom in the other leaflet (see Figure below). This is done by:

  1. providing a Voronoi tessellation for one leaflet
  2. projecting the coordinates of the phosphorus atom of the other leaflet onto the Voronoi surface
  3. identifying the Voronoi cells in which the projected coordinates fall
  4. defining the z distance between the Voronoi site atom and the projected atom as the local thickness

Given this algorithm, the problem of finding the membrane thickness is reduced to the well-known point-in-polygon problem. This approach may lead to some uncertain results, given the nature of Voronoi diagrams and the implemented point-in-polygon test. Two cases can be identified where the given approach can result in uncertain data:

  • The projected coordinate falls exactly on an edge of a Voronoi cell
  • The projected coordinate falls exactly on a vertex of the Voronoi cell

In the first case, the identification of exactly two vertical neighbours is possible, as the common edge of two Voronoi cells
marks all points being the same distance from sites to which the cells are related.

Triangular Prism Insertion Method (TPIM)

A lipid is marked as a boundary lipid for a given protein atom, if the atom falls inside a triangular prism constructed from the lipid atom coordinates and a given triangulation. The protein atom is then marked for later insertion into the existing triangulation. Inserting a protein atom into the triangulation will directly result in the reduced size of the derived neighbouring Voronoi cells (the lipid Voronoi Cells). To take protein atoms into account that lie slightly above or under the dimension defined by the triangulated lipid key atom coordinates, the height of the prism can be modified. The height of the triangular prism is defined by the coordinates of the lipid atoms and the TPIM offset value. A higher prism will result in more atoms remaining protein atoms and, thus, can reduce the calculated area of the boundary lipids. The offset value can either be a user defined value or be a van der Waals radius corresponding to the respective three lipid atoms.

External Libraries

APL@Voro uses Qt version 5.15.3 and Eigen version 3.

Qt is a C++ toolkit for cross-platform application development. Qt provides single-source portability across all major desktop operating systems. It is also available for embedded Linux and other embedded and mobile operating systems. Qt is available under three different licensing options designed to accommodate the needs of our various users. Qt licensed under our commercial license agreement is appropriate for development of proprietary/commercial software where you do not want to share any source code with third parties or otherwise cannot comply with the terms of the GNU LGPL version 3. Qt licensed under the GNU LGPL version 3 is appropriate for the development of Qt applications provided you can comply with the terms and conditions of the GNU LGPL version 3. Please see qt.io/licensing for an overview of Qt licensing. Copyright (C) 2018 The Qt Company Ltd and other contributors. Qt and the Qt logo are trademarks of The Qt Company Ltd. Qt is The Qt Company Ltd product developed as an open source project. See qt.io for more information.

Eigen is a C++ template library for linear algebra: matrices, vectors, numerical solvers and related algorithms. It is licensed under the MPL2.

License

APL@Voro is licensed under the GPL3.

APL@Voro 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.