Tutorials

Starting up
It is assumed that Java Runtime Environment and JOGL have been appropriately installed. Once you extract the binary distribution file of jV3, the directory of the name, jV_(version), is generated (Ex. jV_3_6_2). The version is assumed to be 3_6_x hereafter. The application starts up by double-clicking the file ‘jv_3_6_x.jar’ in the jV_3_6_x directory or executing the following command from the command line interface. java –jar jv_3_6_x.jar Figure 1 shows the start-up screen. The window has a 3-panel structure, and the upper-left panel with the black background is a 3D image display area. The status of files that have been loaded to the application is shown in the upper-right panel and the lower panel is a command-input and a message-output area.

Displaying molecules
If you are working in the environment that is getting on the Internet and know the PDB ID of the molecule that you want to display, the simplest way is as follows. A dialog shown in Figure 2 is opened by selecting the [File] – [Open – Remote] – [PDB ID] menu item. Enter a PDB ID '12as', for example, to the text field and click the 'OK' button, then the PDBML file is read through the Internet and the molecule is displayed. The URL where the PDBML file is retrieved from is specified in the 'properties.txt' file in the jV_3_3_x directory. A molecule is displayed in a wire frame model with colored by atom type in the initial state.



Let us next attempt to load an arbitrary file on the Internet. Here we use 'http://ef-site.hgc.jp/eF-site/jV/1yec.pdb' as an example. The file is a conventional PDB file whose PDB ID is 1yec. In this case we choose the [File] – [Open – Remote] – [PDB] menu item. Then the open-remote dialog is appeared. Enter the above URL to the text field at the top of the dialog and click the 'OK' button and the molecule is read in and displayed. In jV3, each molecule is displayed according to the space coordination described in its file. Therefore, when loading and displaying more than one molecule together, they can be viewed with an appropriate separation in some cases; however, they may be displayed far separately or may be overlapped depending on the combination. In any case, when adding a new file, the position of the viewpoint is automatically controlled for the whole to be displayed. The coordinate system is the right hand system with the x-y plane being on the screen (the x-axis is a horizontal line with positive values to the right and the y-axis is a vertical line with positive values up). Although, the above examples are about operations for remote files, a PDB file on your local hard disk can also be opened from the [File] – [Open – Local] – [PDB] menu item.

Operating molecules
Interactive mouse operations are possible for 3D images. By left-dragging the mouse on the 3D-display panel, molecules are rotated around the x-axis or y-axis. By left-dragging the mouse while holding the Shift key or Alt key on the keyboard, molecules are translated along the z-axis. All mouse operations are as follows (as for the Macintosh environment, the Command key + left-drag substitutes for the right-drag).

In the upper-right panel in the application window (see Figure 3), the file names that have been loaded to the application are listed, where sequential integers are automatically assigned to the individual file. Each integer is a file ID that can be used to specify the file in the command line interface. In addition, two checkboxes are attached to each file. If you change the status of a ‘display’ checkbox, the corresponding molecule is switched to be displayed or not to be displayed. If you change the status of a ‘select’ checkbox, the corresponding molecule is switched to be a target of the mouse operations or not. For example, set the both ‘display’ checkboxes on, and the both ‘select’ checkboxes off. In this case, either molecule does not move against mouse operations. Subsequently set the ‘select’ checkbox of file 1 on. In this case, mouse operations work for the molecule 1. Thus, each file is assigned either selected or not selected, and transform operations, such as rotation or translation, act only on selected files. On the other hand, every atom in a molecule is also assigned either selected or not selected, independently of whether the molecule itself is selected or not. Operations that modify display models or colors work for selected atoms. To see this, choose the [Display] – [Spacefill] menu item. Then the both molecules are displayed with the space fill model because all atoms are initially selected. In the same way, if you choose the [Colors] – [Monochrome] menu item, the both molecules are colored white. These operations are independent of the status of ‘select’ checkboxes mentioned above. Let us next try a more detailed operation. Type ‘select *@2’ in the command line area and press Enter key. This command means to select all atoms contained in the file 2 (the usage of the select command is summarized in the reference manual included in the binary distribution of jV3). Subsequently, choose the [Display] – [Cartoon] menu item. As a result, only the molecule 2 is displayed in the cartoon model. Furthermore select the [Colors] – [Structure] menu item, and each residue of the molecule 2 is colored according to its secondary structure type (see Figure 3). In order to reproduce the same view as that in Figure 3, first execute ‘reset’ command. It restores the position of the viewpoint and the transform of every file to the initial state. Note that the command line interface tries to complement a command word when the Tab key is pressed. If you enter ‘res’ to the command line and subsequently press the Tab key, the command ‘reset’ is automatically entered. Next set the both ‘select’ checkboxes on, and execute ‘translate z 100’ command. This command means to translate the molecules along the z-axis by 100 angstroms.



