This is a preliminary API and may be improved based on user feedback. It is currently available in C++ and Python.

bool OEScreen(const OESubSearchScreen &query,
              const OESubSearchScreen &target)

Returns whether an OESubSearchScreen object generated for a target molecule can be matched to the OESubSearchScreen object generated for a query molecule.

The code snippet below shows how to generate a screens for a query and a target molecule and how to compare them using OEScreen.

  • OEScreen will throw a warning and returns false if the type of the screens are different.

  • If the query screen has any bit ‘on’ that is ‘off’ in the target molecule (i.e. query has some feature that is not present in the target molecule), the OEScreen function returns false and the target molecule can be eliminated from further consideration since it can not be successfully matched to the query.

  • If all the bits that are ‘on’ in the query screen are also ‘on’ in the target screen, OEScreen returns true and match has to be validated by performing atom-by-atom substructure match (see also OESubSearch).


OEQMol qmol;
OEParseSmarts(qmol, "c1cc[o,n,s]c1");
OESubSearchScreen qscreen;
OEMakeSubSearchQueryScreen(qscreen, qmol, OESubSearchScreenType::SMARTS);

OEGraphMol tmol;
OEParseSmiles(tmol, "c1ccoc1");
OESubSearchScreen tscreen;
OEMakeSubSearchTargetScreen(tscreen, tmol, OESubSearchScreenType::SMARTS);

OESubSearch ss(qmol);

if (OEScreen(qscreen, tscreen))
  if (ss.SingleMatch(tmol))
    std::cout << "match" << std::endl;
    std::cout << "false positive match" << std::endl;
  std::cout << "no match" << std::endl;


All screens provided by OEChem TK are rigorously tested to make sure that they do not eliminate any matches that would succeed when utilizing the more elaborate atom-by-atom substructure search algorithm.

See also