chemaxon.util
Class MolHandler

java.lang.Object
  chemaxon.util.ErrorHandler
      chemaxon.util.MolHandler

All Implemented Interfaces:

java.io.Serializable

public class MolHandler
extends ErrorHandler

Class for handling molecules for systems based on ChemAxon's programming intaface. A MolHandler object contains the structure of a molecule.
Operations on the object:

• retrieving the molecule
• adding and removing Hydrogens
• replacing bonds in aromatic systems to aromatic bonds
• calculating molecular weight and formula
• etc.

This class can be used as an ActiveX component. To avoid problems caused by exceptions in environments where exceptions can not be handled, exceptions are caught and stored using the chemaxon.util.ErrorHandler super class in methods with name like <method name>_...NE (where NE means "no exception").

Since method overloading cannot be applied in some environments, overloaded methods have non-overloaded versions that are marked using postfixes in the name. These postfixes include the first letters of the types of parameters. For example, if the parameter of a method is a String, then the postfix is _SNE.

Author:

Ferenc Csizmadia, Andras Volford, Szilard Dorant

See Also:

Serialized Form

Field Summary

Fields inherited from class chemaxon.util.ErrorHandler

CLASS_NOT_FOUND_ERROR, DATABASE_SEARCH_ERROR, exception, ILLEGAL_ACCESS_ERROR, INSTANTIATION_ERROR, IO_ERROR, MAX_SEARCH_FREQUENCY_EXCEEDED_ERROR, MOL_FORMAT_ERROR, NO_ERROR, PROPERTY_NOT_SET_ERROR, SQL_ERROR, UNIDENTIFIED_ERROR

Constructor Summary

MolHandler()
Creates an uninitialized MolHandler object.

MolHandler(byte[] molecule)
Creates a MolHandler object from a byte array.

MolHandler(byte[] molecule, boolean queryMode)
Creates a MolHandler object from a byte array.

MolHandler(Molecule mol)
Creates a MolHandler object from a Molecule.

MolHandler(java.lang.String molecule)
Creates a MolHandler object from a String.

MolHandler(java.lang.String molecule, boolean queryMode)
Creates a MolHandler object from a String.

Method Summary

void	addHydrogens() Adds explicit H atoms instead of the current implicit ones.
void	addHydrogensToAromaticHeteroAtoms() Adds the implicit Hydrogen atoms to heteroatoms in aromatic rings.
double	align(Molecule mol, int[] indexes) Alignes (rotates) a specified molecule realtive to the contained molecule according to the specified atom pairs.
void	aromatize() Converts the bonds in an aromatic system entered using single and double bonds to aromatic bonds.
void	aromatize(int method) Converts the bonds in an aromatic system entered using single and double bonds to aromatic bonds.
java.lang.String	calcMolFormula() Calculates the molecular formula of the molecule.
float	calcMolWeight() Calculates the molecular weight of the molecule.
double	calcMolWeightInDouble() Calculates the molecular weight of the molecule.
void	clean(boolean always, java.lang.String options) Calculates 2D coordinates.
boolean	containsHydrogens() True if the molecule contains explicit Hydrogen atoms, false otherwise.
byte[]	generateFingerprintInBytes(int numberOfInts, int numberOfOnes, int numberOfEdges) Generates chemical hashed fingerprint for the molecule and returns it in byte units.
int[]	generateFingerprintInInts(int numberOfInts, int numberOfOnes, int numberOfEdges) Generates chemical hashed fingerprint for the molecule and returns it in int units.
int	getAtomCount() Retrieves the number of atoms in the Molecule stored in the MolHandler object.
byte[]	getFingerprintInBytes(int numberOfBits, int numberOfOnes, int numberOfEdges) Deprecated. since JChem 3.1 the usage of generateFingerprintInBytes(int, int, int) is recommended
int[]	getFingerprintInInts(int numberOfBits, int numberOfOnes, int numberOfEdges) Deprecated. since JChem 3.1 the usage of generateFingerprintInInts(int, int, int) is recommended
int	getHeavyAtomCount() Retrieves the number of non-hydrogen atoms in the Molecule stored in the MolHandler object.
int	getImplicitHCount() Counts the number of implicir hydrogens on the molecule
Molecule	getMolecule() Retrieves the Molecule from the MolHandler object.
static java.util.ArrayList	getNonHitBondEndpoints(Molecule query, Molecule target, int[] hit) Returns the bonds of the target molecule that should not be colored in hit highlighting.
static java.util.ArrayList	getNonHitBonds(Molecule query, Molecule target, int[] hit) Returns the bonds of the target molecule that should not be colored in hit highlighting.
boolean	getQueryMode() Gets query mode.
static boolean	isDaylightFormat(java.lang.String format) Decides whether the given molecule format belongs to the Daylight family of languages.
static boolean	isPlainH(MolAtom atom) Decides if atom is a plain H atom.
void	removeHydrogens() Removes all hydrogen atoms.
void	removeHydrogensFromCarbons() Removes Hydrogen atoms attached to Carbon atoms.
void	setMolecule_BNE(byte[] molecule) Same as setMolecule(byte[]), but exceptions are caught and stored.
void	setMolecule_SNE(java.lang.String molecule) Same as setMolecule(String), but exceptions are caught and stored.
void	setMolecule(byte[] molecule) Initializes a MolHandler object from a byte array.
void	setMolecule(Molecule molecule) Initializes a MolHandler object from a Molecule.
void	setMolecule(java.lang.String molecule) Initializes a MolHandler object from a String.
void	setQueryMode(boolean q) Sets query mode.
byte[]	toBinFormat(java.lang.String format) Converts the molecule to the specified binary format.
java.lang.String	toFormat(java.lang.String format) Converts the molecule to the specified text format.

Methods inherited from class chemaxon.util.ErrorHandler

checkError, checkException, getError, getErrorMessage, getException, getStackTrace

Methods inherited from class java.lang.Object

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

Constructor Detail

MolHandler

public MolHandler()

Creates an uninitialized MolHandler object.

MolHandler

public MolHandler(Molecule mol)

Creates a MolHandler object from a Molecule.

Parameters:

mol - a clone of this parameter is stored in the MolHandler object

MolHandler

public MolHandler(java.lang.String molecule)
           throws MolFormatException

Creates a MolHandler object from a String.

Parameters:

molecule - the String must contain a molecule in MDL's Molfile or Compressed Molfile or Smiles format.

Throws:

MolFormatException

MolHandler

public MolHandler(java.lang.String molecule,
                  boolean queryMode)
           throws MolFormatException

Creates a MolHandler object from a String.

Parameters:

molecule - the String must contain a molecule in MDL's Molfile or Compressed Molfile or Smiles format.

queryMode - if set to trueSMILES strings are imported as SMARTS. Default is false. since 2.2

Throws:

MolFormatException

MolHandler

public MolHandler(byte[] molecule)
           throws MolFormatException

Creates a MolHandler object from a byte array.

Parameters:

molecule - the byte array must contain a molecule in MDL's Molfile or Compressed Molfile or Smiles format.

Throws:

MolFormatException

MolHandler

public MolHandler(byte[] molecule,
                  boolean queryMode)
           throws MolFormatException

Creates a MolHandler object from a byte array.

Parameters:

molecule - the byte array must contain a molecule in MDL's Molfile or Compressed Molfile or Smiles format

queryMode - if set to trueSMILES strings are imported as SMARTS. Default is false. since 2.2

Throws:

MolFormatException

Method Detail

setMolecule

public void setMolecule(Molecule molecule)

Initializes a MolHandler object from a Molecule.

Parameters:

molecule - a clone of this parameter is stored in the MolHandler object

setMolecule

public void setMolecule(java.lang.String molecule)
                 throws MolFormatException

Initializes a MolHandler object from a String.

Parameters:

molecule - the String must contain a molecule in MDL's Molfile or Compressed Molfile or Smiles format.

Throws:

MolFormatException

setMolecule_SNE

public void setMolecule_SNE(java.lang.String molecule)

Same as setMolecule(String), but exceptions are caught and stored.

See Also:

ErrorHandler, setMolecule(String)

setMolecule

public void setMolecule(byte[] molecule)
                 throws MolFormatException

Initializes a MolHandler object from a byte array.

Parameters:

molecule - the byte array must contain a molecule in MDL's Molfile or Compressed Molfile or Smiles format.

Throws:

MolFormatException

setMolecule_BNE

public void setMolecule_BNE(byte[] molecule)

Same as setMolecule(byte[]), but exceptions are caught and stored.

See Also:

ErrorHandler, setMolecule(byte[])

getMolecule

public Molecule getMolecule()

Retrieves the Molecule from the MolHandler object.

getAtomCount

public int getAtomCount()

Retrieves the number of atoms in the Molecule stored in the MolHandler object.

getHeavyAtomCount

public int getHeavyAtomCount()

Retrieves the number of non-hydrogen atoms in the Molecule stored in the MolHandler object.

addHydrogens

public void addHydrogens()

Adds explicit H atoms instead of the current implicit ones.

addHydrogensToAromaticHeteroAtoms

public void addHydrogensToAromaticHeteroAtoms()

Adds the implicit Hydrogen atoms to heteroatoms in aromatic rings. The coordinates of the H atoms set to 0.

removeHydrogens

public void removeHydrogens()

Removes all hydrogen atoms.

removeHydrogensFromCarbons

public void removeHydrogensFromCarbons()

Removes Hydrogen atoms attached to Carbon atoms.

containsHydrogens

public boolean containsHydrogens()

True if the molecule contains explicit Hydrogen atoms, false otherwise.

aromatize

public void aromatize()

Converts the bonds in an aromatic system entered using single and double bonds to aromatic bonds.

aromatize

public void aromatize(int method)

Converts the bonds in an aromatic system entered using single and double bonds to aromatic bonds. since 2.3

Parameters:

method - specifies the algorithm for aromatization. Possible values:

• AROM_CHEMAXON - Chemaxon aromatization
• AROM_DAYLIGHT - Daylight aromatization (modified Huckel rule)

See Also:

MoleculeGraph.AROM_CHEMAXON, MoleculeGraph.AROM_DAYLIGHT, Aromata

calcMolWeight

public float calcMolWeight()

Calculates the molecular weight of the molecule. In the case of query structures 0 is returned.

calcMolWeightInDouble

public double calcMolWeightInDouble()

Calculates the molecular weight of the molecule. Returns a double value.

calcMolFormula

public java.lang.String calcMolFormula()

Calculates the molecular formula of the molecule. The symbols are listed in Hill Order: C is listed first, followed by H, followed by the remaining elements in alphabetical order.

clean

public void clean(boolean always,
                  java.lang.String options)

Calculates 2D coordinates. The bond length is set to 0.825. The calculation uses the O1 option of cleaning.

Parameters:

always - if false then cleaning will only be performed if the present coordinates are different from zero.

options - specifies the options used for 2D calculation. (E.g.: "O1e")

See Also:

MoleculeGraph.clean(int,java.lang.String)

toFormat

public java.lang.String toFormat(java.lang.String format)

Converts the molecule to the specified text format.

Parameters:

format - "mol", "csmol", "smiles", ...
The documentation of marvin details all the possible formats.

toBinFormat

public byte[] toBinFormat(java.lang.String format)

Converts the molecule to the specified binary format.

Parameters:

format - "png", "jpeg", "ppm", ...
The documentation of marvin details all the possible formats.

Since:

JChem 2.2

getFingerprintInBytes

public byte[] getFingerprintInBytes(int numberOfBits,
                                    int numberOfOnes,
                                    int numberOfEdges)

Deprecated. since JChem 3.1 the usage of generateFingerprintInBytes(int, int, int) is recommended

Retrieves a chemical hashed fingerprint for the molecule in byte units.
NOTE: Since ring search can be time consuming, uses rings found during the last aromatize() call. The structure should not be modified between these two calls. If aromatize() hasn't been called yet, or the structure was modified, calls it.

Parameters:

numberOfBits - the length of the binary fingerprint in bits.

numberOfOnes - the number of bits to switch on for each pattern.

numberOfEdges - the maximum length of edges in patterns used for generating the fingerprint.

getFingerprintInInts

public int[] getFingerprintInInts(int numberOfBits,
                                  int numberOfOnes,
                                  int numberOfEdges)

Deprecated. since JChem 3.1 the usage of generateFingerprintInInts(int, int, int) is recommended

Retrieves a chemical hashed fingerprint for the molecule in int units.
NOTE: Since ring search can be time consuming, uses rings found during the last aromatize() call. The structure should not be modified between these two calls. If aromatize() hasn't been called yet, or the structure was modified, calls it.

Parameters:

