Specialization kata · AGR-002

Estimate reference evapotranspiration with FAO-56 from temperature data

Reproduce FAO's worked examples for extraterrestrial radiation and Penman-Monteith reference evapotranspiration, then compute daily ET0 for a real year from temperature alone and compare it with the Hargreaves equation.

Draft. This recipe is a draft. Its checks may not have been run, and it can change.

Status
Draft
Kata ID
AGR-002
Maintainer
Agriculture pathway maintainer
Last verified
Not available. Built and checked by the Dojo maintainers and CI; no independent, agronomic or engineering review yet.
Found a problem?
Report it

The outcome

A daily reference evapotranspiration series for the record, from code that first reproduces FAO's worked examples.

For: Learners who finished AGR-001 and want to turn weather into a water estimate they can check.

Done when

  • Your code gives Ra 32.2 MJ m-2 day-1 for Example 8 and ET0 3.9 mm/day for Example 18
  • You state each estimate you used for missing humidity, radiation and wind, with its FAO-56 equation number
  • Your monthly Penman-Monteith and Hargreaves totals match /examples/agriculture-pathway/generated/et0-monthly.json

You make: Et series. Outcome: Estimate reference et.

Showcase and provenance

The Dojo’s worked example, made by the maintainers rather than by a learner: one year of NOAA daily weather for a California station, FAO-56 reference evapotranspiration and a maize irrigation estimate, every number computed by the site’s CI.

See the showcase

Made by
NOAA National Centers for Environmental Information (weather record); Developer Dojo maintainers (script and results)
Source
NOAA GHCN-Daily station USW00093193, 2023; method from FAO Irrigation and Drainage Paper 56; results from /examples/agriculture-pathway/tools/agri_pathway.py
Licence
Weather record is a US government work (no US copyright, 17 U.S.C. 105); script and outputs MIT
Date

Brief, inputs and constraints

Inputs

  • noaa-ghcnd-USW00093193-2023.csv. Source: noaa/ghcn-daily (copy on /examples/agriculture-pathway/inputs/). Terms: US government work from NOAA NCEI; cite the dataset as NCEI asks.
  • FAO-56 Examples 8 and 18. Source: fao/crop-evapotranspiration-56. Terms: © FAO; use the published numbers as a check, do not copy the text.

Constraints

  • No paid tools
  • Offline capable
  • No personal data

Capabilities practised

  • Calculate
  • Verify evidence

Stack, permissions and cost

Stack components with version, permissions and cost
PartComponentVersionPermissionsCost
RuntimePython, standard library only3.12Reads the files you give it and writes only the output folder you nameFree
ToolAny spreadsheetNot available. Not fixed; any spreadsheet that opens CSV worksOpens a copy of the CSV filesNot available. Depends on the spreadsheet you use; free ones work
DataNOAA GHCN-Daily record, station USW000931932023, SHA-256 abde4990…b3b9a7Read a copyFree (US government work)
HarnessAny chat assistant or coding agentNot available. Not fixed; an assistant may explain an equation or draft code, and every number it gives is checked against FAO's worked examplesReads what you paste in; give it a copy of the record onlyNot available. Depends on your assistant and plan; not measured

Stack recipes

  • Python standard library

Why this stack

The standard library is enough for these equations, runs offline with nothing to install, and gives the same numbers on every machine. CI runs the identical script on every pipeline.

Alternatives

  • A ready-made evapotranspiration package or FAO's ETo Calculator. Faster, but hides the equations this pathway is about. Not tried for this pathway, so its numbers are not compared here. Not tested for this recipe.

Agents and review gates

  1. Explaining assistant

    Explains one FAO-56 equation at a time and drafts the Python for it.

    Review gate: Its code must reproduce FAO's worked example before you use it on the record.

  2. Learner as reviewer

    Compares each result with FAO's published values and with the Dojo's CI output.

    Depends on: Explaining assistant

    Review gate: A number stays only if you can say which equation and which input produced it.

Setup and smoke test

  1. Use the folder and Python from AGR-001.

Sign-in and access: None. Nothing here needs an account.

Smoke test

Do
Run: python3 -I tools/agri_pathway.py . out (from the folder that holds inputs/ and tools/)
Expect
out/reference-checks.json reports 13 passed and 0 failed
Result
Passed /examples/agriculture-pathway/generated/reference-checks.json, recomputed by CI on every pipeline

