Community Foodshed Methodology

1. National Land Cover Database (NLCD) 2021

2. Shuttle Radar Topography Mission (SRTM)

3. POLARIS Soil Properties

4. JRC Global Surface Water

5. PRISM Climate Normals

6. U.S. Census Bureau (Decennial 2020, ACS, TIGER/Line)

7. gNATSGO (Gridded National Soil Survey)

8. USDA Food Access Research Atlas

Google Earth Engine

H3 Hexagonal Hierarchical Spatial Index

Parcels are classified into production tiers based on their contiguous acreage, NLCD land cover type, and impervious surface percentage.

Source: SPEC Distributed Portfolio v5 — Tier system based on USDA farm size classifications and Peters et al. (2016) carrying capacity methodology.

Each tier assumes specific production systems, methods, skill levels, and loss profiles. These assumptions drive the yield calculations.

Base Yield by Production System

Method Yield Modifiers

Skill Level Modifiers

Sources: [8] McDougall (2019), [9] CoDyre (2015), [10] Beeby (2020), [22] Dowding (2013-2024), [23] U of Minnesota Extension, [26] Resoil Foundation (2022).

curl -H "X-API-Key: $KEY" \
  "$API/api/crops/viable?zone=8"

curl -H "X-API-Key: $KEY" \
  "$API/api/labor/breakdown?sqft=2500&system=intensive_garden&method=raised_bed&skill=beginner"

Adjacent hexes cluster into parcels only if they belong to the same compatibility group AND that group supports clustering. Residential hexes (dev_low, dev_med) are never clustered — each home is its own C1 parcel.

NLCD classification from USGS National Land Cover Database 2021. Compatibility rules from SPEC-300 tessellation design.

Effective acres uses a density-weighted garden potential model that combines NLCD land cover type with impervious surface percentage to estimate realistic garden space per hex. For residential hexes, this estimates homes per hex, then garden space per home.

Agricultural Land

Cultivated, pasture, and grassland use the full hex area minus impervious surfaces. Typically 95-100% of 3.75 acres.

Residential Land (NLCD dev_low, dev_med)

Demand Weighting

Dense residential hexes also generate demand weight (estimated population × 2.5 persons/household). High-density clusters become demand centers (more mouths to feed), while sparse residential areas become the production base.

Density model uses NLCD 2021 + impervious surface data. Residential density estimates are calibrated heuristics, not census-tract-level data.

Livestock is integrated into the expansion loop — not added after it. When a C3+ parcel is activated, livestock potential is calculated alongside plant yield. Pasture animals consume effective acres (feed-land competition), reducing the land available for crops.

Unlock Thresholds

Feed-Land Competition Model

Pasture animals (sheep, beef, pigs) consume land from the parcel's effective acres — up to 30%. This means a 20-acre C4 farm allocates at most 6 acres to livestock grazing, leaving 14 acres for crops.

Non-pasture animals (laying hens, aquaculture) use structures or ponds and do not deduct from crop land. Laying hens are capped at 12 (C3), 25 (C4), or 50 (C5) per parcel.

Portfolio Cap Enforcement

Livestock kcal is included in the portfolio cap check. A C3 parcel producing 500K plant kcal + 200K livestock kcal counts as 700K toward the C3 tier cap (30% of target). This prevents livestock from inflating results beyond cap limits.

Sources: USDA-FDC (nutrition), USDA-NASS (production), ATTRA (small-scale guides), Virginia Tech Extension (sheep), Penn State Extension (housing), Missouri Extension (economics). All citations verified against source PDFs.

curl -H "X-API-Key: $KEY" \
  "$API/api/livestock/viable?sqft=10000&region=humid_east"

1-LX Parcel (3.75 acres effective)

2-LX Parcel (7.5 acres effective)

3-LX Parcel (11.25 acres effective)

