Chemical Calculations with Calculator Plugins

Contents

Introduction

Calculator is a command line program in Marvin Beans and JChem that performs chemical calculations using calculator plugins.

There are some built-in calculations such as charge, pKa, logP and logD computations that can be evaluated in demo mode or purchased from ChemAxon. See the Calculator Plugins guide for the details of these calculations.

Other calculations can be added by writing custom plugins as described in the Plugin Developer's Guide.

Installation

Usage

Calculator performs plugin calculations in a uniform way: it processes general parameters referring to input, output, and SDF file tag names for storing calculation result as well as plugin specific parameters that are different for each plugin. The available plugins are defined in the configuration file.
cxcalc [general options] [input files] <plugin> [plugin options] [input files]
cxcalc [general options] [input files] <plugin1> [plugin1 options] [input files] <plugin2> [plugin2 options] [input files] ...

General Options

  cxcalc -h, --help             this help message
  cxcalc <plugin> -h, --help    plugin specific help message
  -o, --output <filepath>       output file path (default: stdout)
  -t, --tag                     name of the SDFile tag to store the
                                calculation results     
                                default tag name: see plugin help  
  -i, --id                      SDFile tag that stores the molecule ID
                                in the input SDF (default: molecule index)
  -N, --no-header               do not display table header (in text mode)
  -S, --sdf-output              SDF output (otherwise only plugin result)
  -g, --ignore-error            continue with next molecule on error
  -v, --verbose                 print calculation warnings to the console

Input files can be given both on the general option side and on the plugin specific option side, in either case these input files give the input molecules for the calculations. If more plugins are given then all plugin calculations are performed for all input molecules.

The available plugins are configured in one or more configuration files. First the chemaxon/marvin/calculations/calc.properties configuration file is read. User-defined plugins may be configured in this file or in separate files, listed in the rcfiles property. The built-in plugin configuration file is chemaxon/marvin/calculations/calc.properties which contains data for the built-in plugins that can be purchased from ChemAxon. This file path is the default value of the rcfiles property. The configuration file path is taken relative to the directories specified in the CLASSPATH environment variable. A detailed description of the configuration file is given below.

The command line parameter --tag specifies the SDF file tag name to be used when storing the calculation results in an SDF file.

If the --no-header parameter is specified then no table header is displayed. This option has no effect in --sdf-output mode.

If the --sdf-output parameter is given, then the input molecules are written in SDF format and the calculation result is added as an SDF file tag, otherwise only the calculation result is shown in table form.

The parameter --id parameter specifies the input SDF file tag that stores the molecule ID to be written in the output table. This parameter is only used if output is in table form (--sdf-output parameter is not given). If not specified then the input file index of the molecule is used as molecule ID.

Plugin Specific Options

The plugin specific help message is printed if the user types:

    cxcalc <plugin> -h
Here plugin is the plugin key from the configuration file.

Example

Typing

    cxcalc logp -h
produces the help string
Calculator plugin: logp.
logP calculation

Usage:
  cxcalc [general options] [input files] logp
[logp options] [input files]

logp options: 
  -h, --help       this help message
  -p, --precision  <floating point precision as number of
                   fractional digits: 0-8 or inf> (default: 2)
  -t, --type       [increments|implh|logP] (default: logP)
  -i, --implh      [true|false] implicit H logP sum shown in brackets
                   (for incremental logP only) (default: false)

Multiple parameter values should be separated by ',' characters.

The command line parameter --precision specifies the required floating point precision, that is, the number of required decimal digits in the output.

The command line parameter --type specifies the result type: increments gives the atomic logp increment values for each atom in the molecule while molecule gives the overall logp value for the molecule. Both results can be queried by specifying both types separated by a comma: -t increments,implh,logP.

Input

The software may take molecules from a text file. Most molecular file formats are accepted (for instance MDL molfile, Compressed molfile, SDfile, Compressed SDfile, SMILES).

If no input file name is given in the command line, then the standard input is read.


Output

Calculator writes calculation results in a format based on the specified tags. If the result refers to the entire molecule, it is written as a single number. If the calculation gives a separate number for each atom in the molecule, it is written as a list of numbers separated by semicolons. The order of the results corresponds to the order of the atoms determined by their atom indices. Other output formats may be available for certain plugins, see the plugin specific options for the specific plugin. By default, results are written without the input molecule in a table form, but Calculation results can be written in an SDF file as an SDF tag if the --sdf-output parameter is specified.

Configuration File

The available plugins are configured in a java property file for the command line tool calc. The main calculator configuration file is chemaxon/marvin/calculations/calc.properties whose path is taken relative to the directories in the CLASSPATH environment variable. The configuration for user plugins can either be added to this file or can be put in separate ones. In the latter case the value of the rcfiles property has to be modified to include the additional configuration file names (again, relative to the CLASSPATH). By default, the rcfiles property value contains only the configuration file path for the built-in plugins that can be purchased from ChemAxon which is chemaxon/marvin/calculations/calc.properties.

Configuration File Format

The configuration file is a java property file. The format of the configuration file is best shown by an example:

rcfiles=chemaxon/marvin/calculations/calc.properties,pluginconf/plugins.properties
chg=org.charge.ChargePlugin\
	$p=precision:2;t=type:total;i=implh:false\
	$CHARGE\
	$partial charge calculation\
	$-p, --precision=<floating point precision as number of\n\
fractional digits: 0-8 or inf> (default: 2);\
-t, --type=[sigma|pi|total|implh] (default: total);\
-i, --implh=[true|false] implicit H charge sum shown in brackets\n\
(for sigma and total charge only) (default: false)\
        $cxcalc -S -o result.sdf -t myCHARGE charge -t pi,total -p 3 test.mol

The property rcfiles specifies the additional configuration files that contain plugin configurations as a comma-separated file path list, each item is taken relative to directories in the CLASSPATH environment variable. In this example it contains the built-in plugin configuration file and a user defined plugin configuration file.

The key chg is the plugin name that the plugin is referenced by in the calc command line tool.

The value contains the configuration for a custom (user defined) charge plugin: configuration items are separated by '$' characters. The '\' characters allows property values to be expanded to multiple lines: the '\' character itself as well as leading white spaces in the next line are ignored.

The configuration items:

  1. the plugin class with full package name
  2. the plugin specific parameters:
    <short name>=<long name>:<default value>
    separated by semicolons
  3. the default SDF file tag name storing the results in case of SDF file output
  4. a short description used in the plugin specific help message
  5. the plugin specific help text (parameter description text) with newline characters replaced by semicolons
  6. an example usage text (optional)

Important: the long parameter names in the "plugin specific parameters" section must correspond to the parameter property keys used in the plugin class in the setParameters(Properties params) method!

Examples

  1. pKa calculation with table form output, showing the two most significant acidic and the two most significant basic pKa values (this is the default table output mode):
    cxcalc mols.sdf pka
    
  2. The same with molecule ID-s taken from the ID tag of the input SDF file, writing three significant values from each pKa type:
    cxcalc mols.sdf -i ID pka -a 3 -b 3
    
  3. The same with setting minimum basic pKa to -5, maximum acidic pKa to 15:
    cxcalc mols.sdf -i ID pka -a 3 -b 3 -i -5 -m 15
    
  4. Charge calculation for molecules in the mols.sdf file, uses the default configuraion file, writes results to the standard output in SDF format using the default SDF charge tag for storing the calculation results:
    cxcalc -S charge mols.sdf
    
  5. The same with output to the molcharges.sdf file to be created in the same directory:
    cxcalc -S -o molcharges.sdf charge mols.sdf
    
  6. Identical to the previous example, but putting the input file in front of the plugin name:
    cxcalc mols.sdf -S -o molcharges.sdf charge 
    
  7. The same but with all charge types and displaying the result in MarvinView:
    cxcalc -S mols.sdf -o molcharges.sdf charge -t sigma,pi,total
    mview molcharges.sdf
    
    By setting the Table / Show Fields option in MarvinView the SDF file tags will be shown in the table cells and in this way the charge values can be seen.

  8. LogP calculation with both result types (atomic increments and overal molecule) and user defined SDF tag name, piping the result to MarvinView:
    cxcalc -S mols.sdf -t LOGP_BOTH logp -t increments,logP | mview -
    

    Note, that such piping does not work in Windows.

  9. Elemental analysis (all result types), output in table form, molecule ID-s taken from the ID tag of the input SDF file, output written to text file elemanal.txt:
    cxcalc -o elemanal.txt -i ID elemanal mols.sdf
    
  10. A similar example with input taken from mols.smiles and output written as SDF to elemanal.sdf with ELEMANAL tag name:
    cxcalc -S -t ELEMANAL -o elemanal.sdf elemanal mols.smiles