Image rendering

CPSign v 0.3.16 comes with new functionality for rendering and generating molecule images. We plan to add further rendering options in later releases.

Image Creation

CPSign v 0.3.16 comes with the possibility of generating images for predicted molecules. Image creation differs slightly depending on which mode you are running in. There is two types of coloring that exists:

Color complete molecule gradient The coloring is based on the full gradient, meaning that all signatures respective contribution are taken into account and all atoms will be colored. (Not possible for TCP)

Color Significant Signature only The coloring is based on the Significant Signature only. Atoms that are part of the significant signature will be colored after;

  • Classification The class that has the highest p-value (i.e. if a molecule is depicted with a color-scheme of blue:red, and predicted to have a higher p-value for class 0, atoms part of the significant signature will be colored blue, if the molecule would generate a higher p-value for class 1 the atoms would be colored red).
  • Regression The atoms part of the Significant Signature will be always be colored after the highest value in the Color Gradient (see Color Schemes).

Image rendering on Command Line

Flag: -im, --images
Description: Activates the image creation

Flag: -if, --imagefile [path]
Description: Set the output directory and file name for the images. Default is to create a subfolder 'imgs' to where the command is runned from and to use 'Images' as default name. Naming is otherwise used in this convention: '[name]-[count].png' or '[name]-[$cdk:title].png' where 'count' is the running count of molecules predicted from the -smiles and -p/--predictfile molecules (note that invalid molecules will be skipped and the running count will not include these).

Flag: --color-sign-only
Description: Only color the atoms part of the Significant Signature of the molecule, see description above.

Flag: -cs, --color-scheme
Description: See the Color Schemes section.

Flag: --color-legend
Description: Add a color legend at the bottom of the rendered image

Flag: --custom-scheme
Description: Use a custom coloring scheme instead of the pre-defined once that can be used with the -cs/--color-scheme flag. This is a json-string that should be rendered using a plugin for Bioclipse. There you can customize your image rendering after your liking. If you would like to try this out, please contact us and we'll give you instructions.

Flag: --atom-numers
Description: Add atom numbers to the depiction

Flag: --atom-number-color
Description: Choose a custom color for the atom numbering (used when supplying the --atom-numbers flag). Default is blue color.

Flag: --image-height
Description: Set the image height in number of pixels

Flag: --image-width
Description: Set the image width in number of pixels

Color Schemes

Color Scheme is decided by the -cs, --color-scheme flag. The value can be either of the displayed gradients shown below. The text-string is case in-sensitive.

BLUE:RED (Default)

../../_images/BlueRedGradient.png

RED:BLUE

../../_images/RedBlueGradient.png

RED:BLUE:RED

../../_images/RedBlueRedGradient.png

CYAN:MAGENTA

../../_images/CyanMagentaGradient.png

'Rainbow' gradient

../../_images/RainbowGradient.png

Example Images

Color Significant Signature only, using:

java -jar cpsign-[version].jar predict --images \
   --color-sign-only \
   -cs 'BLUE:RED' \
   ...
../../_images/SignificantSignatureOnly.png

Color Significant Signature only with label (classification), using:

java -jar cpsign-[version].jar predict --images \
   --color-sign-only \
   -cs 'BLUE:RED' \
   --color-legend \
   ...
../../_images/SignificantSignatureOnlyWithLabel.png

Color complete molecule gradient with rainbow color scheme, using:

java -jar cpsign-[version].jar predict --images \
   -cs 'rainbow' \
   --color-legend \
   ..
../../_images/FullGradientWithRainbow.png

Color complete molecule gradient with color legend and atom numbers using:

java -jar cpsign-[version].jar predict --images \
   -cs default \
   --color-legend \
   --atom-numbers \
   --atom-number-color 'BLACK' \
   ..
../../_images/FullGradientWithLegendAtomNr.png

Image rendering in API

Image rendering in the API can be done in two basic ways;

  1. MoleculeDepictor: Only renders java BufferedImage of the molecule, including highlighting.
  2. MolImageDepictor: Adds possibility to add a image legend, output in java BufferedImage, Base64 Strings or saved PNG files.

Regardless if you choose the MolImageWriter or the MoleculeDepictor, you will have to take care of how to color the atoms. When you calculate the gradient of a molecule with predictSignificantSignature you will get a both a Significant Signature map (that only points IAtom s to an integer number 0 or 1 depending on which class had the highest p-value) and a map for the full molecule gradient (IAtom to a floating point value). If you wish to use the full molecule gradient, you will have to make sure that the floating point value is normalized (otherwise the depiction will likely not give you much information). If the model was trained through the CLI this will have been done for you, otherwise you will have to either fix this somehow yourself or by calling the computePecentiles method:

// Load data
signACP.fromChemFile(chemFile,
            "Ames test categorisation",
            Arrays.asList("nonmutagen", "mutagen"));

// Train
signACP.trainACP(.2, nrModels);

// Compute percentiles
signACP.computePercentiles(chemFile);

In the CLI implementation, CPSign uses the training data set to compute the lower and upper ranges, but as a API user you are free to run any other dataset to compute percentiles (e.g. use the test dataset). The percentiles will in either way be used for normalising the output in a model and dataset-dependet way. Your free to use any other normalisation if you would like (e.g. a per molecule normalisation).

MolImageDepictor

The MolImageDepictor wraps the low level depiction class MoleculeDepictor and adds some convenience by creating a image legend displaying either the color gradient (if depicting the molecule gradient) or the colors of the classes and class labels (if only depicting the most significant signature and the selected class). MolImageDepictor also have more available output formats:

The usage is fairly straight forward:

// Use either of the two factory methods
MolImageDepictor depictor = MolImageDepictor.getGradientDepictor(GradientFactory.getBlueRedGradient());
MolImageDepictor signSignDepictor = MolImageDepictor.getSignSignDepictor(GradientFactory.getDefaultBloomGradient());

// Use the setters and getters to set image size, legend visibility, legend size, ...
depictor.setDepictLegend(true);

// Use either of the three depiction options
depictor.depictMolecule2File(testMol, ss.getAtomValues(),new File("full-gradient-blue-red-blue.png"));
String base64String = depictor.depictMolecule2Base64String(mol, ss.getAtomValues());
BufferedImage bi = depictor.depictMolecule(mol, ss.getAtomValues());

// For the significant signature depiction, use the getAtomValuesSS() method instead
signSignDepictor.setClassificationLabels(Arrays.asList("NEG", "POS"));
signSignDepictor.setDepictLegend(true);
BufferedImage biSS = signSignDepictor.depictMolecule(mol, ss.getAtomValuesSS());

MolImageWriter

The MolImageWriter acts as a wrapper around the MolImageDepictor class to simplify saving png files in a directory, without having to explicitly give each file. This class takes a MolImageDepictor, that controls all settings for the depiction, and a File stating the directory and 'base name' of the to be created png files. The File given as directory can be null, leading to all images being created in the current directory. Naming of the files follows the usage of the CLI and will be either '[base name]-[count].png' or '[base name]-[$cdk:title].png' if the cdk:title property has been set on the IAtomContainer and 'base name' being the base name of the image. E.g. given a new File("/Users/user/imgs/mols.png") the 'base name' will be 'mols' and all files will be saved in "/Users/user/imgs/mols-[$cdk:title].png" or "/Users/user/imgs/mols-[count].png". The class will also take care of creating all parent directories needed if they do not already exist. Typical workflow is simply:

// initiate MolImageDepictor and configure it in desired way
MolImageDepictor depictor = ...

MolImageWriter writer = new MolImageWriter(depictor, new File("/tmp/imgs/full-gradient.png"));

// Predict the Significant Signature
SignificantSignature ss = signACP.predictSignificantSignature(mol);

// Color full gradient (given that depictor is derived from getGradientDepictor factory method)
writer.depictMolecule(mol, ss.getAtomValues());
// or Color Significant Signature Only (given that depictor is derived from getSignSignDepictor factory method)
writer.depictMolecule(mol, ss.getAtomValuesSS());

Custom images

If you wish to have more flexibility in the depiction, for instance creating a larger report with multiple molecule depictions, render your image on a specific background (e.g. with a watermark) or include a color coding bar, you can use the MoleculeDepictor class (or from 0.5.6 use the MolImageDepictor and get the depiction as a BufferedImage). The MoleculeDepictor renders images and returns them as a BufferedImage, giving you all the flexibility that you could desire. The general usage:

// Get an instance of the MoleculeDepictor with the IColorGradient you wish to use
MoleculeDepictor mp = MoleculeDepictor.getBloomDepictor(GradientFactory.getRainbowGradient());

// Set the background
BufferedImage pageImage = new BufferedImage(mp.getImageWidth(), mp.getImageHeight(), BufferedImage.TYPE_INT_RGB);
Graphics2D graphics = pageImage.createGraphics();
graphics.setColor(Color.WHITE);
graphics.fillRect(0, 0, width, height);

// Get a BufferedImage of the rendered molecule
BufferedImage img = mp.depict(molecule, coloringMap);

graphics.drawImage(img, 0,0,null);

// Save the image as a file
ImageIO.write(pageImage, "png", new File("/tmp/image.png");

There GradientFactory generates gradients these factory methods:

  • getDefaultBloomGradient
  • getBlueRedGradient
  • getRedBlueGradient
  • getRedBlueRedGradient
  • getCyanMagenta
  • getRainbowGradient
  • getCustomGradient(String)

It's also fully possible to implement the IColorGradient interface if you wish to make your own.

The MoleculeDepictor has two factory methods for getting an instance of the class:

  • getBloomDepictor
  • getBloomDepictor(IColorGradient)

There is a working example of how to generate customized images our BitBucket repository, in the class GeneratePredictionImages.java. That code currently depicts this image:

../../_images/subplots.png