Calculator PluginsJózsef Szegezdi, Nóra Máté

ChemAxon Calculator Plugins

ChemAxon’s plugin handling mechanism provides a

framework for calculating various chemical properties

by dynamically loadable software modules.

Some calculations provided by ChemAxon:• pKa, logP, logD• Huckel Analysis• Hydrogen Bond Donor / Acceptor• Elemental Analyser, Topology Analyser• …

Users can extend this list by custom plugins.

web: http://www.chemaxon.com/marvin/chemaxon/marvin/help/calculator-plugins.html

Calculator Plugin Features

Key features:• Plugin modules are packed in dynamically loadable JARs.• Extendible plugin set.• API support:

plugin class loading and instantiation plugin handling (parameter and input setting, running, getting results) GUI access (parameter and result display panels)

• Built-in access from multiple platforms: Marvin GUI (msketch, mview applications and applets) cxcalc command line tool Chemical Terms:

evaluate command line tool search filtering JChem cartridge reaction processing

Marvin GUI – menu

Plugins are listed in the Tools menu. Plugin configuration is read from the xjars/plugins.properties property file.

Marvin GUI – parameter panels

Parameter panels are usually created from XML configuration. In this way it is possible to set plugin parameters before the plugin JAR is loaded, which can be important in case of applets.

These XMLs are stored under the xjars directory with file names:

<plugin class name>Parameters.xml

Marvin GUI – result display

• molecular results are stored in molecule properties

• atomic results are stored in atom labels

Custom result display (e.g. a chart) can also be provided.

Calculation results are displayed based on the decorated result molecule provided by the plugin:

Command line access: cxcalc

Plugin calculations can be run by the command line tool cxcalc. The plugin configuration is read from xjars/calc.properties.

All calculations are listed in the help text:

Calculation specific help is also available:

pKa (strongest acidic and basic pKa values)and major microspecies (pH=7.4) calculation:

Chemical Terms

Chemical expressions can refer to plugins by calculation IDs specified in the XML configuration. The built-in configuration is described in http://www.jchem.com/doc/user/EvaluatorTables.html

Examples:

basic pKa value on atom 5 (0-based):evaluate –e “bpka(5)” test.mrv

true if partial charge on atom 5 is greater than on atom 0:evaluate –e “charge(5) > charge(0)” test.mrv

bromination - select aromatic carbon with minimal energy:react –r “[c:1][H:2]>>[c:1][Br:3]..s:-energyE(ratom(1))” “Nc1ccccc1”

perform search on targets with mol mass greater than 150:jcsearch –e “mass() > 150” –q query.mrv targets.mrv

accept only search hits with acidic pKa less than 5 on target atom matching query atom with map 1: jcsearch –e “apka(hm(1)) < 5” –q query.mrv targets.mrv

Plugin Handling – API without GUI

1. Create the plugin object:• for built-in plugins in applications the plugin class is available in the application JAR (MarvinBeans.jar, jchem.jar),therefore you can simply use the plugin constructor• for custom plugins or in case of applets the plugin classes should be loaded from the plugin JAR; use CalculatorPlugin.create(String clname, String jar)

2. Set plugin parameters by plugin specific API

3. Set the input molecule byCalculatorPlugin.setMolecule(Molecule)

4. Run the calculation byCalculatorPlugin.run()

5. Get calculation results by plugin specific API

API usage examples are written in the apidoc class headers.Links: http://www.chemaxon.com/marvin/doc/dev/plugins.html#examples

Plugin Handling – GUI access from API

PluginFactory

xjars/plugins.properties java.util.Properties object

CalculatorPluginsubclass instance

parameter panel asParameterPanelHandler

CalculatorPluginDisplayobject or subclass instance

XML

JAR

JAR or default

or

Custom Plugin Application

This custom plugin application shows:

• custom plugin implementation and configuration

• test application with customized GUI access

Custom Plugin Implementation – the plugin class I.

The plugin class extends CalculatorPlugin:

The setParameters() method will be called with parameters set in the graphical parameter panel by the user:

Custom Plugin Implementation – the plugin class II.

The setInputMolecule() method will be called to set the molecule drawn in the sketcher:

The run() method performs the main calculation:

Custom Plugin Implementation – the plugin class III.

The getResultMolecule() method will be called by the default CalculatorPluginDisplay to display the molecule in a viewer,with molecular results in text labels and atomic results in atom labels:• molecular results should be stored in molecule properties set by Molecule.setProperty() • atomic results should be stored in atom labels set by MolAtom.setExtraLabel()

Custom Plugin Implementation – the plugin class IV.

Standardization: most calculations require input molecules beingin standardized form. The default standardization aromatizes the molecule and converts nitro and sulphynil groups:

To customize standardization, overwrite the standardize() method.In our SelectionPlugin we do not need standardization at all, therefore we implement standardize() with an empty body:

Custom Plugin Implementation – the display class I.

The display class is responsible for showing plugin results in a graphical component. The default display is CalculatorPluginDisplay, it calls CalculatorPlugin.getResultMolecule() to show the calculation results in a decorated Molecule.

This result molecule stores the computed chemical features in molecule properties (Molecule.setProperty()) and atom labels (MolAtom.setExtraLabel()).

To customize the display, extend the CalculatorPluginDisplay class:

Custom Plugin Implementation – the display class II.

The graphical component displaying the calculation results is returned in getResultComponent():

You can insert the default decorated molecule viewer intothe custom display by calling CalculatorPluginDisplay.createViewPanel().

You can fetch display parameters set in the graphical parameter panel by implementing setParameters():

Custom Plugin Implementation – the display class III.

Error handling: CalculatorPluginDisplay shows error and warning messages returned by CalculatorPlugin.getErrorMessage() and CalculatorPlugin.getWarningMessage() in case when CalculatorPlugin.run() returns false. To customize error display,implement getErrorComponent():

Parameter panel: PluginFactory can create generic parameterpanels from XML configuration. However, if you need a parameter panel that is not supported by this framework, return your parameter panel in getParameterPanel():

Custom Plugin Implementation – parameter panel

Parameter panel: PluginFactory can create generic parameter panels from XML configuration: xjars/<plugin class name>Parameters.xmlOur parameter panel configuration file is SelectionPluginParameters.xml:

To access our plugin from the Marvin Tools menu, we have toaccomplish the following steps:

1. Create the plugin JAR with manifest SelectionPlugin.txt:

The manifest can also refer to additional JARs in its Class-Path attribute. The manifest file can be omitted if the plugin name is specified in the configuration (e.g. xjars/plugins.properties, xjars/calc.properties) and no other resources are needed to load the plugin.

2. Copy the plugin JAR and the parameter XML into the xjars directory.

Custom Plugin Implementation – administration I.

Custom Plugin Implementation – administration II.

3. Insert a line into xjars/plugins.properties:

SelectionPlugin access is added to your Tools menu in the viewer and the sketcher applets / applications.

Custom Plugin Implementation – custom application I.

The following test application shows a customized way to access our plugin. Two buttons are placed to show the OptionsPane (plugin specific parameter panel with “OK”, “Cancel” and “Display” buttons) and to run the plugin.

Configuration is given to PluginFactory in a java.util.Properties object.

Custom Plugin Implementation – custom application II.

Create PluginFactory, set our class as “Display” button ActionListener and parent

component of OptionsPane, set plugin configuration in factory.

Custom Plugin Implementation – custom application III.

Event handling: • Show OptionsPane if the “Set parameters” button is pressed.• Run plugin if the “Run plugin” button is pressed.• Run plugin if the “Display” button is pressed on the OptionsPane.

Note, that the action command is set to “plugin_<plugin key>”.

Custom Plugin Implementation – custom application IV.

Show the OptionsPane:

1. Get the plugin index from the factory.

2. Get and show the plugin OptionsPane.

Custom Plugin Implementation – custom application V.

Run the plugin:

1. Get the plugin index.

2. Get the plugin.

3. Get the display.

4. Get plugin parameters

from the OptionsPane.

5. Handle license key.

6. Set parameters in

plugin and display.

Custom Plugin Implementation – custom application VI.

7. Check input molecule.

8. Set molecule.

9. Run the plugin.

10. Store results in display.

11. Get result component.

12. Show result component.

Custom Plugin Implementation – references

The SelectionPlugin example code will be available in the next Marvin release: Marvin 4.0.

You will find it under the directoryexamples/plugin

See its index.html for installation instructions.

References

Built-in plugin descriptions:http://www.chemaxon.com/marvin/chemaxon/marvin/help/calculator-plugins.html

Developer’s guide with API usage examples:http://www.chemaxon.com/marvin/doc/dev/plugins.html

Plugin framework API (chemaxon.marvin.plugin) (subject to major changes in Marvin 4.0):http://www.chemaxon.com/marvin/doc/api/chemaxon/marvin/plugin/package-summary.html

Built-in plugins’ API (chemaxon.marvin.calculations):http://www.chemaxon.com/marvin/doc/api/chemaxon/marvin/calculations/package-summary.html

Máramaros köz 3/a Budapest, 1037Hungary

info@chemaxon.com

www.chemaxon.com

Thank you for your attention