Depth-First: Tag rcdk

Ruby CDK for Newbies

Rich Apodaca — Thu, 04 Oct 2007 10:01:00 -0400

Scripting languages and cheminformatics can be a highly-effective combination. With their relaxed syntax, compilation-free execution, and interactive testing environments, scripting languages offer fast development iteration cycles. And scripting languages' support for manipulating libraries written in other languages can be key in today's heterogeneous cheminformatics software environment.

Although there are many cheminformatics scripting environments to choose from, Ruby offers some important advantages. Number one on the list is the wildly-popular Ruby on Rails Web development framework. Others worth mentioning include interactive ruby (irb), the RubyGems package manager, the Rake build system, the JRuby Ruby implementation, RubyForge, and a host of other productivity-boosters.

A major focus of Depth-First over the last few months has been Ruby CDK. This library consists of a thin Ruby wrapper around the open source Chemistry Development Kit (CDK), Structure-CDK, an open source 2D rendering toolkit, and OPSIN, an open source chemical nomenclature parser. A recent comment on Depth-First by Egon Willighagen, one of CDK's creators, got me thinking about centralizing this documentation. The following collection of links is a step in that direction.

Overview and Installation

Agile Chemical Informatics Development with CDK and Ruby CDK 0.3.0 Installation of Ruby CDK on Linux.
Running Ruby Java Bridge on Windows Special installation instructions for Ruby CDK on Windows.

Ruby CDK in Its Environment

From IUPAC Nomenclature to 2D Structures with OPSIN OPSIN converts IUPAC nomenclature into molecular representations and is now part of Ruby CDK.
Eleven Free Cheminformatics Scripting Environments So many choices, so little time.
Metaprogramming with Ruby : mapping Java Packages Onto Ruby Modules Behind the scenes look at a trick used in Ruby CDK.

Using Ruby CDK

Build a Rails Cheminformatics Application in Thirty Minutes First article in a series on building a SMILES Depict application.
Anatomy of a Cheminformatics Web Application: Beautifying Depict Second article in the series - cleaning up the Depict user interface.
Anatomy of a Cheminformatics Web Application: Ajaxifying Depict Third article in the series - use Ajax to automatically update the Depict drawing.
Cheminformatics for the Web: Convert SD Files to HTML with Ruby CDK SD Files are both everywhere and useless by themselves to chemists - why not convert them into HTML and post them to the Web?
Diversity-Oriented Chemical Informatics CDK is chock-full of nifty little tidbits, like the ability to enumerate all molecules of a given empirical formula.
Scripting Molecular Fingerprints with Ruby CDK To borrow a phrase from a cheminformatics master: "It's just that easy."
Hacking Molbank: Creating a Graphical Table of Contents The intersection of Open Access, Open Source, and rapid application development.
Anatomy of a Cheminformatics Web Application: Structure Cleanup in Java Molecular Editor The structure editor can be lean, mean, and still highly functional - just offload resource-hungry features to the server.
From IUPAC Name to Molecular Formula with Ruby CDK Peter Corbett's awesome OPSIN Library plays nice with Ruby CDK.
From InChI to Image with Ruby Open Babel and Ruby CDK InChIs are not easy to interpret - fortunately, this little library will do it for you.
Easily Calculate TPSA Descriptors from SMILES Strings Using Ruby CDK It just works.
Ruby CDK One-Liners: Create a Molfile with 2D Atom Coordinates from Arbitrary SMILES Strings Extremely short library for solving a very common cheminformatics problem.
Source Code Documentation in Ruby: RDoc for Ruby CDK When all else fails, read the documentation.

Image Generation Credit: txt2pic.com

Ruby CDK One-Liners: Create a Molfile With 2D Atom Coordinates From Arbitrary SMILES Strings

Rich Apodaca — Thu, 20 Sep 2007 14:18:00 -0400

A very common operation in cheminformatics is the interconversion of molfiles and SMILES strings. Usually, converting from SMILES gives a molfile in which all atoms have coordinates of (0,0,0). Sometimes you just need more than that. The following Ruby CDK code will accept an arbitrary SMILES string and return a molfile with fully-assigned 2D atom coordinates:

require 'rubygems'
require 'rcdk'
require 'rcdk/util'
include RCDK::Util

XY.coordinate_molfile Lang.smiles_to_molfile('c1ccccc1')

Looking at it this way, those four lines of require/include statements seem pretty darn verbose.

Easily Calculate TPSA Descriptors from SMILES Strings Using Ruby CDK

Rich Apodaca — Wed, 19 Sep 2007 09:27:00 -0400

A D-F reader wrote in to ask how to calculate Topological Polar Surface Area (TPSA) using Ruby CDK. TPSA is one of the most widely-used descriptors for predicting membrane permeability and from it other important ADME properties. This article shows how to calculate TPSA with Ruby using Ruby CDK.

The Library

Our library consists of nothing more than a few method calls to manipulate the underlying CDK library. The tpsa_for method accepts any SMILES string and returns the calculated TPSA:

require 'rubygems'
require_gem 'rcdk'
require 'rcdk/util'

jrequire 'org.openscience.cdk.qsar.descriptors.molecular.TPSADescriptor'

module TPSA
  @@calc = Org::Openscience::Cdk::Qsar::Descriptors::Molecular::TPSADescriptor.new

  def tpsa_for smiles
    mol = RCDK::Util::Lang.read_smiles smiles

    @@calc.calculate(mol).getValue.doubleValue
  end
end

An Interactive Test

Saving the library to a file called tpsa.rb lets us test it through interactive Ruby (irb):

$ irb
irb(main):001:0> require 'tpsa'
./tpsa.rb:2:Warning: require_gem is obsolete.  Use gem instead.
/usr/local/lib/ruby/gems/1.8/gems/rcdk-0.3.0/lib/rcdk/java.rb:26:Warning: require_gem is obsolete.  Use gem instead.
=> true
irb(main):002:0> include TPSA
=> Object
irb(main):003:0> tpsa_for 'COCCc1ccc(OCC(O)CNC(C)C)cc1' # metoprolol
=> 50.72
irb(main):004:0> tpsa_for 'O=C3Nc1ccc(Cl)cc1C(c2ccccc2)=NC3O' # oxazepam
=> 61.69

The results we obtain for metoprolol and oxazepam are 50.72 and 61.69, respectively. These values compare well with those reported by Ertl et al. in the definitive paper on TPSA (50.7 and 61.7, respectively).

Conclusions

It doesn't take much Ruby to command a wide range of cheminformatics functionality - in this case TPSA calculations. But the fun doesn't stop there. The CDK, and by extension Ruby CDK, offer access to a wide array of descriptor calculations, each of which follow the same basic pattern outlined here. All of it can be prototyped, debugged, and deployed through one of the most flexible programming languages currently available.

From InChI to Image with Ruby Open Babel and Ruby CDK

Rich Apodaca — Thu, 06 Sep 2007 08:25:00 -0400

Like SMILES, InChI is a line notation that can be used to encode and store chemical information relatively efficiently. Although there are a number of scenarios where this strategy is used, what many of them have in common is the need to eventually convert an InChI into a human-readable form. In most cases, this form will be a 2D chemical structure. This article will show how a small Ruby library can convert InChI strings into color PNG images with the help of Ruby Open Babel and Ruby CDK.

The Library

Our library accepts an InChI as input and produces a scaled PNG image as output. It re-uses part of a previously-discussed library for the interconversion of SMILES and InChI.

require 'rubygems'
require 'openbabel'
require_gem 'rcdk'
require 'rcdk/util'

module InChI
  @@to_smiles = OpenBabel::OBConversion.new
  @@to_smiles.set_in_and_out_formats 'inchi', 'smi'

  def inchi_to_png inchi, path_to_png, width, height
    smiles = inchi_to_smiles inchi

    RCDK::Util::Image.smiles_to_png smiles, path_to_png, width, height
  end

  private

    def inchi_to_smiles inchi
      mol = OpenBabel::OBMol.new

      @@to_smiles.read_string(mol, inchi) or raise "Can't parse InChI: #{inchi}."
      @@to_smiles.write_string(mol).strip
    end
end

Testing

Our library can be tested by saving it to a file called inchi.rb and using interactive Ruby (the warning can safely be ignored for now):

$ irb
irb(main):001:0> require 'inchi'
./inchi.rb:3:Warning: require_gem is obsolete.  Use gem instead.
/usr/local/lib/ruby/gems/1.8/gems/rcdk-0.3.0/lib/rcdk/java.rb:26:Warning: require_gem is obsolete.  Use gem instead.
i=> true
irb(main):002:0> include InChI
=> Object
irb(main):003:0> inchi='InChI=1/C23H27FN4O2/c1-15-18(23(29)28-10-3-2-4-21(28)25-15)9-13-27-11-7-16(8-12-27)22-19-6-5-17(24)14-20(19)30-26-22/h5-6,14,16H,2-4,7-13H2,1H3' #risperidone
=> "InChI=1/C23H27FN4O2/c1-15-18(23(29)28-10-3-2-4-21(28)25-15)9-13-27-11-7-16(8-12-27)22-19-6-5-17(24)14-20(19)30-26-22/h5-6,14,16H,2-4,7-13H2,1H3"
irb(main):004:0> inchi_to_png inchi, 'risperidone.png', 300, 300
=> nil

This code produces the following image:

Our library can also be used on more complicated molecules, for example Brevetoxin:

$ irb
irb(main):001:0> require 'inchi'
./inchi.rb:3:Warning: require_gem is obsolete.  Use gem instead.
/usr/local/lib/ruby/gems/1.8/gems/rcdk-0.3.0/lib/rcdk/java.rb:26:Warning: require_gem is obsolete.  Use gem instead.
=> true
irb(main):002:0> include InChI
=> Object
irb(main):003:0> inchi='InChI=1/C49H70O13/c1-26-17-36-39(22-45(52)58-36)57-44-21-38-40(62-48(44,4)23-26)18-28(3)46-35(55-38)11-7-6-10-31-32(59-46)12-8-14-34-33(54-31)13-9-15-43-49(5,61-34)24-42-37(56-43)20-41-47(60-42)30(51)19-29(53-41)16-27(2)25-50/h6-8,14,25-26,28-44,46-47,51H,2,9-13,15-24H2,1,3-5H3/b7-6-,14-8-' #brevetoxin a
=> "InChI=1/C49H70O13/c1-26-17-36-39(22-45(52)58-36)57-44-21-38-40(62-48(44,4)23-26)18-28(3)46-35(55-38)11-7-6-10-31-32(59-46)12-8-14-34-33(54-31)13-9-15-43-49(5,61-34)24-42-37(56-43)20-41-47(60-42)30(51)19-29(53-41)16-27(2)25-50/h6-8,14,25-26,28-44,46-47,51H,2,9-13,15-24H2,1,3-5H3/b7-6-,14-8-"
irb(main):004:0> inchi_to_png inchi, 'brevetoxin.png', 300, 200
=> nil

This produces the following image:

Conclusions

While our library could certainly be improved, it solves what otherwise would be a very difficult problem conveniently. Areas for further work include error handling and improving the appearance of the images (the latter is the aim of Firefly). Despite the fact that three programming languages are used (Ruby, C++, and Java), this complexity is neatly encapsulated behind a simple Ruby interface.

From IUPAC Name to Molecular Formula with Ruby CDK

Rich Apodaca — Tue, 13 Mar 2007 10:25:00 -0400

Recently, a question was raised on the Yahoo cheminf group list regarding the conversion of IUPAC names into molecular formulas. This can be done quickly with Ruby CDK, as this article will show.

Prerequisites

This tutorial requires Ruby CDK, which in turn requires Ruby Java Bridge (RJB). A recent Depth-First article described the minimal system configuration required to run RJB on Linux. Another article showed how to install RJB on Windows.

A Small Library

The following library will convert IUPAC nomenclature into molecular formulas with Ruby:

require 'rubygems'
require_gem 'rcdk'
require 'rcdk'
require 'rcdk/util'

module Formulator
  @@hydrogen_adder = Rjb::import('org.openscience.cdk.tools.HydrogenAdder').new

  def get_formula(iupac_name)
    mol = RCDK::Util::Lang.read_iupac iupac_name
    @@hydrogen_adder.addExplicitHydrogensToSatisfyValency mol
    analyzer = Rjb::import('org.openscience.cdk.tools.MFAnalyser').new(mol)

    analyzer.getMolecularFormula
  end
end

Save this code as a file named formulator.rb in your working directory.

Testing the Library

The Formulator library can be tested with the following code:

require 'formulator'
include Formulator

get_formula 'benzene' # => "C6H6"
get_formula '4-(3,4-dichlorophenyl)-N-methyl-1,2,3,4-tetrahydronaphthalen-1-amine' # => "C17H17NCl2"

Limitations

You may run across classes of structures that are not recognized by Ruby CDK. This is due to limitations of the underlying OPSIN library. For example, OPSIN does not yet recognize fused heterocycle names such as 'imidazo[2,1-b][1,3]thiazole'.

Conclusions

Ruby CDK makes short work of converting IUPAC names into molecular formulas. This is just one example of the kind of conversion that's possible. For example, a recent article discussed the conversion of IUPAC names to color 2-D structures.

Due to Ruby's position as both a highly functional scripting language and as the foundation for the popular Web application framework Ruby on Rails, a variety of IUPAC nomenclature translation applications are just a few lines of code away.

Hacking Molbank: Creating a Graphical Table of Contents

Rich Apodaca — Mon, 11 Dec 2006 15:00:00 -0500

Molbank is an Open Access collection of single-compound articles on synthetic chemistry. Previous articles on Depth-First have highlighted Molbank's practice of including machine-readable molecular representations of its content, and its very liberal policy on mirroring and robots. In this article, we'll take advantage of both of these features to build something that was left out of Molbank: a graphical table of contents.

The Graphical Table of Contents (GTOC)

The Molbank Graphical Table of Contents (Molbank GTOC) is available online. It consists of a single Web page containing a grid of color 2-D chemical structures representing the contents of Molbank. Each structure is hyperlinked into the Molbank site itself. Clicking on the structure takes you to the complete synthetic procedure and characterization data.

Prerequisites, Downloading, and Running

To run this project, you'll need Ruby CDK. A recent article described the small amount of system configuration required for Ruby CDK on Linux. Another article showed how to install Ruby CDK on Windows.

The complete source code for this project can be downloaded from RubyForge. A subdirectory called demo contains the pre-built final result.

After unpacking the molbank-0.1.0 archive, the demo application can be run:

$ cd molbank-0.0.1
$ ruby test.rb

Problems, We've Got Problems

Several problems were uncovered while building the Molbank GTOC. This is to be expected with any data produced "in the wild" rather than within the safety of an Ivory Tower. Here are the main categories:

Blank Images The entry for M52 is blank. Checking the underlying molfile reveals four instances of bond stereo flags set to "6," a problem common to many of the blank images in the GTOC. According to the Molfile specification, a value of 6 indicates "Down, double bonds," whatever that means. Given that the molecules shown in M52 only have one possible stereo bond, and that the Molfile specification relies on 2-D coordinates to encode double-bond geometry, an encoding inconsistency or incorrect stereo interpretation may be the cause.
Images Containing an "R" Atom Label Entry M53 shows an "R" group at what should be the carbonyl carbon. The underlying molfile contains several less-common entries in the properties block, a common feature of images containing "R" in the GTOC.
Molfile not Found Entry M95 has no associated Molfile because it simply reports errata for other articles. M253-M259, on the other hand, lack molfiles because the articles were "withdrawn before publication." M347 describes a cyclodextrin for which, understandably, no molfile was provided. There are also a couple of cases in which a link to a molfile is provided, but is not available, such as M352.
Broken Molfiles The Molfile for M162 encodes its line endings as two carriage returns and a newline, giving rise to the appearance of blank lines after data lines. This is something the Molfile specification strictly forbids. Apparently, the underlying CDK molfile reader can only handle one carriage return and a newline. Perhaps the extra return was introduced as the file was copied into and out of text editors on various operating systems in preparation for uploading it to Molbank. Another common problem was binary files being used for molfiles, such as with M402. These files don't appear to be compressed with either Zip or GZip and their nature is currently unknown.
Bogus Molfiles For reasons I still can't understand, the Molfile for M407 encodes ethylene. So do several other Molbank molfiles. Other common dummy molfiles include toluene, benzene, and ethane.

After cataloging the problems that exist with the Molbank dataset and the software used to mine it, two interesting questions come into focus:

What can be done to help Molbank fix the most obvious problems in their molfiles and would they accept these improvements?
How can "real" datasets like Molbank help developers build better cheminformatics software? (a graphical Molfile Debugger Utility would come in handy...)

Clearly, the connection between Open Access, Open Source, and Open Data is very strong and runs very deep.

Behind the Scenes

The Ruby Molbank GTOC generator works by connecting to the www.mdpi.net server to get its data in real-time. Internally, the software creates a map of the Molbank website so that the molfile (and URL) for any article can be retrieved on demand. Each readable molfile is used to create a 2-D image using Ruby CDK. As a final step, the index.html page is generated, linking the 2-D images to a specific URL for a Molbank article. This file is produced with eRuby using a previously-described technique.

Conclusions

Building a Graphical Table of Contents for Molbank is not that difficult given the power of Ruby, and Molbank's forward-thinking attitude toward mirroring and robots. In working on this project, several problems were uncovered, both with Molbank's data, and the software used to mine it.

In some ways, the software described here and its output are less interesting than the larger questions they raise:

How do scientific journals best serve not only their readers, but developers who want to provide new ways to use the journal?
How far does copyright extend in scientific publications? For example, are molfiles copyrightable? If so, at what level of detail are they not? If atom coordinates or some other kind of non-essential information is left out, does that change anything?
In what other practical ways could the connection between Open Source, Open Data, and Open Access be explored?

These and many related questions are waiting just around the corner. As Open Access becomes more viable, both technically and commercially, look to Open Source and Open Data to provide the synergies that will unlock its true potential.

Scripting Molecular Fingerprints with Ruby CDK

Rich Apodaca — Wed, 22 Nov 2006 15:44:00 -0500

A molecular fingerprint represents a molecule as series of bits. There are many situations in which this reduced form of molecular representation is useful. For example, fingerprints are frequently used as a fast prescreen for database substructure searches. They can also be used for "fuzzy" comparisons involving molecular similarity, a nice complement to binary queries such as substructure search.

Fingerprints have their limitations. Being a form of hashing, they are imprecise in that two different molecules can have exactly the same fingerprint. The converse is also true: many molecular fingerprints exaggerate small differences between two molecules that most chemists would say are similar - for example between oxygen and sulfur analogs of the same structure.

Despite their limitations, the advantages of fingerprints make them useful in many situations. As a result, numerous fingerprinting systems have become popular. This tutorial will focus on creating and manipulating molecular fingerprints from Ruby using the Ruby Chemistry Development Kit (RCDK).

Prerequisites

For this tutorial, you'll need Ruby CDK (RCDK). A recent article described the small amount of system configuration required for RCDK on Linux. Another article showed how to install RCDK on Windows.

A Small Fingerprint Library

Let's build a small Ruby library for working with fingerprints. Place the following code into a file called fingerprint.rb in your working directory:

require 'rubygems'
require_gem 'rcdk'
require 'rcdk/util'

jrequire 'org.openscience.cdk.fingerprint.Fingerprinter'
jrequire 'org.openscience.cdk.similarity.Tanimoto'

