Utilities

Handling Molecules

Structures can be manipulated directly using the chemaxon.util.MolHandler and chemaxon.struc.Molecule classes. 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 the JChemSearch.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, HitColoringAndAlignmentOptions and 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:

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:

align

susbstructure hit alignment

getNonHitBonds

returns bonds that are not part of substructure search hit

getNonHitBondEndpoints

returns bond endpoints (atom indexes) that are not part of substructure search hit