datagrok-chem-toolkit

Function catalog for the structure-and-modeling half of Datagrok cheminformatics: Chem, Admetica.

Every function below is callable through the datagrok_exec tool via grok.functions.call('<Package>:<funcName>', {param1, param2, ...}). For ones exposed under a top-menu path, the path is shown so you can describe it in plain language ("Top menu → Chem → ...").

Param-type conventions used below

Types match the Datagrok function declarations: dataframe, column, string, int, float, bool, list<T>, object. A column with a required semType is written column<semType> (e.g. column<Molecule>, column<Macromolecule>, column<numerical>). Choices for enum-style params are listed inline as 'a' | 'b' | 'c'. ? marks optional, = x shows the default.

Always emit an exec block when the intent is clear

If the user asks for a concrete chemistry action ("generate analogs", "dock these ligands", "compute IC50", "register this compound", "what is the SMILES of aspirin") — call datagrok_exec with code calling the relevant function below, even if some args have to be guessed from context (table columns, sensible defaults). Don't ask the user to re-state inputs you can already infer; if a required input is genuinely missing, still emit the block with the best guess and add a one-line note. Don't answer chemistry questions from memory when a catalog function exists — call the function.

---

Cross-package routing — "User wants X → call Y"

User intent	Function	Package
Draw / depict a molecule	Chem:drawMolecule	Chem
Convert SMILES ↔ Molfile ↔ SMARTS ↔ InChI	Chem:convertMolNotation	Chem
Get InChI / InChI key	Chem:getInchis, Chem:getInchiKeys	Chem
Molecular formula	Chem:getMolecularFormula	Chem
Canonical SMILES	Chem:canonicalize	Chem
Validate SMILES (RDKit)	Chem:validateMolecule, Chem:isSmiles, Chem:isSmarts	Chem
Basic properties (MW, LogP, HBA, HBD, PSA, ...)	Chem:addChemPropertiesColumns or Chem:getProperties	Chem
Single-molecule cLogP only	Chem:getCLogP	Chem
Chemical descriptors (RDKit set)	Chem:getDescriptors / Chem:chemDescriptors	Chem
Toxicity risks (OCL: mutagenicity, tumorigenicity, ...)	Chem:addChemRisksColumns or Chem:getToxicityRisks	Chem
Structural alerts (PAINS, BMS, SureChEMBL, ...)	Chem:structuralAlertsTopMenu or Chem:getStructuralAlerts	Chem
Pharmacophore features (donor, acceptor, ...)	Chem:pharmacophoreFeaturesTopMenu	Chem
Morgan / RDKit / MACCS / AtomPair fingerprints	Chem:getMorganFingerprints, Chem:getFingerprints	Chem
Find similar molecules in a column	Chem:findSimilar, Chem:callChemSimilaritySearch	Chem
Tanimoto similarity matrix	Chem:similarityMatrixTopMenu	Chem
Substructure search	Chem:searchSubstructure, Chem:SubstructureSearchTopMenu	Chem
Chemical space 2D (UMAP / t-SNE)	Chem:chemSpaceTopMenu	Chem
Diversity picking	Chem:callChemDiversitySearch	Chem
BitBIRCH O(N) clustering	Chem:bitbirchClusteringTopMenu	Chem
Cluster MCS (most-common-substructure per cluster)	Chem:performClusterMCS	Chem
R-Group decomposition	Chem:rGroupsAnalysisMenu, Chem:rGroupDecomposition	Chem
Matched Molecular Pairs	Chem:mmpAnalysis	Chem
Activity cliffs	Chem:activityCliffs	Chem
Scaffold tree (hierarchical)	Chem:getScaffoldTree, Chem:addScaffoldTree	Chem
Elemental analysis (atom counts)	Chem:elementalAnalysis	Chem
Synthon (REAL-like) space search	Chem:synthonSearchFunc	Chem
Drug name(s) → SMILES (ibuprofen, aspirin, ...)	Chem:namesToSmiles (ChEMBL-backed; needs Chembl pkg)	Chem
Free text → SMILES (LLM fallback)	Chem:freeTextToSmiles	Chem
Map IDs incl. InChI key → ChEMBL, ChEMBL → DrugBank, etc.	Chem:getMapIdentifiers / Chem:mapIdentifiersTransform	Chem
MPO score (weighted desirability)	Chem:mpoCalculate, Chem:_mpo	Chem
Apply reaction SMARTS (transformation)	Chem:transformationReactionsTopMenu	Chem
Two-column reaction enumeration	Chem:twoComponentReactionTopMenu	Chem
Remove water and salts	Chem:removeWaterAndSaltsTopMenu	Chem
Deprotect (remove protecting groups)	Chem:deprotect	Chem
Recalculate 2D coordinates	Chem:recalculateCoords	Chem
Train Chemprop QSAR model	Chem:trainChemprop	Chem
Apply Chemprop QSAR model	Chem:applyChemprop	Chem
ADMET predictions (full panel)	Admetica:getAdmeProperties	Admetica
ADMET for single molecule	Admetica:getAdmePropertiesSingle	Admetica
ADMET in Hit Triage pipeline	Admetica:admeticaHT	Admetica

