pyfao56

A Python implementation of the FAO-56 crop coefficient approach for crop water use estimation and irrigation scheduling

The pyfao56 Python package facilitates FAO-56 computations of daily soil water balance using the single and dual crop coefficient methods to estimate crop evapotranspiration (ET).

The FAO-56 method is described in the following documentation: Allen, R. G., Pereira, L. S., Raes, D., Smith, M., 1998. FAO Irrigation and Drainage Paper No. 56. Crop Evapotranspiration: Guidelines for Computing Crop Water Requirements. Food and Agriculture Organization of the United Nations, Rome Italy.

Reference ET is computed using the ASCE Standardized Reference ET Equation, which is described in the following documentation: ASCE Task Committee on Standardization of Reference Evapotranspiration (Walter, I. A., Allen, R. G., Elliott, R., Itenfisu, D., Brown, P., Jensen, M. E.,Mecham, B., Howell, T. A., Snyder, R., Eching, S., Spofford, T., Hattendorf, M., Martin, D., Cuenca, R. H., Wright, J. L.), 2005. The ASCE Standardized Reference Evapotranspiration Equation. American Society of Civil Engineers, Reston, VA.

Source Code

The main pyfao56 package contains the following modules:

• autoirrigate.py - I/O tools to specify parameters for autoirrigation
• irrigation.py - I/O tools to specify irrigation schedules explicitly
• model.py - Equations for daily soil water balance and ET computations
• parameters.py - I/O tools and methods for required input parameters
• refet.py - Equations for computing ASCE Standardized Reference ET
• soil_profile.py - I/O tools to define stratified soil layer properties
• update.py - I/O tools and methods for state variable updating
• weather.py - I/O tools for required weather information

The source code is available here. It uses a basic object-oriented design with separate classes to make FAO-56 calculations and to manage parameter, weather, irrigation management, and soil profile data. Pandas data frames are used for data storage and management. Further documentation of the class structure is contained in the source files.

The pyfao56 package contains a subpackage called tools, which has several modules to facilitate model use as follows:

• forecast.py - Obtain a seven-day weather forecast from the National Digital Forecast Database (NDFD)
• soil_water.py - I/O tools for managing measured volumetric soil water content data and computing root zone soil water metrics from those measurements
• statistics.py - Compute 16 goodness-of-fit statistics between measured and simulated data
• tables.py - Provides the data from Table 11 (growth stage lengths), Table 12 (Kcm and hmax), Table 17 (Kcb), and Table 22 (Zrmax and pbase) in FAO-56
• visualization.py - Develop plots to visualize measured and simulated data for root zone soil water depletion and evapotranspiration

The pyfao56 package also contains a subpackage called custom. Here, users can add customized scripts to improve their personal pyfao56 workflows. For example, the custom subpackage contains modules for development of customized weather files using data from the Arizona Meteorological Network (AZMET) station at Maricopa, Arizona and from the National Digital Forecast Database (NDFD). These modules were developed to facilitate irrigation management for field studies conducted at the Maricopa Agricultural Center. Users can follow this example to create customized weather tools for other weather data sources. Additionally, the custom subpackage contains a module for customizing the creation of soil files using ordered lists of soil water holding limits and initial soil water content data.

Install

pip install pyfao56

Quickstart

Import the package

import pyfao56 as fao

Specify the model parameters

• Instantiate a Parameters class: par = fao.Parameters()
• To print parameter values: print(par)
• To adjust parameter values: par.Kcbmid = 1.225
• To load values from a file: par.loadfile('myfilename.par')
• To write values to a file: par.savefile('myfilename.par')

An example of the parameter file format is here.

Specify the weather information

• Instantiate a Weather data class: wth = fao.Weather()
• To print weather data: print(wth)
• To load data from a file: wth.loadfile('myfilename.wth')
• To write data to a file: wth.savefile('myfilename.wth')
• To compute daily reference ET for yyyy-ddd (4-digit year and day of year): refet = wth.compute_etref('2021-150')

