Utilities

    Contents

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

        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