Per-Hex Yield (Liebig's Law — Multiplicative)

Stage 2: Aggregation-Level Adjustments (applied during regional rollup, NOT per-hex)

Per-Parcel Yield (Sum of Member Hexes)

Regional Portfolio Yield (Capped Tiers)

Yield Variance Disclosure

Coefficient framework: FAO (1976) Framework for Land Evaluation. Multiplicative model: Liebig's Law of the Minimum.

curl -H "X-API-Key: $KEY" \
  "$API/api/caloric-plan?sqft=2500&zone=8&skill=beginner&focus=mixed_garden&method=raised_bed&mouths=4"

Source: USDA-ERS LAFA (2011) Loss-Adjusted Food Availability data. Blended factors computed from per-crop retail loss, consumer loss, and inedible share.

Production method modifiers are hardcoded in foodshed_core_v3.py METHODOLOGIES dict with inline citations. The methods.json file exists for UI display only and is NOT consumed by calculations.

Each method defines: land cover requirements (NLCD types), hard gates (min/max acreage, tree cover), preferred conditions, and a yield key that maps to the YIELD_TABLE for production estimates.

Method Definitions

Method definitions derived from USDA extension publications, ATTRA sustainable agriculture guides, and peer-reviewed field studies. See inline citations in foodshed_core_v3.py METHODOLOGIES dict.

Skill modifiers are hardcoded in foodshed_core_v3.py SKILL_MODIFIERS dict with inline citations. The skills.json file exists for UI display only and is NOT consumed by calculations.

Skill creates 3-11x yield variance on identical plots. This is the LARGEST source of uncertainty in residential food production estimates.

Participation Rate (Survey Penalty)

Applied during site assessment. Each red-flag answer reduces yield estimate by 3%, floored at 50%. This captures site-specific risks (contamination, access issues, etc.) that satellite data cannot detect.

CoDyre et al. (2015) doi:10.1016/j.ufug.2014.11.001; Conk & Porter (2016) doi:10.2105/AJPH.2015.302991; University of Minnesota Master Gardener Study (2018-2022).

The yield calculation pipeline draws from multiple data sources with a clear hierarchy:

Primary Yield Data

Constants and Framework (Peters et al. 2016)

Citation Enrichment (Reference Only)

peters_yields.json contains 127 crop yields from Peters et al. (2016) Table S12. These are attached to crop recommendations as reference metadata for transparency but are NOT used as the calculation driver. The actual per-crop kcal/acre values come from crops_garden.json.

Peters, C.J. et al. (2016). Carrying capacity of U.S. agricultural land: Ten diet scenarios. Elementa: Science of the Anthropocene, 4, 000116. DOI: 10.12952/journal.elementa.000116

Planned but Not Yet Implemented

• Computer vision photo analysis: Upload 3 photos of your land, AI estimates sun exposure, tree cover, and existing infrastructure.
• Sensor integration: IoT soil moisture sensors feed real-time data into yield estimates.
• Mesh network: Community sensor mesh for hyper-local microclimate data across L0 neighborhoods.
• Climate adjustment coefficients: Regional climate multipliers (currently, Peters yields are national averages that implicitly include climate variation).
• Food forest tier: Assign existing forest hexes to food forest production with 7-year establishment curve.

Every number the algorithm uses, its source paper, and confidence level. Loaded from Section B of foodshed_core_v1.py.

Confidence levels: HIGH peer-reviewed / official data MEDIUM extension / grey literature LOW estimates / extrapolations UNKNOWN needs citation

Detailed algorithm documentation for the six core computation modules. Source code references included for each section.

Source: assessment_engine.py

8-Phase Pipeline

Hex Data Derivation

The system auto-answers 7 survey questions from satellite/soil data:

Yield Formula

Season Multiplier

Constraint Extraction Rules

Cross-references survey answers with hex data. Hex data can escalate but not downgrade a constraint.

Method Ranking Algorithm

Each method starts with a base score of 50 and is adjusted by constraint interactions:

Returns top 3 viable methods plus all blocked methods. Biointensive is blocked by high contamination and requires full sun.

Source: assessment_engine.py. Contamination thresholds from EPA (400 ppm lead action level).

# Get the 38-question checklist
curl -H "X-API-Key: $KEY" "$API/api/checklist"

# Submit a quick plot assessment
curl -X POST -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"space_type":"backyard_medium","area_sqft":1500,"skill_level":"beginner","mouths_to_feed":2,"crop_focus":"mixed_garden"}' \
  "$API/api/myplot"

Source: assessment.py SPACE_TYPES + plot_routes.py /api/myplot

Space Type Definitions

The user selects a space type that defines their growing context. Each type has a square-footage range, default area, and constraints on which growing methods are available.

Hex-Area Integrity Constraint

When a user selects hex cells on the map, the system constrains which space types are available based on the physical land area those hexes represent. This prevents incoherent configurations (e.g., claiming 20 acres of farmland when only 3.75 acres of satellite data is selected).

Backend Area Cap (Safety Net)

Even if a disallowed space type reaches the backend (e.g., direct API call), the server caps the growing area to the physical hex coverage:

Canopy Area Reduction (Physical Land Exclusion)

When satellite data shows tree canopy coverage on selected hexes, the system reduces the available growing area proportionally. This is a physical geometry reduction, not a yield coefficient. If 65% of the land has trees on it, only 35% is physically plantable — regardless of how productive that 35% might be.

Survey-Hex Dampening

When satellite data and user survey answers cover the same environmental factor, the system dampens the satellite penalty based on the user's ground observation. This prevents double-counting and respects the user's direct knowledge of their site.

Raised Bed Soil Bypass

When the recommended method is raised_bed or container, the soil modifier penalty is reduced by 70% because imported soil replaces native ground:

Space type boundaries aligned to H3 resolution-8 hex area (3.75 acres). Survey-hex overlap mapping derived from HEX_COVERED_QUESTIONS in assessment.py. Dampening factors are design choices calibrated to balance satellite confidence against user observation.

Source: parcels.py

Algorithm Steps

Compatibility Groups

Performance

Effective Acres

Uses the density-weighted garden potential model (Section 4). Agricultural land uses simple impervious deduction; residential land estimates homes per hex, then garden sqft per home.

Demand Clustering

Demand hexes are identified using NLCD classification (dev_med/dev_high = definite, dev_low > 35% impervious = likely). Clusters use Haversine distance (accurate at all latitudes) with adaptive radius:

Cluster centroids are population-weighted using demand_weight from the Phase 2 density model, not simple geographic averaging.

Tier Assignment

For each parcel, check acreage ranges against eligible tiers for its compatibility group. Checked largest-first (C5 before C1). Must also satisfy minimum hex count.

Union-Find: Tarjan (1975). H3 adjacency: Uber Engineering H3 resolution 8 hexagonal grid.

Source: services/simulation.py

Portfolio Caps

Caps prevent any single tier from dominating production. They are design choices (not peer-reviewed parameters) and vary by optimization strategy to match each strategy's objective.

Diversification Score

Used by the resilience strategy to score parcels that increase portfolio diversity.

Demand Constants — Two Baselines

Peters et al. (2016) "Carrying capacity of U.S. agricultural land" Elementa 4:000116, p.4. Portfolio caps: local design decision for production diversity — not derived from academic research.

# Step 1: Load a community (returns session_id)
curl -H "X-API-Key: $KEY" "$API/api/location/load?l1_id=YOUR_L1_ID"

# Step 2: Run simulation (use session_id from step 1)
curl -H "X-API-Key: $KEY" -H "X-Session-ID: $SESSION" \
  "$API/api/simulation?local_target=0.70&strategy=labor"

# Step 3: Compare all 8 strategies
curl -H "X-API-Key: $KEY" -H "X-Session-ID: $SESSION" \
  "$API/api/simulation/compare?local_target=0.70"

Source: services/simulation.py

After the simulation builds its plan (which parcels to activate, how many labor hours each needs), the Workforce Model converts raw labor hours into real people at real commitment levels. There is no user-facing "hours per week" input — the model determines workforce composition from the plan itself.

Three Commitment Levels

Staffing Mix by Tier

Each tier has a fixed staffing mix — the fraction of its total labor hours filled by each commitment level. These are design choices based on observed patterns in community agriculture, not peer-reviewed parameters.

Calculation

Example: 2-Acre Market Garden

At 1,000 hrs/acre, a 2-acre market garden needs 2,000 labor hours/year:

Commitment-level model: local design decision. Labor hours per acre per tier from BASE_YIELDS (Section 2) with method modifiers applied.

Source: foodshed_solver.py

5 Fixed Scenarios

Effective kcal/acre

Participation Solver

Break-Even Finder

Iterates method x diet combos in escalating intensity order (conventional/us_avg first, biointensive/vegan last). Returns the first combination where min_participation ≤ 50%. If none achieve 50%, returns the best combo with achievable=false.

Diet Efficiency Table

Loss Factors by Method

Diet efficiency from Peters et al. (2016). Loss factors from USDA-ERS LAFA (2011).

# Requires a location loaded first (see Section 12 API example)
curl -H "X-API-Key: $KEY" -H "X-Session-ID: $SESSION" \
  "$API/api/foodshed"

This feature is currently archived. The layout engine code is preserved in _archived/draw-plot/garden_layout.py for future re-addition.

Source: _archived/draw-plot/garden_layout.py

Bed Positioning

Beds are arranged within a rectangular plot using a border-inset grid layout:

Method Bed Dimensions

Crop Assignment

Crops are assigned to beds using round-robin from the recommendation list, with companion planting checks:

Planting Calendar

Timing is calculated relative to frost dates. Each crop stores:

Materials Calculator

Companion planting: Carrots Love Tomatoes (Riotte, 1998). Bed dimensions: Jeavons (2012) biointensive standards.

Source: foodshed_core_v1.py — Section C coefficient functions (not covered in B.1-B.17 registry)

Elevation Coefficient (beta_elevation)

Based on adiabatic lapse rate (~6.5 deg C per 1,000m):

Aspect Coefficient (beta_aspect)

Northern Hemisphere only. South-facing slopes receive maximum solar radiation.

Farmland Class Coefficient (beta_farmland)

Based on USDA farmland classification system:

Complete Expanded Hex Yield Formula

Elevation: adiabatic lapse rate (standard atmospheric). Aspect: Northern Hemisphere solar geometry. Farmland: USDA-NRCS Farmland Classification System. FAO classes: FAO (1976) Framework for Land Evaluation.