Traceable residues

In the first stage of calculation AQ finds all residues that should be traced and appends them to the list of traceable residues. It is done in a loop over all frames. In each frame residues of interest are searched and appended to the list but only if they are not already present on the list.

The search of the residues is done according to user provided definitions. Two requirements have to be met to append residue to the list:

1. The residue has to be found according to the Object definition.
2. The residue has to be within the Scope of interest.

The Object definition encompasses usually the active site of the protein. The Scope of interest defines, on the other hand, the boundaries in which residues are traced and is usually defined as protein.

Since AQUA-DUCT in its current version uses MDAnalysis Python module for reading, parsing and searching of MD trajectory data, definitions of Object and Scope have to be given as its Selection Commands.

(resname WAT) and (sphzone 6.0 (resnum 99 or resnum 147))

resname WAT around 2.0 protein

Raw paths

The second stage of calculations uses the list of all traceable residues from the first stage and finds coordinates of center of masses for each residue in each frame. As in the first stage, it is done in a loop over all frames. For each residue in each frame AQUA-DUCT calculates or checks two things:

1. Is the residue in the Scope (this is always calculated according to the Scope definition).
2. Is the residue in the Object. This information is partially calculated in the first stage and can be reused in the second. However, it is also possible to recalculate this data according to the new Object definition.

For each of the traceable residues a special Path object is created. If the residue is in the Scope its center of mass is added to the appropriate Path object together with the information if it is in the Object or not.

Separate paths

The third stage uses collection of Path objects to create Separate Path objects. Each Path comprise data for one residue. It may happen that the residue enters and leaves the Scope and the Object many times over the entire MD. Each such an event is considered by AQUA-DUCT as a separate path.

Each separate path comprises of three parts:

1. Incoming – Defined as a path that leads from the point in which residue enters the Scope and enters the object for the firs time.
2. Object – Defined as a path that leads from the point in which residue enters the Object for the first time and leaves it for the last time.
3. Outgoing – Defined as a path that leads from the point in which residue leaves the Object for the last lime and leaves the Scope.

It is also possible that incoming and/or outgoing part of the separate path is empty.

After the initial search of Separate Path objects it is possible to run special procedure, Auto Barber, which trims paths down to the approximated surface of the macromolecule or other molecular entity defined by the user.

Separate paths can be optionally smoothed. This can be done in two modes: soft and hard. In the former mode smoothed paths are used only for visualization purposes. In the latter, raw paths are replaced by smoothed. AQUA-DUCT implements several smoothing methods, including Savitzky-Golay filter.

Clustering of inlets

Each of the separate paths has beginning and end. If they are at the boundaries of the Scope they are considered as Inlets, i.e. points that mark where the traceable residues enters or leaves the Scope. Clusters of inlets, on the other hand, mark endings of tunnels or ways in the system which was simulated in the MD.

Clustering of inlets is performed in following steps:

1. Initial clustering: All inlets are submitted to selected clustering method and depending on the method and settings, some of the inlets might not be arranged to any cluster and are considered as outliers.

2. [Optional] Outliers detection: Arrangement of inlets to clusters is sometimes far from optimal. In this step, inlets that do not fit to cluster are detected and annotated as outliers. This step can be executed in two modes:

   1. Automatic mode: Inlet is considered to be an outlier if its distance from the centroid is greater then mean distance + 4 * standard deviation of all distances within the cluster.
   2. Defined threshold: Inlet is considered to be an outlier if its minimal distance from any other point in the cluster is greater then the threshold.

3. [Optional] Reclustering of outliers: It may happen that the outliers form actually clusters but it was not recognized in initial clustering. In this step clustering is executed for outliers only and found clusters are appended to the clusters identified in the first step. Rest of the inlets are marked as outliers.

At the end of clustering stage it is possible to run procedure for master path generation. First, separate paths are grouped according to clusters. Paths that begin and end in particular clusters are grouped together. Next, for each group a master path (i.e., average path) is generated.

Analysis

Fifth stage of AQUA-DUCT calculations analyses results calculated in stages 1 to 4. Results of the analysis are displayed on the screen or can be save to text file. Detailed description of analysis result file can be found in the AQ documentation.

Visualization

Sixth stage of AQUA-DUCT calculations visualizes results calculated in stages 1 to 4. Visualization is done with PyMOL. AQUA-DUCT automatically starts PyMOL and loads visualizations in to it. Molecule is loaded as PDB file. Other objects like Inlets clusters or paths are loaded as CGO objects.