pKa-Prospector - OpenEye Scientific Software · pKa-Prospector, Release 1.0.0.3 A folder containing...

pKa-ProspectorRelease 1.0.0.3

OpenEye Scientific Software, Inc.

September 25, 2013

CONTENTS

1 Front Matter 1

2 Installation 32.1 Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32.2 Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42.3 Mac OS X . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

3 Introduction 7

4 QuickStart 94.1 Open a molecule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94.2 Edit the Molecule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94.3 Turn on Additional Search Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104.4 Perform a Substructure Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104.5 Open up a Result Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104.6 Save it to PDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

5 Interface Details 135.1 Query Molecule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135.2 Property Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145.3 Search Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165.4 Results View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185.5 Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185.6 Result Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195.7 Menu Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215.8 Appending Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215.9 Selecting an Imported Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

6 Citation 25

7 Release Notes 277.1 pKa-Prospector v1.0.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Index 29

i

CHAPTER

ONE

FRONT MATTER

Copyright 1997-2013 OpenEye Scientific Software, Santa Fe, New Mexico. All rights reserved.

All rights reserved. This material contains proprietary information of OpenEye Scientific Software. Use of copyrightnotice is precautionary only and does not imply publication or disclosure.

The information supplied in this document is believed to be true but no liability is assumed for its use or the infringe-ment of the rights of others resulting from its use. Information in this document is subject to change without noticeand does not represent a commitment on the part of OpenEye Scientific Software.

This package is sold/licensed/distributed subject to the condition that it shall not, by way of trade or otherwise, belent, re-sold, hired out or otherwise circulated without OpenEye Scientific Software’s prior consent, in any form ofpackaging or cover other than that in which it was produced. No part of this manual or accompanying documentation,may be reproduced, stored in a retrieval system on optical or magnetic disk, tape, CD, DVD or other medium, ortransmitted in any form or by any means, electronic, mechanical, photocopying recording or otherwise for any purposeother than for the purchaser’s personal use without a legal agreement or other written permission granted by OpenEye.

This product should not be used in the planning, construction, maintenance, operation or use of any nuclear facilitynor the flight, navigation or communication of aircraft or ground support equipment. OpenEye Scientific Software,shall not be liable, in whole or in part, for any claims arising from such use, including death, bankruptcy or outbreakof war.

Windows is a registered trademark of Microsoft Corporation. Apple, OS X, and Macintosh are registered trademarksof Apple Inc. UNIX is a registered trademark of the Open Group. Linux is a registered trademark of Linus Torvalds.Red Hat is a registered trademark of Red Hat, Inc. SUSE, SLED and SLES are registered trademarks of Novell, Inc.Ubuntu is a registered trademark of Canonical Ltd.

SYBYL is a registered trademark of Tripos, L.P. MDL is a registered trademark and ISIS is a trademark of Accel-rys Software Inc. SMILES is a trademark, SMARTS and SMIRKS are registered trademarks of Daylight ChemicalInformation Systems, Inc. MacroModel is a trademark of Schrodinger, LLC.

Python is a registered trademark of the Python Software Foundation. Django is a registered trademark of the DjangoSoftware Foundation. Java is a registered trademark of Oracle and/or its affiliates.

Other products and software packages referenced in this document are trademarks and registered trademarks of theirrespective vendors or manufacturers.

1

pKa-Prospector, Release 1.0.0.3

2 Chapter 1. Front Matter

CHAPTER

TWO

INSTALLATION

2.1 Linux

Linux distributions are provided as a gzipped tarball of the distribution tree described below. Installation is performedby simply untarring the file in the desired location. The top-level directory in the tarball is named openeye. Distri-butions for different Linux variants can be installed into the same location, allowing multiple Linux versions to be runfrom a single shared directory.

To ensure that the installed applications can be called from the command line, be sure to add the full path of theopeneye/bin subdirectory to the PATH environment variable. For instance, if the distribution was installed into/usr/local/openeye, the PATH environment variable should contain: /usr/local/openeye/bin.

Under the top-level openeye directory are the following subdirectories:

arch This directory contains the collection of platform specific subdirectories. Each subdirectory con-tains the actual installed executables and support libraries for the associated platform. In the platformspecific subdirectory there will be a subdirectory for each application. Within that will be anothersubdirectory for each version of that application.

bin This directory contains a startup script for each application that has been installed. This script de-termines, at run-time, what the current platform is and then calls the appropriate executable in thearch. This script enables the easy co-existence of multiple platforms and versions of any OpenEyeapplication in the same distribution tree.

data This directory contains all of the associated data for the installed applications. There will be a subdi-rectory for each installed application and within that subdirectory there will be another subdirectoryfor each specific version of that application.

docs This directory contains all of the documentation associated with the installed applications. Therewill be a subdirectory for each installed application and within that subdirectory there will be anothersubdirectory for each specific version of that application.

examples This directory contains all of the examples associated with the installed applications. Therewill be a subdirectory for each installed application and within that subdirectory there will be anothersubdirectory for each specific version of that application.

The startup script discussed in the section on the bin directory above will have the same name as the installedexecutable with which it is associated. When the script is called, it will attempt to determine the current platform andrun the appropriate executable if installed. If an appropriate executable cannot be found, the script will report thatinformation, as well as a list of the currently installed platforms. The auto-detection can be overridden by setting oneof two environment variables:

• OE_ARCH can be used to specify a colon separated list of compatible distributions for the current platformsuch as:

3


redhat-RHEL5-x64:redhat-RHEL4-x64

Specification of this environment variable overrides the auto-detection process, if it is present. If none of thecompatible distributions listed are found, the script will fall back to the auto-detection process.

• APPNAME_OE_ARCH can be used to specify a colon separated list of compatible distributions for a spe-cific application (as specified by changing the APPNAME text in the environment variable name) just likeOE_ARCH as detailed above.

Specification of this environment variable overrides the OE_ARCH environment variable as well as the auto-detection process. If none of the compatible distributions listed are found, the script will fall back to theOE_ARCH list first and then to the auto-detection process.

Specifying this variable provides a simple way to customize the behavior for individual applications on non-standard platforms.

The startup script also supports a few commandline arguments including:

-path Specifying this argument will output the full path of the executable to be run. Theexecutable will not be started if this argument is present.

-print_arch Specifying this argument will output the details of the current platform as de-tected by the script as well as which platform-version of the executable is beingrun. The executable will be started if this argument is present.

-use_version Specifying this argument followed by a specific version number allows the userto control which released version of the executable to run.

2.2 Windows

Windows distributions are provided as a standard EXE installer. For installation double click the executable and followthe installation instructions. By default, OpenEye applications will install into the C:\Program Files (x86)directory (for 32-bit applications) or C:\Program Files (for 64-bit applications).

Under the application directory (C:\Program Files\Application Name) there are subdirectories for:

bin This directory contains the application executable.

data This directory contains all of the associated data for the installed applications.

docs This directory contains all of the documentation associated with the installed applications.

examples This directory contains all of the examples associated with the installed applications.

An OpenEye group with an application specific subgroup will be added to the Start menu. The application specificsubgroup will contain links to the documentation, the uninstaller, and, for some applications, a Windows commandshell with PATH settings already defined to allow the user to simply type the executable name at the prompt withoutconcern for where the executable is actually installed. Links are also included to add and remove the installed locationto the user’s default path.

For graphical applications, a link to the application will be created on the desktop as well as in the application specificsubgroup of the Start menu.

2.3 Mac OS X

Mac OS X distributions are provided as a dmg disk image. For installation, double click the .dmg file to open it, anddrag the application to the Applications folder.

4 Chapter 2. Installation


A folder containing documentation and example data is included in the disk image (Right click, Show PackageContents). Under the top level Contents folder there are subdirectories for:

data This directory contains all of the associated data for the installed applications.

docs This directory contains all of the documentation associated with the installed applications.

MacOS/bin This directory contains the application executable.

The documentation and example data can be copied to any convenient location. Graphical applications have built-indocumentation, which is available from the application’s Help menu.

For command-line only tools, an application named “Install Command Line Support” can be run from the .dmg file,and this will allow the user to add the application’s location to the user’s PATH environment variable. Command-lineapplications can also be run from the Applications folder, in which case they will open a terminal window with aproperly configured environment.

2.3. Mac OS X 5


6 Chapter 2. Installation

CHAPTER

THREE

INTRODUCTION

These pKa databases represent the extremely careful conversion of IUPAC’s extensive compilations of experimentalpKa values of organic acids and bases (in aqueous solution) from book form into fully curated computer-readable data.

Data Sources

• Base 1 (3775 molecules, 8766 pKas) Dissociation Constants of Organic Bases in Aqueous Solution, by D.D.Perin

• Acid 1 (1063 molecules, 2893 pKas) Dissociation Constants of Organic Acids in Aqueous Solution, by G.Kortum, W. Vogel and K. Andrussow

• Base 2 (4275 molecules, 7844 pKas) Dissociation Constants of Organic Bases in Aqueous Solution, Supplement1972, by D.D. Perin

• Acid 2 (4584 molecules, 10912 pKas) Ionisation Constants of Organic Acids in Aqueous Solution, by E.P.Serjeant and Boyd Dempsey

The actual conversion process was done entirely by hand by Tony Slater (http://www.pkadata.com/) of pKaData Lim-ited to ensure accuracy and consistency.

Figure 3.1: pKa Prospector

The pKa-Prospector application provides a tool for users primarily interested in their own compound to find what theprimary data may say about their compound or model compounds closely analogous to their molecule of interest.

7

http://www.pkadata.com/


8 Chapter 3. Introduction

CHAPTER

FOUR

QUICKSTART

4.1 Open a molecule

Figure 4.1: Open a file

Click the button next to where it says “Open a file...” Figure: Open a file. It does the default search, which is an“Analog Search”, automatically. Or you can paste a SMILES string directly into the query window and it will againrun the “Analog Search” automatically.

4.2 Edit the Molecule

Double click the query molecule in the upper left corner of the application. This will open the Editor. You can editthe molecule with the building blocks or you can type in a SMILES or common name of a molecule. Hitting the OKbutton will make this your new query molecule and perform an Analog Search. Figure: Editor.

9


Figure 4.2: Editor

4.3 Turn on Additional Search Options

Figure 4.3: Show Additional Searches

Open up the preferences dialog and click the checkbox which says “Show Additional Search Options...” Figure: ShowAdditional Searches

4.4 Perform a Substructure Search

Lasso with the mouse a sub portion of the molecule you wish to use for a Substructure Search. Figure: Lasso aSubstructure The results will now be highlighted with the matching substructure. Figure: Substructure Search

4.5 Open up a Result Report

Double click a results table on the right hand column of the results viewer. This will display a result report. Clickingthe blue links will jump to the detailed report of that particular measurement. Figure: Result Report

10 Chapter 4. QuickStart


Figure 4.4: Lasso a Substructure

Figure 4.5: Substructure Search

Figure 4.6: Result Report

4.5. Open up a Result Report 11


4.6 Save it to PDF

Click the Save to PDF button to save the report to a PDF file. There are additional export options under the file menu.

12 Chapter 4. QuickStart

CHAPTER

FIVE

INTERFACE DETAILS

Features

Figure 5.1: Mainwindow

5.1 Query Molecule

The upper left contains a depiction of the current query molecule. A query molecule can be loaded by opening a filefrom the file combo box directly below the depiction, pasting from your favorite molecule editor, or by double clickingthe depiction which launches the editor. The editor can accept both common molecule names and SMILES strings.

Once a molecule is loaded the application performs an “Analog Search.” The individual ionizable regions of the querymolecule are highlighted. After the “Analog Search” is performed the ionizable regions become clickable, indicatedby the highlighting color becoming more saturated when the mouse is hovered above. Clicking on a given ionizableregion will limit the results to molecules that match that particular ionizable substructure. Clicking in the negativewhite space will return the full list of results.

The Query Molecule will persist between sessions.

13


Figure 5.2: Editor

5.1.1 Tautomers

If pKa-Prospector detects a more common tautomer for a given query molecule it will prompt the user to use the morecommon tautomer. Often search results will improve if the more common tautomer is used as the query molecule.

5.2 Property Filters

5.2.1 pKa and Temperature

The property filters below the query molecule depiction allow for filtering of the results that are displayed. Checkingthe “pKa Range” check box and setting the range sliders will limit the results displayed to only those measurementswhich fall within that range; likewise the “Temp Range” check box will also filter out measurements that do not fallbetween the provided ranges. The ranges can be set by either moving the range sliders or entering the desired numericvalues in the spin boxes. The pKa filter range is limited between 0 and 14, the temperature filter range is limited from0 and 50. Although there may be some data points that fall beyond these ranges these endpoints were chosen to allowfor the maximum filter granularity of the vast majority of the data.

5.2.2 Ionization Types

By checking a subset of Acids, Bases, and Excited the results can be limited to showing measurements which havebeen assigned as falling into one of these categories.

5.2.3 Quality Minimum

The data has been annotated based upon the author’s assessment of quality, and the radio buttons allow for limiting thedisplayed results. There are a great deal more measurements on the lower end of the quality scale, so if ever it seemsthat the results list does not contain molecules that you believe should be there it helps to lower this threshold to hitupon a greater set of molecules.

14 Chapter 5. Interface Details


Figure 5.3: Tautomer Selection

Figure 5.4: Property Filters

Figure 5.5: Quality Quantities

5.2. Property Filters 15


Figure 5.6: Show Additional Search Options

5.3 Search Buttons

There are a total of five search options. By default only the “Analog Search” button is displayed. To get access to thefull set, simply open the preferences dialog and then click “Show Additional Search Options” check box.

Figure 5.7: Search Buttons

5.3.1 Analog Search

This is the default search, which is performed whenever a new molecule is loaded into the application. It attemptsto find the best model compounds in the database by exhaustively searching in a chemically aware manner. Firstlyif there is an exact match in the database the measurements associated with that molecule are reported first. Thenthe application performs a rooted maximum common subgraph search beginning at each ionizable region, and appliesa positive score for matches and a penalty for substitutions, graded based upon the electronic commutative distanceto the ionizable atom. The sum of these scores for each ionizable region match determines the overall rank of themolecule and its measurements. Only molecules with measurements that pass the property filters will be reportedback. If you do not wish this search to be performed every time you load a new molecule simply turn that option offin the preferences.

5.3.2 Exact Search

This search attempts to find an exact match in the database, and reports back only those measurements which pass theproperty filters.



Figure 5.8: Property Search

5.3.3 Property Search

This search ignores any query molecule information and simply reports back those molecules which pass the propertyfilters. The query molecule depiction is deemphasized, and the results view does not have a query molecule in the firstrow. Figure: Property Search

5.3.4 Substructure Search

Figure 5.9: Lasso a Substructure

This search will look for molecules that have a common substructure with the query molecule. A subset of thequery molecule can be used by lassoing with the mouse. Figure: Lasso a Substructure Again only molecules withmeasurements that pass the property filter will be reported.

Figure 5.10: Substructure Search

5.3. Search Buttons 17


5.3.5 Similarity Search

This search will perform a circular fingerprint search which is generated by exhaustively enumerating all circularfragments grown radially from each heavy atom of the molecule up to a given radius and then hashing these fragmentsinto a fixed-length bit vector. Only measurements which pass both the property filter and are above the Tanimotocutoff value will be reported.

5.4 Results View

On the right hand side of the application is the results view.

5.4.1 Search Summary

The first row of the results view contains a depiction of the query molecule and a summary of the search, includingany filters that were applied. If there is an exact match to the query molecule which passes the property filters this willalways be in the second row.

5.4.2 Depiction

The left hand column contains a depiction of the search results molecules. For an “Analog Search” the highlight-ing indicates the portion of the molecule which matches the ionizable region of the query molecule with the samecolor. For a “Substructure Search” the highlighting show the matching substructure. For a “Property Search” the high-lighting corresponds to the resulting molecules individual ionizable regions, and is unrelated to any other moleculeshighlighting.

Double clicking the depiction will make the molecule the new query molecule.

5.4.3 Results Table

The right hand column contains a table enumerating all available measurements that pass the preference filter for thegiven molecule. Layout of the Results Table can be changed in the Preferences.

Double clicking the result table will open a detailed report of the selected molecule. More detail is given below.

The results view can be saved to PDF or CSV through the file menu.

5.5 Preferences

5.5.1 Results View Customization

The application’s preference dialog allows for the customization of the reported data columns. By checking itemsfrom the list titled “Results Table Headers” will affect how the results table is generated. The individual items can bereordered and that order will be respected within the results table.



Figure 5.11: Preference dialog

5.5.2 Search Options

The “Show Additional Search Options” enables the “Substructure Search,” “Similarity Search,” “Exact Search,” andthe “Property Search” options. The “Display Aqueous Determination Only” checkbox will cause the results to onlyever display aqueous pKa values. The “Perform Search Automatically” checkbox will cause the application to performthe “Analog Search” automatically after any change to the query molecule.

5.6 Result Report

The Result Report is a detailed listing of all data which passes the property filter for a given result molecule. Thiswindow can remain open while performing other searches.

5.6.1 Depiction

The molecular depiction has highlighting for the individual ionizable regions, independent of any other molecules andtheir highlighting.

5.6.2 Summary

The top right contains a short summary table with a few key fields, along with links to jump to the specific detailedreport. The alternating background color of the summary table rows corresponds to the background color of the fulldata listing for that particular measurement.

5.6.3 Full Listing

The full listing contains all available data for that particular molecule. If data field is missing then that row will beomitted. The data fields are always in a fixed order.

5.6. Result Report 19


Figure 5.12: Result Report



5.6.4 Saving

The “Save to PDF” button will save the table to an easily printable PDF file including the depiction.

5.7 Menu Items

5.7.1 Saving Data

Under the “File” menu there are various options to save your results to PDF or CSV. “Save Selected as PDF” savesonly those rows which have been selected in the results view. Shift clicking and control clicking will select range andindividual rows respectively.

5.7.2 Session History

The “Session History” menu keeps track of all searches performed during a session. The search results are stored inmemory so they can be retrieved quickly, without having to search again.

5.7.3 Query Bookmarks

The “Query Bookmark” menu provides a means of saving individual query molecules and current property filtersettings. These bookmarks persist between sessions.

5.8 Appending Data

For institutions with their own pKa data, pKa-Prospector provides a means of folding that data into the user interface.It can live side by side with the IUPAC data.

Under the “File” menu there is an “Import Data...” dialog which will guide the user through the import process. Theuser has the option to name the imported database.

Figure 5.13: Data Loader

5.7. Menu Items 21


5.8.1 Data Formatting

In order for pKa-Prospector to properly import institutional data, the data must first be in an oeb or sdf file formatwith the desired measurement data set in SD data fields. The file is initially loaded through the dialogs “Open a file...”combo box. The application will then inspect the first 10 molecules to get a list SD data tags.

5.8.2 Data Mapping

The application requires that the various file SD data tags get associated to their corresponding properties. This isaccomplished by using the pull down combo boxes. As any given data tag is assigned it will be removed from the listsunder the other properties.

pKa Value: This is the only required data field; all others can have assumed default values. This field must be in adecimal format such that it can be converted using “float pka = atof(...);“

Temp: Much like “pKa Value” this field must be easily converted to a float. The “Default Value” column is the valuewhich will be assigned if there is no data tag assigned or if the assigned data tag is missing.

Ionization: This field must match the literal strings “Acid”, “Base”, “Excited” or “Unknown”. Much like temperaturethe default value can be set as well.

Assessment: This field must match the literal strings “reliable”, “uncertain”, or “approximate”. The default assign-ment can be set as well.

Aqueous: This fields indicates whether or not the pKa measurement was determined in aqueous solution. This fieldmust be “0” or “1” for false or true satisfying “bool aqueous = (bool) atoi(...);“

5.8.3 Extra Data

pKa-Prospector also allows for importing of extra data tags to be displayed along within results table. This may beuseful in some cases, for example if a molecule or measurement is associated with a particular corporate id.

5.9 Selecting an Imported Database

Figure 5.14: Select Database



5.9.1 Select Database

Once all the data fields are assigned and “OK” is clicked, pKa-Prospector will process the file and create an internaldata file from where it can be loaded upon future sessions. After the conversion process is finished a dialog is displayedwhere various data bases can be selected. Currently the application allows for IUPAC and the user data or just the userdata. If two imported databases have the same name the application will distinguish them by applying a time stamp.Also the user can delete an imported database by right clicking the database and selecting “Delete...” from contextmenu.

After the desired databases are selected the application will need to be restarted for the changes to take effect.

5.9. Selecting an Imported Database 23

CHAPTER

SIX

CITATION

Note: To cite pKa-Prospector please use the following:

pKa-Prospector 1.0.0.3: OpenEye Scientific Software, Santa Fe, NM. http://www.eyesopen.com.

25

http://www.eyesopen.com


26 Chapter 6. Citation

CHAPTER

SEVEN

RELEASE NOTES

7.1 pKa-Prospector v1.0.0

2013

First release of pKa-Prospector.

These pKa databases represent the extremely careful conversion of IUPAC’s extensive compilations of experimentalpKa values of organic acids and bases (in aqueous solution) from book form into fully curated computer-readable data.The pKa-Prospector application provides a tool for users primarily interested in their own compound to find what theprimary data may say about their compound or model compounds closely analogous to their molecule of interest.

7.1.1 Features

• Auto-identify ionizable centers.

• Auto-search to identify model compounds.

• Additional search types include property, substructure, exact and fingerprint similarity.

• Export PDF to share results.

• Extensible to operate over user supplied data.

27


28 Chapter 7. Release Notes

INDEX

AAnalog Search, 16Appending Data, 21APPNAME_OE_ARCH, 4

Eenvironment variable

APPNAME_OE_ARCH, 4OE_ARCH, 3, 4PATH, 3–5

Exact Search, 16

MMenu Items, 21

OOE_ARCH, 3, 4

PPATH, 3–5Preferences, 18Property Filters, 14Property Search, 17

QQuery Molecule, 13

RResult View, 18

SSimilarity Search, 18Substructure Search, 17

TTautomers, 14

29

pKa-Prospector - OpenEye Scientific Software · pKa-Prospector, Release 1.0.0.3 A folder containing...

Documents

Transcript of pKa-Prospector - OpenEye Scientific Software · pKa-Prospector, Release 1.0.0.3 A folder containing...