Utilities

Handling Molecules

Structures can be manipulated directly using the chemaxon.util.MolHandlerand chemaxon.struc.Moleculeclasses. In usual cases, developers will not need to access Molecule directly, however MolHandler might be needed occasionally.

After creating the MolHandler object from a Molecule, several operations can be performed on the structure using methods of MolHandler:

`addHydrogens`	Adds the implicit Hydrogen atoms to the molecule.
`aromatize`	Converts the bonds in an aromatic system entered using single and double bonds to aromatic bonds.
`removeHydrogens`	Removes the Hydrogen atoms from the molecule.
`toFormat`	Converts the molecule to the specified text format (mol, csmol, smiles, ...)

The following methods can be used to retrieve information on a structure:

`calcMolFormula`	Calculates the formula of the molecule.
`calcMolWeight`	Calculates the molecular weight of the molecule.
`containsHydrogens`	True if the molecule contains explicit Hydrogen atoms, false otherwise.
`getAtomCount`	Retrieves the number of atoms in the Molecule stored in the MolHandler object.
`getFingerprintInBytes`	Retrieves a chemical hashed fingerprint for the molecule in bytes.
`getFingerprintInInts`	Retrieves a chemical hashed fingerprint for the molecule in `int` units.
`getHeavyAtomCount`	Retrieves the number of atoms in the Molecule stored in the MolHandler object.
`getMolecule`	Retrieves the Molecule from the MolHandler object.

Steps of working with MolHandler:

Create the MolHandler object.
Specify a molecule.
Perform several operations and/or retrieve information.
Get the modified structure and process it.

Specify a new molecule...

To speed up the manipulation of structures by decreasing the burden on the garbage collector, MolHandler supports recycling. For this purpose, it is recommended to apply the same MolHandler object to process a list of structures.

Java example:

    MolHandler mh = new MolHandler();
    while(...) {
        String molfile = ...;
        mh.setMolecule(molfile);
        mh.addHydrogensToHeteroAtoms();
        mh.aromatize();
        Molecule molecule = mh.getMolecule();
        ...
    }

Hit coloring and alignment

The JChem API provides three levels of API support for hit coloring and alignment. The first two higher-level methods return a colored Molecule object, which can be directly set for a Marvin GUI component (e.g. MViewPane). In other cases the Molecule should be exported to Marvin Documents (MRV) format, which preserves coloring. Then it can be displayed with coloring by the Marvin Applet on a web page or other ChemAxon applications.

Retrieving hits from a JChemSearch object

In JChemSearch aligned (rotated) hits can be obtained by using theJChemSearch.getHitsAsMolecules() method. It returns a Molecule array of the aligned hits that contain the colored query. Its first parameter is the array of cd_ids to retrieve, the second parameter is a{{HitColoringAndAlignmentOptions}} object (third and fourth parameters are optional, they serve for fetching database fields).

Please, see RotateDatabaseHitsExample.java demonstrating how to retrieve search results rotated according to the query.

Visualization of hits

During a substructure search the match can be visualized by coloring the matching atoms in the target structure. Two classes are used in the following examples, HitColoringAndAlignmentOptionsand HitDisplayTool.

HitColoringAndAlignmentOptions contains information about coloring and rotating the match. Its main parameters are:

coloring	true, if match should be colored
hitColor nonHitColor	color of hit and non-hit atoms
alignmentMode	can be one of the following constants: ALIGNMENT_OFF: no alignment ALIGNMENT_ROTATE: only rotation * ALIGNMENT_PARTIAL_CLEAN: match will be in the same position as the query, new coordinates will be generated for the remainder of the structure

Java example:

    HitColoringAndAlignmentOptions displayOptions =
            new HitColoringAndAlignmentOptions();
    displayOptions.setColoringEnabled(true);
    displayOptions.setHitColor(Color.RED);
    displayOptions.setNonHitColor(Color.GREEN);
    displayOptions.setAlignmentMode(
            HitColoringAndAlignmentOptions.ALIGNMENT_ROTATE);

HitDisplayTool performs a search with the given query, target, search options and coloring options and returns a colored / aligned molecule that can be displayed.

    Molecule query = MoleculeImport.importMol("Q1.mrv", true);
    MolSearchOptions searchOptions =
            new MolSearchOptions(SearchConstants.DEFAULT_SEARCHTYPE);
    hdt = new HitDisplayTool(displayOptions, searchOptions, query);
    Molecule result = hdt.getHit(target);

Code examples:

HitColoringExample.java demonstrates hit coloring.
PartialCleanExample.java demonstrates partial clean.
RotateExample.java demonstrates how to rotate the target molecule to be aligned with the query.

Lower level coloring tools

The two methods above perform the graph search internally, which enables them to select the "best fit" from multiple hits for alignment.

In some cases one may already have the hit atom indexes, so for performance or other reasons the older, lower-level methods of MolHandler may be useful: