Two routes in

Choose how you want to run it

Both routes run the same three-stage pipeline. Pick based on how much control you want over the process, and how comfortable you are with Jupyter Notebooks.

RECOMMENDED

Run the Notebook locally

The full pipeline, running in your own Jupyter environment with your own OpenAI account. Handles the widest range of spreadsheet formats and gives you the intermediate ingredient and category files to review and correct.

QUICKER, LIGHTER

Use the hosted web tool

A browser-based version at pcnudde.github.io/food-impact. Good for a fast first look at a file, but it's less capable than the Notebook — lacking options to review intermediate step results and correct any mistakes.

Open the web tool →

Route 1

Running the Notebook

Download five files
From the Downloads page: FoodImpacts_v10f.ipynb, your procurement file (or the sample usfoods.csv), factors.csv, foodcategories.json, and item_weights.json. Place them all in the same folder as the Notebook.
Have an OpenAI account ready
The Notebook calls OpenAI to identify ingredients and categories. If you don't have an API key, stephen.ronan@wfa.org can help.
Format your procurement spreadsheet
See the format guide below — most vendor exports need a couple of column renames and a type label before the Notebook can read them.
Run it
On a 1,700+ line file, expect roughly five minutes of runtime and less than $0.50 in OpenAI usage. The Notebook writes two output files: impacts_lbs_{yourfile}.csv and impacts_metric_{yourfile}.csv.
Review and, if needed, re-run partway
If anything in the ingredients or categories output looks off, fix it directly in that file, then set START_MODE in the first cell to after_ingredients or after_categories to skip the stages you don't need to redo. Set it back to full before starting a new file.

Formatting your spreadsheet

Column name labels to use

Save your procurement worksheet as a .csv, then rename columns so the Notebook can find product, product_weight, unit, and qty. Then in the first column of the row after the last product enter type01, type02 or type03 to correspond to one of the vendor formats below

type01 — quantity and unit combined in one column

Example: a column reading "80.000 OZ" for quantity and unit together.

Original column	Rename to
Product	product
Quantity (base unit)	product_weight

The Notebook's third cell splits the combined value ("80.000", "OZ") into separate fields automatically. Add type01 (lowercase, no space) in the first column below your last product row.

type02 — total weight with no unit column (e.g. usfoods.csv)

Original column	Rename to
Item Description	product
Total Weight / Net Wght Shipped	product_weight
Qty Shipped	qty
(add a new, empty column)	unit

Remove any "Total" rows beneath the product listing, then add type02 below the last product row.

type03 — weight folded into the product description

Common in some Baldor-style worksheets, where weight per case is written into the item name.

Original column	Rename to
Item Description	product
Qty Sold CW	qty
Stock Unit	unit

Remove any "Grand Total" line, then add type03 below the last product row.

Something not fit one of these three shapes? Write to stephen.ronan@wfa.org for free help prepping a worksheet in a different format. The Notebook can process a single file that mixes units — lbs, kilos, grams, gallons, liters — without any extra setup.

Tuning

One setting worth knowing about

CATEGORY_PERCENT_MIN, set in the first cell, defaults to 2.1. It filters out ingredients — typically additives — that make up a very small share of a product's total weight, so they don't clutter the categorized output. Raise or lower it depending on how granular you want the ingredient breakdown to be.

Want to see where the numbers come from?

Every conversion factor in factors.csv is sourced and explained on the Data & methods page.

See the sources →