An example of the weather file format is here.

Users can customize loading of weather data with wth.customload(). The azmet_maricopa.py module in the custom subpackage provides an example for developing a custom weather data class that inherits from Weather and overrides its customload() function.

Specify the irrigation management information

• Instantiate an Irrigation data class: irr = fao.Irrigation()
• To print irrigation data: print(irr)
• To load data from a file: irr.loadfile('myfilename.irr')
• To write data to a file: irr.savefile('myfilename.irr')
• To add an irrigation event (provide yyyy, ddd, depth in mm, and fw): irr.addevent(2019, 249, 28.3, 1.00)
• Optionally, add an irrigation efficiency (default = 100.0%): irr.addevent(2019, 249, 28.3, 1.00, 95.0)

An example of the irrigation file format is here.

Run the daily soil water balance model

• Instantiate a Model class (provide starting yyyy-ddd, ending yyyy-ddd, and classes for Parameters, Weather, and optionally Irrigation): mdl = fao.Model('2013-113','2013-312', par, wth, irr=irr)
• To run the model: mdl.run()
• To print the output: print(mdl)
• To save the output to file: mdl.savefile('myoutputfile.out')

An example of the model output file is here. Definitions of the output file header names are given in the docstring of the Model class in model.py.

Specify a layered soil profile (optional)

• Instantiate a SoilProfile class: sol = fao.SoilProfile()
• To load data from a file: sol.loadfile('myfilename.sol')
• To write data to a file: sol.savefile('myfilename.sol')
• Instantiate a Model class with stratified soil layer data (provide starting yyyy-ddd, ending yyyy-ddd, and classes for Parameters, Weather, Irrigation, and SoilProfile): mdl = fao.Model('2019-108','2019-274', par, wth, irr=irr, sol=sol)
• To run the model: mdl.run()

An example of the soil file format is here.

Users can customize loading of soil profile data with sol.customload(). The example_soil.py module in the custom subpackage provides an example for developing a custom soil data class that inherits from SoilProfile and overrides its customload() function.

Run the daily soil water balance model with autoirrigation (optional)

• Instantiate an AutoIrrigate class: airr = fao.AutoIrrigate()
• Add one (or more) autoirrigation parameter set(s): airr.addset('2018-108','2018-250',mad=0.4)
• Instantiate a Model class with autoirrigation enabled: mdl = fao.Model('2018-108','2018-303', par, wth, autoirr=airr)
• To run the model: mdl.run()

There are currently 25 parameters that can be used to customize the autoirrigation computation. The autoirrigation parameters are described in the comments of the autoirrigate.py module. Furthermore, the cotton2018.py module in test9 provides many examples of various ways to implement the autoirrigation method.

Update basal crop coefficients (Kcb), crop height (h), or crop cover (fc) (optional)

• Instantiate an Update class: upd = fao.Update()
• To load data from a file: upd.loadfile('myfilename.upd')
• To write data to a file: upd.savefile('myfilename.upd')
• Instantiate a model class with updating (provide starting yyyy-ddd, ending yyyy-ddd, and classes for Parameters, Weather, Irrigation, and Updates): mdl = fao.Model('2019-108','2019-274', par, wth, irr=irr, upd=upd)
• To run the model: mdl.run()

An example of the update file format is here.

Further examples

Further example scripts for setting up and running the model are here.

test01 - The cottondry2013.py and cottonwet2013.py modules contain code to setup and run pyfao56 for the water-limited and well-watered treatments for a 2013 cotton field study at Maricopa, Arizona.

test02 - The refet_testA.py module contains a function to compare the short crop reference evapotranspiration (ETo) calculation from the pyfao56 refet.py module with ETo reported by the AZMET station at Maricopa, Arizona for 2003 through 2020. The refet_testB.py module contains a function to com