docs/data.md

# Inputs and data preparation

## Execution graphs

A graph JSON contains `nodes`, `edges`, `root`, and `metadata`. A node has a unique string `id`, a fixed-width numerical `features` list, optional `metadata`, and an `outcome` for terminal nodes. An edge has a unique `id`, `source`, `target`, finite nonnegative `cost`, and an `action` record. Outcomes are canonical and unique across terminal nodes.

Graph construction checks acyclicity, root reachability, terminal identity, and absence of nonterminal dead ends. Cycles in the underlying execution system are represented by adding a step counter to states. Terminal merging occurs after resource states have been created.

`log_rewards.json` maps every canonical outcome to one finite log weight. Missing or extra outcomes are rejected. Costs and route temperature use the same units. The finite-precision implementation is intended for representable positive probabilities and moderate reward ranges.

## Molecular inventory

Parent and reagent inputs have `id,smiles` columns. Case-insensitive aliases include `Enamine_ID`, `catalog_id`, and `code`. Additional columns are retained as metadata. Gzip and tab-delimited inputs are supported. A row limit applies before canonical deduplication. Supplier IDs with the pattern `m_22_654222_29794186` retain chemistry class, supplier reaction ID, and supplier reagent IDs.

Canonicalization uses RDKit isomeric SMILES and requires one connected molecule. Duplicate parent structures share a graph state, with alternative supplier identifiers retained as aliases. Conflicting structures under one supplier identifier raise an error. Salt stripping and tautomer normalization are user-supplied preprocessing choices.

Reaction JSON is a list of records with unique `id`, two-reactant `smarts`, and finite nonnegative `cost`. The first SMARTS reactant is the current molecule. The second is an available reagent. Each successful application consumes one additional reaction. Products are sanitized, canonicalized, deduplicated, and restricted to molecular weight at most 750 Da. The cap is recorded in graph metadata. The purchased parent's own supplier route is recorded separately from the additional-reaction budget.

The shipped templates describe amide and ester graph transformations. Their experimental scope, coupling reagents, solvents, protection requirements, and yields require a chemistry-specific protocol. Replace these examples with the reaction rules and stock restrictions selected for the intended synthesis campaign.

Generation writes JSONL records with `outcome`, `edge_ids`, `edge_indices`, `cost`, `log_probability`, and `actions`. Actions begin with a parent selection, contain zero or more reaction records, and end with stop. Each reaction record contains template ID, SMARTS, reagent ID, reagent SMILES, input, and product.

## Public property data

| Dataset | Released source | Columns | Units |
|---|---|---|---|
| Caco-2 Wang | [TDC release on Harvard Dataverse](https://dataverse.harvard.edu/api/access/datafile/4259569) | `Drug`, `Y` | log10 permeability in cm/s |
| BACE | [MoleculeNet processed release](https://deepchemdata.s3-us-west-1.amazonaws.com/datasets/bace.csv) | `mol`, `pIC50` | pIC50 |

The original Caco-2 study is [Wang et al., JCIM 2016](https://doi.org/10.1021/acs.jcim.5b00642). MoleculeNet is described by [Wu et al., Chemical Science 2018](https://doi.org/10.1039/C7SC02664A). The TDC dataset collection is described in the NeurIPS Datasets and Benchmarks paper cited in `paper/references.bib`.

Downloads are cached locally with SHA-256 checksums and source metadata. Unparseable, disconnected, and nonfinite-label rows are excluded. Canonical duplicates are averaged. Entire Bemis-Murcko scaffold groups are assigned to the 80/20 training/test split. All acyclic molecules share one scaffold group. Split seeds change tie ordering among groups of equal size.

Each predictor uses 1,024-bit radius-two Morgan fingerprints and 256 extra trees, minimum leaf size 2, and feature fraction 0.5. Test labels are used for reported MAE and R². The molecular state encoder uses 128 Morgan bits plus consumed budget, terminal, and root indicators. These two feature widths serve different computations.

Public generation utilities are `clip((predicted_BACE_pIC50 - 4)/5, 0, 1)` and `clip((predicted_Caco2 + 7)/3, 0, 1)`. The default log reward is five times their equally weighted mean. QED, logP, and size rewards are available when `dooable score` is called without property models.

Raw download archives are omitted from this repository. Split membership, held-out predictions, source records, and fitted weights accompany the executed runs. Upstream dataset and publication terms apply to those sources. The small named-compound fixtures and generated route records were created for this implementation. No licensed Enamine catalog or credentials are included.