Package chemaxon.search.api

Class MolComparator

java.lang.Object
chemaxon.search.api.MolComparator
@PublicApi public class MolComparator extends Object
Interface for comparing atoms, bonds, etc. against different criteria. Its subclasses are used by the search classes. Methods that can be overridden: compareAtoms(int, int), compareBonds(int, int), compareHit(int[], int). The default implementations of these comparison methods always return true.

Utility methods to get original query and target atom molecular indexes are: getOrigQueryAtom(int), getOrigTargetAtom(int), getOrigQueryNeighbour(int), getOrigTargetNeighbour(int).

By using MolComparators one can introduce extra matching conditions. Working examples can be found here.

Since:
JChem 3.2

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    MAYBE_USEFUL
    Describes that the MolComparator may be needed with the current search object and the current query, depending on the target.
    static final int
    NOT_USEFUL
    Describes that the MolComparator is not needed with the current search object, the current query (and target).
    protected Molecule
    query
    The query molecule.
    protected MolSearchOptions
    searchOptions
    The search options.
    protected Molecule
    target
    The target molecule.
    static final int
    USEFUL
    Describes that the MolComparator should be used with the current search object and the current query, regardless of the target.

  • Constructor Summary

    Constructors
    Constructor
    Description
    MolComparator()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    compareAtoms(int a1, int a2)
    Compares atoms of indices a1 and a2.
    boolean
    compareBonds(int b1, int b2)
    Compares bonds of indices b1 and b2.
    boolean
    compareHit(int[] internalHit, int internalHitLength)
    Checks a partial hit during the search algorithm.
    final int
    getOrigQueryAtom(int a1)
    Converts search internal atom index (in the query) to the original atom index in the query molecule.
    final int
    getOrigQueryAtom1(int bi)
    Returns the index of the first atom (atom index in the query molecule) of the given query bond(search internal bond index in the query).
    final int
    getOrigQueryAtom2(int bi)
    Returns the index of the second atom (atom index in the query molecule) of the given query bond(search internal bond index in the query).
    final int
    getOrigQueryBond(int bi)
    Returns bond index in the query molecule for the given query bond (search internal bond index in the query).
    final int
    getOrigQueryNeighbour(int a)
    For a search internal atom index (in the query), returns a neighbour atom index (original atom index in the query molecule).
    final int
    getOrigTargetAtom(int a1)
    Converts search internal atom index (in the target) to the original atom index in the target molecule.
    final int
    getOrigTargetAtom1(int bi)
    Returns the index of the first atom (atom index in the target molecule) of the given target bond(search internal bond index in the target).
    final int
    getOrigTargetAtom2(int bi)
    Returns the index of the second atom (atom index in the target molecule) of the given target bond(search internal bond index in the target).
    final int
    getOrigTargetBond(int bi)
    Returns bond index in the target molecule for the given target bond (search internal bond index in the target).
    final int
    getOrigTargetNeighbour(int a)
    For a search internal atom index (in the target), returns a neighbour atom index (original atom index in the target molecule).
    int
    isUsefulForQuery()
    Decides based on the query and the search object if the comparator should be used or not.
    int
    isUsefulForTarget()
    Decides based on the query, target and the search object if the comparator should be used or not.
    void
    setQuery(Molecule q)
    Loads the query molecule into this comparator.
    final void
    setSearchOptions(MolSearchOptions searchOptions)
    Loads the search options into this comparator.
    void
    setTarget(Molecule t)
    Loads the target molecule into this comparator.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • query

      protected Molecule query
      The query molecule. It is set before any compare method is called. Do not change it in derived classes.

    • target

      protected Molecule target
      The target molecule. It is set before any compare method is called. Do not change it in derived classes.

    • searchOptions

      protected MolSearchOptions searchOptions
      The search options. It is set before any compare method is called. Do not change it in derived classes.

    • USEFUL

      public static final int USEFUL
      Describes that the MolComparator should be used with the current search object and the current query, regardless of the target.
      See Also:

    • MAYBE_USEFUL

      public static final int MAYBE_USEFUL
      Describes that the MolComparator may be needed with the current search object and the current query, depending on the target.
      See Also:

    • NOT_USEFUL

      public static final int NOT_USEFUL
      Describes that the MolComparator is not needed with the current search object, the current query (and target).
      See Also:

  • Constructor Details

    • MolComparator

      public MolComparator()

  • Method Details

    • setQuery

      public void setQuery(Molecule q)
      Loads the query molecule into this comparator.

      the default implementation saves the query into the field 'query'.

      Parameters:
      q - the query that will be used from now on

    • setTarget

      public void setTarget(Molecule t)
      Loads the target molecule into this comparator.

      the default implementation saves the target into the field 'target'.

      Parameters:
      t - the query that will be used from now on

    • setSearchOptions

      public final void setSearchOptions(MolSearchOptions searchOptions)
      Loads the search options into this comparator.

    • compareAtoms

      public boolean compareAtoms(int a1, int a2)
      Compares atoms of indices a1 and a2. This method is called during initial match matrix creation.

      The given atom indices are internal search indices, they don't refer to the original molecules directly! You should use getOrigQueryAtom(int) and getOrigTargetAtom(int) to obtain the relevant atoms.

      The default implementation returns true. You can override this method to implement additional matching requirements between atoms.

      Parameters:
      a1 - atom in query (search internal index)
      a2 - atom in target (search internal index)
      Returns:
      whether query atom a1 matches target atom a2
      See Also:

    • compareBonds

      public boolean compareBonds(int b1, int b2)
      Compares bonds of indices b1 and b2. This method is called during the refinement part of the search process.

      The given bond indices are internal search indices, they don't refer to the original molecules directly! You should use getOrigQueryBond(int) and getOrigTargetBond(int) to obtain the relevant atoms.

      The default implementation returns true. You can override this method to implement additional matching requirements between bonds.

      Parameters:
      b1 - bond index in query
      b2 - bond index in target
      Returns:
      whether the two bonds match

    • compareHit

      public boolean compareHit(int[] internalHit, int internalHitLength)
      Checks a partial hit during the search algorithm.

      The default implementation returns true. You can override this method to implement additional matching requirements. It is useful if the matching criteria involves multiple query or target atoms.

      Parameters:
      internalHit - the current hit vector from the associated search object that contains atom indices of internal search representation. Strictly read only! The values of this array are incremented by 1 because of algorithmic reasons. This vector may contain only a partial match, so possibly not all query atoms have associated matchings.
      You can get original atom indexes by using getOrigQueryAtom(int) (from array indexes) and getOrigTargetAtom(int) (from array values - do not forget to call a decreased value: getOrigTargetAtom(internalHit[i]-1) ).
      For efficiency reasons, an array longer than necessary is returned, parameter internalHitLength contains the effective length of the array.
      The search algorithm is incremental, so for the call history of this method a (partial) hit vector is preceded by its shorter prefixes of size at least 2. (This means that for a partial hit vector [1, 5, 2, 3], hit vectors [1, 5] and [1, 5, 2] have already been checked.)
      internalHitLength - the effective length of internalHit.
      Returns:
      true if the partial hit describes a correct query-target correspondence.
      See Also:

    • getOrigQueryAtom

      public final int getOrigQueryAtom(int a1)
      Converts search internal atom index (in the query) to the original atom index in the query molecule.
      Parameters:
      a1 - internal query atom index
      Returns:
      The atom index in the query molecule or -1 if no corresponding atom exists. (e.g. implicit H. In this case, getOrigQueryNeighbour(int) may be helpful.)

    • getOrigTargetAtom

      public final int getOrigTargetAtom(int a1)
      Converts search internal atom index (in the target) to the original atom index in the target molecule.
      Parameters:
      a1 - internal target atom index
      Returns:
      The atom index in the target molecule or -1 if no corresponding atom exists. (E.g. implicit H atoms. In this case, getOrigTargetNeighbour(int) may be helpful.)

    • getOrigTargetNeighbour

      public final int getOrigTargetNeighbour(int a)
      For a search internal atom index (in the target), returns a neighbour atom index (original atom index in the target molecule).
      Parameters:
      a - internal target atom index
      Returns:
      The neighbour atom index in the molecule or -1 if no neighbour atom exists. (e.g. isolated atom)
      See Also:

    • getOrigQueryNeighbour

      public final int getOrigQueryNeighbour(int a)
      For a search internal atom index (in the query), returns a neighbour atom index (original atom index in the query molecule).
      Parameters:
      a - internal query atom index
      Returns:
      The neighbour atom index in the molecule or -1 if no neighbour atom exists. (e.g. isolated atom)
      See Also:

    • isUsefulForQuery

      public int isUsefulForQuery()
      Decides based on the query and the search object if the comparator should be used or not. Override to save execution time of the search. If MAYBE_USEFUL is returned by this method, isUsefulForTarget is also called.
      Returns:
      USEFUL (default), MAYBE_USEFUL or NOT_USEFUL.
      See Also:

    • isUsefulForTarget

      public int isUsefulForTarget()
      Decides based on the query, target and the search object if the comparator should be used or not. Override to save execution time of the search. It is only used after isUsefulForQuery returned MAYBE_USEFUL
      Returns:
      USEFUL (default) or NOT_USEFUL.
      See Also:

    • getOrigQueryAtom1

      public final int getOrigQueryAtom1(int bi)
      Returns the index of the first atom (atom index in the query molecule) of the given query bond(search internal bond index in the query).
      Parameters:
      bi - internal query bond index
      Returns:
      The atom index in the query molecule or -1 if no corresponding atom exists. (e.g. implicit H.)
      Since:
      JChem 3.2.3

    • getOrigQueryAtom2

      public final int getOrigQueryAtom2(int bi)
      Returns the index of the second atom (atom index in the query molecule) of the given query bond(search internal bond index in the query).
      Parameters:
      bi - internal query bond index
      Returns:
      The atom index in the query molecule or -1 if no corresponding atom exists. (e.g. implicit H.)
      Since:
      JChem 3.2.3

    • getOrigTargetAtom1

      public final int getOrigTargetAtom1(int bi)
      Returns the index of the first atom (atom index in the target molecule) of the given target bond(search internal bond index in the target).
      Parameters:
      bi - internal target bond index
      Returns:
      The atom index in the target molecule or -1 if no corresponding atom exists. (e.g. implicit H.)
      Since:
      JChem 3.2.3

    • getOrigTargetAtom2

      public final int getOrigTargetAtom2(int bi)
      Returns the index of the second atom (atom index in the target molecule) of the given target bond(search internal bond index in the target).
      Parameters:
      bi - internal target bond index
      Returns:
      The atom index in the target molecule or -1 if no corresponding atom exists. (e.g. implicit H.)
      Since:
      JChem 3.2.3

    • getOrigQueryBond

      public final int getOrigQueryBond(int bi)
      Returns bond index in the query molecule for the given query bond (search internal bond index in the query).
      Parameters:
      bi - internal query bond index
      Returns:
      The bond index in the query molecule or -1 if no corresponding atom exists. (e.g. relating to an implicit H.)
      Since:
      JChem 3.2.3

    • getOrigTargetBond

      public final int getOrigTargetBond(int bi)
      Returns bond index in the target molecule for the given target bond (search internal bond index in the target).
      Parameters:
      bi - internal target bond index
      Returns:
      The bond index in the target molecule or -1 if no corresponding atom exists. (e.g. relating to an implicit H.)
      Since:
      JChem 3.2.3