setImplicitHMatching()

Can you explain the fairly new feature setImplicitHMatching() and its three options? The API is unclear. If you look at the entry for IMPLICIT_H_MATCHING_DISABLED, it says,

Code:

Option value constant for indicate matching between explicit hydrogens only. // * @see #OPTION_IMPLICIT_H_MATCHING

but there is no entry for OPTION_IMPLICIT_H_MATCHING. It looks like you were trying to comment out that line, but you misplaced your //.





As I see it, there are three possible ways to match H atoms when doing *exact* searches:





(1) Explicit H atoms in the query may be implicit in the target, and vice versa.


(2) Explicit H atoms in the query must be explicit in the target, but explicit H atoms in the target may be implicit in the query.


(3) Explicit H atoms in the query must be explicit in the target, and vice versa.





The JChem Query Guide discusses explicit H atoms in queries in *substructure* searches, but it contains no references to API variables. And it's not clear to me whether setImplicitHMatching() is supposed to apply to exact searches, substructure searches, or both.

Hi Bob,





I've moved this topic to the appropriate forum.





Best regards,





Akos

Hi Bob,





setImplicitHMatching() applies to exact (and perfect) search as well.





By default implicit and explicit hydrogens can match if it is needed (IMPLICIT_H_MATCHING_DEFAULT), it's (1) in your list. You can override this behaviour with IMPLICIT_H_MATCHING_DISABLED, (2) in your list.





There is only one exception to the rule: perfect search in a database query table. In this case implicit and explicit hydrogen matching is disabled by default, but you can override this by setting IMPLICIT_H_MATCHING_ENABLED.





OPTION_IMPLICIT_H_MATCHING was to introduce in 5.0 but in the final implementation it was omitted.


We will fix the apidoc in our next release. Is it OK something like this?

Quote:

IMPLICIT_H_MATCHING_DISABLED: indicates that an explicit hydrogen can match only to another explicit hydrogen

Regards,


Tamás

So the meaning of IMPLICIT_H_MATCHING_DEFAULT is different depending on the type of search? That's *very* confusing. I would get rid of that constant entirely, and just say in the documentation that implicit H matching is set to IMPLICIT_H_MATCHING_DISABLED for perfect database (JChemSearch?) searches, and to IMPLICIT_H_MATCHING_ENABLED otherwise.





By "database searches", you mean JChemSearch, right? So in MolSearch, the option is always set to IMPLICIT_H_MATCHING_ENABLED, regardless of whether the search type is set to perfect?





I would like to see a third value for setImplicitHMatching(), which would be (3) on my list. Right now, we do (3) by converting all explicit H atoms in both query and target into pseudoatoms. But it would be more convenient just to set a MolSearch option. We need this option to deal with student's responses that contain valence errors. You could call it, "IMPLICIT_H_EXISTENCE_IGNORED".

I would also suggest new names for the constants. Even knowing what they mean, I find the current constant names confusing. I suggest:





IMPLICIT_H_MATCHING_DISABLED -> EXPLICIT_H_REQUIRED_IN_TARGET





IMPLICIT_H_MATCHING_ENABLED -> EXPLICIT_H_NOT_REQUIRED_IN_TARGET





(After all, if setImplicitHMatching() is set to IMPLICIT_H_MATCHING_ENABLED, the target may have no H at all, implicit or explicit.)





Then my previous suggestion:





IMPLICIT_H_EXISTENCE_IGNORED ->


EXPLICIT_H_REQUIRED_IN_BOTH

Hi Bob,





Sorry for the late answer.

Quote:

So the meaning of IMPLICIT_H_MATCHING_DEFAULT is different depending on the type of search? That's *very* confusing. I would get rid of that constant entirely, [...]

   


We have to know whether the user has set the option or it has its default value so we need this constant. Also, the mentioned exception is a special case of searches, those who use query tables.

Quote:

So in MolSearch, the option is always set to IMPLICIT_H_MATCHING_ENABLED, regardless of whether the search type is set to perfect?

   


Yes, e.g.


perfect search; query: C[H]; target: C --> matches

Quote:

I would like to see a third value for setImplicitHMatching(), which would be (3) on my list. Right now, we do (3) by converting all explicit H atoms in both query and target into pseudoatoms.

  


You may check explicit hydrogen matching in a custom MolComparator (compare the number of explicit hydrogen ligands of the atoms). Does it help? If not, please send some examples.





We will consider renaming constants, thanks for your suggestions.





Regards,


Tamás

Quote:

You may check explicit hydrogen matching in a custom MolComparator (compare the number of explicit hydrogen ligands of the atoms). Does it help? If not, please send some examples.

Oh, yeah, good idea.  MolComparator is new enough that I don't think about it much.  We'll look into it.