# What a cup weighs, by every published source

Ask how many grams are in a cup of flour and the web answers 120, or 125, or 142, or 161,
depending on whose chart you land on. This dataset is 222 such figures, from
16 sources, for 74 staple ingredients, each recorded as the source
printed it: the gram figure, the amount it was printed for, the cup volume the source
itself stated, the filling method the source itself stated, and the page and date it was
read on. It is the table behind [What a Cup Weighs](https://artwaste.land/tools/cup-weights/).

## What the numbers came out at

| | |
|---|---|
| figures | 222 |
| sources | 16 |
| ingredients | 74 |
| figures whose source states how the cup was filled (for the row or its whole chart) | 63 |
| figures whose source states its cup volume | 103 |
| all-purpose flour, one cup, lightest to heaviest source | 110 to 161 g |

## Read this before you use a figure

- **A figure is the number a source printed, in that source's own cup, filled the way that
  source says.** Where `cup_ml_stated` is null the source stated no volume; where
  `method` is null it stated no method for that row. Nothing was inferred from the
  country the source writes in, and no figure was rescaled to a different cup. The
  difference between the largest and smallest cups any source here states is under six per cent;
  the sources that weighed the same cup filled two ways report differences larger than that.
- **A source's figure is for that source's product.** Two mills' all-purpose flour, spooned
  the same way, weigh differently, and the table keeps both.
- **The mapping is a judgement and it is committed.** Which printed row is "all-purpose
  flour" was decided by hand in `research/cup-weights/harvest/overrides.json` after a
  strict alias match; rows the mapper could not place were left out and are printed by the
  mapper, never silently dropped.
- **The verbatim quotations are not here.** The page shows each figure beside the source's
  own words, as a quotation. Those words are the source's, under a licence none of the
  sources states, so this file carries the figure and a transcribed row label and points at
  the page.
- **The USDA household-measure tables are a separate dataset**, `usda-cup-portions`,
  because their licence question has a different answer (US Government work), and because
  they are compiled figures rather than a chart somebody printed.

## Files

- `claims.jsonl`: one JSON object per line, one per figure.
- `schema.json`: JSON Schema draft 2020-12 for a row.
- `sources.json`: every source, with its URL, the date it was read, and the licence status
  we could establish, which for every chart is "not established".
- `validate.mjs`: a dependency-free validator that re-checks every row against the schema
  and the digests and row count in `manifest.json`.

## How it was made

`research/cup-weights/harvest/*.json` holds what each scout returned from each page, verbatim,
including the pages that could not be fetched. `map-claims.mjs` places the rows by strict
alias or by hand and writes `claims.json`; `build-data.mjs` builds the module the page ships;
this emitter reshapes that module. `research/cup-weights/verify.mjs` checks the shipped module
against the page and, with `--fetch`, re-reads every quotation from its page.