GeinQSAR Studio
Home › Provenance and replay

Provenance and replay

Every saved dataset carries a record of how it was made. From that record the dataset can be regenerated and checked byte for byte, or rebuilt from the current database release to see what has changed.

A dataset curated by hand cannot be repeated: nobody remembers which records were dropped and why. The Dataset Builder writes the decisions down. The curation is a pure function of the raw records and the options, and the provenance file pins both, so the same records with the same options give the same table, byte for byte, on any machine.

The provenance file

name.curation.json is written with every dataset, whatever is switched off under Files. It is plain JSON and records:

The curation report repeats the source, the funnel and the checksums in readable form, and ends with the command that repeats the curation, so a reader of the supplementary material knows how to check it.

Replaying a dataset in the application

Data > Replay a provenance file (also under File) opens the replay dialog.

  1. Choose the Provenance file of the dataset, name.curation.json, with Browse or by typing the path.
  2. Leave Query the source again off for an exact check. Tick Write the regenerated files if you want the result on disk; otherwise the replay only compares.
  3. Press Replay. It runs in the background and can be cancelled from its progress row.
A replay that reproduced its dataset: Identical to the recorded table, 15 compounds against 15 recorded, the same ChEMBL release, and the SHA-256 checksum of the regenerated table.
A replay that reproduced its dataset: Identical to the recorded table, 15 compounds against 15 recorded, the same ChEMBL release, and the SHA-256 checksum of the regenerated table.
LineMeaning
Identical to the recorded table or Different from the recorded tableWhether the regenerated table has the checksum recorded in the provenance file.
CompoundsThe number of compounds now, with the recorded number.
ReleaseThe database release of the records now, with the recorded one.
ChecksumThe SHA-256 of the regenerated table. When the tables differ, Recorded gives the checksum from the provenance file beside it.
DifferencesWhat changed: a line for every step whose counts changed, with the recorded and the new numbers in and out, and the change of release, of the number of records retrieved and of the number of compounds.
WrittenWith Write the regenerated files: the table written next to the provenance file as name.replay.csv, with its SD file, snapshot, removal log, reports and provenance file of the same stem.

What identical means

Identical means that the regenerated table has the SHA-256 checksum recorded in the provenance file: it is byte for byte the same file. Before the curation runs, the raw snapshot itself is checked against its recorded checksum; a snapshot that was modified or replaced is refused with that reason instead of producing a different table. The replay needs no network connection and does not depend on whether the remote database has changed since.

The SD file is written without a date in its molfile headers, so a replay reproduces it too, and its checksum is recorded in the provenance file and the report. The verdict of the replay is given on the table. An SD file written by an earlier build of the program carried the time of writing in each header; such a dataset still replays to the same table, but its recorded SD checksum cannot be reproduced.

A replay needs the raw snapshot next to the provenance file. If the dataset was saved with Raw snapshot switched off, or the snapshot was moved, the replay refuses with the provenance file names no raw snapshot; replay with refetch to query the source again. Keep the three files name.csv, name.raw.json and name.curation.json together when you archive or share a dataset.

Querying the source again

With Query the source again the records are downloaded again with the recorded request, and the recorded options are applied to them. This answers a different question: not whether the curation is reproducible, but what a newer database release changes. The Differences then list a changed release, a changed number of records retrieved, every step whose counts changed and the change in the number of compounds; for your own file, whether the file has changed since (by its checksum). A different release legitimately gives a different table. A PubChem dataset that was not built from an assay, such as a compound list, can only be replayed from its snapshot.

To apply different settings to records you already have, which is a third question, start the Dataset Builder with the source Previous download (see PubChem, files and other sources).

The same from the command line

gqsar-cli runs the same engine with the same options; a dataset built in the window and one built on the command line are interchangeable, and either can be replayed by the other. The complete list of options is in The command line.

gqsar-cli fetch chembl-targets --query EGFR
gqsar-cli fetch chembl --target CHEMBL203 --type IC50 --preset regression -o egfr.csv
gqsar-cli fetch chembl-document --id CHEMBL1133184 --target CHEMBL220 --type IC50 --preset series3d -o series.csv
gqsar-cli fetch pubchem-assays --gene ACHE --organism "Homo sapiens" --potency-only --largest-first
gqsar-cli fetch pubchem-assay --aid 1796508 --info
gqsar-cli fetch pubchem-assay --aid 1000 --unit uM --preset regression -o aid1000.csv
gqsar-cli fetch pubchem-compounds --names names.txt --preset library -o library.csv
gqsar-cli curate -i measurements.csv --smiles-col SMILES --value-col "IC50 (nM)" --unit nM --preset regression -o curated.csv
gqsar-cli curate -i egfr.raw.json --preset classification --threshold 6 --grey-zone 0.3 -o egfr_classes.csv