---

Calling conventions for column-based functions

Most Chem functions operate on a DG.Column of molecules and a parent DG.DataFrame. In datagrok_exec code:

const mol = t.columns.bySemType(DG.SEMTYPE.MOLECULE);   // first Molecule column
const res = await grok.functions.call('Chem:getProperties', { molecules: mol });
// res is a DG.DataFrame with one column per requested property

Function tables below carry a Tags column. The values it can hold:

Tag	Meaning
vectorFunc	Returns a DG.DataFrame. Usable from the Add-New-Column dialog and inside a t.columns.addNewCalculated(name, formula) call. Functions WITHOUT this tag cannot be embedded in a formula — call them via grok.functions.call.
join(table)	Output declares action: 'join(table)' — result columns are auto-appended to the input table. Do not also append yourself.
transform	Tagged as a data-sync transform — same behavior as the un-tagged sibling, but tracked in the project history.
topMenu	Has a Top-menu path; otherwise programmatic only.
panel	Context-panel widget — returns DG.Widget, shown in the right side panel.
action	Right-click / context-menu action.

If the molecule notation is unknown, sourceNotation: DG.chem.Notation.Unknown works for SMILES, SMARTS, molblock, and V3K molblock inputs.

---

Chem package — RDKit/OpenChemLib core (Chem:...)

The flagship cheminformatics package. RDKit is the engine; OpenChemLib provides fallback rendering and a few descriptors (logP, logS, drug-likeness, toxicity).

Four pitfalls to avoid

1. MW / LogP / LogS / HBA / HBD / PSA / Rotatable bonds / Stereo centers / Molecule charge are boolean flags on Chem:addChemPropertiesColumns(...) and strings in the selected list of Chem:getProperties(molecules, selected?). No standalone Chem:CalculateMW / Chem:CalculateLogP etc. exist.
2. Chem:convertMolNotation has no inchi. The sourceNotation / targetNotation enum is 'smiles' | 'cxsmiles' | 'smarts' | 'cxsmarts' | 'molblock' | 'v3Kmolblock'. For InChI use Chem:getInchis / Chem:getInchiKeys. For InChI key → ChEMBL ID, use Chem:getMapIdentifiers / Chem:mapIdentifiersTransform (sources include inchi_key, chembl, pubchem, drugbank, zinc, ...).
3. Chem:namesToSmiles is ChEMBL-backed. It delegates to Chembl:namesToSmiles and will fail if the Chembl package / DB isn't deployed. Still pick it for any "drug name → SMILES" / list-of-names task (aspirin, ibuprofen, caffeine, ...). Don't fall back to Chem:freeTextToSmiles (LLM path, for free-form text fragments). Don't answer from memory.
4. Docking / generation must route to the right package. "Dock these ligands" → Docking:getAutodockResults / Docking:runAutodock or Boltz1:docking — never to a Chem: function. "Generate analogs" / "design new molecules" → Reinvent4:reinvent / Reinvent4:reinventTopMenu — not R-group, MMP, or reaction enumeration (those operate on existing series). Always make the datagrok_exec call; if a target/seed is missing, pass a sensible default (first molecule column, first configured target).

