Working with the 3D Viewer

From CheS-Mapper Wiki
Jump to: navigation, search

After pressing Start mapping-Button in the Wizard (see Main Page#Wizard), the 3D Viewer shows up.

General Viewer Options

Mouse Controls

The 3D viewer is controlled with the mouse:

  • to rotate hold the left mouse button down and dragg the mouse.
  • to zoom in/out use the mouse wheel (or hold shift key and left mouse button down while moving the mouse cursor up/down).
  • to translate the rotation center double click, hold the mouse button down and dragg the mouse.

Select and Zoom in on Compounds and Clusters

  • clustering disabled:
    • to zoom in on a compound: click on the structure, or select it in the compound list on the top left
  • clustering enabled:
    • to zoom in on a cluster: click on a structure within the cluster, or select it in the cluster list on the top left.
    • to zoom in on a compound: zoom in on cluster first and then select the compound, or click on "All Compounds" in the cluster list at the top left to enable "Single compound selection"
  • to zoom out: double-click somewhere into empty space, or click on the x-button next to compound list on the top left
  • to select a compound w/o zooming in: hold control-key down while clicking
  • to select multiple compounds at once: see #Select_Multiple_Compounds

Reset the view

To reset the view press the Home-Button (Pos1 on german keyboard) or use Menu: View > Reset view

Change Compound Depiction

Using the radio buttons at the bottom left, the compound depiction can be changed. Available options are wireframe (draws only bonds), balls & sticks (draws atoms as well) and dots (draws only a single sphere instead of the compound). The latter option (dots) is suitable to get a better overview when using large datasets.

Change Compound Size

By using the 'Size' slider (or the "+" or "-" buttons) at the bottom left of the screen, you can change the size of the compound structures. Reducing the compound size can be advantageous, as sometimes compounds overlap in the field of view. A shortcut to use this function is pressing CRTL and +/-.

Spread Compounds (Jittering)

By using the 'Spread' slider (or the "+" or "-" buttons) at the bottom left of the screen, you can move close compounds apart. This helps to separate compounds that have equal or very similar feature values, and are thus mapped to the same or very close positions.

Hide Unselected Compounds

To provide a clear view on the selected compounds, unselected compound are drawn translucent. This can be configured in Menu: View > Hide unselected compounds. (There is also an option to draw unselected compounds translucent when the selection is only via mouse-over, i.e. when the viewer is NOT zoomed in on a compound).

Change Compound Identifier

The compound identifier is shown in the compound list at the top left, and when hovering the mouse over compounds. CheS-Mapper automatically looks for integrated features in the dataset file with feature name "name" or "ID", to use this feature value as identifier. If no suitable feature is found, the index of the compound in the dataset file is used. The feature used as compound identifier can be selected manually (Menu: View > Compound identifier).

Filter, Remove and Export

Compounds that are currently selected (or unselected), can be filtered, removed and exported (see also: #Select_Multiple_Compounds).

Filter Compounds

The filter option removes (currently selected) compounds temporarily from the view (Menu: Edit > Filter). If multiple compounds are selected, a filter icon appears next to the compound list. Filtering is especially helpful when working with large datasets. The filter can be removed with the X-button at the top left.

Remove Compounds

Removes (currently selected) compounds from the viewer (Menu: Edit > Remove). The original dataset is not modified. You have to restart the mapping to get all compounds back into the 3D viewer.

Export Compounds

Exports selected compounds or the entire dataset (Menu: Edit > Export) to a new dataset file. Supported output formats are SDF and CSV. Calculated features and cluster assignments can be stored in the file as well. By default, a SD-File is exported, to create CSV-output name your export file "<filename>.csv".

Export Images / Take Screenshots

You can export high-resolution images from CheS-Mapper, showing only the compounds (without the control and info panels). The export function makes use of the export dialog that is built into Jmol. Supported image types are: "jpg", "png", "gif", "ppm", "pdf". Start export with Menu: Edit -> Export -> Export Image. White background may be better suited for articles that will be printed (Disable: Menu: View > Background color black); using Balls & Sticks instead of Wireframe might be a good idea as well.

Export Wizard Settings

See Export/Import Wizard Settings

View and Highlighting Options

Feature values can be highlighted with the drop-down menu on the bottom left or with the feature list on the right-hand side.

Feature Types

  • Numeric features: compounds with high feature values are highlighted with red color, compounds with low values are highlighted with blue color.
  • Nominal features: A distinct color is assigned to each nominal value. Note that the color for each nominal value has no semantic information (The color order is fixed, the nominal feature values are sorted lexicographically).
  • Structural fragments: Match is highlighted red, no-match is highlighted blue, the matched fragment is highlighted orange (configurable in Menu: Highlighting > Substructure Match Color). All possible occurrences in the compound are highlighted, for example, the SMARTS string c:c would highlight all aromatic carbon atoms, that are connected to another aromatic carbon atom in each compound. Click on the Show-button (just above the bar chart) to open a visualization using

Highlighting with Spheres

By default feature values are highlighted by changing the color of the compound atoms and bonds. You can select spheres for highlighting (Menu: Highlighting > Sphere highlighting) to preserve the CPK coloring of compound atoms and bonds. (You can adjust the size and the translucency of the spheres (Menu: Highlighting > Sphere settings), hotkeys are CTRL+SHIFT+'+/-' and CTRL+ALT+'+/-'.)

Log-transform feature values

Features can be transformed using the logarithm (to base 10) via Menu: Edit > Log-transform feature values). This is especially helpfull for inspecting activity data that is often log distributed.

Adjust highlighting colors

The highlighting colors of cluster assignments or feature values can be manually adjusted (Menu: View > Colors...). For example, the color gradient for numerical features can be adjusted (by default, low feature values are indicated with blue color, medium values with white, and high values with red).

Highlight two Features

Two features can be directly compared (Menu: Highlighting > Double feature highlighting). This will highlight the currently selected feature in a sphere, and the previously selected feature in a second, flattened spheroid. In the example below the actual carcinogenicity class value is selected, as well as the classification of a kNN QSAR model. Therefore, miss-classifications can be easily identified.

Change Font Size and Size of Components

The font size of the viewer can be adjusted. Moreover, the user can change the size of the 2D compound image as well as control and information components (Menu: View > Font size and component size...).

Advanced Functionalities

Sorting of Compounds and Clusters

When a feature is selected, the feature value is added to the compounds and clusters within the lists. Moreover, the compound list is sorted according to feature values. Similarly, the cluster list is sorted according to the mean feature value (for numeric features, and according to the ratio of the mode for nominal features).

Select Multiple Compounds

Multiple compounds can be selected at a time, by holding down the control-key when clicking on each compound. You can directly select multiple compounds using the compound list and holding down the shift-key. Alternatively, click on a bar in the histogram-chart (at the bottom right) to select groups of compounds according to feature values. Multi-selection is useful to detect common properties of compounds and for filtering or exporting.

Detect Common Properties of Compounds (Sorting of Features)

The feature values of the selected cluster or compound/s are shown in a table on the right side. The table is sorted dynamically to show the most important features at the top that distinguish the selected compounds from the remaining dataset.

In more detail, the features are sorted from top to bottom according to the specificity of the feature value/s of this cluster or compound compared to the complete dataset. The specificity values are computed as the p-value of a Chi-Square two sample test for nominal features, and the ANOVA p-value for multiple numeric features. (For single numeric feature a Chi-Square test on binned data is performed.) This shows features at the top, that have a different distribution for the selected elements, compared to the overall distribution in the dataset.

This functionality can answer the following questions:

  • Why are these compounds clustered together? (example is for a dataset with 4 features, but especially helpful when having hundreds of features)
  • What does these compounds have in common? They are close in 3D space, so they have similar feature values, but what makes them similar?

Compute Distance to Compound

CheS-Mapper can compute and show the distance of a particular compound to all other compounds in the dataset (Menu: Edit > Distance to selected compound, or press Alt + D when the compound is selected). (The distance is computed based on the features that have been used for 3D embedding and it uses the same (dis)similarity measure as the embedding algorithm.)

This can be used to select and inspect the nearest neighbors of a compound. This is especially useful, if a compound has high embedding stress (as the nearest neigbhors of a compound with high embedding stress are not necessarily close in 3D space).

Detect Activity Cliffs

Activity cliff describe pairs/groups of compounds with similar feature values, but differing endpoint value. A compound pair that resembles an activity cliff has a high SALI [2] value. CheS-Mapper can compute the mean SALI values (Menu: Edit > Activity Cliffs) for each compound. (An activity endpoint has to be stored in the dataset file.). Additionally to the mean, the maximum pairwise SALI value, and the standard deviation of SALI values is provided as feature.

Example workflow: