Ye cannae change the laws of physics

Montgomery "Scotty" ScottOne of the problems with curating chemical databases of small organic molecules is filtering out bogus connection tables from legitimate molecules. One aspect of this challenge has been termed [Ed: “I” have termed] EOCWR standing for “Explodes On Contact With Reality”.

An interesting class of broken molecules, that are often overlooked by reasonableness filters, are those that defy the standard model of physics. In this view of matter, atoms are composed of whole numbers of protons, neutrons and electrons. To paraphrase, Democritus “all that exists are groupings of protons, neutrons and electrons in empty space, all else is opinion”. Naturally, under this model the formal charge on an atom cannot exceed its atomic number. Whilst [Ed: “While”] an arbitrary number of electrons may be associated with an atom, it cannot have fewer electrons than zero; hence the positive charge is bounded by the number of protons in the nucleus. However, many cheminformatics file formats record the formal charge rather than the electron count leading to the ability to represent impossible molecules. Checking for these is relatively trivial and allows compounds such as [H+2] or [C+7] to be flagged as erroneous.

Another example of testing for EOCWR is the work of Dr Jonathan Goodman and colleagues at the University of Cambridge on the challenges on embedding alkanes in three dimensions (here and here). Their work explains that in some molecules, although all atomic valences are reasonable, steric crowding would produce sufficient strain that the molecule would fall apart. Hence although graph theoretically an sp3 carbon may have four neighbours that each itself has three additional neighbours (all unique) in reality there is an energetic upper bound of 10 second neighbours in alkanes. As above, checking the number of second (and third) neighbours of an atom provides a convenient and efficient way of distinguishing plausible molecules from the artifacts of erroneous molecule processing (termed “robochemistry” by NCBI PubChem’s Evan Bolton).

Image credit: Graham Lees (Tram Painter on Flickr)

Using PubChem’s REST interface from Python

Version 1.0 of PubChem’s REST interface (PUG REST) went live on Sept 13. The tutorial gives examples of use, while full details are in the spec.

The following code shows illustrates basic usage from Python. If you want to simultaneously query large numbers of molecules, or do a substructure search, you need to perform a query “in the background” using the ListKey approach shown by SubstructureToCids:

import os
import sys
import time

import urllib2

def getresult(url):
        connection = urllib2.urlopen(url)
    except urllib2.HTTPError, e:
        return ""

def NameToSmiles(name):
    return getresult("" % name)

def NameToCid(name):
    return getresult("" % name)

def CidToSmiles(cid):
    return getresult("" % cid)

def SubstructureToCids(smiles):
    result = getresult("" % smiles)
    if not result:
        return []
    listkey = ""
    for line in result.split("\n"):
        if line.find("ListKey")>=0:
            listkey = line.split("ListKey>")[1][:-2]
    assert listkey

    url = "" % listkey
    delta = 2
    while True:
        time.sleep(delta) # ...perchance to dream
        if delta < 8:
            delta += 1
        result = getresult(url).split("\n")
        if result[0] != "Your request is running":
    return result

if __name__ == "__main__":
    print NameToSmiles("Gleevec")
    print NameToCid("Gleevec")
    print CidToSmiles("123596")
    print SubstructureToCids("CC1=C(C=C(C=C1)NC(=O)C2=CC=C(C=C2)CN3CCN(CC3)C)NC4=NC=CC(=N4)C5=CN=CC=C5")

Lazy File Reading with mmap

Will Fix Defects For CaffeineThe example source code often provided with cheminformatics libraries to demonstrate the available functionality often try to address two conflicting requirements. On the one hand, these attempt to be pedagogical teaching examples, explaining how to perform a task often to a new or inexperienced user. On the other, these also attempt to address realistic problems and have utility in their own right. Alas in some cases, the best or most efficient way to do something is not the easiest to understand, so efficiency is sacrificed for clarity, or the other way around.

A recent example of this dilema arose for an example program to demonstrate how NextMove Software’s CaffeineFix library can be used with jQuery to provide efficient autocompletion/suggestion in chemical search engine text boxes, such as provided by Google. A minor implementation detail of this approach was the reading of CaffeineFix’s binary .cfx file format from disk.

In C or C++, a simple way to perform this shown by LoadDictionary1 below, that uses the standard I/O library to read in the dictionary in sequential chunks of 64 Kbytes at a time.

#include <stdlib.h>
#include <stdio.h>

unsigned char *LoadDictionary1(const char *fname) {
  unsigned int alloc = 65536
  unsigned char *result;
  unsigned int len = 0;

  FILE *fp = fopen(fname,"rb");
  if (!fp) {
    fprintf(stderr,"Error: Unable to read dictionary file %s\n",fname);
    return (unsigned char*)0;

  result = (unsigned char*)malloc(65536);
  if (!result) {
    fprintf(stderr,"Error: Unable to allocate 64K buffer!\n");
    return (unsigned char*)0;

  for(;;) {
    unsigned int chunk = fread(result+len,1,65536,fp);
    len += chunk;

    if (chunk != 65536) break;
    alloc += 65536;
    result = (unsigned char*)realloc(result,alloc);
    if (!result) {
      fprintf(stderr,"Error: Unable to reallocate %uK buffer!\n",alloc>>10);
  return result;

This is functional, highly portable between systems and even works with streams, such as stdin.

Ultimately, however, the most efficient implementation for reading binary CaffeineFix dictionaries on UNIX-like operating systems is to use “mmap“. Memory mapping lets the operating system decide where to return contents of a file, but with a clever trick of virtual memory that the data is (typically) only read from disk when a memory location is accessed.

#include <fcntl.h>
#include <unistd.h>
#include <sys/stat.h>
#include <sys/types.h>
#include <sys/mman.h>
static unsigned char *LoadDictionary4(const char *fname)
  unsigned char *result;
  unsigned int len;
  struct stat buf;

  int fd = open(fname,O_RDONLY);
  if (fd < 0) {
    fprintf(stderr,"Error: Unable to read dictionary file %s\n",fname);
    return (unsigned char*)0;

  if (fstat(fd,&buf) < 0) {
    fprintf(stderr,"Error: Unable to determine file size\n");
    return (unsigned char*)0;

  len = (unsigned int)buf.st_size;
  result = (unsigned char*)mmap(0,len,PROT_READ,MAP_FILE|MAP_PRIVATE,fd,0);
  if (result == MAP_FAILED) fprintf(stderr,"Error: Unable to memory map dictionary!\n");
  return result;

For the example use-case described above, autocompletion using CaffeineFix typically only (randomly) accesses a small fraction of the binary file. In practice, this means that only a small part need be read from disk.

To quantify the performance advantage, we consider autocompleting the text “bisul” using NCBI pubchem’s synonym dictionary of 46.6 million compound names. The original 976 Mbyte ASCII dictionary file is very efficiently encoded as a 718 Mbyte binary CFX file. Using LoadDictionary1 above, autocompletion of “bisul” to return 10 possible completions takes 68 seconds on my Apple laptop, over 99.9% spent in file I/O. Using memory mapped file I/O with LoadDictionary4, the same task takes under half a second.

In practice, if using a persistent process on a web server there’s very little difference between approaches, as once the dictionary has been read into memory suggestions can be made as fast as a user types. However, for applications where this start-up time is an issue, memory mapping is clearly superior.

As a final word, I should point out that memory mapped file I/O is also available to programmers on Microsoft Windows using the MapViewOfFile APIs, and even to Java programmers using the method to return a ByteBuffer. [Ed: It’s also available in the Python standard library!]

Image credit: James Nash (aka Cirrus) on Flickr

Identifying suspect InChIs in Wikipedia Chemboxes using Chemical Name to Structure

Wikipedia is a highly useful source of Chemistry and also of chemical nomenclature. A limitation in chemical name to structure software, such as OPSIN, is that trivial names that are similar to systematic names may be misinterpreted if the program has never encountered the trivial names. The nature of Wikipedia means that the most important chemicals and hence the most prevalent trivial names are included so surely Wikipedia would be a great resource to look for name to InChI relationships where the name to structure software was at fault?

I used Matthew Gamble’s code for extracting chemboxes as RDF to quickly grab the contents of all the current chemboxes. From the output of this tool it was simple to get the name/InChI pairs. As I was interested in trivial names I used the title of each Wikipedia page as the input for name to structure.

430 cases were flagged up for a range of reasons: ring/chain tautomerism, intentionally underspecified names, under or over specification of stereochemistry and of course the type of error I was expected. However there were also a significant number of cases where the InChI clearly described a different compound. Upon investigation for the records I’ve corrected so far the root cause appeared to be an incorrect reference to ChemSpider. This then allows script assisted updates to pull in inappropriate InChIs/SMILES.

Example of a previously incorrect page.

Increasing the precision of identificiation of these incorrect name/strucutral identifiers pairs should be possible if the IUPAC names were used as input…

Visualising a hierarchy of substructures

Given a set of chemical structures as SMILES, how can you visualise the substructure/superstructure relationship between them?

For example, the following picture shows the relationship between members of a set of structures containing several benzene derivatives and monosaccharides:
This was created using the following Python script, which iteratively looks for the structure that matches the largest number of molecules in the set, building up a tree as it does so. The output is the tree in a form suitable for depiction using Graphviz’s dot program. The Python script uses Open Babel, but could easily be adapted for other toolkits.