Two routes in

Choose how you want to run it

Both routes run the same Notebook and produce the same result files. 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. Gives you the intermediate ingredient and category files to review and correct, and lets you re-run from any stage.

QUICKER, NO SETUP

Use the hosted web tool

Upload a spreadsheet at pcnudde.github.io/food-impact and the results arrive by email, named after your file. No setup or OpenAI account needed, but there is no chance to review intermediate results and correct any mistakes before the impacts are calculated.

Open the web tool →

Route 1

Running the Notebook

  1. Download five files

    From the Downloads page: the current Notebook (FoodImpacts_2026-11-15.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. The step-by-step guide Running the Code (PDF) covers each of the steps below in more detail.

  2. 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.

  3. Point it at your procurement spreadsheet

    Set LOCAL_INPUT in the first cell to your file's name. Most vendor reports can be used as they come — see Your spreadsheet below.

  4. Run it

    On a 1,700+ line file, expect roughly 15 minutes of runtime and less than $0.50 in OpenAI usage. The Notebook writes its results to a folder named output that it creates next to the Notebook: the two impact files, impacts_lbs_{yourfile}.csv and impacts_metric_{yourfile}.csv; the shares report, shares_report_{yourfile}.txt, with its tables; and the ingredients and categories files. When it finishes it prints the folder's full location. Running the same file again replaces those results, so rename or move any you want to keep.

  5. Review and, if needed, re-run partway

    If anything in the ingredients or categories output looks off, fix it directly in that file (keeping it in the output folder under the same name), 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.


Route 2

Using the web tool

  1. Open the web tool and add your spreadsheet

    At pcnudde.github.io/food-impact, add a .csv or Excel file. The page finds the column headings, shows a preview, and leaves out blank and "Total" rows.

  2. Enter your email address and send

    The results arrive by email as a zip file named after your spreadsheet, usually within minutes for a few hundred products. It holds the same files the Notebook writes.

What happens to an uploaded file. It is used only to produce your results, which are sent to you by email. Uploads are deleted within a day, and nothing from your file is kept with the processing runs; their logs show neither your email address nor your file's name. Product descriptions are sent to OpenAI to identify ingredients; OpenAI does not use data sent through its API to train its models.

Your spreadsheet

Most vendor reports work as they come

Save your purchasing report as .csv or .xlsx. No renaming of columns or extra labels are needed: the Notebook recognizes common vendor layouts, finds the column headings even below title or date lines, and skips "Total" lines.

Each row needs a product description and either a weight, or a quantity with a unit (case, each, pound, kilogram, and so on). A single file can mix units — lbs, kilos, grams, gallons, liters. Reports from US Foods, Baldor, Freshpoint, Jamix and others have been tested as delivered.

Results look empty or odd? Write to stephen.ronan@wfa.org for free help with a worksheet in a different format. Running the Code (PDF) also describes how to rename columns by hand for a format the Notebook does not recognize.

Reporting frameworks

Anchors in Action and AASHE/STARS

We have experimental versions that aim to additionally facilitate measurements consistent with the full Anchors in Action and AASHE/STARS frameworks. Please contact stephen.ronan@wfa.org to request access to those versions. We would welcome your testing of those.

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 →