Displaying polygons
In addition to molecules, arbitrary shapes described by polygons can be read in and displayed together, where the polygon file is an XML file, whose document type is described in the section 6. Here, we use ’http://ef-site.hgc.jp/eF-site/jV/1yec.surface.gz’ as an example. This polygon file represents a molecular surface of the molecule 2 (1yec) and the surface is colored according to the electrostatic potential and the hydrophobicity. It is assumed that the current image is the same as that in Figure 3. Then, open the open-remote dialog by choosing the [File] – [Open – Remote] – [Polygon] menu item, enter the above URL to the text field at the top of the dialog, and click the 'OK' button. As a result, the polygon is loaded, displayed and assigned file ID 3. Note that the polygon is displayed at the different position from the molecule 2 since the molecule 2 is translated. However, because the polygon and the molecule 2 are described by the same coordinates in their files, their images can be exactly superposed by executing ‘fit 3 2’ from the command line, where the ‘fit’ command performs the copy of the transform matrix. Finally, the image in Figure 4 appears.



You can control the transparency rate of polygons. Try ’set transparency 0.5’ from the command line, where 0.5 stands for 50% transparency. To restore the image, execute ‘reset transparency’ or ‘set transparency 0’. In the same sense as each atom of a molecule, each vertex of a polygon is assigned either selected or not selected. All vertices are selected in the initial state. Execute a command ’displayvertex off’ and all vertices become invisible. Next execute ’selectvertex within(10.0, 1&*H@2)’, where this means to select vertices that exist within 10 angstroms from each atom that belongs to the first residue of the ‘H’ chain of the molecule 2. Subsequently execute ’displayvertex on’. As a result, only the selected vertices are appeared. The usage of the selectvertex command is summarized in the Command List.

Working with xPSSS
Functional site information on a molecule stored at xPSSS (xml-based Protein Structure Search Service) is available in jV3. Before trying this, let us close the molecule 2 and the polygon 3 to make the situation simple. Select the [File] – [Close] – [2. 1yec.pdb] and [File] – [Close] – [3. 1yec.surface.gz] menu items sequentially. Then execute a ‘reset’ command and the transform of the molecule 1 and the position of the viewpoint are initialized. Next, confirm that the ‘select’ checkbox of the file 1 is checked, and try a ‘show xps3’ command. The functional site information of the molecule ‘12as’ is read from the xPSSS and ‘type’ and ‘subtype’ keywords for each functional site are listed. These keywords can be used to select a set of atoms. For example, if a keyword ‘CATRES’ exists (probably it does), the command ‘select xps3:CATRES’ selects the corresponding atoms. In addition, gene ontology information can be obtained from the xPSSS. The gene ontology information for the molecule 12as is displayed by the command ’show godata’. Similar operations can be applied to other external databases on the Internet provided that the external database supports the interface that jV3 requires. See the Functional site information for molecules for details.

Animation
The animation of molecules can be performed in jV3. The animation file takes the PDB format, where the MODEL line divides each frame. Let us open an animation file ’http://ef-site.hgc.jp/eF-site/jV/anim.pdb.gz’ as an example from the open-remote dialog shown by selecting the [File] – [Open – Remote] – [Animation] menu item. When an animation file is loaded to the application, the first frame is automatically displayed in the wire frame model. You can start the animation by using the animation-control dialog that is shown by choosing the [Options] – [Animation] menu item. The dialog provides operations such as start and stop of the animation, selection of the animation mode, and adjustment of the speed. Some sample figures of the dialog are shown in the GUI

Saving your work
While in your work, you can create a script file that contains a set of commands that reproduces the current work by using the [File] – [Save] – [Script] menu item. The script file can be loaded by the [File] – [Open – Local] – [Script] menu item. On the other hand, the [File] – [Save] – [PDB] menu item enables to save a molecule to a PDB format file with the coordinates of the atoms being transformed according to the current image. Here, only one molecule must be selected and only selected atoms in the molecule are saved. The other two menu items in the [File] – [Save] menu, [PNG] and [JPEG], save the current screen image to an image file in the PNG and JPEG format, respectively. The created image file has the same size as that of the 3D-display panel in the application.

Terminating the application
The application is terminated when the [File] – [Exit] menu item is chosen or the application window is closed by the way your operation system provides. You can also quit the application by executing ‘exit’ or ‘quit’ command.