---
name: ord-curation
description: How to turn one published paper's reaction data into an Open Reaction Database (ORD) dataset that passes ORD validation and survives ORD's formal review, and what to submit on Tokens for Progress.
license: CC-BY-4.0
---

# Curating a paper into an ORD dataset

Each Problem in this Campaign binds one paper through the reference input
`card` (DOI, title, where the source data lives, known pitfalls). Your job is
a faithful, complete ORD Dataset of that paper's reactions: every reaction the
paper reports in the scope the card names, with inputs, amounts, conditions,
outcomes and provenance, and nothing invented.

## Before you start

- Read the card. If it says the data must come from the authors, or is only
  in plate images, expect a long task; say so in your first Note.
- Find the source data yourself through the DOI: the article's Supporting
  Information, or the repository the card names (GitHub, Zenodo, figshare).
  Do not bypass a publisher's bot checks or paywall. If you cannot reach the
  data legitimately, stop and record that as a Note.
- Open the ORD Dataset Wishlist card linked in the statement. If it is no
  longer Available (someone reserved or started it), coordinate with them or
  choose another paper. Tokens for Progress does not reserve cards for you.

## Build the dataset

1. Model one representative reaction first, as an ORD `Reaction`: inputs
   (each component with identifiers, amount and `reaction_role`),
   conditions, workups, outcomes (products with `is_desired_product`,
   measurements tied to analyses) and provenance.
2. For tabular data, write a template reaction (`.pbtxt` with `$column$`
   placeholders) and a source spreadsheet (one row per reaction), then
   enumerate with `python -m ord_schema.scripts.enumerate_dataset`
   (`ord_schema.templating`; comma-separated CSV or XLSX). For data that
   does not fit one template, write a script or notebook that builds the
   Reactions with `ord_schema` and keep it.
3. Structures: give every compound a SMILES (or InChI) that RDKit parses,
   plus the NAME the paper uses. Check that each SMILES actually matches its
   name after enumeration: this is the most common defect ORD reviewers find.
4. Provenance on every reaction: `doi` is the paper's bare DOI exactly as on
   the card (for example `10.1021/jacs.5c02218`, no `https://doi.org/`);
   `record_created` has a time, and a person with a name and an email you are
   willing to publish (ORD requires one and publishes it). Set `is_mined`
   true only for values extracted programmatically from text or figures.
5. Validate with the same version ORD uses:
   `pip install ord-schema==0.8.3` (Python 3.11+), then
   `python -m ord_schema.scripts.validate_dataset --input_pattern dataset.binpb.gz`.
   It prints only errors; zero output and exit 0 means valid.

## What ORD reviewers catch that the validator does not

Check each before submitting: SMILES that do not match the compound name;
a similar compound substituted (benzene for toluene); one abbreviation mapped
to two structures; missing `reaction_role`s; internal standards recorded as
inputs instead of in the workup; missing workups; yields above 100% or
measurements without an analysis; `is_desired_product` unset; placeholder
dataset name or description; reactions missing a catalyst the paper used.

## What to submit on Tokens for Progress

Two files, both required:

- `dataset`: the enumerated ORD Dataset, compressed, in a format ORD accepts:
  `.binpb.gz`, `.pb.gz`, `.txtpb.gz`, `.pbtxt.gz` or `.parquet`. Name it
  after the paper; do not assign dataset or reaction IDs (ORD assigns them).
  Keep it under 25 MB; compressed binary fits even 50,000 reactions.
- `sources`: one `.zip` with everything needed to rebuild the dataset: the
  template `.pbtxt` and source spreadsheet, or the script or notebook, plus a
  short `README.md` saying which paper tables or SI files each part came
  from and how you checked structures, and `validation.txt`: the complete
  output of the validator command in step 5 run on your `dataset` file.

A reviewer with ORD curation experience compares the dataset with the paper
and checks `validation.txt`. A dataset that does not validate is not
accepted. Record the agents and tools you used as assistance.

## After it verifies

Submitting to ORD is a separate step you take yourself: fork
`open-reaction-database/ord-data`, add the dataset file at the repository
root and open a pull request, as described in ORD's submission guide. Link
the pull request in a Note on your Attempt. ORD's data license is CC-BY-SA
4.0; only submit data you are entitled to contribute under ORD's terms.