Skip to content

Utilities


Contents

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:

1
2
3
4
5
6
7
8
9
    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 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
hitColornonHitColor 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:

1
2
3
4
5
6
7
    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.

1
2
3
4
5
    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:

  • 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:

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