pKaPlugin (Marvin API documentation (c) 1998-2004 ChemAxon Ltd.)

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

chemaxon.marvin.calculations
Class pKaPlugin

java.lang.Object
  chemaxon.marvin.plugin.CalculatorPlugin
      chemaxon.marvin.calculations.pKaPlugin

public class pKaPlugin
extends CalculatorPlugin

Plugin class for macro/micro pKa calculation.

Example API usage:

	// instantiate and validate plugin
	pKaPlugin plugin = new pKaPlugin();
	plugin.validate(<pKa license>);

	// set parameters
	Properties params = new Properties();
	params.put("ions", "6");
	params.put("min", "-10");
	params.put("max", "20");
	plugin.setParameters(params);

	MolImporter importer = new MolImporter(
				     new BufferedInputStream(
					 new FileInputStream("molecule.mol")));
	Molecule mol = null;
	while ((mol = importer.read()) != null) {
	    // set molecule and run calculation
	    plugin.setMolecule(mol);
	    plugin.run();
	    
	    // get the 3 strongest ACIDIC pKa values
	    double[] acidic_pka = new double[3];
	    int[] acidic_indices = new int[3];
	    plugin.getSortedValues(pKaPlugin.ACIDIC, acidic_pka, acidic_indices);

	    // get the 3 strongest BASIC pKa values
	    double[] basic_pka = new double[3];
	    int[] basic_indices = new int[3];
	    plugin.getSortedValues(pKaPlugin.BASIC, basic_pka, basic_indices);

	    // get and print pKa values for each atom
	    int count = mol.getAtomCount();
	    for (int i=0; i < count; ++i) {

		// get ACIDIC and BASIC pKa values
		double apka = plugin.getpKa(i, pKaPlugin.ACIDIC);
		double bpka = plugin.getpKa(i, pKaPlugin.BASIC);
          }
     }
     importer.close();

Since:: 3.0
Version:: 3.0 12/06/2002
Author:: Nora Mate

Field Summary
`static int`	`ACIDIC` Constant denoting acidic pKa.
`static int`	`BASIC` Constant denoting basic pKa.
`static int`	`BLUE` Constant storing the blue rgb value (the basic pKa result color).
`static int`	`DEF_MAXIONS` The default value of the number of ionizable atoms to consider.
`static double`	`EPSILON` The microspecies is ignored if its distribution is less than EPSILON for all pH values.
`static int`	`RED` Constant storing the red rgb value (the acidic pKa result color).
`static java.lang.String`	`TYPE_DISTR` Type constant for microspecies distribution.

Fields inherited from class chemaxon.marvin.plugin.CalculatorPlugin

ATOM, CHART, MOLECULE, NAN, SUBRESULT

Constructor Summary
`pKaPlugin()` Constructor.

Method Summary
`void`	`checkMolecule(Molecule mol)` Checks the input molecule.
`java.lang.String`	`getErrorMessage()` Returns the calculation error information message if `run()` returned false (calculation error): the number of ionizable atoms exceeds the specified limit (given in the "ions" parameter).
`protected java.lang.String`	`getLicenseKey()` Returns the built-in license key for the given plugin class.
`int`	`getMsCount()` Returns the number of microspecies.
`double[]`	`getMsDistribution(int msIndex)` Returns the microspecies distribution array.
`Molecule`	`getMsMolecule(int msIndex)` Returns the microspecies molecule.
`java.lang.String`	`getOutputClassName()` Returns the output provider class name for the command line interface.
`double[]`	`getpHs()` Returns the pH array.
`double`	`getpKa(int index, int type)` Returns the pKa value for the given atom index and pKa type.
`Molecule`	`getReferenceMolecule(java.lang.Object type, int index)` Returns the molecule to be used as reference image for the given result type and index.
`java.lang.Object`	`getResult(java.lang.Object type, int index)` Returns the result item for the specified key and index.
`java.lang.Object`	`getResult(java.lang.Object type, java.lang.String arg)` Returns the result item for the specified type ("acidic" or "basic") and the specified strongness index ("1" means the strongest value, "2" means the second strongest value, etc.) given in the argument string.
`int`	`getResultAsRGB(java.lang.Object type, int index, java.lang.Object result)` Returns the specified result color as int format (alpha<<24 + red<<16 + green<<8 + blue): RED for acidic pKa, BLUE for basic pKa.
`java.lang.String`	`getResultAsString(java.lang.Object type, int index, java.lang.Object result)` Returns the specified result in String format.
`int`	`getResultCount(java.lang.Object type)` Returns the number of result items for the given result key.
`int`	`getResultDomain(java.lang.Object type)` Returns the calculation domain `CalculatorPlugin.ATOM` or `CalculatorPlugin.MOLECULE`.
`long`	`getResultsAsRGB(java.lang.Object type, int index, java.lang.Object result)` Returns the specified result color(s) as int format (alpha<<24 + red<<16 + green<<8 + blue).
`java.lang.String`	`getResultsAsString(java.lang.Object type, int index, java.lang.Object result)` Returns the specified result with possible subresults (both pKa values instead of the most significant pKa) in String format.
`java.lang.Object[]`	`getResultTypes()` Returns the result types (possible types: pKa, acidic, basic).
`void`	`getSortedValues(int pkatype, double[] values, int[] indices)` Calculates the least acidic pKa values in ascending order or the biggest basic pKa values in descending order.
`java.lang.String`	`getXAxisLabel(java.lang.Object type)` Returns the X axis label to be displayed in case of chart data.
`java.lang.String[]`	`getXLabels()` Returns the X label array (pH array as String[]).
`java.lang.String`	`getYAxisLabel(java.lang.Object type)` Returns the Y axis label to be displayed.
`boolean`	`isNegligibleResult(java.lang.Object type, int index, java.lang.Object result)` Returns whether the result can be ignored.
`boolean`	`run()` Runs the macro pKa calculation.
`protected void`	`setInputMolecule(Molecule mol)` Sets the input molecule.
`void`	`setParameters(java.util.Properties params)` Sets the input parameters for the plugin.
`protected void`	`standardize(Molecule mol)` Standardizes the molecule.

Methods inherited from class chemaxon.marvin.plugin.CalculatorPlugin

check, checkLicense, checkLicenseKey, create, createStandardizedMolecule, dehydrogenize, format, format, format, format, getAtomCount, getAtomIndex, getDoublePrecision, getResult, getResult, getResultAsRGB, getResultAsString, getResultCount, getResultDomain, getResultsAsRGB, getResultsAsString, getTypeString, handlesMultiFragmentMolecules, isLicensed, isRgrouped, setDoublePrecision, setDoublePrecision, setLicense, setMolecule, setMolecule, standardizeNitro, validate

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ACIDIC

public static final int ACIDIC

Constant denoting acidic pKa.

See Also:: Constant Field Values

BASIC

public static final int BASIC

Constant denoting basic pKa.

See Also:: Constant Field Values

RED

public static final int RED

Constant storing the red rgb value (the acidic pKa result color).

BLUE

public static final int BLUE

Constant storing the blue rgb value (the basic pKa result color).

TYPE_DISTR

public static final java.lang.String TYPE_DISTR

Type constant for microspecies distribution.

See Also:: Constant Field Values

DEF_MAXIONS

public static final int DEF_MAXIONS

The default value of the number of ionizable atoms to consider.

See Also:: Constant Field Values

EPSILON

public static final double EPSILON

The microspecies is ignored if its distribution is less than EPSILON for all pH values.

See Also:: Constant Field Values

Constructor Detail

pKaPlugin

public pKaPlugin()

Constructor. Creates the macro pKa calculator object.

Method Detail

getLicenseKey

protected final java.lang.String getLicenseKey()

Returns the built-in license key for the given plugin class. This license key has to be checked against the license key read from the property file.

Overrides:: getLicenseKey in class CalculatorPlugin

Returns:: the built-in license key for the given plugin class
See Also:: CalculatorPlugin.checkLicense()

setParameters

public void setParameters(java.util.Properties params)
                   throws PluginException

Sets the input parameters for the plugin. pKa parameters and value ranges:

type: pKa,acidic,basic (pKa is either the basic or the acidic pKa)
precision: 0-8 or inf (default: 2) (number of displayed fractional digits, inf for unrounded value)
mode: macro or micro (default: macro)
min: minimal basic pKa
max: maximal acidic pKa

If mode is "macro" then we have additional parameters for microspecies distribution:

showms: true if microspecies distribution to be shown, false otherwise (default: true)
lower: pH lower limit (default: 0.0)
upper: pH upper limit (default: 14.0)
count: pH step count between lower and upper limits (default: 0.5)

Specified by:
setParameters in class CalculatorPlugin

Parameters:
params - is the parameter table
Throws:
PluginException - on error

checkMolecule

public void checkMolecule(Molecule mol)
                   throws PluginException

Checks the input molecule. Throws exception if the molecule molecule contains R-groups.

Overrides:: checkMolecule in class CalculatorPlugin

Parameters:: mol - is the input molecule
Throws:: PluginException - with error message for the user if the molecule is refused

setInputMolecule

protected void setInputMolecule(Molecule mol)
                         throws PluginException

Sets the input molecule.

Specified by:: setInputMolecule in class CalculatorPlugin

Parameters:: mol - is the input molecule
Throws:: PluginException - on error

run

public boolean run()
            throws PluginException

Runs the macro pKa calculation.

Specified by:: run in class CalculatorPlugin

Returns:: true if the calculation was successful, false if the number of ionizable atoms exceeds the specified limit
Throws:: PluginException - on error
See Also:: CalculatorPlugin.getErrorMessage()

getMsCount

public int getMsCount()

Returns the number of microspecies. Calculated only if macro pKa is computed and the "mscalc" parameter is set to "true".

Returns:: the number of microspecies

getMsMolecule

public Molecule getMsMolecule(int msIndex)

Returns the microspecies molecule. Calculated only if macro pKa is computed and the "mscalc" parameter is set to "true".

Parameters:: msIndex - is the microspecies index
Returns:: the microspecies molecule

getpHs

public double[] getpHs()

Returns the pH array. Calculated only if macro pKa is computed and the "mscalc" parameter is set to "true".

Returns:: the pH array

getMsDistribution

public double[] getMsDistribution(int msIndex)

Returns the microspecies distribution array. Calculated only if macro pKa is computed and the "mscalc" parameter is set to "true".

Parameters:: msIndex - is the microspecies index
Returns:: the microspecies distribution array

getpKa

public double getpKa(int index,
                     int type)

Returns the pKa value for the given atom index and pKa type. The pKa calculation has to be run beforehand by calling run().

Parameters:: index - is the atom index; type - is the pka type: ACIDIC or BASIC
Returns:: the pKa value, or Double.NaN if there is no pKa value for the given atom index and pKa type

getErrorMessage

public java.lang.String getErrorMessage()

Returns the calculation error information message if run() returned false (calculation error): the number of ionizable atoms exceeds the specified limit (given in the "ions" parameter).

Overrides:: getErrorMessage in class CalculatorPlugin

Returns:: the calculation error information message

getResultTypes

public java.lang.Object[] getResultTypes()

Returns the result types (possible types: pKa, acidic, basic).

Specified by:: getResultTypes in class CalculatorPlugin

Returns:: the result types

getResultDomain

public int getResultDomain(java.lang.Object type)

Returns the calculation domain CalculatorPlugin.ATOM or CalculatorPlugin.MOLECULE. pKa always returns CalculatorPlugin.ATOM.

Specified by:: getResultDomain in class CalculatorPlugin

Parameters:: type - is the result type
Returns:: CalculatorPlugin.ATOM
See Also:: getResultTypes()

getResultCount

public int getResultCount(java.lang.Object type)

Returns the number of result items for the given result key. pKa returns the atom count.

Specified by:: getResultCount in class CalculatorPlugin

Parameters:: type - is the result type
Returns:: the number of result items
See Also:: getResultTypes()

getResult

public java.lang.Object getResult(java.lang.Object type,
                                  int index)
                           throws PluginException

Returns the result item for the specified key and index. If the type is "msdistr" then returns the pH - distribution table as a double[][] with the 0-th element the pH array and the 1-st element the distribution array corresponding to the microspecies with the specified index (result index). Otherwise pKa returns the required pKa value as a Double object for the given atom index (result index). Returns Double.NaN if the atom with the given index does not have a valid macro pKa value for the specified result type.

Specified by:: getResult in class CalculatorPlugin

Parameters:: type - is the result type; index - is the result index
Returns:: the result item for the specified key and index
Throws:: PluginException - if the result cannot be returned
See Also:: getResultTypes()

getResult

public java.lang.Object getResult(java.lang.Object type,
                                  java.lang.String arg)
                           throws PluginException

Returns the result item for the specified type ("acidic" or "basic") and the specified strongness index ("1" means the strongest value, "2" means the second strongest value, etc.) given in the argument string. Returns Double.NaN for non-existent values (e.g. when the type is "acidic" and the arg string is "2" but there is only one acidic pKa value for the input molecule).

Overrides:: getResult in class CalculatorPlugin

Parameters:: type - is the result type ("acidic" or "basic"); arg - is the strongness order index
Returns:: the result item for the specified type and strongness index
Throws:: PluginException - if the result cannot be returned
See Also:: CalculatorPlugin.getResultTypes()

getSortedValues

public void getSortedValues(int pkatype,
                            double[] values,
                            int[] indices)
                     throws PluginException

Calculates the least acidic pKa values in ascending order or the biggest basic pKa values in descending order. The pKa calculation has to be run beforehand by calling run(). The length of the result value array determines the number of pKa values to be computed. If the index array is non-null then it is assumed to have the same length as the value array and will be filled with the corresponding atom indices (0-based).

Parameters:: pkatype - is the pKa type (ACIDIC or BASIC); values - is the pKa value array to be filled with pKa values in ascending strongness order (increasing for acidic pKa, descending for basic pKa values), the last entries are set to Double.NaN if there are less pKa values than the array length; indices - is the corresponding atom index array to be filled (may be null), the index is set to -1 for non-existent values (Double.NaN)
Returns:: the strongest pKa values in strongness order
Throws:: PluginException - if an error occurs during the calculation

getResultAsString

public java.lang.String getResultAsString(java.lang.Object type,
                                          int index,
                                          java.lang.Object result)
                                   throws PluginException

Returns the specified result in String format. If the type is "msdistr" then returns the pH - distribution table as a 2-column tab-separated table with the 0-th element the pH array and the 1-st element the distribution array corresponding to the microspecies with the specified index (result index). Otherwise pKa returns the rounded pKa value in string format: the value is rounded using the 'precision' input parameter that determines the number of fractional digits displayed. If the result is Double.NaN then returns the empty string.

Specified by:: getResultAsString in class CalculatorPlugin

Parameters:: type - is the result type; index - is the result index; result - is the result item
Returns:: the specified result in String format
Throws:: PluginException - if an invalid result item is given

getResultsAsString

public java.lang.String getResultsAsString(java.lang.Object type,
                                           int index,
                                           java.lang.Object result)
                                    throws PluginException

Returns the specified result with possible subresults (both pKa values instead of the most significant pKa) in String format.

Overrides:: getResultsAsString in class CalculatorPlugin

Parameters:: type - is the result type; index - is the result index; result - is the result item
Returns:: the specified result in String format
Throws:: PluginException - if an invalid result item is given

getResultAsRGB

public int getResultAsRGB(java.lang.Object type,
                          int index,
                          java.lang.Object result)
                   throws PluginException

Returns the specified result color as int format (alpha<<24 + red<<16 + green<<8 + blue): RED for acidic pKa, BLUE for basic pKa.

Overrides:: getResultAsRGB in class CalculatorPlugin

Parameters:: type - is the result type; index - is the result index; result - is the result item
Returns:: the specified result in color as int format
Throws:: PluginException - if an invalid result item is given

getResultsAsRGB

public long getResultsAsRGB(java.lang.Object type,
                            int index,
                            java.lang.Object result)
                     throws PluginException

Returns the specified result color(s) as int format (alpha<<24 + red<<16 + green<<8 + blue). (e.g. both pKa colors instead of the most significant pKa color) as long (lower and upper bits).

Overrides:: getResultsAsRGB in class CalculatorPlugin

Parameters:: type - is the result type; index - is the result index; result - is the result item
Returns:: the specified result in color as int
Throws:: PluginException - if an invalid result item is given

getReferenceMolecule

public Molecule getReferenceMolecule(java.lang.Object type,
                                     int index)

Returns the molecule to be used as reference image for the given result type and index. Returns the microspecies with the given index (result index).

Overrides:: getReferenceMolecule in class CalculatorPlugin

Parameters:: type - is the result type; index - is the result index
Returns:: the original molecule clone

isNegligibleResult

public boolean isNegligibleResult(java.lang.Object type,
                                  int index,
                                  java.lang.Object result)
                           throws PluginException

Returns whether the result can be ignored. Returns true for microspecies distributions below EPSILON. Returns false for all other results.

Overrides:: isNegligibleResult in class CalculatorPlugin

Parameters:: type - is the result type; index - is the result index; result - is the result object
Returns:: true for microspecies distributions below EPSILON
Throws:: PluginException

getXLabels

public java.lang.String[] getXLabels()

Returns the X label array (pH array as String[]).

Overrides:: getXLabels in class CalculatorPlugin

Returns:: the X label array

getXAxisLabel

public java.lang.String getXAxisLabel(java.lang.Object type)

Returns the X axis label to be displayed in case of chart data.

Overrides:: getXAxisLabel in class CalculatorPlugin

Parameters:: type - is the result type

getYAxisLabel

public java.lang.String getYAxisLabel(java.lang.Object type)

Returns the Y axis label to be displayed.

Overrides:: getYAxisLabel in class CalculatorPlugin

Parameters:: type - is the result type

getOutputClassName

public java.lang.String getOutputClassName()

Returns the output provider class name for the command line interface.

Overrides:: getOutputClassName in class CalculatorPlugin

Returns:: the output provider class name

standardize

protected void standardize(Molecule mol)

Standardizes the molecule. This is done by performing the transformations necessary to run the plugin (e.g. aromatize, dehydrogenize, bring nitro groups to common form). Apart from the default standardization (aromatize and nitro) removes explicit hydrogens and stores the index-map between atom indices in the original and the new molecule. This map is used when the macropKa values and types are queried and the new atom indices should be mapped to the original ones. TODO: replace by call to chemaxon.reaction.Standardizer

Overrides:: standardize in class CalculatorPlugin

Parameters:: mol - is the molecule to be standardized

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

chemaxon.marvin.calculations Class pKaPlugin

ACIDIC

BASIC

RED

BLUE

TYPE_DISTR

DEF_MAXIONS

EPSILON

pKaPlugin

getLicenseKey

setParameters

checkMolecule

setInputMolecule

run

getMsCount

getMsMolecule

getpHs

getMsDistribution

getpKa

getErrorMessage

getResultTypes

getResultDomain

getResultCount

getResult

getResult

getSortedValues

getResultAsString

getResultsAsString

getResultAsRGB

getResultsAsRGB

getReferenceMolecule

isNegligibleResult

getXLabels

getXAxisLabel

getYAxisLabel

getOutputClassName

standardize

chemaxon.marvin.calculations
Class pKaPlugin