Organize datasets and model experiments; preserve original checkpoint under uncertain (#1)

- Organize datasets and model experiments; preserve original checkpoint under uncertain (96e912a716402577792c054bcc9d8805cc04a259)


Co-authored-by: Almaz Gilmullin <Protolaw@users.noreply.huggingface.co>

.gitattributes

@@ -33,3 +33,6 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+
+# Keep raw reaction tables in large-file storage.
+*.csv filter=lfs diff=lfs merge=lfs -text

README.md

@@ -1,3 +1,68 @@
 ---
 license: mit
 ---
+# SynPlanner Chemformer artifacts
+
+Model checkpoints and raw reaction datasets for the Chemformer workflows project.
+The existing model's MIT declaration is preserved in `models/uncertain/README.md`.
+Dataset sources retain their own usage and citation terms.
+
+## Repository layout
+
+```text
+datasets/
+  README.md
+  artifacts.json
+  absynth/
+    README.md
+    dataset.yaml
+    raw/absynth_full_filtered_classed.csv
+  uspto_mit/
+    README.md
+    dataset.yaml
+    raw/molecular_transformer_data.zip
+  uspto_synplanner/
+    README.md
+    dataset.yaml
+models/
+  README.md
+  uspto_mit/README.md
+  uspto_synplanner/
+    README.md
+    random/README.md
+    harsh/README.md
+  uncertain/
+    .gitattributes
+    last.ckpt
+    hparams.yaml
+    README.md
+```
+
+## Datasets
+
+Raw files use the same relative paths and bytes as the local project.
+[datasets/artifacts.json](datasets/artifacts.json) records their sizes and SHA-256
+hashes. Prepared data, generated outputs, and machine-specific manifests are not
+published here.
+
+- [AbSynth](datasets/absynth): the supplied raw CSV. The import recipe remains
+  unverified; preserve the source export when preparing experiments.
+- [USPTO-MIT](datasets/uspto_mit): the unchanged ZIP downloaded from the original
+  [MolecularTransformerData source](https://ibm.box.com/v/MolecularTransformerData).
+  The ZIP includes several variants; the documented benchmark uses non-augmented
+  `MIT_separated` with 409,035 training, 30,000 validation, and 40,000 test rows.
+- [USPTO-SynPlanner](datasets/uspto_synplanner): reserved for future data; no raw
+  files have been uploaded yet.
+
+## Models
+
+`models/uspto_mit/` and `models/uspto_synplanner/{random,harsh}/` are placeholders.
+Their README files keep these otherwise-empty directories visible on the Hub.
+
+The original four files are preserved under [models/uncertain](models/uncertain).
+The checkpoint's dataset, split, and reagent condition are not documented, so
+moving it does not assign it to a benchmark. Its SHA-256 remains
+`649e40511d6632d64e405432d7397d3b9fdb41434442e48e88eba658524f43d1`.
+
+A root `.gitattributes` is retained for large-file handling. The original contents
+remain available in `models/uncertain/.gitattributes` as well.

datasets/README.md

@@ -0,0 +1,53 @@
+# Local dataset conventions
+
+The code repository tracks acquisition notes, file identities, and import settings.
+The [Hugging Face artifact repository](https://huggingface.co/Manajit/SynplannerChemformer/tree/main/datasets)
+mirrors the corresponding raw data paths:
+
+- `absynth/raw/absynth_full_filtered_classed.csv`: the supplied AbSynth export.
+- `uspto_mit/raw/molecular_transformer_data.zip`: the original archive from
+  [MolecularTransformerData](https://ibm.box.com/v/MolecularTransformerData).
+- `uspto_synplanner/`: documentation and settings only; raw data will be added later.
+
+`artifacts.json` records sizes, SHA-256 hashes, and known acquisition sources.
+`uspto_mit` supports existing Chemformer pickles. The `uspto_synplanner` and
+`absynth` import recipes still need source-specific validation. No downloads happen
+implicitly. The raw data remains ignored in the code repository.
+
+Place inputs under `<dataset>/raw/` and generated files under `<dataset>/prepared/`.
+Both are ignored. Pass source/destination paths explicitly to the CLI.
+
+`dataset.yaml` has an `import` mapping with:
+
+| Setting | Meaning |
+| --- | --- |
+| `input_mode` | `reactants` (ignore reagents) or `separated` (preserve them) |
+| `reaction_column` | Column containing `reactants>reagents>products` or `reactants>>products` |
+| `reactant_column`, `product_column` | Supply both to use separate columns |
+| `reagent_column` | Required for separated mode with separate SMILES columns |
+| `split_column` | Existing train/validation/test labels; defaults to `set` |
+| `default_split` | Explicit assignment if the split column is absent; otherwise null |
+| `id_column` | Optional source identifier retained in the row map |
+| `separator` | Input delimiter for text tables |
+| `remove_atom_maps` | Defaults to true |
+
+RDKit-molecule pickles are recognized through `reactants_mol` and `products_mol`.
+Separated mode also requires `reagents_mol`. Blank reagents are valid; unparsable
+nonempty reagents are rejected. No fallback changes the selected input mode.
+
+Preparation normalizes validation aliases (`valid`, `validation`) to `val` and
+preserves supplied membership. Invalid splits are rejected. Training data without
+splits must be assigned explicitly; this refactor does not invent or silently
+randomize dataset splits. For custom evaluation only, `predict` defaults missing
+splits to `test` and predicts all supplied valid rows.
+
+The prepared pickle contains `reactants_mol`, `products_mol`, `set`, and optionally
+`reagents_mol`. Sidecar `.rows.csv` maps every original positional row to a prepared
+row or rejection reason, preserving optional source IDs. `.report.json` stores the
+source SHA-256, import settings, and split/rejection counts. Keep these sidecars
+with their associated predictions.
+
+Before claiming a new dataset is supported, document its source/release/usage
+terms, inspect representative exports, configure columns, preserve its published
+splits, and validate input-mode semantics. The small original capivasertib reaction
+list is retained under `examples/`; its generated predictions are not tracked.

datasets/absynth/README.md

@@ -0,0 +1,11 @@
+# absynth
+
+The supplied raw export is `raw/absynth_full_filtered_classed.csv`. The Hugging
+Face artifact repository mirrors this file byte-for-byte at the same relative
+path. Its SHA-256 and size are recorded in `../artifacts.json`.
+
+Import recipe is a configurable placeholder. Obtain a representative export and confirm its columns and published splits before using it for training; source-specific support has not been validated.
+
+Keep source files in `raw/` and derived pickles/reports in `prepared/`; both are ignored.
+Record the dataset release, source URL, acquisition date, and applicable usage terms here when selecting a source.
+Edit `dataset.yaml` to match the export. Paths are passed explicitly to the CLI.

datasets/absynth/dataset.yaml

@@ -0,0 +1,13 @@
+dataset: absynth
+status: unverified-export
+import:
+  input_mode: reactants
+  reaction_column: rxn_smiles
+  reactant_column: null
+  product_column: null
+  reagent_column: null
+  split_column: set
+  id_column: null
+  default_split: null
+  separator: ','
+  remove_atom_maps: true

datasets/absynth/raw/absynth_full_filtered_classed.csv

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2e207a3e91d18a81c997279a079e49b6340cc7fb3fce0bae5ec3f5801f2ce376
+size 22652814

datasets/artifacts.json

@@ -0,0 +1,16 @@
+{
+  "files": [
+    {
+      "path": "datasets/absynth/raw/absynth_full_filtered_classed.csv",
+      "bytes": 22652814,
+      "sha256": "2e207a3e91d18a81c997279a079e49b6340cc7fb3fce0bae5ec3f5801f2ce376",
+      "provenance": "User-supplied local export; source-specific import recipe unverified."
+    },
+    {
+      "path": "datasets/uspto_mit/raw/molecular_transformer_data.zip",
+      "bytes": 276751431,
+      "sha256": "1724f48b07e1f8d3c7267ab50913c6e684750850a16fbb417961e8130350d0f7",
+      "source_url": "https://ibm.box.com/v/MolecularTransformerData"
+    }
+  ]
+}

datasets/uspto_mit/README.md

@@ -0,0 +1,64 @@
+# USPTO-MIT
+
+Download the public [Molecular Transformer archive](https://ibm.box.com/v/MolecularTransformerData)
+and prepare its original, non-augmented `MIT_separated` splits:
+
+```bash
+chemformer data download uspto-mit
+chemformer data prepare-uspto-mit --workers 4
+```
+
+Every command also works as `python -m chemformer_workflows ...`. Downloading uses
+only Python's standard library; preparation needs pandas and RDKit. In the code
+checkout, see `README.md` for runtime status and
+`docs/uspto-mit-reproduction.md` for the reproduction procedure.
+
+The downloader verifies the full archive before accepting it and reuses a valid
+local copy. Downloading or preparing does not import the Chemformer model.
+
+| Property | Pinned value |
+| --- | --- |
+| Box filename | `data.zip` |
+| Box file / version | `344263095532` / `444624691904` |
+| Size | 276,751,431 bytes |
+| SHA-1 (Box metadata) | `18651da54b198a89207c137a92312d318547cdb9` |
+| SHA-256 (verified download) | `1724f48b07e1f8d3c7267ab50913c6e684750850a16fbb417961e8130350d0f7` |
+| Training / validation / test | 409,035 / 30,000 / 40,000 |
+
+The archive is stored as `raw/molecular_transformer_data.zip`, alongside its
+local download manifest. The Hugging Face artifact repository mirrors the ZIP
+at the same relative path; `../artifacts.json` records its identity and original
+Box source. Machine-specific download manifests and prepared outputs stay local.
+If the automated Box URL stops working, download `data.zip`
+from the public page, save it under that local name, and rerun the command to
+verify its identity. A changed archive fails verification and needs an explicit
+review of the pinned release.
+
+The importer reads only `data/MIT_separated/{src,tgt}-{train,val,test}.txt`.
+It removes tokenization whitespace, parses `reactants>reagents` and products,
+removes atom maps, and preserves every source row and published split. Invalid
+chemistry, unequal source/target lengths, or changed split sizes fail preparation.
+It does not extract arbitrary ZIP paths. The
+[publisher's format description](https://github.com/pschwllr/MolecularTransformer#data)
+distinguishes separated, mixed, and augmented variants. `MIT_mixed` still contains
+reagents and must not be used for the reagent-free ablation. The `_augm` variants
+must not be substituted for this benchmark.
+
+The output `prepared/uspto_sep.pickle` contains ordinary RDKit molecules in
+`reactants_mol`, `reagents_mol`, `products_mol`, and the `set` column. Both reagent
+conditions use this same pickle; the chosen upstream data module controls whether
+reagents enter the model. Existing Chemformer pickles remain supported unchanged.
+
+Sidecars appended to the pickle filename:
+
+- `.rows.csv`: original row, pickle row, and stable `split:line` source IDs.
+- `.reactions.csv`: canonical SMILES, splits, and source IDs; convenient for analysis
+  without loading the larger molecule pickle.
+- `.report.json`: archive/member/output checksums, library versions, counts, and
+  preparation settings.
+- `.reagents.json`, `.reagent_groups.csv`, `.reagent_examples.csv`: measured
+  reagent-association statistics and supporting rows.
+
+`raw/` and `prepared/` are ignored by Git. The data and generated reports are not
+included in distributions. Follow the source's usage and citation terms; this
+repository's code license does not grant additional rights to the dataset.

datasets/uspto_mit/dataset.yaml

@@ -0,0 +1,21 @@
+dataset: uspto_mit
+status: verified-public-archive
+source:
+  url: https://ibm.box.com/v/MolecularTransformerData
+  variant: MIT_separated
+  augmented: false
+  download_command: chemformer data download uspto-mit
+  prepare_command: chemformer data prepare-uspto-mit
+# The generic mapping below is for existing exports. The fixed benchmark archive
+# uses its dedicated, strictly validated importer.
+import:
+  input_mode: separated
+  reaction_column: rxn_smiles
+  reactant_column: null
+  product_column: null
+  reagent_column: null
+  split_column: set
+  id_column: null
+  default_split: null
+  separator: ','
+  remove_atom_maps: true

datasets/uspto_mit/raw/molecular_transformer_data.zip

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1724f48b07e1f8d3c7267ab50913c6e684750850a16fbb417961e8130350d0f7
+size 276751431

datasets/uspto_synplanner/README.md

@@ -0,0 +1,7 @@
+# uspto_synplanner
+
+Import recipe is a configurable placeholder. Obtain a representative export and confirm its columns and published splits before using it for training; source-specific support has not been validated.
+
+Keep source files in `raw/` and derived pickles/reports in `prepared/`; both are ignored.
+Record the dataset release, source URL, acquisition date, and applicable usage terms here when selecting a source.
+Edit `dataset.yaml` to match the export. Paths are passed explicitly to the CLI.

datasets/uspto_synplanner/dataset.yaml

@@ -0,0 +1,13 @@
+dataset: uspto_synplanner
+status: unverified-export
+import:
+  input_mode: reactants
+  reaction_column: rxn_smiles
+  reactant_column: null
+  product_column: null
+  reagent_column: null
+  split_column: set
+  id_column: null
+  default_split: null
+  separator: ','
+  remove_atom_maps: true

models/README.md

@@ -0,0 +1,12 @@
+# Model artifacts
+
+- `uspto_mit/`: reserved for USPTO-MIT models.
+- `uspto_synplanner/random/`: reserved for the SynPlanner random-split experiment.
+- `uspto_synplanner/harsh/`: reserved for the SynPlanner harsh-split experiment.
+- `uncertain/`: the four original repository files, preserved without changing
+  their contents. The checkpoint training dataset and reagent condition are
+  unverified, so it has not been assigned to an experiment folder.
+
+The original `.gitattributes` is preserved in `uncertain/`. A root copy continues
+handling large files for this repository. The original model card is also
+preserved in `uncertain/README.md`; the root card describes the new organization.

models/uncertain/.gitattributes

@@ -0,0 +1,35 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

models/uncertain/README.md

@@ -0,0 +1,3 @@
+---
+license: mit
+---

models/uspto_mit/README.md

@@ -0,0 +1,3 @@
+# uspto_mit
+
+Reserved for USPTO-MIT model checkpoints. No checkpoint has been assigned to this dataset yet.

models/uspto_synplanner/README.md

@@ -0,0 +1,3 @@
+# uspto_synplanner
+
+Reserved for models trained on USPTO-SynPlanner. Use random/ and harsh/ for the respective split experiments.

models/uspto_synplanner/harsh/README.md

@@ -0,0 +1,3 @@
+# uspto_synplanner/harsh
+
+Reserved for the USPTO-SynPlanner harsh-split experiment. No checkpoint is available yet.

models/uspto_synplanner/random/README.md

@@ -0,0 +1,3 @@
+# uspto_synplanner/random
+
+Reserved for the USPTO-SynPlanner random-split experiment. No checkpoint is available yet.