MDFF GUI and Timeline Analysis

As of VMD version 1.9.2, the mdff plugin can also be used through a graphical user interface, found in the "Modeling" section of the VMD "Extensions" menu. This interface provides many of the same features found in the command line version of the plugin in a more user friendly package. The GUI can be used to easily set up both MDFF and xMDFF simulations, as well as launch, connect to, and analyze interactive MDFF simulations. Additionally, the Timeline plugin in the "Analysis" section of the VMD "Extensions" menu now contains functionality for calculating, displaying, and analyzing the local cross correlation of a structure over the entire fitting trajectory. The following sections will present the steps for setting up and analyzing the same system found in Section 2, but now using the MDFF GUI and Timeline analysis. If you are learning how to use MDFF for the first time, it is best to start with Section 2 before returning to this section.

Setting up simulations with the MDFF GUI

Before proceeding through this section and setting up your MDFF simulation, make sure you have worked through Section 2. You will need the simulated density, psf, and pdb from Section 2.1 to proceed. If you have these files, you can begin by opening up the MDFF GUI from the "Modeling" section of the VMD "Extensions" menu. Please note you may need to type the package require mdff command into the TkConsole before launching the GUI.

Figure 16: MDFF Files tab of the MDFF GUI, where parameters for the files required by MDFF are set

1

Upon starting the MDFF GUI, you will see several drop-down sections relating to various aspects of setting up the MDFF simulation. Begin by opening the 'MDFF Files...' section, seen in Fig. 16. Here you will choose the already loaded molecule containing both the psf and pdb files obtained from Section 2, 1ake-initial_autopsf.psf and 1ake-initial_autopsf-docked.pdb. The 'Working Directory' indicates where all of the output files will be saved when we generate them later.

2

After selecting the molecule, you will have to select the density map 4ake-target_autopsf.situs which you previously generated in Section 2.1, by clicking the `Add' button. A window will open where you can browse for the map. Additionally, the window contains an input box for selection text for the 'gridpdb' file which marks the atoms being affected by the density-derived potential. You may leave the default text for this tutorial. Similarly, you can also set the grid scaling factor , which again you can leave as the default value. When you are satisfied with the settings, click the `Add Density' button.

3

In the 'Simulation Output Name' field, you can select a name for your MDFF simulation. This can remain the default for this tutorial, as well as the 'Simulation Output Step'. It is important to note that if you place any number greater than 1 in the Step field, the generated NAMD files will automatically load the output from the previous simulation step which will act as a starting point for your next simulation. This can be very useful for quickly setting up multi-step fitting workflows.

4

As further discussed in Section 2.4, restraints are an important aspect of MDFF simulatiuns to prevent overfitting. You should select all three restraint check boxes so that the corresponding files will be created.

Figure 17: Simulation Parameters subsection of the MDFF GUI.

5

Next, you should close the 'MDFF Files' subsection of the GUI and open the 'Simulation Parameters' subsection, as seen in Fig. 17. This is the location of basic NAMD simulation parameters, such as temperature and time steps. All of the default values can remain for this tutorial. You may want to check the box labeled 'gridforcelite', which will tell NAMD to use a faster, but slightly less accurate, interpolation for calculating the forces derived from the density map. In this section you can also select the environment of your MDFF simulation, e.g. vacuum, explicit solvent with periodic boundary conditions, or a generalized Born implicit solvent. Vacuum should be used for this tutorial.

The next subsection of the GUI, 'xMDFF...' will not be used here, but anyone interested in applying MDFF to low-resolution crystallography should begin by reading Section 6. You can use the files from that section to set up an xMDFF simulation similar to what you have done here, but with the addition of setting the parameters in the xMDFF GUI subsection.

You now have all of the options set to be able to create all the files you need for the MDFF simulation. If you wish to run the MDFF simulation and move on to analyzing the trajectory, you can simply select the 'Generate NAMD files' button at the bottom of the 'MDFF Setup' tab of the MDFF GUI. However, if you wish to run an interactive MDFF simulation, please skip the following commands and proceed to Section 7.2. Before continuing either way, you should first save your current settings, using the 'File' drop down menu at the top of the GUI. You can select 'Save Settings...' to write the current GUI settings to a tcl file. This file can later be loaded using 'Load Settings...', which will set all of your saved parameters and load any structure and density files you had previously loaded. If you do choose to generate the NAMD files now, this button will automatically generate all the files you need to begin your simulation. Once this process is complete, you can start your simulation by running the following command in a terminal: namd2 mdff-step1.namd > mdff-step1.log