numberOfBits - the length of the binary fingerprint in bits.

numberOfOnes - the number of bits to switch on for each pattern.

numberOfEdges - the maximum length of edges in patterns used for generating the fingerprint.

generateFingerprintInInts

public int[] generateFingerprintInInts(int numberOfInts,
                                       int numberOfOnes,
                                       int numberOfEdges)

Generates chemical hashed fingerprint for the molecule and returns it in int units.
NOTE: The structure should be standardized (including aromatization) before fingerprint generation.

Parameters:

numberOfInts - the length of the binary fingerprint in int (32 bit) units.

numberOfOnes - the number of bits to switch on for each pattern.

numberOfEdges - the maximum length of edges in patterns used for generating the fingerprint.

Since:

JChem 3.1

See Also:

generateFingerprintInBytes(int, int, int)

generateFingerprintInBytes

public byte[] generateFingerprintInBytes(int numberOfInts,
                                         int numberOfOnes,
                                         int numberOfEdges)

Generates chemical hashed fingerprint for the molecule and returns it in byte units.
NOTE: The structure should be standardized (including aromatization) before fingerprint generation.

Parameters:

numberOfInts - the length of the binary fingerprint in int (32 bit) units.

numberOfOnes - the number of bits to switch on for each pattern.

numberOfEdges - the maximum length of edges in patterns used for generating the fingerprint.

Since:

JChem 3.1

See Also:

generateFingerprintInInts(int, int, int)

getImplicitHCount

public int getImplicitHCount()

Counts the number of implicir hydrogens on the molecule

Returns:

the number of implicit hydrogens

align

public double align(Molecule mol,
                    int[] indexes)
             throws java.lang.IllegalArgumentException

Alignes (rotates) a specified molecule realtive to the contained molecule according to the specified atom pairs.
NOTE: S-groups in the MolHandler contained molecule will be expanded.

Parameters:

mol - the molecule to be aligned

indexes - the atom indexes of the pattern in the order of the atoms of the molecule to be aligned. Negative values are ignored. The size of this array should be at least the number of atoms in the pattern molecule (in case of RgMolecules, the number of non R-group atoms of the root structure). If the size of the array is grater, the excess elements are ignored.

Returns:

the error value of the alignment, can be used to try to align multiple hits and choose the best solution.

Throws:

java.lang.IllegalArgumentException

getNonHitBondEndpoints

public static java.util.ArrayList getNonHitBondEndpoints(Molecule query,
                                                         Molecule target,
                                                         int[] hit)

Returns the bonds of the target molecule that should not be colored in hit highlighting. Bonds surrounding lonely atoms are never included

Parameters:

query - the query Molecule

target - the target Molecule

hit - the hit list

Returns:

the non-hit bonds specified by the atom indexes of their endpoints. The ArrayList contains int[2] objects.

Since:

JChem 2.2

getNonHitBonds

public static java.util.ArrayList getNonHitBonds(Molecule query,
                                                 Molecule target,
                                                 int[] hit)

Returns the bonds of the target molecule that should not be colored in hit highlighting. Bonds surrounding lonely atoms are never included

Parameters:

query - the query Molecule

target - the target Molecule

hit - the hit list

Returns:

the non-hit bonds specified by the atom indexes of their endpoints. The ArrayList contains MolBond objects.

Since:

JChem 2.2

getQueryMode

public boolean getQueryMode()

Gets query mode. SMILES strings are imported as SMARTS if query mode is set.

Returns:

query mode

Since:

JChem 2.2

setQueryMode

public void setQueryMode(boolean q)

Sets query mode. SMILES strings are imported as SMARTS if query mode is set.

Parameters:

q - query mode

Since:

JChem 2.2

isDaylightFormat

public static boolean isDaylightFormat(java.lang.String format)

Decides whether the given molecule format belongs to the Daylight family of languages.

Parameters:

format - The molecular format, as used in Molecule.getInputFormat().

Returns:

Whether format is one of "smiles", "smarts", "smirks", "chuckles", "chortles", "charts" or cx<format> where <format> is one of the above Daylight formats.

isPlainH

public static boolean isPlainH(MolAtom atom)

Decides if atom is a plain H atom.

Parameters:

atom - MolAtom to decide.

Returns:

true if atom is an uncharged, nonisotopic hydrogen.

Since:

JChem 3.2