# Cold storage data dictionary

**Publisher:** Omaha Dock Door Repair Research  
**Source verification date:** September 12, 2026  
**Data version:** 2026-09-12-audited

These files preserve USDA NASS published estimates and supply reproducible comparisons. They are not a new field survey, a census of every refrigerated facility, or a measure of construction or occupancy. Source observations and verification dates are distinct.

## State panel

Files: [us-refrigerated-warehouse-capacity-by-state-2023-2025.csv](/research/data/us-refrigerated-warehouse-capacity-by-state-2023-2025.csv) and [us-refrigerated-warehouse-capacity-by-state-2023-2025.json](/research/data/us-refrigerated-warehouse-capacity-by-state-2023-2025.json).

The panel contains **50 state rows plus one United States row**, with **30 fields**. The CSV and JSON contain the same records; JSON also contains a metadata object. Source observations are October 1, 2023 and October 1, 2025. Capacity values use **1,000 cubic feet**, not individual cubic feet, square feet, pounds or pallet positions.

### Value conventions

- **D:** the agency withheld the source cell to avoid disclosing individual operations. D is not zero. It remains the string `D` in CSV and JSON.
- **0:** the agency’s published zero within its survey coverage. Source-table dashes used for numeric zero are represented as `0`; they are not confidentiality markers.
- **Blank CSV / JSON null:** an undefined derived calculation or an unavailable comparison flag. Percentage change is undefined when the baseline is zero; withheld inputs also prevent calculation. Empty cells are never silently converted to zero.
- **star:** a source-check designation, not a quality grade for USDA’s underlying survey estimates.

The national row is USDA’s separately published total, not a sum of the disclosed state rows. The page’s positive-baseline change comparison has 37 states; the 2025 positive disclosed cooler/freezer panel has 25. These subsets are calculated from source disclosure status, not estimated missing values.

### Fields

| Field | Unit or type | Definition |
|---|---|---|
| `state` | text | State name, or United States for the national total. |
| `state_abbr` | text | Two-letter state abbreviation; US marks the national row. |
| `warehouses_2023_total` | locations | Agency-published count of all qualifying locations on October 1, 2023; not a company count. |
| `warehouses_2023_public` | locations | Agency-published count of public warehouse locations on October 1, 2023; not a company count. |
| `warehouses_2023_private` | locations | Agency-published count of private and semiprivate warehouse locations on October 1, 2023; not a company count. |
| `warehouses_2025_total` | locations | Agency-published count of all qualifying locations on October 1, 2025; not a company count. |
| `warehouses_2025_public` | locations | Agency-published count of public warehouse locations on October 1, 2025; not a company count. |
| `warehouses_2025_private` | locations | Agency-published count of private and semiprivate warehouse locations on October 1, 2025; not a company count. |
| `gross_refrigerated_2023_total` | 1,000 ft³ or D | Agency-published gross total refrigerated capacity on October 1, 2023, for all warehouse operating categories. |
| `gross_refrigerated_2023_public` | 1,000 ft³ or D | Agency-published gross total refrigerated capacity on October 1, 2023, for public warehouses. |
| `gross_refrigerated_2023_private` | 1,000 ft³ or D | Agency-published gross total refrigerated capacity on October 1, 2023, for private and semiprivate warehouses. |
| `gross_cooler_2023_total` | 1,000 ft³ or D | Agency-published gross cooler capacity on October 1, 2023, for all warehouse operating categories. |
| `gross_freezer_2023_total` | 1,000 ft³ or D | Agency-published gross freezer capacity on October 1, 2023, for all warehouse operating categories. |
| `gross_refrigerated_2025_total` | 1,000 ft³ or D | Agency-published gross total refrigerated capacity on October 1, 2025, for all warehouse operating categories. |
| `gross_refrigerated_2025_public` | 1,000 ft³ or D | Agency-published gross total refrigerated capacity on October 1, 2025, for public warehouses. |
| `gross_refrigerated_2025_private` | 1,000 ft³ or D | Agency-published gross total refrigerated capacity on October 1, 2025, for private and semiprivate warehouses. |
| `gross_cooler_2025_total` | 1,000 ft³ or D | Agency-published gross cooler capacity on October 1, 2025, for all warehouse operating categories. |
| `gross_freezer_2025_total` | 1,000 ft³ or D | Agency-published gross freezer capacity on October 1, 2025, for all warehouse operating categories. |
| `usable_refrigerated_2025_total` | 1,000 ft³ or D | Agency-published usable refrigerated capacity on October 1, 2025, after the source’s allowances; not occupied space. |
| `change_2023_2025` | 1,000 ft³ | 2025 gross total minus 2023 gross total, when both source totals are disclosed. A zero-to-zero absolute change is 0. |
| `change_2023_2025_pct` | percent | Absolute change divided by the disclosed positive 2023 gross total, multiplied by 100. File values rounded to two decimal places; page percentages are computed directly from raw totals before rounding to one decimal. |
| `freezer_share_of_gross_2025_pct` | percent | 2025 gross freezer divided by disclosed positive 2025 gross total, multiplied by 100; rounded to one decimal. |
| `usable_share_of_gross_2025_pct` | percent | 2025 usable total divided by disclosed positive 2025 gross total, multiplied by 100; rounded to one decimal. This is not occupancy. |
| `identical_in_both_surveys` | yes / no / blank or null | Compares disclosed gross totals in both years. The four zero-to-zero states are yes in the file; the page’s seven-state finding restricts this flag to positive totals in both years. |
| `verification_tier` | text | star means the source values or disclosure designations were checked directly against the cited primary tables. It does not remove uncertainty in the underlying survey estimates. |
| `source_2025` | text | Title and publication vintage of the 2025 capacity source. |
| `source_2023` | text | Title and publication vintage of the 2023 capacity source. |
| `verified_date` | ISO date | Date the cited source material was checked: 2026-09-12, not a warehouse observation date. |
| `source_2025_url` | URL | Primary USDA URL for the 2025 Summary, released February 9, 2026. |
| `source_2023_url` | URL | Primary USDA URL for the 2023 Summary, released January 31, 2024. |

Source: USDA NASS, [2023 Summary](https://esmis.nal.usda.gov/sites/default/release-files/x059c7329/cc08k3098/vq281845s/rfwh0125.pdf), printed pp. 5, 7–9; [2025 Summary](https://esmis.nal.usda.gov/sites/default/release-files/795764/rfwh0126.pdf), printed pp. 5, 7–9. Definitions and methodology: printed pp. 11–12 of each. Sources checked September 12, 2026.

### JSON structure

The top-level `metadata` object records title, publisher, canonical page URL, units, observation dates, verification date, version, row count, column names, source details and limitations. The `rows` array contains the same 51 records as the CSV. Numeric cells are JSON numbers, withheld capacity cells are `"D"`, and undefined cells are `null`.

### Rounding and nonadditivity

Original integer source cells are retained. Source percentages in this compilation are derived, not agency-published percentages: state percentage changes in the file use two decimal places; freezer and usable shares use one. The page calculates its one-decimal changes from original integer inputs, avoiding a second rounding of the file’s two-decimal display values.

USDA prints a general rounding note, but the national 2025 gross cooler and freezer components sum to 3,987,721 while the separately published gross total is 3,987,732, in 1,000 cubic feet. The corresponding 2023 difference is 9 in the same unit. The report supplies no cell-specific reconciliation; the files retain the published totals and components. For the 25 positive disclosed 2025 state component pairs, the absolute difference from the separately published total is no more than 1 in that unit.

## National 2017–2025 series

File: [us-refrigerated-capacity-by-warehouse-type-2017-2025.csv](/research/data/us-refrigerated-capacity-by-warehouse-type-2017-2025.csv).

Five rows represent October 1 observations in 2017, 2019, 2021, 2023 and 2025. No intervening annual observations are invented.

| Field | Unit or type | Definition |
|---|---|---|
| `survey_year` | year | Observation year, not release year. |
| `as_of` | date text | October 1 of the stated observation year. |
| `gross_public` | 1,000 ft³ | Published public gross refrigerated capacity. |
| `gross_private_semiprivate` | 1,000 ft³ | Published private/semiprivate gross refrigerated capacity. |
| `gross_total` | 1,000 ft³ | Separately published national gross total; retain source nonadditivity. |
| `public_share_pct` | percent | Public capacity divided by published national total; one decimal. |
| `private_share_pct` | percent | Private/semiprivate capacity divided by published national total; one decimal. |
| `index_2017_total` | 2017 = 100 | Year’s gross total divided by 2017 gross total × 100; one decimal. |
| `index_2017_public` | 2017 = 100 | Year’s public gross divided by 2017 public gross × 100; one decimal. |
| `index_2017_private` | 2017 = 100 | Year’s private/semiprivate gross divided by 2017 private/semiprivate gross × 100; one decimal. |
| `source` | text | Source title and publication vintage. |
| `verified_date` | ISO date | Source-check date. |
| `source_url` | URL | Primary report. |
| `source_page` | integer | Printed source page. |
| `capacity_unit` | text | `1000_cubic_feet`. |

Source: USDA NASS, [2025 Summary](https://esmis.nal.usda.gov/sites/default/release-files/795764/rfwh0126.pdf), printed p. 6; checked September 12, 2026.

## July 2026 stock snapshot

File: [us-cold-storage-stocks-2026-07-31.csv](/research/data/us-cold-storage-stocks-2026-07-31.csv).

This contains **16 displayed commodity/aggregate rows** from the August 24, 2026 release, with observations dated July 31, 2026. Those are the initial July estimates in that edition, subject to subsequent revision. The file is not silently updated to later releases.

All inventory quantities use **1,000 pounds**. They are not cubic feet, pallet positions or occupied capacity. The capacity and stock surveys have different observation dates and survey lists; their public-warehouse shares cannot establish relative storage density or occupancy.

| Field | Unit or type | Definition |
|---|---|---|
| `commodity` | text | Displayed commodity or aggregate name. |
| `indent` | integer | Source file display grouping only; not a rule permitting rows to be summed. |
| `stocks_all_warehouses_1000_lb` | 1,000 lb | Published estimate across qualifying warehouses. |
| `public_warehouse_stocks_1000_lb` | 1,000 lb or blank | Published public-warehouse estimate; blank where no matching subtotal split is provided in the cited table. |
| `public_share_pct` | percent or blank | Public weight divided by all-warehouse weight × 100; one decimal, only with a published split. |
| `as_of` | date text | July 31, 2026 observation. |
| `source` | text | Source report and release edition. |
| `verified_date` | ISO date | Source-check date. |
| `source_url` | URL | Primary report. |
| `release_date` | ISO date | 2026-08-24. |
| `revision_status` | text | Initial estimates in that edition; later revisions are not incorporated. |
| `public_split_status` | text | Published split versus subtotal split not published in the cited table. |

Commodity lines overlap. Chicken and turkey are included in poultry; beef and pork are included in red meat. Do not sum every row as though all categories were mutually exclusive. Juice figures represent pounds of concentrate as reported, not gallons of reconstructed juice.

Source: USDA NASS, [Cold Storage, August 24, 2026](https://esmis.nal.usda.gov/sites/default/release-files/796029/cost0826.pdf), printed pp. 4–7; survey methodology and revision procedure p. 25. Checked September 12, 2026.

## Reproduction

[Reproduction script](/research/data/reproduce-cold-storage-analysis.py), Python 3.10 or later, standard library only. Place it beside the four data files and run:

```bash
python reproduce-cold-storage-analysis.py
```

A different directory can be supplied with `--data-dir`. The script checks CSV/JSON equivalence, published location totals, withheld and zero conventions, raw-input changes, share and index rounding, stock-share calculations, comparison groups and component differences. It prints the principal findings as JSON, including the 62.2% Georgia/South Carolina comparison. Failure produces a nonzero exit code and an explanation.

This reproduces the arithmetic from the supplied source-value files. It does not make network requests, re-verify later versions of agency pages, audit an operator’s facility, or establish that USDA’s underlying estimates are exact.