Integration of third party calculations into Marvin and JChem

Contents

Introduction

Third-party calculations can be integrated into Marvin and JChem by using ChemAxon's Calculator Plugin system. As third-party calculation we refer to any calculation which is not provided by ChemAxon with Marvin Beans or JChem package. The guides below describe how third-party calculations can be integrated with ChemAxon applications and toolkits, including GUI, applet, command line and API usages. All guides contain code examples and links to the related topics in developers guide.
MarvinSketch GUI offers a new, user-friendly version of integrating third-party calculation as service via the Services module.

Example plugin

In the first place, it is required to extend the chemaxon.marvin.plugin.CalculatorPlugin class, the descendant class should call the third-party calculation. The steps of the implementation are described in the Calculator Plugins Developers Guide.

In the examples below BemisMurckoPlugin will be used as example third-party plugin implementation. The BemisMurckoPlugin can calculate the Bemis-Murcko framework of a molecule, return it as Molecule object, and also can calculate the number of atoms and bonds in the generated Bemis-Murcko framework, returning them as integers.

A custom plugin implementation - of course - can call any Java library, native application (through JNI), or libraries written in other languages, such as C or C++ (through JNI). In the current example only MarvinBeans Java library is called from the code of the BemisMurckoPlugin.

General notes

In this document we will refer to the Marvin installation directory as MarvinBeans directory.
If Marvin's default installation was followed, Marvin installation directory is located in:

  • Windows: C:\Program Files\ChemAxon\MarvinBeans
  • Linux: $HOME/ChemAxon/MarvinBeans (e.g. /home/myusername/ChemAxon/MarvinBeans)
  • OS X: /Applications/ChemAxon/MarvinBeans

MarvinSketch and MarvinView

In MarvinSketch and MarvinView Calculator Plugins can be accessed from the Tools menu.

Applications

To integrate a calculation into MarvinSketch/MarvinView application the following steps should be made:

  1. Implement a CalculatorPlugin class (more). Implement also a CalculatorPluginDisplay class, if required (more).

    We only implemented BemisMurckoPlugin.java. In the current example BemisMurckoPluginDisplay class is not required.

  2. Compile the classes.

    Use the Marvin Beans package for compilation. 

    javac -classpath MarvinBeans/lib/MarvinBeans.jar BemisMurckoPlugin.java
  3. Create the plugin options panel description in XML file ().

    Copy the created BemisMurckoPluginParameters.xml to a directory named xjars.

  4. Pack the created class and XML files into a JAR.

    In the next command BemisMurckoPlugin.txt refers to JAR manifest file, which also has to be created. The BemisMurckoPlugin.class file is the result of the compilation of BemisMurckoPlugin.java into class file. 

    jar cmf BemisMurckoPlugin.txt BemisMurckoPlugin.jar BemisMurckoPlugin.class xjars/BemisMurckoPluginParameters.xml
  5. Copy the JAR file into the plugins directory.

    The created JAR file (BemisMurckoPlugin.jar) has to be copied to the MarvinBeans/plugins directory.

  6. Create/edit the Tools menu configuration file (more).

    Create your own instance of plugins.properties in the MarvinBeans/plugins directory. This properties file describes the structure of the Tools menu in MarvinSketch/MarvinView. If this file exists, it overwrites the default Tools menu. There is a template for plugins.properties (plugins.properties.sample.txt) in this directory. Just make a copy of it, and edit it.

    To add a new menuitem for the new plugin add the following line to the file: 

    plugin_999=$BemisMurckoPlugin$BemisMurckoPlugin.jar$Bemis Murcko Framework$B$$

    Note: The plugin class has to be referenced with full name (including the name of the package that contains the class).

Run MarvinSketch/MarvinView. You can run the example plugin by selecting Bemis Murcko Framework from the Tools menu.

Applets

Integration into MarvinSketch and MarvinView applets is quite similar to the application integration, only the compilation process and the JAR file creation is different. In this section marvin will refer to the root directory of Marvin Applets.

  1. Implement a CalculatorPlugin class (more). Implement also a CalculatorPluginDisplay class, if required (more).

    We only implemented BemisMurckoPlugin.java. In the current example BemisMurckoPluginDisplay class is not required.

  2. Compile the classes.

    Use JAR files from Marvin Applets package for compilation of the new plugin. Since Marvin Applets classes are compiled with 1.5 compatible compiler, additional code has to compile with 1.5 compatible JDK. To provide compatibility, set the source and the target attributes to 1.5. 

    javac -source 1.5 -target 1.5 -classpath "marvin/jmarvin.jar:marvin/sjars/Plugin.jar:marvin/sjars/PluginGUI.jar" BemisMurckoPlugin.java
  3. Create the plugin options panel description in XML file ().

    Copy the created BemisMurckoPluginParameters.xml to a directory named xjars.

  4. Pack the created class and XML files into a JAR.

    Marvin applets accept custom plugins from certain location: marvin/plugin/extensions.jar. Therefore, wrap resources for your plugin into extensions.jar. In this example, BemisMurckoPlugin.txt is the manifest file for the JAR file, BemisMurckoPlugin.class file is the result of the compilation of BemisMurckoPlugin.java into class file.

    jar cmf BemisMurckoPlugin.txt extensions.jar BemisMurckoPlugin.class xjars/BemisMurckoPluginParameters.xml

    The JAR files that Marvin applets load have to be signed.

    jarsigner -keystore "<keystorepath>" -storepass <password> extensions.jar <alias>

    In the above statement, the <keystorepath> is the location of the keystore file where your signing key is stored. The <password> gives the password for the keystore. The <alias> is the alias of the certification key in the keystore.

  5. Copy the JAR file into the plugins directory.

    The created JAR file (extensions.jar - note: the downloadable jar is not signed) has to be copied to the marvin/plugins directory.

  6. Create/edit the Tools menu configuration file (more).

    Create your own instance of plugins.properties in the marvin/plugins directory. This properties file describes the structure of the Tools menu in MarvinSketch/MarvinView. If this file exists, it overwrites the default Tools menu. There is a template for plugins.properties (plugins.properties.sample.txt) in this directory. Just make a copy of it, and edit it.

    To add a new menuitem for the new plugin add the following line to the file: 

    plugin_999=$BemisMurckoPlugin$BemisMurckoPlugin.jar$Bemis Murcko Framework$B$$
Now, you are ready. In MarvinSketch/MarvinView applet the new plugin will display in the Tools menu.

cxcalc

cxcalc is ChemAxon's application for performing the plugin calculations in batch mode. Integration with cxcalc goes as follows:

  1. Implement a CalculatorPlugin class (more). Implement also a CalculatorPluginOutput class, if required (more).

    We only implemented BemisMurckoPlugin.java. In the current example BemisMurckoPluginOutput class is not required.

  2. Compile the classes.

    Use the Marvin Beans package for compilation. 

    javac -classpath MarvinBeans/lib/MarvinBeans.jar BemisMurckoPlugin.java
  3. Pack the created class file(s) into a JAR.

    In the next command BemisMurckoPlugin.txt refers to JAR manifest file, which also has to be created. 

    jar cmf BemisMurckoPlugin.txt BemisMurckoPlugin.jar BemisMurckoPlugin.class
  4. Copy the JAR file into the plugins directory.

    The created JAR file (BemisMurckoPlugin.jar) has to be copied to the MarvinBeans/plugins directory.

  5. Create/edit the calc.properties configuration file (more).

    Create your own instance of calc.properties in the MarvinBeans/plugins directory. This properties file should contain the configurations (parameters, help text, etc.) of the third-party calculations. If this file exists, then the calculations defined in it are added to default calculations. There is a template for calc.properties (calc.properties.sample.txt) in this directory; just make a copy of it, and edit it.

The new calculations can be run with the following commands:
  • Generate the Bemis-Murcko framework 
    cxcalc bemismurcko testmols.sdf
  • Count atoms of the Bemis-Murcko framework 
    cxcalc bemismurckoatomcount testmols.sdf
  • Count bonds of the Bemis-Murcko framework 
    cxcalc bemismurckobondcount testmols.sdf

Chemical Terms

Chemical Terms is a language for adding advanced chemical intelligence to cheminformatics applications. It is an additional interface to access plugin calculations, and is integrated into a number of ChemAxon's applications (e.g. Instant JChem, JChem Base, JChem Cartridge, Reactor). Chemical Terms can also be used with Marvin applets through JavaScript.

In case of Chemical Terms, integration means adding a new Chemical Terms function. After the function is added, it can be used from all applications that make use of Chemical Terms.

