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.
Table of Contents
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).
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).
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.
Description: Add a color legend at the bottom of the rendered image
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.
Description: Add atom numbers to the depiction
Description: Choose a custom color for the atom numbering (used when supplying the --atom-numbers flag). Default is blue color.
Description: Set the image height in number of pixels
Description: Set the image width in number of pixels
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.
Color Significant Signature only, using:
java -jar cpsign-[version].jar predict --images \ --color-sign-only \ -cs 'BLUE:RED' \ ...
Color Significant Signature only with label (classification), using:
java -jar cpsign-[version].jar predict --images \ --color-sign-only \ -cs 'BLUE:RED' \ --color-legend \ ...
Color complete molecule gradient with rainbow color scheme, using:
java -jar cpsign-[version].jar predict --images \ -cs 'rainbow' \ --color-legend \ ..
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' \ ..
Image rendering in the API can be done in two basic ways;
MoleculeDepictor: Only renders java BufferedImage of the molecule, including highlighting.
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
// 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 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:
- Java BufferedImage
- Base64 String
- PNG file
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 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());
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
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");
GradientFactory generates gradients these factory methods:
It's also fully possible to implement the
IColorGradient interface if you wish to make your own.
MoleculeDepictor has two factory methods for getting an instance of the class:
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: