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 +142 -3
- package/lib/functionKeys/dictionary.json +72071 -0
- package/lib/functionKeys/index.d.ts +105 -0
- package/lib/functionKeys/index.d.ts.map +1 -0
- package/lib/functionKeys/index.js +98 -0
- package/lib/functionKeys/index.js.map +1 -0
- package/lib/functions.d.ts +38 -0
- package/lib/functions.d.ts.map +1 -0
- package/lib/functions.js +54 -0
- package/lib/functions.js.map +1 -0
- package/lib/index.d.ts +83 -2
- package/lib/index.d.ts.map +1 -1
- package/lib/index.js +103 -2
- package/lib/index.js.map +1 -1
- package/lib/records.d.ts +45 -0
- package/lib/records.d.ts.map +1 -0
- package/lib/records.js +96 -0
- package/lib/records.js.map +1 -0
- package/lib/scan.d.ts +62 -0
- package/lib/scan.d.ts.map +1 -1
- package/lib/scan.js +69 -1
- package/lib/scan.js.map +1 -1
- package/lib/substructureSearch.d.ts +8 -5
- package/lib/substructureSearch.d.ts.map +1 -1
- package/lib/substructureSearch.js +28 -5
- package/lib/substructureSearch.js.map +1 -1
- package/lib/types.d.ts +83 -2
- package/lib/types.d.ts.map +1 -1
- package/lib/types.js +6 -1
- package/lib/types.js.map +1 -1
- package/package.json +6 -3
- package/src/functionKeys/index.ts +181 -0
- package/src/functions.ts +56 -0
- package/src/index.ts +122 -0
- package/src/records.ts +142 -0
- package/src/scan.ts +91 -1
- package/src/substructureSearch.ts +29 -6
- package/src/types.ts +115 -2
- package/wasm/data.js +1 -1
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
|
-
|
|
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
|
|
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).
|