# Molecule fingerprinting
class Fingerprinter
  def initialize
    @fingerprinter = Org::Openscience::Cdk::Fingerprint::Fingerprinter.new
  end

  def fingerprint(smiles)
    mol = RCDK::Util::Lang.read_smiles smiles

    fp = @fingerprinter.getFingerprint mol

    # Metaprogramming!
    fp.extend(Fingerprint)
  end
end

# BitSet comparison
module Fingerprint
  # Returns true of all of the bits set to true in this fingerprint are also set to true in the specified fingerprint
  def subset?(fingerprint)
    Org::Openscience::Cdk::Fingerprint::Fingerprinter.isSubset(fingerprint, self)
  end

  # Tanimoto similarity of this fingerprint and the specified fingerprint
  def tanimoto(fingerprint)
    Org::Openscience::Cdk::Similarity::Tanimoto.calculate(self, fingerprint)
  end
end

Of particular note is the use of Ruby's Object.extend method. This method allows a single instance of an object to be extended at runtime - a form of metaprogramming. In this case, we add the subset? and tanimoto methods for determining whether all of the bits in one fingerprint are present in another, and for determining similarity, respectively. We use this technique here because currently RJB doesn't provide the complete interface into Java classes that would be required to create a Ruby class that directly inherits from Java's BitSet class.

Testing the Library

Claritin (loratadine, left) and Clarinex (desloratadine, right) are two structurally-related antihistamines. Can we quantitate the degree of similarity between these two structures? Fingerprints provide one way. The following code creates fingerprints for the two structures, determines if one is the subset of another, and assigns a Tanimoto similarity value:

require 'fingerprint'

f = Fingerprinter.new

loratadine = f.fingerprint 'CCOC(=O)N1CCC(=C2C3=C(CCC4=C2N=CC=C4)C=C(C=C3)Cl)CC1'
desloratadine = f.fingerprint 'C1CC2=C(C=CC(=C2)Cl)C(=C3CCNCC3)C4=C1C=CC=N4'

puts "Loratadine is a subset of desloratadine: #{loratadine.subset? desloratadine}" # => false
puts "Desloratadine is a subset of loratadine: #{desloratadine.subset? loratadine}" # => true
puts "Tanimoto similarity of desloratadine and loratadine: #{loratadine.tanimoto desloratadine}" # => 0.895683467388153

Variations

CDK's Fingerprinter class returns an instance of the Java class BitSet. This BitSet can be further manipulated in Ruby. For example, to find the size (the total number of bits) of the BitSet, we could use:

loratadine.size # => 1024

Similarly, to find the number of bits set to true, we would use:

loratadine.cardinality # => 278

To print out a list of all bits set to true, we could use the toString method:

loratadine.toString # => "{2, 8, 11, 16, 18, 22, 32, 37, 38, 41, 42, 46, 47, 51, 57, 64, 65, 66, 69 ... }"

Conclusions

Fingerprints enable many useful and fast comparisons between molecules. The form of fingerprint we've used here is but one of possibilities offered by CDK. The next article in this series will discuss fingerprints in Open Babel using both Ruby and Python.

Build a Rails Cheminformatics Application in Thirty Minutes

Rich Apodaca — Tue, 21 Nov 2006 15:06:00 -0500

A recent article highlighted the Web as a new cheminformatics platform. Advocacy is one thing, but a working, open, demo built with modern technologies is far more compelling. In the following tutorial we'll build a first-generation cheminformatics Web application using the Ruby on Rails framework and 100% Open Source components. We'll just cover the essentials here - look for future articles to discuss the underlying technology in more detail.

The Problem

Simplified Molecular Input Line Entry System (SMILES) is one of the most compact and easy-to-learn molecular representation systems ever developed. Part of a larger family of molecular languages called line notations, SMILES strings are always written as a single line of ASCII text. This makes them perfect in situations calling for data entry; witness their use in a wide range of new free online chemistry databases. This system typically works by a chemist drawing a structure in a graphical editor, copying a SMILES string from the editor, and pasting this string into a search window in the database application.

SMILES is a great language for computers, but not for chemists, who are trained to communicate through 2-D structure diagrams. Although SMILES strings can be decoded manually, this is a tedious and error-prone process, especially for SMILES encoding high degrees of branching and ring content. It's preferable for the computer to do this hard work for us, providing a perfectly laid-out 2-D structure diagram for use in debugging or inclusion in documents.

Depict is a Web application originally developed by Daylight for the conversion of SMILES strings into 2-D structure diagrams. Type a SMILES string into the form, press enter, and get a raster image of the encoded molecule. Daylight's Depict does a good enough job, but you can't change the interface or output. You also can't take the software apart to see how it works. Wouldn't it be great if you could?

About This Tutorial Series

This tutorial is the first in a series describing how to build a Depict server using 100% Open Source components. The application will accept a SMILES string in a Webpage text field, and then produce a 2-D structure diagram. It won't be designed for ease of use, appearance, or configurability - these improvements will be described in subsequent articles. When this application is finished, I'll deploy it on a Web server. At every step in this process, I'll provide enough detail for anyone to do the same.

It won't be necessary to finish every step yourself before you can work with the finished product. Near the beginning of each installment will be be a "Download and Prerequisites" section containing a link to the complete source code. Simply download this code and run it to see what it does.

Download and Prerequisites

For this tutorial, you'll need Ruby CDK (RCDK). A recent article described the small amount of system configuration required for RCDK on Linux. Another article showed how to install RCDK on Windows.

In addition, you'll need to install Ruby on Rails - something that can be done through RubyGems.

The complete Depict application can be downloaded from this link.

A Note on Ruby Java Bridge and AMD64 Linux Platforms

Our Depict application will use Ruby Java Bridge (RJB) as a Ruby interface to Java bytecode. Recently, a problem with RJB on AMD64-Linux was uncovered. This problem prevents third-party jarfiles from being loaded after Rails has been loaded.

In practice, this means that the command to start the Rails server (Step 2) needs to be prefixed with an assignment of LD_PRELOAD. You also need to make LD_LIBRARY_PATH point to your native Java libraries. On my platform, which is AMD64-Linux running Sun's JVM, the commands are:

$ export LD_LIBRARY_PATH=/usr/java/jdk1.5.0_09/jre/lib/amd64:/usr/java/jdk1.5.0_09/jre/lib/amd64/server
$ LD_PRELOAD=/usr/java/jdk1.5.0_09/jre/lib/amd64/libzip.so ruby script/server

If you get an "Internal Error" due to an "unknown exception" while running Depict, chances are good that you've hit the same problem. Starting the Rails server as above should resolve it.

Step 1: Create the Application

Getting started with Rails is as simple as issuing the rails command with the name of your application as an argument:

$ rails depict

Executing this command creates a complete Rails application template under the depict subdirectory in your working directory. You build your application by editing the files and directories that were generated.

Step 2: Start the Server

You can start the Depict application by running the included server script:

$ cd depict
$ ruby script/server
=> Booting WEBrick...
=> Rails application started on http://0.0.0.0:3000
=> Ctrl-C to shutdown server; call with --help for options
[2006-11-18 10:17:08] INFO  WEBrick 1.3.1
[2006-11-18 10:17:08] INFO  ruby 1.8.5 (2006-08-25) [x86_64-linux-gnu]
[2006-11-18 10:17:08] INFO  WEBrick::HTTPServer#start: pid=4036 port=3000

Let's see what Depict looks like so far. Point your browser to http://localhost:3000. You should see the following page:

Congratulations! You're now running Ruby on Rails.

Step 3: Create the SmilesController

Rails adapts the Model-View-Controller application paradigm to the Web. It also automates many of the steps in building models, views, and controllers. Let's create a controller to handle the manipulation of SMILES strings:

$ ruby script/generate controller Smiles
      exists  app/controllers/
      exists  app/helpers/
      create  app/views/smiles
      exists  test/functional/
      create  app/controllers/smiles_controller.rb
      create  test/functional/smiles_controller_test.rb
      create  app/helpers/smiles_helper.rb

Currently, SmilesController is just a skeleton:

class SmilesController < ApplicationController
end

Let's give SmilesController the ability to accept a SMILES string as input by adding an input method.

class SmilesController < ApplicationController
  def input

  end
end

Step 4: Create a Form

At this stage, pointing your browser to http://localhost:3000/smiles/input gives a screen containing an error message:

Rails is looking for view that doesn't exist, so let's create one. To your depict/app/views/smiles directory, add the following file, called input.rhtml:

<html>
  <head>
    <title>Enter a SMILES String</title>
  </head>
  <body>
    <%= form_tag :action=>'depict' %>
      Enter a SMILES String: <br />
      <%= text_field('smiles', 'value') %><br />
    <%= end_form_tag %>
  </body>
</html>

This HTML view is an example of Ruby's templating mechanism, eRuby, which was discussed earlier in the context of converting SD files to HTML. In the template above, we've configured our form to invoke an action called depict when submitted. This action does not yet exist, but will be created in Step 5 below.

Now, pointing your browser to http://localhost:3000/smiles/input should give an input field:

Let's try it. Submitting the SMILES string for benzene gives the following error screen:

We haven't defined the depict action yet, a fact that Rails is communicating with this error message.

Have you noticed how we haven't had to restart the Rails Web server as we've made changes? This is but one of the many conveniences that makes Rails such a productive platform.

Step 5: Add a Depict Action

We need a way to pass a SMILES string from the Web page text field in which it's entered to our application and back to another view. To do this we'll add a depict method to depict/app/controllers/smiles_controller.rb:

def depict
  @smiles = @params[:smiles][:value]
end

Of course, our application still won't run properly because we haven't created a view for the new depict method to use. Let's do this by adding the following file, named depict.rb to the depict/app/views/smiles directory:

<html>
  <head>
    <title>Depict SMILES: <%= @smiles %></title>
  </head>
  <body>
    <h1>SMILES: <%= @smiles %></h1>
  </body>
