Examples of structure checking in various ChemAxon products

Introduction
Check structures in structurechecker command-line
Check structures in Evaluator
Check structures in JChem Cartridge
Evaluator Reference table
Links

Introduction

The following examples demonstrate how to check/fix structures in various ChemAxon products via the relevant commands and action string defined checker/fixer configurations. Find the valid structure checker action strings online, or type structurechecker -hc for checker action strings and structurechecker -hf for fixer action strings in your preferred command-line interface.

Remember the following tips in order to create a reliable Structure Checker configuration when using action strings.

Action string defined Structure Checker configuration has to be specified between quotation marks ("...").
Subsequent action strings must be separated by "..". Example:
```
"alias..radical..aromaticity"
```
Comment:
This configuration in check mode searches for atoms with alias information first, then for radical atoms, and finally for aromaticity errors with default aromatization type (general), as no checker option is indicated.
When a checker or fixer has further options, you can define the wanted option(s) as a colon (:) disconnected list after the checker (or fixer) action string. When no option(s) is defined, default option will be used. Example:
```
"aromaticity:loose"
```
Structure Checker searches only for loose aromatic systems.
```
"atomqueryproperty:R=true:a=true"
```
Structure Checker searches only for "ring count" and "aromaticity" type atom query properties.
```
"atomqueryproperty:R=true:a=true..alias..aromaticity"
```
Structure Checker searches only for ring count and aromaticity like atom query properties, finds atoms with alias information, and detects "general" aromatic systems (the option of aromaticity checker is "general" by default).
You can set check or fix mode to be performed.
- Check mode is suitable mostly for report generation. The report provides information about the errors and problems detected in molecules. In "check" mode, only checker actions are taken into account; additional fixers will not modify the checking behavior.
- In fix mode, Structure Checker processes molecules based on the set checker and fixer action strings. Automatically fixable issues are modified according to the set configuration.
First define the checker action string and then the relevant fixer action string using the following schema: checkerActionString->fixerActionSting.
In fix mode, when no additional fixer action string is defined after a checker action string, all fixers of the relevant checker will be applied in priority order.
Example:
```
"abbrevgroup:contracted=true->expandgroup..alias->aliastogroup..staratom" 
```
In fix mode, Structure Checker searches for contracted abbreviated groups and expands them then finds any aliases and converts them to groups. Finally, Structure Checker searches for star atoms and applies fixer "convert to carbon atoms" as higher priority fixer. If fixer "convert to carbon atoms" has not solved the issue, the next fixer in line "remove atom" will be applied.

Example: `structurechecker` command-line

To run a structure check, define your command as follows: structurechecker command followed by the configuration as xml file or action strings and the structure to be checked.

```
structurechecker -c configuration.xml strchk_input.mrv -f mrv -o output.mrv -rp
```
Structure(s) of strchk_input.mrv is checked according to the actions of configuration.xml. Output file is saved in MRV format as output.mrv and checker result is written to the propery fields of output file.
```
structurechecker -c "abbrevgroup:contracted=true..explicith:mapped=true:wedged=true" strchk_input.mrv -f mrv -o output.mrv -rp 
```
Structure Checker finds only contracted abbreviated groups and any explicit hydrogens, mapped, or wedged explicit hydrogens. Output file is saved in MRV format as output.mrv and checker result is written to the propery fields of output file.
```
structurechecker -c "abbrevgroup:contracted=true->expandgroup..explicith:mapped=true:wedged=true" strchk_input.mrv -m fix 
```
Result:
```
[2H]C1=CC(C[C@H](C)CC(O)=O)=CC=C1
```
Structure Checker finds only contracted abbreviated groups and uses "expand group" fixer on them and finds any explicit hydrogens, mapped, or wedged explicit hydrogens and removes them.

Chemical Terms language enable checking, fixing, or filtering of structures according to a given action string configuration. Use this feature in Evaluator or JChem Cartridge.

Example: Check structures in Evaluator

The examples below demonstrate how to use structure checking in Chemical Terms Evaluator command line tool (evaluate). There are three modes to select in evaluate: check, fix, or filter structures via the check() , fix() , or isValid() commands, respectively. Please, pay attention to the usage of single (') and double (") quotation marks around commands and configuration.

evaluate -e "check('explicith:mapped=true:lonely=true:wedged=true..substructure:[CH3]')" "[H]C1=C([H])C(C)=CC(=C1)N(=O)=O" "[H]C1=CC(C)=CC=C1" "CC1=CC(=CC=C1)N(=O)=O" "N1C=CC=C1"

Result:

failed, Explicit Hydrogen Checker: 2 explicit hydrogens found, Substructure Checker: 1 substructure found
failed, Explicit Hydrogen Checker: 1 explicit hydrogen found, Substructure Checker: 1 substructure found
failed, Substructure Checker: 1 substructure found
passed

Comment on the result:
evaluate checks the input structures considering the actions strings, and returns the following report:

"failed": The set actions found structural issues during scanning the input; when no issues are identified, the result is "passed";
Names of checkers that have found any issue separated by commas (,);
The number of certain issue types.

evaluate -e "fix('explicith:mapped=true:lonely=true:wedged=true..substructure:[CH3]>>[CH2]C')" "[H]C1=C([H])C(C)=CC(=C1)N(=O)=O" "[H]C1=CC(C)=CC=C1" "CC1=CC(=CC=C1)N(=O)=O" "N1C=CC=C1"

Result:

CCC1=CC(=CC=C1)N(=O)=O
CCC1=CC=CC=C1
CCC1=CC(=CC=C1)N(=O)=O
N1C=CC=C1

evaluate returns the fixed structures based on the set fixer action strings ("remove explicit hydrogen" and "transform"), or else the original structure.

evaluate -e "isValid('explicith:mapped=true:lonely=true:wedged=true..substructure:[CH3]>>[CH2]C')" "[H]C1=C([H])C(C)=CC(=C1)N(=O)=O" "[H]C1=CC(C)=CC=C1" "CC1=CC(=CC=C1)N(=O)=O" "N1C=CC=C1"

Result:

false
false
false
true

evaluate returns false or true.

"false": The set actions found structural issues during scanning the input;
"true": No issues were found during scanning the input.

Example: Check structures in JChem Cartridge

The examples below demonstrate how to use structure checking in JChem Cartridge. Please, pay attention to the usage of single (') and double (") quotation marks around commands and configuration.

In general:

 select jc_evaluate_x('<input_structure>','chemTerms:check("aromaticity..valence..queryAtom..queryBond")') from dual;

The following SQL query checks the structure for errors, according to the configuration:
```
select jc_evaluate('C[C](C)(C)(C)c1ccocc1', 'isValid("aromaticity..valence..queryAtom..queryBond")') from dual;
```
Returns 0 indicating that the structure is not valid, i.e., examined molecule contains error(s) according to the configuration.
The following SQL query checks the structure for errors, according to the action string defined configuration, returns the result (passed/failed) along with (in the case of the structure is invalid) a short explanation why the structure is invalid:
```
select jc_evaluate_x('C[C](C)(C)(C)c1ccocc1', 'chemTerms:check("aromaticity..valence..queryAtom..queryBond")') from dual
```
Returns:
```
failed, Aromaticity Error Checker: 6 wrong aromatic bonds found, Valence Error Checker: 1 atom with valence problem found
```

The following SQL queries check the structure for errors, according to the configuration, and then fix the errors:

select jc_evaluate_x('[H]C1=C([H])C([H])=C([3H])C([2H])=C1[1H]',
    'chemTerms:fix("explicitH->removeExplicitH..valence->fixValence..bondAngle->clean..atomMap..abbrevGroup->contractGroup")')
    from dual

Returns:

[1H]C1=C([2H])C([3H])=CC=C1

As no further option of explicit hydrogen checker is set, fix mode removes only "simple" explicit hydrogens, isotopes are not removed. To remove isotopic hydrogen as well, select the explicith:isotopic=true option.

select jc_evaluate_x('[H]C1=C([H])C([H])=C([3H])C([2H])=C1[1H]',
    'chemTerms:fix("explicitH:isotopic=true->removeExplicitH..valence->fixValence..bondAngle->clean..atomMap..abbrevGroup->contractGroup")')
    from dual

returns:

C1=CC=CC=C1

Structure Checker Evaluator Functions

Name License Description Return value Parameters Examples

Name	License	Description	Return value	Parameters	Examples
check	-	checks the structure for errors, according to the configuration	the error report	Structure checker/fixer configuration string	Molecule Context (All) `check("aromaticity..valence")` checks for aromaticity and valence errors, and returns the error report Reaction Context (All) `check(reactant(0), "aromaticity..valence")` checks for aromaticity and valence errors in first reactant, and returns the error report
fix	-	checks the structure for errors, according to the configuration, and then fixes the errors	the fixed molecule	Structure checker/fixer configuration string	Molecule Context (All) `fix("explicitH..isotope->converttoelementalform")` searches for explicit hydrogens and isotopes, and removes them or converts them to elemental form Reaction Context (All) `fix(product(1), "explicitH..isotope->converttoelementalform")` searches for explicit hydrogens and isotopes in second product, and removes them or converts them to elemental form
isValid	-	checks the structure for errors, according to the configuration	true, if the structure is valid (has no errors), false othervise	Structure checker/fixer configuration string	Molecule Context (All) `isValid("aromaticity..valence")` checks for aromaticity and valence errors, and returns if the structure is valid Reaction Context (All) `isValid(reactant(0), "aromaticity..valence")` checks for aromaticity and valence errors in first reactant, and returns if it is valid

check

checks the structure for errors, according to the configuration

the error report

Structure checker/fixer configuration string

Molecule Context (All)

check("aromaticity..valence") checks for aromaticity and valence errors, and returns the error report

Reaction Context (All)

check(reactant(0), "aromaticity..valence") checks for aromaticity and valence errors in first reactant, and returns the error report

fix

checks the structure for errors, according to the configuration, and then fixes the errors

the fixed molecule

Structure checker/fixer configuration string

Molecule Context (All)

fix("explicitH..isotope->converttoelementalform") searches for explicit hydrogens and isotopes, and removes them or converts them to elemental form

Reaction Context (All)

fix(product(1),
						"explicitH..isotope->converttoelementalform")

searches for explicit hydrogens and isotopes in second product, and removes them or converts them to elemental form

isValid

checks the structure for errors, according to the configuration

true, if the structure is valid (has no errors), false othervise

Structure checker/fixer configuration string

Molecule Context (All)

isValid("aromaticity..valence") checks for aromaticity and valence errors, and returns if the structure is valid

Reaction Context (All)

isValid(reactant(0), "aromaticity..valence") checks for aromaticity and valence errors in first reactant, and returns if it is valid

Links

List of available checkers

Structure Checker GUI

Structure Checker in MarvinSketch

structurechecker Command Line Tool

Structure Checker Developer Guide

Examples of structure checking in various ChemAxon products

Contents

Introduction

Example: structurechecker command-line

Chemical Terms language enable checking, fixing, or filtering of structures according to a given action string configuration. Use this feature in Evaluator or JChem Cartridge.

Example: Check structures in Evaluator

Example: Check structures in JChem Cartridge

Structure Checker Evaluator Functions

Links

Example: `structurechecker` command-line