Applications

Integration steps:

  1. Implement a CalculatorPlugin class (more).

    We implemented BemisMurckoPlugin.java.

  2. Compile the classes.

    Use the Marvin Beans package for compilation. 

    javac -classpath MarvinBeans/lib/MarvinBeans.jar BemisMurckoPlugin.java
  3. Pack the created class files into a JAR.

    In the next command BemisMurckoPlugin.txt refers to JAR manifest file, which also has to be created. The BemisMurckoPlugin.class file is the result of the compilation of BemisMurckoPlugin.java into class file. 

    jar cmf BemisMurckoPlugin.txt BemisMurckoPlugin.jar BemisMurckoPlugin.class
  4. Copy the JAR file into the plugins directory.

    The created JAR file (BemisMurckoPlugin.jar) has to be copied to the MarvinBeans/plugins directory.

  5. Create/edit the evaluator.xml configuration file (more).

    Create your own instance of evaluator.xml file in the MarvinBeans/config directory (see the Evaluator manual for alternative location). This XML file describes the Chemical Terms functions. If this file exists, then the functions defined in it are added to default functions. There is a template for evaluator.xml (evaluator.xml.sample.txt) in this directory; just make a copy of it, and edit it.

Test the new functions with Chemical Terms Evaluator:

  • Generate the Bemis-Murcko framework 
    evaluate -e bemisMurcko() testmols.sdf
  • Count atoms of the Bemis-Murcko framework 
    evaluate -e bemisMurckoAtomCount() testmols.sdf
  • Count bonds of the Bemis-Murcko framework 
    evaluate -e bemisMurckoBondCount() testmols.sdf

Applets

After performing the steps below the Chemical Terms functions will be accessible via JavaScript from MarvinSketch/MarvinView applet. For usage examples see: Marvin, Calculator Plugin and Chemical Terms Demo page. In this section marvin will refer to the root directory of Marvin Applets.

  1. Implement a CalculatorPlugin class (more).

    We implemented BemisMurckoPlugin.java.

  2. Compile the classes.

    Use JAR files from Marvin Applets package for compilation of the new plugin. Since Marvin Applets classes are compiled with 1.5 compatible compiler, additional code has to compile with 1.5 compatible JDK. To provide compatibility, set the source and the target attributes to 1.5. 

    javac -source 1.5 -target 1.5 -classpath "marvin/jmarvin.jar:marvin/sjars/Plugin.jar:marvin/sjars/PluginGUI.jar" BemisMurckoPlugin.java
  3. Pack the created class files into a JAR.

    Marvin applets accept custom plugins from certain location: marvin/plugin/extensions.jar. Therefore, wrap resources for your plugin into extensions.jar. In this example, BemisMurckoPlugin.txt is the manifest file for the JAR file, BemisMurckoPlugin.class file is the result of the compilation of BemisMurckoPlugin.java into class file.

    jar cmf BemisMurckoPlugin.txt extensions.jar BemisMurckoPlugin.class

    The JAR files that Marvin applets load have to be signed.

    jarsigner -keystore "<keystorepath>" -storepass <password> extensions.jar <alias>

    In the above statement, the <keystorepath> is the location of the keystore file where your signing key is stored. The <password> gives the password for the keystore. The <alias> is the alias of the certification key in the keystore.

  4. Copy the JAR file into the plugins directory.

    The created JAR file (extensions.jar - note: the downloadable jar is not signed) has to be copied to the marvin/plugins directory.

  5. Create/edit the evaluator.xml configuration file (more).

    Create your own instance of evaluator.xml file in the marvin/config directory (see the Chemical Terms Language Reference for alternative location). This XML file describes the Chemical Terms functions. If this file exists, then the functions defined in it are added to default functions. There is a template for evaluator.xml (evaluator.xml.sample.txt) in this directory; just make a copy of it, and edit it.

After performing these steps the new calculations can be called from the applet via JavaScript, as show on Marvin, Calculator Plugin and Chemical Terms Demo page.

API

The implemented BemisMurckoPlugin.java provides also java Application Programming Interface, so it can be used from other java code. For details see Calculator Plugins Code Examples.

Do you have a question? Would you like to learn more? Please browse among the related topics on our support forum or search the website. If you want to suggest modifications or improvements to our documentation email our support directly!