</html>

Notice how the instance variable @smiles is available for use within the template.

Let's have a look at Depict so far. Pointing your browser to http://localhost:3000/smiles/input, entering the SMILES string for benzene, and pressing return produces the page show below:

So far, so good. We've been able to read user input from an HTML form and reprocess it into some simple HTML output. Now, lets render a 2-D molecular image to go with it.

Step 6: Generate the 2-D Image

We'll use a method called image_for, which we'll define shortly. The file depict/app/views/smiles/depict should look like this:

<html>
  <head>
    <title>Depict SMILES: <%= @smiles %></title>
  </head>
  <body>
    <h1>SMILES:<%= @smiles %></h1>
    <img src="<%= url_for :action => "image_for", :smiles => @smiles %>"></img>
  </body>
</html>

The added img tag is a placeholder for now. It loads an image dynamically generated from the image_for method, which we'll shortly add to SmilesController. We pass the SMILES string as a parameter.

The image_for method does all of the real work in the Depict application. It accepts a SMILES string as a parameter, and produces a laid-out 2-D color molecular image as output. The method uses a variety of functionality contained in the Java API itself, and in Ruby CDK.

In addition to an image_for method, we'll need to add some accessory code to make it work. Edit depict/app/controllers/smiles_controller.rb so that it looks like this:

# Load the RCDK library
require_gem 'rcdk'
require 'rcdk/util'

# New jrequire calls.
jrequire 'java.io.ByteArrayOutputStream'
jrequire 'net.sf.structure.cdk.util.ImageKit'
jrequire 'javax.imageio.ImageIO'

class SmilesController < ApplicationController

  # Already defined.
  def input

  end

  # Already defined.
  def depict
    @smiles = @params[:smiles][:value]
  end

  # New method.
  def image_for
    smiles = @params[:smiles]
    mol = RCDK::Util::Lang.read_smiles smiles
    mol = RCDK::Util::XY::coordinate_molecule mol
    out=Java::Io::ByteArrayOutputStream.new
    image=Net::Sf::Structure::Cdk::Util::ImageKit.createRenderedImage(mol, 300, 300)

    Javax::Imageio::ImageIO.write(image, "png", out)

    send_data(out.toByteArray, :type => "image/png", :disposition => "inline", :filename => "molecule.png")
  end
end

Let's test the application with a real-world example. The achiral SMILES string for Carmine is:

CC1=C2C(=CC(=C1C(=O)O)O)C(=O)C3=C(C2=O)C(=C(C(=C3O)O)C4C(C(C(C(O4)CO)O)O)O)O

Pointing your browser to http://localhost:3000/smiles/input and entering the above SMILES string produces a color 2-D image of the structure of the red food coloring:

Conclusions

Ruby on Rails is a fun and agile framework for rapid Web development. Although Depict isn't much to look at yet, it demonstrates many key Rails concepts. Several techniques could be used improve the application's look and usability. For example, we could use AJAX to depict SMILES strings as they are being typed - without the need to hit return. We could also provide options for changing image format, size, and color scheme. Future articles will describe these and other improvements.

Diversity-Oriented Chemical Informatics

Rich Apodaca — Wed, 15 Nov 2006 15:03:00 -0500

How would you enumerate all of the molecules represented by a molecular formula? This question was recently posed to members of the Blue Obelisk mailing list. Formula-based exhaustive structure enumeration may seem on the surface to be just another esoteric problem. Nevertheless, playing with open, interactive software that can perform such enumerations can be a great source of new ideas for applications and unit tests.

The Chemistry Development Kit offers a fully-functional exhaustive structure enumerator through its GENMDeterministicGenerator class. This article will use GENMDeterministicGenerator through the Ruby CDK interface to generate color 2-D images for all molecules of a given molecular formula.

A Solution

The software described in this article will generate a collection of 2-D molecular PNG images based on a user-supplied molecular formula. When viewed in a file browser such as Windows Explorer or Konqueror, the output is visible as a matrix of images. The filename of each image is given by the SMILES string of the corresponding molecule. All molecules are enumerated, whether they look "reasonable" or not. As an example, consider a section of the output for 'C4H8ClNO', which looks like this on my system:

Enumerator: A Small Ruby Library

We'll create a small Ruby class to do most of the work. Save the following in a file called enum.rb:

require 'rubygems'
require_gem 'rcdk'
require 'rcdk/util'

jrequire 'org.openscience.cdk.structgen.deterministic.GENMDeterministicGenerator'
jrequire 'net.sf.structure.cdk.util.ImageKit'

class Enumerator

  def initialize(formula)
    @generator = Org::Openscience::Cdk::Structgen::Deterministic::GENMDeterministicGenerator.new(formula, '')
    @width = 150
    @height = 150
  end

  def set_size(width, height)
    @width = width
    @height = height
  end

  def write_images
    mols = @generator.getStructures
    iterator = mols.iterator

    while (iterator.hasNext)
      mol = RCDK::Util::XY.coordinate_molecule(iterator.next)
      smiles = RCDK::Util::Lang.get_smiles(mol)

      Net::Sf::Structure::Cdk::Util::ImageKit.writePNG(mol, @width, @height, "#{smiles}.png")
    end
  end