Rendering & notation

Notation enum (used by convertMolNotation, convertMoleculeNotation, convertNotation): 'smiles' | 'cxsmiles' | 'smarts' | 'cxsmarts' | 'molblock' | 'v3Kmolblock'. No inchi — use getInchis / getInchiKeys instead.

Function	Tags	What it does
drawMolecule(molStr: string, w?: int, h?: int, popupMenu?: bool)	—	Returns an HTMLElement of a rendered molecule.
canvasMol(x: int, y: int, w: int, h: int, canvas: object, molString: string, scaffoldMolString: string, options?: object, renderingOptions?: object)	—	Draws into an existing canvas (with optional scaffold highlight).
convertMolNotation(molecule: string, sourceNotation: <notation>, targetNotation: <notation>)	—	Returns a single string in the target notation.
convertMoleculeNotation(molecule: column<Molecule>, targetNotation: <notation>, kekulize?: bool = false)	vectorFunc	Notation conversion. Returns a new DG.Column.
convertNotation(data: dataframe, molecules: column<Molecule>, targetNotation: <notation> = 'smiles', overwrite: bool = false, join: bool = true, kekulize?: bool)	topMenu	Top-menu version: appends or overwrites the column. Top menu: Chem → Transform → Convert Notation.
recalculateCoords(table: dataframe, molecules: column<Molecule>, method: 'OCL' | 'CoordGen' = 'OCL', join: bool = true)	topMenu	Recompute 2D layout. Top menu: Chem → Transform → Recalculate Coordinates.
canonicalize(molecule: string)	—	→ canonical SMILES (string).
getInchis(molecules: column<Molecule>) / getInchiKeys(molecules: column<Molecule>)	vectorFunc	Vector InChI / InChI key.
addInchisTopMenu(table: dataframe, molecules: column<Molecule>) / addInchisKeysTopMenu(table: dataframe, molecules: column<Molecule>)	topMenu	Append as a new column. Top menu: Chem → Calculate → To InchI / To InchI Keys.
getMolecularFormula(molecule: string)	—	Hill formula string (via OCL).
isSmiles(s: string) / isSmarts(s: string) / validateMolecule(s: string)	—	RDKit-based validators. validateMolecule returns the RDKit error string or null if OK.
detectSmiles(col: column, min: int)	—	Heuristic — tags the column as SMILES / Molecule if enough cells parse.
getMolFileHandler(molString)	—	Returns a low-level molfile parser handler.
getRdKitModule()	—	Returns the raw RDKit-JS module (for advanced calls like mol.get_descriptors()).
chemCellRenderer / rdKitCellRenderer / rdKitReactionRenderer / rdKitMixtureRenderer	—	Cell renderers — call only via the grid system, not directly.
editMoleculeCell(cell)	—	Pops a sketcher dialog bound to a grid cell.
openChemLibSketcher()	—	Returns the OCL sketcher widget.

Properties, descriptors, fingerprints

Property names for getProperties(molecules, selected) and equivalent flags on addChemPropertiesColumns: 'MW' | 'HBA' | 'HBD' | 'LogP' | 'LogS' | 'PSA' | 'Rotatable bonds' | 'Stereo centers' | 'Molecule charge'. Pass them in selected as a list of strings, exactly as shown.

Fingerprint enum (<fp>): 'Morgan' | 'RDKit' | 'Pattern' | 'AtomPair' | 'MACCS' | 'TopologicalTorsion'.

Similarity metric enum (<metric>, from BitArrayMetricsNames in @datagrok-libraries/ml): 'Tanimoto' | 'Dice' | 'Asymmetric' | 'Braun-Blanquet' | 'Cosine' | 'Kulczynski' | 'Mc-Connaughey' | 'Rogot-Goldberg' | 'Russel' | 'Sokal' | 'Hamming' | 'Euclidean BitArray'. Default is 'Tanimoto'.

Toxicity risk names for getToxicityRisks(molecules, risks): 'mutagenicity' | 'tumorigenicity' | 'irritatingEffects' | 'reproductiveEffects'.

Structural alert rule sets for getStructuralAlerts(molecules, alerts) and the per-flag args of structuralAlertsTopMenu: 'PAINS' | 'BMS' | 'SureChEMBL' | 'MLSMR' | 'Dundee' | 'Inpharmatica' | 'LINT' | 'Glaxo'.

Function	Tags	What it does
addChemPropertiesColumns(table: dataframe, molecules: column<Molecule>, MW?: bool = true, HBA?: bool = false, HBD?: bool = false, logP?: bool = false, logS?: bool = false, PSA?: bool = false, rotatableBonds?: bool = false, stereoCenters?: bool = false, moleculeCharge?: bool = false)	topMenu	OCL-based properties → appended as columns. Top menu: Chem → Calculate → Chemical Properties.
getProperties(molecules: column<Molecule>, selected?: list<string>)	vectorFunc	Vector form. selected is a subset of the property names above; omit/empty for all. Returns a standalone DataFrame — NOT auto-joined; append its columns to your table yourself.
getCLogP(smiles: string)	—	Single-mol Crippen logP (RDKit).
getChemPropertyFunction(name: string)	—	Returns a (smiles) => any closure for one property — useful for column.applyFormula.
getDescriptors(molecules: column<Molecule>, selected?: list<string>)	vectorFunc	RDKit descriptor set (via Chem docker). Returns a standalone DataFrame — NOT auto-joined; append its columns yourself. Use chemDescriptorsTree() for the legal selected names.
chemDescriptors(table: dataframe, molecules: column<Molecule>, descriptors: list<string>)	topMenu	Same, appended to table.
chemDescriptorsTree()	—	Returns the tree of available descriptor groups (for UI).
descriptorsDocker()	topMenu	Opens the descriptors picker dialog. Top menu: Chem → Calculate → Descriptors.
calculateDescriptorsTransform(table: dataframe, molecules: column<Molecule>, selected: list<string>)	transform	Same but tagged transform for data-sync projects.
getMorganFingerprints(molColumn: column<Molecule>)	vectorFunc	Returns a Column of DG.BitSet fingerprints.
getMorganFingerprint(molString: string)	—	Single-mol → DG.BitSet.
getFingerprints(col: column<Molecule>, _metric?: string, fingerprintType?: <fp>)	—	Returns {entries, options} for the dim-reduction preprocessor.
addChemRisksColumns(table: dataframe, molecules: column<Molecule>, mutagenicity?: bool = true, tumorigenicity?: bool = false, irritatingEffects?: bool = false, reproductiveEffects?: bool = false)	topMenu	OCL toxicity risk flags. Top menu: Chem → Calculate → Toxicity Risks.
getToxicityRisks(molecules: column<Molecule>, risks?: list<string>)	vectorFunc	Vector form. risks is a subset of the risk names above. Returns a standalone DataFrame — NOT auto-joined; append its columns yourself.
structuralAlertsTopMenu(table: dataframe, molecules: column<Molecule>, pains: bool = true, bms: bool = false, sureChembl: bool = false, mlsmr: bool = false, dundee: bool = false, inpharmatica: bool = false, lint: bool = false, glaxo: bool = false)	topMenu	Apply rule-based structural alerts. Top menu: Chem → Analyze → Structural Alerts.
getStructuralAlerts(molecules: column<Molecule>, alerts?: list<string>)	vectorFunc	Vector form. Returns a standalone DataFrame — NOT auto-joined; append its columns yourself.
pharmacophoreFeaturesTopMenu(table: dataframe, molecules: column<Molecule>, donor: bool = true, acceptor: bool = true, hydrophobic: bool = true, aromatic: bool = true, positive: bool = false, negative: bool = false, halogenBond: bool = false)	topMenu	RDKit pharmacophore family flags. Top menu: Chem → Analyze → Pharmacophore Features.
biochemPropsWidget()	topMenu	Opens the auto-discovery dialog for biochem calculators. Top menu: Chem → Calculate → Biochemical Properties.

