openchemlib-search-wasm 2.0.0 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -21,7 +21,8 @@ maintainer job**: the `openchemlib` git submodule and the JDK it needs live in
21
21
  ## Use
22
22
 
23
23
  ```ts
24
- substructureSearch<Entry>(idCodeQuery: string, entries: Entry[],
24
+ // idCodeQuery: one idcode, or several — a molecule then matches when it holds any of them
25
+ substructureSearch<Entry>(idCodeQuery: string | string[], entries: Entry[],
25
26
  options?: SubstructureSearchOptions): SubstructureSearchResult<Entry>;
26
27
  similaritySearch<Entry>(idCodeQuery: string, entries: Entry[],
27
28
  options?: SimilaritySearchOptions): SimilaritySearchResult<Entry>;
@@ -30,7 +31,25 @@ similaritySearch<Entry>(idCodeQuery: string, entries: Entry[],
30
31
  getIndex(idCode: string): Int32Array;
31
32
  getIndexes(idCodes: string[]): Int32Array[];
32
33
 
33
- // the 64-bit hash a molecule keeps across its stereoisomers
34
+ // the 512-bit screen next to it, from a dictionary of 512 query fragments
35
+ getScreen(idCode: string): Int32Array;
36
+ getScreens(idCodes: string[]): Int32Array[];
37
+
38
+ // what every molecule a query matches has in its FragFp and in its screen
39
+ getQueryIndex(idCodeQuery: string): Int32Array;
40
+ getQueryScreen(idCodeQuery: string): Int32Array;
41
+
42
+ // the 512 key fragments behind the bits of each, in bit order
43
+ getFragFpKeys(): string[];
44
+ getScreenKeys(): string[];
45
+
46
+ // FUNCTIONS ARE NOT YET WELL DEFINED AND MAY / WILL CHANGE ANYTIME WITHOUT BREAKING CHANGE !
47
+ // 512 named function bits — thioether, aromatic ring, uracil, Boc — and their fragments
48
+ getFunction(idCode: string): Int32Array;
49
+ getFunctions(idCodes: string[]): Int32Array[];
50
+ getFunctionKeyFragments(): string[][];
51
+
52
+
34
53
  getNoStereoHash(idCode: string, options?: HashOptions): bigint;
35
54
  getNoStereoHashes(idCodes: string[], options?: HashOptions): BigInt64Array;
36
55
 
@@ -44,6 +63,13 @@ getNoStereoIdCodes(idCodes: string[], options?: HashOptions): string[];
44
63
  getNoStereoTautomerIdCode(idCode: string, options?: HashOptions): string;
45
64
  getNoStereoTautomerIdCodes(idCodes: string[], options?: HashOptions): string[];
46
65
 
66
+ // everything a molecule table stores, from one parse per molecule
67
+ getMoleculeRecords(idCodes: string[], options?: MoleculeRecordsOptions): MoleculeRecords;
68
+ // only the atom count and the relative weight of each molecule
69
+ getMoleculeSizes(idCodes: string[]): MoleculeSizes;
70
+ // the fewest atoms a molecule needs to contain the query
71
+ getQueryAtomFloor(idCodeQuery: string): number;
72
+
47
73
  // a hash as the 16 hex digits that cross an API, and back
48
74
  hashToHex(hash: bigint): string;
49
75
  hexToHash(hex: string): bigint;
@@ -169,6 +195,85 @@ testing on one molecule.
169
195
 
170
196
  This is the expensive half of importing a library, and where the biggest speedup is.
171
197
 
198
+ ## Screens
199
+
200
+ FragFp alone lets many molecules through a prescreen that a substructure search then rejects.
201
+ `getScreen` adds 512 more bits: bit i is set when key i of a frozen dictionary of 512 OpenChemLib
202
+ query fragments is a substructure of the molecule, matched exactly as FragFp matches its own keys. A
203
+ molecule is a candidate for a query only if it holds every bit of the query's FragFp and of its
204
+ screen:
205
+
206
+ ```js
207
+ const isSubset = (query, molecule) =>
208
+ query.every((word, i) => (word & molecule[i]) === word);
209
+
210
+ const isCandidate =
211
+ isSubset(getQueryIndex(query), getIndex(idCode)) &&
212
+ isSubset(getQueryScreen(query), getScreen(idCode));
213
+ ```
214
+
215
+ On 1 M PubChem molecules, requiring both lets through 16% of the non-matching molecules FragFp alone
216
+ lets through, and 2% for rare queries; no true match was rejected over 23 M true pairs. A screen
217
+ costs about 0.7 times a fingerprint.
218
+
219
+ `getQueryIndex` and `getQueryScreen` read a query the way the substructure search matches it.
220
+ OpenChemLib's own query fingerprint does not yet, and rejects true matches of a query with an
221
+ exclude group cutting an aromatic ring or with a "match formal bond order" bond
222
+ ([Actelion/openchemlib#177](https://github.com/Actelion/openchemlib/issues/177)); it also skips atom
223
+ ring sizes when it matches a key in a query
224
+ ([#178](https://github.com/Actelion/openchemlib/issues/178)). For any other query, `getQueryIndex`
225
+ equals OpenChemLib's own.
226
+
227
+ `getFragFpKeys` and `getScreenKeys` return the two dictionaries as idcodes, in bit order, so a page
228
+ can draw what each bit stands for. Bit i is key i, in word `i >> 5` at `1 << (31 - (i & 31))`:
229
+
230
+ ```js
231
+ const screen = getScreen(idCode);
232
+ const held = getScreenKeys().filter(
233
+ (key, i) => screen[i >> 5] & (1 << (31 - (i & 31))),
234
+ );
235
+ ```
236
+
237
+ ## Function keys
238
+
239
+ `getFunction` adds 512 named bits: bit i is set when the molecule holds function key i — a
240
+ thioether, an aromatic ring, a uracil, a Boc group. A question in words becomes bit arithmetic over
241
+ stored words, and each bit is exactly what `substructureSearch(key.fragments, entries)` answers.
242
+
243
+ The dictionary sits in a subpath, so a page that only searches never loads its 3 MB:
244
+
245
+ ```js
246
+ import {
247
+ getFunctionKey,
248
+ getRecordBit,
249
+ searchFunctionKeys,
250
+ } from 'openchemlib-search-wasm/function-keys';
251
+
252
+ searchFunctionKeys('lactam'); // keys whose names hold "lactam", an exact name first
253
+ const key = getFunctionKey('thioether'); // by id, name or synonym, case aside
254
+ const { word, mask } = getRecordBit(key);
255
+ const holds = (records.words[48 * i + word] & mask) !== 0; // records of getMoleculeRecords
256
+ ```
257
+
258
+ It holds 3,611 keys in 19 categories (`getFunctionCategories`), each with a unique name and its
259
+ synonyms:
260
+
261
+ | tier | keys | answered by |
262
+ | --------------- | ----: | ------------------------------------------------------------------------- |
263
+ | `stored` | 512 | bit `key.plane` of `getFunction`, words 32 to 47 of a record |
264
+ | `existingPlane` | 22 | bit `key.bit` of the FragFp or the screen, which holds the same molecules |
265
+ | `onDemand` | 3,077 | `substructureSearch(key.fragments, entries)` |
266
+
267
+ `getRecordBit` is undefined for an on-demand key. `key.prevalence` is the share of 1,034,054 PubChem
268
+ molecules holding the key, which orders the tests of a query from the most selective. The stored
269
+ keys are frozen with the module: changing, adding or reordering one changes every stored record,
270
+ so the 512 only change in a major release.
271
+
272
+ The definitions are ours and those of ChemCaption, AccFG, medchem, RDKit and openchemlib-utils,
273
+ with their licences in `getFunctionKeySources`. Every SMARTS was compiled to OpenChemLib query
274
+ fragments and checked against RDKit on 100,000 molecules; where the two aromaticity models disagree,
275
+ as on pyridones and coumarins, the key follows OpenChemLib's.
276
+
172
277
  ## Identity hashes
173
278
 
174
279
  Two hashes, for the two things "the same compound" usually means. Both are OpenChemLib's own —
@@ -332,6 +437,36 @@ string, which also keeps a 64-bit value from ever being read into a JavaScript n
332
437
  SELECT printf('%016x', no_stereo_tautomer_hash) AS hash FROM molecules WHERE id = ?;
333
438
  ```
334
439
 
440
+ ## Molecule records
441
+
442
+ `getMoleculeRecords` computes what a molecule table stores, parsing each idcode once:
443
+
444
+ | field | per molecule |
445
+ | ---------------- | ---------------------------------------------------------------------------------- |
446
+ | `idCodes` | the canonical idcode, as `openchemlib`'s `Molecule.fromIDCode(idCode).getIDCode()` |
447
+ | `words` | 48 words at `48 * i`: the FragFp, the screen, then the function bits |
448
+ | `atomCounts` | `getAllAtoms()`, explicit hydrogens included |
449
+ | `weights` | OpenChemLib's relative weight |
450
+ | `noStereoHashes` | the hash of `getNoStereoHashes` |
451
+ | `tautomerHashes` | the hash of `getNoStereoTautomerHashes`, unless that one is not canonical |
452
+ | `tautomerCounts` | how many tautomers were enumerated |
453
+
454
+ A molecule whose enumeration reaches `maxTautomers` (default `DEFAULT_MAX_TAUTOMERS`) gets its
455
+ no-stereo hash as its tautomer hash, because a key from a cut-short enumeration depends on where it
456
+ stopped. An idcode that will not parse gets `''`, zeros, 0 atoms, `NaN`, `NO_HASH` and a count of 0.
457
+
458
+ The canonical idcode keeps stereochemistry, so it is canonized on invented 2D coordinates, as
459
+ `openchemlib` parses by default. Canonizing the coordinate-free molecule instead gives another
460
+ idcode for 330 of the 1,999 test idcodes.
461
+
462
+ One call costs about what `getIndexes`, `getScreens`, `getFunctions` and the two hash functions cost together: the
463
+ parses it saves roughly pay for the atom count and the weight, and the canonical idcode adds a
464
+ coordinate invention per molecule. `node benchmark/records.js` measures it.
465
+
466
+ `getMoleculeSizes` returns only `atomCounts` and `weights`, for one parse each. `getQueryAtomFloor`
467
+ is the atom count below which a molecule cannot contain a query: its atoms once exclude groups are
468
+ removed, plain hydrogens aside.
469
+
335
470
  ## Diagnostics
336
471
 
337
472
  **Nothing here writes to your console.** The generated TeaVM runtime maps Java's standard output
@@ -384,4 +519,8 @@ anything is parsed, which is worth far more than 2x. Search the survivors, not t
384
519
 
385
520
  ## License
386
521
 
387
- BSD-3-Clause.
522
+ BSD-3-Clause. The function-key dictionary adapts definitions from
523
+ [ChemCaption](https://github.com/lamalab-org/chem-caption) (MIT),
524
+ [AccFG](https://github.com/xuanliugit/AccFG) (MIT), [medchem](https://github.com/datamol-io/medchem)
525
+ (Apache-2.0), [RDKit](https://github.com/rdkit/rdkit) (BSD-3-Clause) and
526
+ [openchemlib-utils](https://github.com/cheminfo/openchemlib-utils) (MIT).