Class McsSearchResult


  • @PublicAPI
    public final class McsSearchResult
    extends Object
    Class for representing the result of a MaxCommonSubstructure (MCS) search. It stores a mapping between common substructures of two molecules.

    The search result objects returned by an instance of MaxCommonSubstructure class can be considered immutable as the underlying molecules are copies of the original ones and they can never be changed.

    • Constructor Detail

      • McsSearchResult

        public McsSearchResult​(Molecule target,
                               int[] atomMap,
                               int[] bondMap,
                               int fragmentCount)
        Creates a SearchResult object representing a common substructure of two molecules.

        The constructor does not check for validity of its parameters! Furthermore, the Molecule object is NOT cloned, so it should not be modified after the construction of this object.

        Parameters:
        target - the target molecule.
        atomMap - atom mapping, see getAtomMapping()
        bondMap - bond mapping, see getBondMapping()
        fragmentCount - number of fragments in the common substructure
    • Method Detail

      • isEmpty

        public boolean isEmpty()
        Checks whether the common substructure contains any bonds or is empty.
        Returns:
        true if the common substructure contains is empty.
      • getAtomCount

        public int getAtomCount()
        Gets the number of atoms in the found common substructure.
        Returns:
        number of atoms in common substructure
      • getBondCount

        public int getBondCount()
        Gets the number of bonds in the found common substructure.
        Returns:
        number of bonds in common substructure
      • getFragmentCount

        public int getFragmentCount()
        Gets the number of fragments in the found common substructure.
        Returns:
        number of fragments in common substructure
      • getAtomMapping

        public int[] getAtomMapping()
        Gets the atom mapping of the found common substructure. The result is a mapping from query atom indices to target atom indices.

        This method returns a clone copy of the internally stored array. Its result should be stored instead of multiple calls.

        Returns:
        Mapping between the atoms of the query and target structures. The i-th element of the array is the index of the target atom that is matched with the i-th query atom, or -1 if no such atom is found in the target molecule.
      • getAtomReverseMapping

        public int[] getAtomReverseMapping()
        Gets the reverse atom mapping of the found common substructure. The result is a mapping from target atom indices to query atom indices.

        This method returns a clone copy of the internally stored array. Its result should be stored instead of multiple calls.

        Returns:
        Mapping between the atoms of the target and query structures. The i-th element of the array is the index of the query atom that is matched with the i-th target atom, or -1 if no such atom is found in the query molecule.
      • getBondMapping

        public int[] getBondMapping()
        Gets the bond mapping of the found common substructure. The result is a mapping from query bond indices to target bond indices.

        This method returns a clone copy of the internally stored array. Its result should be stored instead of multiple calls.

        Returns:
        Mapping between the bonds of the query and target structures. The i-th element of the array is the index of the target bond that is matched with the i-th query bond, or -1 if no such bond is found in the target molecule.
      • getBondReverseMapping

        public int[] getBondReverseMapping()
        Gets the reverse bond mapping of the found common substructure. The result is a mapping from target bond indices to query bond indices.

        This method returns a clone copy of the internally stored array. Its result should be stored instead of multiple calls.

        Returns:
        Mapping between the bonds of the target and query structures. The i-th element of the array is the index of the query bond that is matched with the i-th target bond, or -1 if no such bond is found in the query molecule.
      • getMatchedQueryAtoms

        public List<Integer> getMatchedQueryAtoms()
        Gets the indices of the query atoms that are part of the found common substructure. For each i, the i-th element of getMatchedQueryAtoms() corresponds to the i-th element of getMatchedTargetAtoms().
        Returns:
        the matched atoms of the query molecule
      • getMatchedQueryBonds

        public List<Integer> getMatchedQueryBonds()
        Gets the indices of the query bonds that are part of the found common substructure. For each j, the j-th element of getMatchedQueryBonds() corresponds to the j-th element of getMatchedTargetBonds().
        Returns:
        the matched bonds of the query molecule
      • getMatchedTargetAtoms

        public List<Integer> getMatchedTargetAtoms()
        Gets the indices of the target atoms that are part of the found common substructure. The indices are stored in increasing order. For each i, the i-th element of getMatchedQueryAtoms() corresponds to the i-th element of getMatchedTargetAtoms().
        Returns:
        the matched atoms of the target molecule
      • getMatchedTargetBonds

        public List<Integer> getMatchedTargetBonds()
        Gets the indices of the target bonds that are part of the found common substructure. The indices are stored in increasing order. For each j, the j-th element of getMatchedQueryBonds() corresponds to the j-th element of getMatchedTargetBonds().
        Returns:
        the matched bonds of the target molecule
      • getAsMolecule

        public Molecule getAsMolecule()
        Gets the found common substructure as a Molecule object.

        The returned molecule is originated from the target structure, since the query might contain special non-specific atoms or bonds (e.g., any atom, list atom, any bond, etc.). As a result, the substructure has the same properties (atom types, bond types, coordinates, charges, isotopes, etc.) as the corresponding substructure of the target molecule. Those properties that are not considered during the search, however, could differ from the corresponding substructure of the query molecule.

        This method builds a new Molecule object each time it is called. Its result should be stored instead of multiple calls.

        Returns:
        the common substructure as a new Molecule object
      • getSimilarity

        public float getSimilarity()
        Returns a Tanimoto-like similarity score of the input molecules based on the found maximum common substructure. It is a real number between 0 and 1, where 0 means no similarity at all (no common substructure) and 1 means the molecules are the same. It is calculated as mcsBondCount / (queryBondCount + targetBondCount - mcsBondCount).

        If neither molecules contain bonds, 0 is returned.

        Returns:
        a similarity value between 0 and 1. It equals to 1 - getDissimilarity().
      • getDissimilarity

        public float getDissimilarity()
        Returns a Tanimoto-like dissimilarity metric score of the input molecules based on the found maximum common substructure. It is a real number between 0 and 1, where 0 means the molecules are the same and 1 means no similarity at all (no common substructure). It is calculated as 1 - mcsBondCount / (queryBondCount + targetBondCount - mcsBondCount).

        If neither molecules contain bonds, 1 is returned.

        Returns:
        a dissimilarity value between 0 and 1. It equals to 1 - getSimilarity().