Migration guide to JChem Choral from JChem Oracle Cartridge

The aim of this page is to provide help for migrating applications based on JChem Oracle Cartridge (JOC) API to JChem Choral API by collecting their different solutions for the main functionality areas.
This page supplements the information available on the below linked video and pages.

Migration demo

Comparison documentation

JChem Oracle Cartridge API documentation

JChem Oracle Cartridge Developer guide

JChem Choral API documentation

How to apply in Choral the business logic set as CREATE INDEX parameters in JOC

JOC provides many CREATE INDEX parameters for setting different business logic to the given structure column.
Choral does not provide any CREATE INDEX parameter. The business logic settings can be applied differently, mainly by the configuration of Molecule types.

JOC also provides some ALTER INDEX parameters, but
ALTER INDEX cannot be applied on _idxtype Choral domain indexes.

	JOC Parameter(s)	Choral solution	Comment
JChem table specific parameters	JChemPropertiesTable regenerateTable	N/A	JChem tables are not supported in Choral
type of structures (molecules, queries, reactions, any structures, markush)	structureType	specification is not needed markush type is not supported
stereo assumption mode (absolute or relative)	absoluteStereo	in Molecule type file: stereoAssumption parameter
standardizer configuration	std_config std_conf:sql	in Molecule type file: standardizerAction setting or standardizerFile parameter
fingerprint configuration	pat_length fp_size fp_bit	in Molecule type file the following parameters: fpLenght fpEdges fpOnes
tautomer mode	tautomerEqualityMode	in Molecule type file: tautomer parameter
duplicate filtering	duplicateFiltering	N/A	recommended solution: execute duplicate search against the table before inserting a structure into it if multiple structures are to be inserted, batch this operation using a temporary table
considering tautomers in duplicate search by default	TDF	in Molecule type file: tautomer parameter apply _idxtype and _search where the file contains the needed tautomer parameter	Note, that in this case the specified tautomer mode will be used in case of substructure and full fragment searches as well.
Chemical Terms columns	autoCalcCt	standard SQL ALTER table, UPDATE TABLE methods using the appropriate chemterm function	see example here
specifying table name where non indexable structures are stored	errorTableName	N/A	See here how to check for invalid structures in the table or in the index.

How to migrate jc_compare search cases

In JOC, there are many search options implemented. See their list at jc_compare.
Choral has only a few search options. The table below contains mainly only those JOC search options which have their Choral equivalent or almost equivalent.

General search syntax in JOC

SELECT * FROM <tablename> where <JOC_owner>.jc_compare(<column>, '<query_structure>', '<parameters>')=1;

where

• : all the available search types, the additional options and their possible combinations

General search syntax in Choral

SELECT * FROM <tablename> where <choral_owner>.<type>_search(<column>, '<query_structure>', '<parameters>', '[parameters]')=1;

where

• : the Molecule type file name
• : available search types (DUPLICATE, FULLFRAGMENT, SUBSTRUCTURE, SUPERSTRUCTURE, SIMILARITY)
• [parameters]: options (IGNOREISOTOPE, IGNORECHARGE, DBSMARKEDONLY, IGNORETETRAHEDRALSTEREO and their combinations)

	JOC Parameters	Choral solution	Comment
duplicate search	t:d	DUPLICATE	in JOC jc_equals also provides duplicate search
substructure search	t:s	SUBSTRUCTURE	in JOC jc_contains also provides substructure search
full fragment search	t:ff	FULLFRAGMENT	works the same way in Choral as in JOC
full structure search	t:f	N/A	recommended solution: FULLFRAGMENT search with an additional condition for fragment count matching - using fragmentCount Chemical Terms - requiring the same fragment count for the query and target see example here
superstructure search	t:u	SUPERSTRUCTURE	works the same way in Choral as in JOC
similarity search	t:i	SIMILARITY	in JOC jc_tanimoto and jc_dissimilarity also provide similarity search
	dissimilarityThreshold simThreshold	threshold defined after the comparison operator see syntax here
	dissimilarityMetric	N/A	only Tanimoto metric is supported in Choral
tautomer search	tautomerSearch	in Molecule type file: tautomer parameter the type file name applied in _search	Choral provides variety of tautomer combinations for duplicate and substructure search: GENERIC, NORMAL_CANONIC_GENERIC_HYBRID, NORMAL_CANONIC_NORMAL_GENERIC_HYBRID see details here
isotope	isotope	IGNOREISOTOPE only in substructure and full fragment search
charge	charge	IGNORECHARGE only in substructure and full fragment search
double bond stereo	doubleBondStereo	DBSMARKEDONLY only in substructure and full fragment search
tetrahedral stereo	ignore tetrahedral stereo	IGNORETETRAHEDRALSTEREO only in substructure and full fragment search

To be also taken into account:

JOC: Those SMILES/SMARTS strings which can be interpreted even in SMILES and SMARTS, the default interpretation mode is SMARTS in case of query structures.
Choral: Those SMILES/SMARTS strings which can be interpreted even in SMILES and SMARTS, the default interpretation mode is SMILES in case of query structures.

How to migrate jc_standardize cases

Refers to jc_standardizeb and their function analogues as well.
In Choral, the standardization actions are defined in the Molecule type files. These Molecule type files must be defined upfront and need to be initialized by running init-choral or update-choral.

Syntax in JOC

jc_standardize(structure IN VARCHAR2/CLOB/BLOB, param IN VARCHAR2) RETURN VARCHAR2/CLOB/BLOB;

where param can be the standardizer action string or configuration

Syntax in Choral

<type>_standardize('molecule')

where is the name of Molecule type file containing the relevant standardizer configuration

How to migrate jc_molconvert cases

Refers to jc_molconvert analogues (like jc_molconvertc, jcf.molconvert, jcf.moconvertc, ...) as well.

Syntax in JOC

jc_molconvert (structure IN VARCHAR2/BLOB/CLOB, options_outputformat IN VARCHAR2) RETURN VARCHAR2/BLOB/CLOB;

Syntax in Choral

molconvert('structure','format')

How to migrate jc_evaluate cases

Refers to jc_evaluate analogues (like jc_evaluate_x, jcf.evaluate, jcf.evaluate_x, ...) as well.

Syntax in JOC

jc_evaluate ('structure' IN VARCHAR2/CLOB/BLOB, expression IN VARCHAR2, options IN VARCHAR2)

where options refer to the Chemical Terms expression

Syntax in Choral

chemterm('chemical_term', 'structure')

How to migrate structure checkers/fixers

Syntax in JOC

Structure checker/fixer operations are executed as Chemical Terms.

SELECT jc_evaluate_x('structure', 'chemTerms:check("checkerAction")') from dual;

SELECT jc_evaluate_x('structure', 'chemTerms:fix("checkerAction->fixerAction")') from dual;

Syntax in Choral

Structure checker/fixer operations are executed as Chemical Terms.

SELECT chemterm('check(''checkerAction’')','structure') FROM DUAL;

SELECT chemterm('fix(''checkerAction->fixerAction'')','structure') FROM DUAL;