Similarity, diversity, substructure search

Shorthand recap — <metric> expands to the 12-value BitArrayMetricsNames enum defined above ("Similarity metric enum"); <fp> expands to the 6-value fingerprint enum ("Fingerprint enum"). Used in this section by callChemSimilaritySearch, callChemDiversitySearch, similarityMatrixTopMenu. The dim-reduction entries (chemSpaceTopMenu, getChemSpaceEmbeddings, activityCliffs) hard-narrow <metric> via choices: to the 4-value subset 'Tanimoto' | 'Asymmetric' | 'Cosine' | 'Sokal' — those rows inline the narrowed list directly in the signature.

Function	Tags	What it does
findSimilar(molStringsColumn: column<Molecule>, molString: string, limit: int = MAX, cutoff: float = 0.0)	—	Returns a DataFrame of the most-similar molecules (Morgan/Tanimoto).
callChemSimilaritySearch(df: dataframe, col: column<Molecule>, molecule: string, metricName: <metric>, fingerprint: <fp>, limit: int, minScore: float)	—	Underlying version with explicit metric and FP type.
getSimilarities(molStringsColumn: column<Molecule>, molString: string)	—	Returns just the similarity scores as a DataFrame.
getDiversities(molStringsColumn: column<Molecule>, limit: int)	—	DataFrame of the most-diverse molecules.
callChemDiversitySearch(col: column<Molecule>, metricName: <metric>, fingerprint: <fp>, limit: int)	—	Returns indices of diverse picks.
similarityMatrixTopMenu(table: dataframe, molecules: column<Molecule>, symbols: column, fingerprintType: <fp> = 'Morgan')	topMenu	Full pairwise Tanimoto matrix → opens as a new table. Top menu: Chem → Calculate → Similarity Matrix.
searchSubstructure(molStringsColumn: column<Molecule>, molString: string, molBlockFailover: string)	—	RDKit substructure search → returns a Column wrapping a BitSet of matches.
SubstructureSearchTopMenu(molecules: column<Molecule>)	topMenu	Opens the filter sketcher. Top menu: Chem → Search → Substructure Search.
similaritySearchViewer() / diversitySearchViewer()	—	Returns a ChemSimilarityViewer / ChemDiversityViewer. Add via view.addViewer('Chem Similarity Search').
similaritySearchTopMenu() / diversitySearchTopMenu()	topMenu	Top menu shortcuts. Top menu: Chem → Search.
sortBySimilarity(value: object)	action	Right-click action that sorts the grid by similarity to the picked molecule.
useAsSubstructureFilter(value: object)	action	Right-click action that adds the picked molecule as a substructure filter.
synthonSearchFunc(spaceName: string, molecule: string, maxHits: int = 100, searchType: 'substructure' | 'similarity' | 'exact', similarityCutoff?: float = 0.5, includeSynthons?: bool = false)	—	Search in a synthon (REAL-style) chemical space.
getSynthonSpacesFunc()	—	Lists installed synthon spaces (filenames in Chem/files/synthon-data/).
removeDuplicates(molecules: list<string>, molecule: string)	—	Removes duplicates of molecule from a list.

Chemical space, R-groups, MMP, activity cliffs, scaffold tree

Dim-reduction method enum: 'UMAP' | 't-SNE'. R-group matching strategy: 'Greedy' | 'GreedyChunks' | 'Exhaustive' | 'NoSymmetrization' | 'GA'. MMP diff type: 'delta' | 'ratio'. MMP activity scaling: 'none' | 'lg' | '-lg'.

Function	Tags	What it does
chemSpaceTopMenu(table: dataframe, molecules: column<Molecule>, methodName: 'UMAP' | 't-SNE', similarityMetric: 'Tanimoto' | 'Asymmetric' | 'Cosine' | 'Sokal' = 'Tanimoto', plotEmbeddings: bool = true, options?: object, preprocessingFunction?: func, clusterEmbeddings?: bool, clusterMCS?: bool)	topMenu	Projects molecules to 2D (UMAP / t-SNE) + scatter plot. Top menu: Chem → Analyze → Chemical Space.
chemSpaceTransform(...)	transform	Transform-tagged version (for data-sync).
getChemSpaceEmbeddings(col: column<Molecule>, methodName: 'UMAP' | 't-SNE', similarityMetric: 'Tanimoto' | 'Asymmetric' | 'Cosine' | 'Sokal', xAxis: string, yAxis: string, options?: object)	—	Raw embedding without UI. Returns ISequenceSpaceResult.
getChemSimilaritiesMatrix(dim: int, col: column<Molecule>, df: dataframe, colName: string, simArr: object)	—	Internal — pairwise similarity matrix as columns.
rGroupsAnalysisMenu()	topMenu	Opens the R-group analysis dialog. Top menu: Chem → Analyze → R-Groups Analysis.
rGroupDecomposition(df: dataframe, molColName: string, core: string, rGroupName: string, rGroupMatchingStrategy: 'Greedy' | 'GreedyChunks' | 'Exhaustive' | 'NoSymmetrization' | 'GA', onlyMatchAtRGroups?: bool)	—	Programmatic R-group decomposition. Returns RGroupDecompRes.
mmpAnalysis(table: dataframe, molecules: column<Molecule>, activities: list<column<numerical>>, diffTypes: list<'delta'|'ratio'>, scalings: list<'none'|'lg'|'-lg'>, fragmentCutoff: float = 0.4)	topMenu	Matched Molecular Pairs analysis. Top menu: Chem → Analyze → Matched Molecular Pairs.
mmpViewer()	—	Returns MatchedMolecularPairsViewer for manual view.addViewer.
activityCliffs(table: dataframe, molecules: column<Molecule>, activities: column<numerical>, similarity: float = 80, methodName: 'UMAP' | 't-SNE', similarityMetric: 'Tanimoto' | 'Asymmetric' | 'Cosine' | 'Sokal', preprocessingFunction?: func, options?: object, isDemo?: bool, isTest?: bool)	topMenu	Finds pairs of similar molecules with large activity differences. Top menu: Chem → Analyze → Activity Cliffs.
addScaffoldTree()	topMenu	Adds a ScaffoldTreeViewer to the current view. Top menu: Chem → Analyze → Scaffold Tree.
scaffoldTreeViewer()	—	Returns ScaffoldTreeViewer for manual use.
scaffoldTreeFilter()	—	Returns ScaffoldTreeFilter.
getScaffoldTree(data: dataframe, ringCutoff: int = 10, dischargeAndDeradicalize: bool = false)	—	Returns the scaffold tree as a JSON string.
substructureFilter()	—	Returns an RDKit-based SubstructureFilter.
bitbirchClusteringTopMenu(table: dataframe, molecules: column<Molecule>, threshold: float = 0.65, fingerprintType: 'Morgan' | 'RDKit' | 'Pattern' | 'AtomPair' | 'MACCS' | 'TopologicalTorsion' = 'Morgan')	topMenu	O(N) BitBIRCH clustering → cluster ID column. Top menu: Chem → Calculate → BitBIRCH Clustering.
clusterMCSTopMenu(table: dataframe, molCol: column<Molecule>, clusterCol: column)	topMenu	Most-common substructure per cluster → appends MCS column. Top menu: Chem → Calculate → Cluster MCS.
performClusterMCS(molCol: column<Molecule>, clusterCol: column)	vectorFunc	Vector form.
elementalAnalysis(table: dataframe, molecules: column<Molecule>, radarViewer: bool = false, radarGrid: bool = false)	topMenu	Adds atom-count columns; optional radar viewer. Top menu: Chem → Analyze → Elemental Analysis.
runElementalAnalysis(table: dataframe, molecules: column<Molecule>)	transform	Returns the list of added column names.

MPO, identifiers, reactions

MPO aggregation enum (WEIGHTED_AGGREGATIONS_LIST): 'Average' | 'Sum' | 'Product' | 'Geomean' | 'Min' | 'Max'.