Prompts

Copy a prompt into the assistant you use. Replace anything that does not fit your situation, and never paste private or personal data you are not allowed to share.

One equation, one check

Build the method from parts you have each checked, instead of trusting a whole formula at once.

You can also select and copy the text.

Practice exercise

Crop evapotranspiration (FAO Irrigation and Drainage Paper 56). From Crop evapotranspiration (FAO Irrigation and Drainage Paper 56) (Food and Agriculture Organization of the United Nations).

Terms: © FAO. Free to read online; cite it and read FAO's terms before copying text or figures.

Execution and handoffs

  1. Learner: Implement and check Ra (Example 8), then actual vapour pressure and ET0 (Example 18).
  2. Explaining assistant: Explains the chapter 3 estimates for missing humidity, radiation and wind. Hand-off: You decide which to use and write down why.
  3. Learner: Run the method on every day of the record and compare the monthly totals with Hargreaves and with the CI output.

Tests, failures and corrections

Checks with expected and recorded results
CheckExpectedResultEvidence
Run the pathway script's reference checksExample 8 dr 0.985, declination 0.120, sunset hour angle 1.527, Ra 32.2; Example 18 Ra 41.09, ea 1.409, ET0 3.9; all passPassed on /examples/agriculture-pathway/generated/reference-checks.json, recomputed by CI on every pipeline
Compute monthly ET0 for the recordPenman-Monteith with missing-data estimates gives 125.6 mm in April and 217.8 mm in July; Hargreaves over Penman-Monteith is 0.99 in January and 1.07 in April; no unavailable daysPassed on /examples/agriculture-pathway/generated/et0-monthly.json
Your own monthly table matches the CI outputSame totals to 0.1 mmNot runNot run, so there is no evidence. This is not a pass.

Failures and corrections

  • Observed: Example 8 gives the wrong Ra Correction: The latitude goes in radians and is negative in the southern hemisphere; Example 8 is at 20 degrees south.

Adapt it

  • Use a station that measures humidity or wind Replace the estimate with the measurement and record how much ET0 changes; that difference is the error the estimate carried.

Unseen Randori

See the agriculture Randori recipe, AGR-R01.

Constraints

  • Reproduce FAO's examples before you use the code on the record

How it is judged: The monthly table matches the CI output for the same record.

More Randori challenges

Belt evidence

Belt stages are proposed practice stages, not issued credentials. Evidence below is what a reviewer would look for; it is not a record that anyone has shown it.

Evidence a reviewer looks for

  • Code that reproduces FAO-56 Examples 8 and 18 to the published precision (Automated check, against FAO Irrigation and Drainage Paper 56 (Crop evapotranspiration))
  • A monthly ET0 table for the record that matches the Dojo's CI output, with any unavailable day counted and not filled with zero (Automated check)
  • A short note on where Penman-Monteith and Hargreaves disagree, and why neither is a measurement (Self-check)

Belt criteria

  • Practice: Reproduces Examples 8 and 18 and the monthly ET0 table for the record
  • Adapt: Computes ET0 for another station-year and explains each missing-data estimate used
  • Demonstrate: Explains to a reviewer which inputs the estimate most depends on and how a measured humidity or wind would change it

See the belt stages

Connections

Used by
No other kata names this one as a foundation yet.
Transfers to
Professional review
Required. Any real use of this outcome needs independent validation and any approval required from a qualified professional. Practice here does not grant a licence.

Standards in scope

  • FAO Irrigation and Drainage Paper 56 (Crop evapotranspiration), 1998. Applies to: The reference evapotranspiration method and its missing-data estimates, used on one station-year for practice. Review scope: What the listed checks test: that the code reproduces FAO's worked examples to the published precision. No claim about measured evapotranspiration at any site.

Sources

Maintenance and caveats

Review cadence: Every six months, or when FAO revises Paper 56

  • This recipe is a draft: the example was built and checked by the Dojo maintainers and CI, and no learner has run it yet.
  • Nothing here is an irrigation recommendation. No agronomist, irrigation engineer or water authority has reviewed it, and real water use needs the qualified people and local rules that apply to it.
  • Humidity, radiation and wind are estimated from temperature, as FAO-56 describes for missing data. The results are estimates, not measurements.
  • NOAA says GHCN-Daily is not homogenized. One station and one year say nothing about a trend.

All kata recipes · Back to katas