This step should take about 35 minutes on a single processor. If you don't want to wait, you can proceed to the Timeline section, 7.3 and use the provided trajectory files. You can also improve the speed of the simulation by using more processors by passing namd2 the +p$ option, where $ is the number of processors you wish to use.

Interactive MDFF

Interactive molecular dynamics (IMD) allows you to view and manipulate a NAMD simulation in real-time using VMD. Additional information on IMD can be found here. IMD allows users to selectively apply forces to your structure which can be very useful during MDFF to help guide the structure into the regions of density which you believe it should fit. Complex structures, poorly resolved maps, or starting structures requiring very large or complex conformational changes to fit into the density, may necessitate such manual intervention. Sometimes pieces of a structure can even become trapped in local density minima which they do not belong in, and manually dragging them out can improve the effeciency and end result of your MDFF fitting. This particular test case, 1AKE, does not have any such issues, however you may still want to experiment to see how IMD works.

With the MDFF GUI, we can now easily set up, launch, connect to, and even analyze interactive MDFF (IMDFF) simulations. The 'IMD Parameters...' subsection of the MDFF GUI on the MDFF Setup tab contains options related to setting up IMDFF simulations.

1

Open the 'IMD Parameters' subsection of the MDFF GUI and check the 'IMD' box to turn on IMDFF. Next, check the 'Wait for IMD Connection' box so NAMD will wait until you have connected VMD to the simulation before beginning. 'Ignore IMD Forces' tells NAMD to ignore any steering forces that could be applied through VMD (e.g. use this setting if you only wish to observe your simulation). Do NOT check this box for this tutorial. The IMD Port, Frequency, and Keep Frames settings can all be kept as default. The IMD Port is the computer network port over which VMD and NAMD communicate. IMD Frequency sets the frequency of NAMD simulation steps sent from NAMD to VMD. IMD Keep Frames sets how many of the steps NAMD sends to VMD are saved in VMD. The simulation steps will still be saved to a .dcd regardless, but you may want to save them in VMD immediately as they come in. Be aware that this may use a significant amount of computer memory.

2

The next settings, IMD Server and Processors, are related to where and how the NAMD simulations will be run. By default, the simulations are run on your local machine by calling the namd2 command with the selected number of processors. This assumes that namd2 is on your computer's PATH. If you wish to adjust how NAMD is called or add additional server definitions, you can add them to a MDFF GUI settings file. To see how the default server is set, save your settings file (discussed at the end of the previous section) and open the file with a text editor. You should see near the bottom something like:

MDFFGUI::gui::add_server "Local" {
maxprocs 12
namdbin {namd2 +p%d}
jobtype local
timeout 20
numprocs 12
}

Here you can modify the "Local" server, or create a new entry and name it something unique (i.e. not "Local"). You can change how namd2 is called in the namdbin setting, the default number of processors to use, and the timeout (in seconds) for how long VMD should wait after attempting to contact NAMD before giving up.

3

With all of the parameters now set, you should click the 'Generate NAMD files' button at the bottom of the MDFF Setup tab, seen in Fig. 18. This button will automatically generate all the files you need to begin your simulation and save them in your selected working directory.

Figure 18: The Generate NAMD files button creates all of the files needed for MDFF and saves them in your working directory

4

Navigate to the 'IMDFF Connect' tab of the MDFF GUI, shown in Fig. 19. This section of the GUI contains buttons for submitting, connecting to, pausing, stopping, and analyzing the IMDFF simulation set up in the MDFF Setup tab.

Figure 19: IMDFF Connect tab of the MDFF GUI, where interactive MDFF simulations can be submitted, connected to, paused, terminated, and analyzed

5