end

As you can see, this class is nothing more than a thin wrapper around a large amount of CDK functionality. Most of the action happens in the write_images method, where three things take place:

We retrieve a list of molecules from the GENMDeterministicGenerator instance that satisfy the molecular formula passed to Enumerator's constructor.
These molecules are iterated.
For each molecule, an image is written with the filename given by its SMILES string.

Testing the Library

To test the library, the following code can either be entered interactively via Interactive Ruby (irb) or saved to a file and run with the Ruby interpreter (ruby):

require 'enum'

e=Enumerator.new 'C4H8ClNO'

e.write_images

Running this code will produce a collection of PNG images in your working directory. By changing the argument passed to the Enumerator constructor, you can change the makeup of the image set.

Prerequisites

For this tutorial, you'll need Ruby CDK (RCDK). A recent article described the small amount of system configuration required for RCDK on Linux. Another article showed how to install RCDK on Windows.

Unexpected Behavior

After testing the Enumerator library, you may notice a new file in your working directory called structuredata.txt. This file is written automatically by GENMDeterministicGenerator on instantiation, providing information on each structure that is generated. The CDK API does not mention the creation of this file, and it would be preferable for this file to only created on request. I'll be submitting a feature request to this effect shortly.

Food for Thought

If you plan to explore larger areas of chemical space with the Enumerator library, be prepared to wait. The generation of molecules, determination of 2-D coordinates, and rendering can take some time. Of course, the number of molecules increases dramatically with the number of atoms in the molecular formula - a concrete demonstration of what makes organic chemistry the fascinating discipline that it is.

An interesting variation on the ideas presented here would be to filter out molecules based on some criteria. One approach would be to remove molecules containing reactive functionality such as nitrogen substituted with chorine. A SMARTS pattern search could easily form the basis for this filter. In applying this and similar filters, larger areas of interesting chemical space could be sampled in a reasonable amount of time.

Conclusions

CDK's GENMDeterministicGenerator class, when combined with 2-D structure layout and 2-D rendering, provides the foundation of an intriguing tool for exploring chemical diversity. Further combining this capability with that offered by other freely-available tools offers some thought-provoking possibilities.

Agile Chemical Informatics Development with CDK and Ruby: RCDK-0.3.0

Rich Apodaca — Mon, 30 Oct 2006 14:03:00 -0500

Ruby Chemistry Development Kit (RCDK) version 0.3.0 is now available from RubyForge. RCDK enables the complete CDK API to be accessed from Ruby. This release adds support for IUPAC nomenclature translation and tighter Java integration.

Dependencies

RCDK requires Ruby, the Ruby developer libraries, a working build toolchain, and Ruby Java Bridge (RJB). This latter dependency can be satisfied during the RCDK installation process if the RubyGems method is used (see 'Installation').

Installation

RCDK can be conveniently installed using the RubyGems packaging mechanism:

# gem install rcdk

Alternatively, the source package and RubyGem can be downloaded here.

Tighter Java Integration

RCDK-0.3.0 introduces a previously-described Java package to Ruby module mapping mechanism. For example, if you'd like to create a Java ArrayList, it can be done through the new jrequire command:


require 'rubygems'
require_gem 'rcdk'
jrequire 'java.util.ArrayList'

list = Java::Util::ArrayList.new

list.size # => 0

IUPAC Nomenclature Translation

RCDK's most important new chemical informatics feature is made possible by Peter Corbett's excellent IUPAC nomenclature translation library OPSIN. It can either be used directly with jrequire, or indirectly through RCDK's convenience library RCDK::Util:

require 'rubygems'
require_gem 'rcdk'
require 'rcdk/util'

mol = RCDK::Util::Lang.read_iupac 'quinoline'
mol.getAtomCount # => 10

There are two things to notice here. First, no jrequire statement is needed when using the RCDK::Util library. Second, there is a multisecond delay after read_iupac is invoked. OPSIN itself introduces this delay during the NameToStructure constructor call, and RCDK inherits this behavior. However, after the first invocation of read_iupac, subsequent calls to this method are very fast.

Let's decorate the quinoline nucleus with some substituents and render a 2-D image of the result. Execute the following code, either through the Ruby interpreter (ruby) or through Interactive Ruby (irb):

require 'rubygems'
require_gem 'rcdk'
require 'rcdk/util'

RCDK::Util::Image.iupac_to_png('3-chloro-4-(2-aminopropyl)-6-mercapto-8-(2-hydroxyphenyl)-quinoline-2-carboxylic acid', 'test.png', 300, 300)

Running this code produces the following image in your working directory:

Be Agile

RCDK marries the agility of the Ruby language with the functionality of three Open Source chemical informatics libraries: CDK; OPSIN; and Structure-CDK. Future articles will discuss some simple applications of this powerful combination.