The presets are regression, classification, series3d and library, and the options of the Curate page have command-line forms, for example --confidence N, --keep-variants, --stereo keep|flatten, --mixtures remove|keep-largest, --max-spread X, --aggregate median|mean|geomean and --select-target ID for records on several targets. --options FILE.json reads a complete option set. Each run writes the same files as the Save page, with the same defaults: --no-sdf and --no-report leave out the SD file and the report, and --report-word and --report-excel add those two forms of it. --cache DIR --offline answers every request from a response cache and sends nothing.

Replay

gqsar-cli curate --replay egfr.curation.json
gqsar-cli curate --replay egfr.curation.json --refetch
gqsar-cli curate --replay egfr.curation.json -o check.csv --no-sdf --no-report

The first command runs the recorded options on the recorded snapshot, prints the funnel and reports replay is identical to the recorded run with the number of compounds and the checksum. It writes the regenerated files as egfr.replay.csv and so on, or under the name given with -o. --refetch queries the source again and lists every difference. The exit code says what happened, so an archive of datasets can be checked automatically:

Exit codeMeaning
0The replay is identical, or, with --refetch, the source was queried again and the differences were listed.
1A usage error in the command.
2The provenance file or the snapshot cannot be read, or the snapshot does not match its recorded checksum.
3The replay does not reproduce the recorded table; both checksums are printed.
4Cancelled with Ctrl+C.

Measured agreement

The curation engine was checked against ChEMBL's own numbers and against an established reference implementation. The figures below hold for the data and the release stated.

p-scale conversion against pChEMBL

Every record of five ChEMBL downloads (IC50 of CHEMBL220, CHEMBL240 and CHEMBL203; Ki, Kd and EC50 of CHEMBL220 and CHEMBL203; ChEMBL_37) was curated with all validity filters off and with disagreeing records set to be removed, so that any disagreement would appear in the removal log. Of 62,628 records, 56,026 carry a numeric value and 41,193 a pchembl_value. The p-value computed by the pipeline agreed with ChEMBL's for all 41,193 (100 %), at two decimals with the tolerance 0.011; none was listed as a mismatch.

The tolerance is needed, and the reason is known. Rounding -log10(mol/L) once to two decimals reproduces 39,468 of the values exactly (95.812 %); rounding first to three decimals and then to two reproduces all 41,193. The 1,725 records that differ under single rounding differ by one unit of the second decimal (for example 394 nM gives 6.4045, which rounds to 6.40, while ChEMBL publishes 6.41). This is an empirical finding on release 37, since ChEMBL's documentation does not state its rounding, so the pipeline compares with a tolerance and uses its own unrounded value. The 14,833 records with a value but no pchembl_value are all explained by ChEMBL's stated conditions: a relation other than "=" (13,326), the flag outside typical range (1,199), units other than nM (221), a transcription-error flag (86) and one value that is not positive.

Structure standardisation

Every distinct input structure of three ChEMBL IC50 downloads and of PubChem AID 1000, 37,315 in all, was standardised and compared with the largest-fragment and neutralisation procedure of an established reference implementation, by standard InChIKey. For the comparison the builder kept the largest component of mixtures and applied no size, element or isotope rule. 10 structures were removed on purpose (4 without carbon, 6 nitroxide radicals); of the 37,305 compared, 37,303 (99.995 %) gave the same InChIKey, including all 1,976 salts and solvates. The 2 differences are sulfoximines that ChEMBL draws charge-separated and that the builder's functional-group normalisation writes with double bonds, by design; the parent structure is the same. The comparison does not cover the rejection rules, which were switched off for it, or tautomers, which were not canonicalised on either side.

Replay

All thirteen demonstration datasets built while validating the engine (from 11 to 13,677 compounds: EGFR, hERG and acetylcholinesterase from ChEMBL, two publications, PubChem assays 1000, 588342, 1796508, 1802763 and 68107) were regenerated from their provenance files with the recorded SHA-256 checksum. Fetched again live without a cache, the publication series and the AID 1000 dataset, and later six PubChem tables, gave the checksums of the recorded tables as well.

In the wizard itself, on ChEMBL_37 (release of 2026-05-01): the 10,079 IC50 records of the human acetylcholinesterase became 5,627 compounds, 7,275 of 7,275 computed p-values agreed with pchembl_value, and the replay of the saved provenance file was byte-identical. The 59 IC50 records of publication CHEMBL1133184 became a series of 35 compounds, with 59 of 59 p-values in agreement. The same choices made again from the response cache, without a request, gave both tables byte for byte. The full account is in Accuracy and validation.