Before (or after) connecting to a running IMDFF simulation, you can open the 'Cross Correlation Analysis' subsection in the IMDFF Connect tab to perform real-time analysis of your fitting. To do so, check the 'Calculate Real-Time Cross Correlation' box. You can also set the atom selection for the piece of the structure you wish to analyze, as well as the resolution of the map (the defaults for both are fine for this tutorial). You can also set a threshold value, where any density values less than the threshold will not be included in the analysis. More information on choosing a threshold is given in Section 7.3. The cross correlation value for each simulation frame will be graphed in the area at the bottom of this tab, as seen in Fig. 20. This is a convenient way of determining how well your fitting is progressing and whether the simulation has converged.

Figure 20: Analyze your interactive MDFF simulation in real-time by computing the cross correlation of the structure to the density map as the simulation runs

6

You should now start your simulation by selecting the "Submit" button. Wait several seconds after clicking the 'Submit' button, then select the 'Connect' button. VMD will make several attempts (dictated by the amount of time in the selected server's timeout parameter) to connect to the running NAMD simulation.

7

Once VMD is connected to the simulation, you should see your structure moving in the VMD display window. This VMD window is showing your running MDFF simulation in real-time. You can pause or terminate the simulation at any time with the "Pause" and "Finish" buttons in the IMDFF Connect tab of the MDFF GUI.

8

When connected to a running IMDFF simulation, you can not only view the progress of your fitting, but manually manipulate the structure as well. To do so, in the Mouse menu of the VMD Main window, select "Mouse -$>$ Force -$>$ Atom". You may alternately select "Residue", or "Fragment" to apply forces to whole residues or fragments. Your mouse can now be used to apply forces to your simulation. Click on an atom, residue, or fragment and drag to apply a force. Click quickly without moving the mouse to turn the force off. The structure you are using for this tutorial, 1AKE, has no trouble fitting into the density and does not require interactive MDFF, but you should take this oppurtunity to try out this feature and drag pieces of the structure around. Please note however that the simulation will end once the previously set number of steps have been calculated. You can always change the number of time steps, regenerate the NAMD files, and re-submit the simulation and connect to it again if you wish to have more time.

Timeline Analysis

We will now analyze the MDFF simulation by calculating the cross-correlation coefficient for each frame of the trajectory. As of VMD version 1.9.2, the Timeline analysis plugin found in the Analysis section of the VMD extensions menu contains a method for quickly computing the cross correlation of an MDFF trajectory. The default behavior of this function computes the cross correlation for all the contiguous sections of secondary structure found in your model. The result is local cross correlations of the structure over the course of the entire fitting trajectory. This type of analysis provides an unprecendented level of fine-grained detail that you can use to easily examine your fitting and find regions of interest (e.g. regions of poor fit).

1

First, make sure you have your structure loaded into VMD:

mol new 1ake-initial_autopsf.psf
mol addfile 1ake-initial_autopsf-docked.pdb

Then, add the dcd file from your simulation:

mol addfile mdff-step1.dcd

or you may use the provided dcd's:

mol addfile adk-step1-result.dcd
mol addfile adk-step2-result.dcd

2

Open Timeline from the VMD menu in Extensions -$>$ Analysis -$>$ Timeline. You should see a window like the one in Fig. 21. Make sure the number on the left-hand side of the window next to the Molecule: label is the same as the ID of the molecule that contains the DCD you wish to analyze.

Figure 21: Timeline window prior to analysis

3

Open the Calculate menu, near the top of the Timeline window, which contains a wide range of analysis methods which you can use on your trajectory. For now, we are just interested in the 'Calc. cross-corr. ...' option. Select this method, which will open a window for parameters.

Figure 22: Cross correlation parameters

4

You should now see a window containing options for setting the parameters of the cross correlation calculation, similar to the one in Fig. 22. First you must select the density map used earlier for the MDFF fitting. This should be the same density map you provided in the MDFF Setup GUI (4ake-target_autopsf.situs), and not the resulting potential file. The next two options, map resolution and spacing, control how the simulated density is computed. The simulated density is made from your structure, which is then compared to the experimental density you fit the structure into. The resolution should be the same as the resolution of the experimental density. For the tutorial, you can leave both default values.

5

The next option, Use a map threshold, allows you to set a threshold value at which any values in the simulated density that are lesser than this value will not be included in the correlation calculation. Setting a threshold value causes the correlation to disregard lower density regions which tend to be further out from the structure. To get an idea of how different threshold values affect the resulting density map, you can use the following command in the TkConsole:

mdffi cc

Typing this in the TKConsole will print usage information. The mdffi cc function can be used to calculate the cross correlation, but here we are mostly interested in examing the output maps. You will need to provide an atom selection for the region of the structure you wish to use to create the map. Assuming your structure is the top molecule, you can type:

set sel [atomselect top "protein and noh"]

then run the mdffi cc command:

mdffi cc $sel -res 5 -i 4ake-target_autopsf.situs -thresholddensity .1 -savesynthmap simulated.dx

This will output a simulated density map, simulated.dx, which you can then load into VMD. You can adjust the isovalue from the VMD Representations menu and visualize the extent of the map. You can try this for a range of threshold values to see how the generated maps are affected. For this tutorial, we can use a threshold value of 0.1.

6

There are two ways we can perform the correlation analysis. The default behavior is to segment the structure into pieces based on contiguous regions of secondary structure. Each one of these segments will have its own correlation calculated. If, however, you want to segment the structure differently, you can use the Custom selection list option and provide a set of atomselection keywords. For this tutorial we will use the default secondary structure method.

7

Select the OK button at the bottom of the parameters window. This will begin the correlation calculation and a progress window will appear. Once the calculation is complete, your Timeline window should look similar to Fig. 23.

Figure 23: Timeline window after correlation analysis. Residues on the y axis, trajectory frames on the x axis

8

The y axis of the plot contains the residues from your structure, while the x axis is the trajectory frames. Every residue in every frame has an associated colored block, which represents the local correlation of that residue to the experimental density. The color scale can be found in the bottom left corner of the Timeline window. The default view shows black squares as the worst correlation, while white is the highest. Clicking anywhere on the plot will select that residue for that particular frame and show its information in the area directly to the right of the color scale.

9

A black to white color scale can be difficult to interpret, so we will try changing to a red, green, and blue scale. To do this, click on the Appearance menu at the top of the Timeline window and select Color scale -$>$ Rainbow (RGB), making your plot look similar to Fig. 24. Now the worst correlation will appear in red, medium correlation in green, and the best in blue. Hopefully, by the last frame, most of your structure should be blue and green.

Figure 24: Timeline correlation analysis colored with red, green and blue. Red represents the worst correlation, green a medium correlation, and blue represents the best correlation

10

Next we will copy the correlation data to our structure, for another way of visualizing the correlation. From the Analysis menu at the top of the Timeline window, select 'Copy data to User field...'. This function will add the correlation data to the 'User' representation field. From the Representations menu of VMD, located in the Display menu of the VMD Main window, you should select the molecule that you analyzed in Timeline. Set the Drawing Method to NewCartoon, then set the Coloring Method to Trajectory -$>$ User -$>$ User. This will color the structure by the local correlations calculated in Timeline.

11

Because we changed our Timeline color scale to RGB, we should do the same for our representation. From the Colors window in the Graphics menu of the VMD main window, you should select the Color Scale tab at the bottom, as seen in Fig. 25. In the Method box, select RGB. Now the colors in our Timeline plot should match the colors on the structure.

Figure 25: VMD color scale window

12

Back in the Graphical Representations window, you should select the density map 4ake-target_autopsf.situs, and change the Draw option to Solid Surface and the Material to Transparent. This will make it easier to visually inspect the fitting of your structure inside the density.

13

Whenever we select a residue in the Timeline window, that residue will be highlighted with a licorice representation in the VMD display. The trajectory will also jump to the selected frame, and the structure will be colored according to the correlations for that frame. Finding interesting events in the Timeline window and viewing the structure at that point at the same time can be a powerful method for analyzing your fitting simulation and understanding what occurred. This analysis method is especially useful for tracking down regions of poor fit and inspecting how those regions are fitting, or failing to fit, into the density map. You could set up subsequent MDFF simulations and concentrate on improving those regions, perhaps even using interactive MDFF to manually steer those regions into the density.