Skip to main content

Module 3: estimating cultivar coefficients (GLUE), soil data and water-limited production

DSSAT training, module 3 of 6. Follows day 3 of the course, with code instead of the DSSAT shell

How to use this module. Read this page for the ideas; every chart comes from the module 3 notebook (), which runs the DSSAT engine and writes the small data files the charts read. The runs on this build were made on .

What you will learn

  • How cultivar coefficients are estimated from field data, and why the answer is a distribution, not one number: the GLUE method of DSSAT, here as a Python port (glue.py), for soybean and for a new maize hybrid.
  • How to calibrate by hand against growth measured during the season, with the statistics the course uses.
  • What a soil profile in DSSAT holds, how much water a soil can store for a crop, and how to build a profile from a soil survey sheet.
  • How the water balance limits production: soil water layer by layer, the effect of the soil’s storage, and automatic irrigation.

1. Estimating cultivar coefficients with GLUE

A cultivar’s coefficients cannot be measured directly; they are estimated by running the model with many candidate values and keeping those that reproduce field observations. DSSAT’s tool for this is GLUE (Generalized Likelihood Uncertainty Estimation), written in R (DSSAT/glue). The notebook uses a Python port of its method, docs/notebooks/glue.py, which follows the R files step by step (the module docstring lists them).

Estimating coefficients: the ideas

A model coefficient is estimated by changing it until the simulation matches measurements, which is only as good as the measurements, the order and the error model. Three ideas from the course carry through this module:

  • Least squares and likelihood. Fitting by hand usually minimizes an error measure such as the RMSE; GLUE instead asks how likely the measurements are under each candidate set, given an assumed measurement error, and keeps a weight for every candidate.
  • Order. Coefficients that set dates (phenology) are fitted first, against flowering and maturity dates; those that set weights (growth) after, against biomass and yield. Module 2’s coefficient sweep shows why: the date coefficients move everything else, the growth ones do not move the dates.
  • Diverse data. Experiments at several sites and sowing dates separate coefficients that would compensate for each other in one experiment: the day-length coefficients, for example, only show their effect across day lengths.

GLUE is one way to estimate cultivar coefficients. The course’s lecture on estimating coefficients set it among the others:

  • Measure the trait directly. Controlled-environment experiments that control one or more factors (for example temperature or day length) and measure the crop’s response.
  • Fit to field data, the usual way: experiments with known weather, soil and management, and observed phenology, growth and yield. Within that:
    • trial and error: start from the closest cultivar in the DSSAT list, change one coefficient at a time, phenology first, and watch the error (module 4 gives the order);
    • software-assisted search: GenCalc, distributed with DSSAT, searches coefficients to minimize the error for chosen variables;
    • Bayesian estimation: GLUE, below, which also says how uncertain each value is.
  • Gene-based estimation: coefficients expressed as functions of the alleles a cultivar carries, so they can be predicted from molecular markers. The course called this “in its infancy” in 2018.

Whatever the method, several sites and years estimate coefficients better than one: with one experiment, errors in the weather, soil or measurements are absorbed into the coefficients.

The observations

The course’s GLUE exercise calibrates Williams-82, a soybean cultivar of maturity group 3, on the five treatments it selects: the first treatment of four experiments from Ames, Iowa (IUAM) and Wooster, Ohio (OHWO), and the fully irrigated treatment 4 of UFGA7902 from Gainesville, all shipped with DSSAT (DSSAT Foundation 2026). Dates are days after planting.

Two more experiments, IUAM9701 and IUAM9702, are kept back to test the result; only their yield was measured.

Step 1: a range for every coefficient

GLUE draws candidate values uniformly within a range for each coefficient (Uniform.r). DSSAT keeps the ranges in the cultivar file itself, in a MINIMA and a MAXIMA row, with a !Calibration row that marks each coefficient as P (phenology), G (growth) or N (not calibrated).

Note the last column: Williams-82’s own values of lie outside the ranges that GLUE samples from.

Step 2: how likely is each candidate?

For every measurement, GLUE asks how likely the simulated value would be if the measurement had a normal error with a fixed variance (Calculation.r, variances in MeasurementVariance_All.csv): a standard deviation of 3 days for anthesis and 7 days for maturity, and 30% for yields and weights. The likelihoods are multiplied over the measurements and the experiments and normalised, so the probabilities of all candidates add up to 1. For candidate \(i\), measurement \(j\) with value \(O_j\), simulation \(S_{ij}\) and variance \(\sigma_j^2\), in experiment \(e\):

\[ \begin{gathered} L_{ij} = \frac{1}{\sqrt{2\pi\sigma_j^2}}\,\exp\!\left(-\frac{(O_j - S_{ij})^2}{2\sigma_j^2}\right), \qquad L_{ie} = \prod_{j \in e} L_{ij} \\[6pt] p_i = \frac{\prod_e \left( L_{ie} \big/ \sum_k L_{ke} \right)}{\sum_m \prod_e \left( L_{me} \big/ \sum_k L_{ke} \right)} \end{gathered} \]

GLUE works in two rounds: round 1 varies the phenology coefficients and is scored on the dates; round 2 keeps the best round-1 values and varies the growth coefficients, scored on the weights. The notebook draws candidates per round, soybean seasons in all.

Try the likelihood of one date: with a standard deviation of 3 days, how much less likely is a candidate that misses anthesis by your chosen number of days than one that hits it?

Step 3: the posterior

Each dot is one candidate; its height is its GLUE probability.

Many candidates are almost as good as the best. In round 1, of the candidates have at least 1% of the best candidate’s probability; in round 2, . Different combinations of coefficients reproduce the same observations (equifinality). That is why the posterior mean and spread matter as much as the single best set.

When the best value sits on the edge

If the best value of a coefficient lies at the edge of its range, the data want a value the range does not allow. That happens in round 2. The notebook reruns round 2 with those ranges widened by half their width on the side that was hit:

Result: better dates; the weights depend on the ranges

GLUE improves the dates: the error in anthesis falls from to days and in maturity from to days. It does not improve the weights. The default Williams-82 reproduces tops weight with an error of kg/ha, the GLUE cultivar with , and with the wider ranges . Two things on this page point to why. The new phenology lengthens the season (later maturity in of experiments), and the GLUE cultivar grows more tops in of them. And the growth coefficients that could offset that, the leaf photosynthesis rate LFMAX among them, were sampled inside ranges that exclude the engine’s own Williams-82 values. A calibration is only as good as its observations, its ranges and its error model; GLUE makes all three explicit, which is its main use.

GLUE self test 4: a new maize hybrid from Colorado

The course’s last GLUE exercise calibrates a cultivar DSSAT does not have yet: the maize hybrid DEKALB 52-59 AF, grown at Greeley, Colorado, in 2008 and 2010 under full irrigation and with 40% of it (Anothai et al. 2013). The experiment files, weather and soils came with the course. The exercise asks for a new cultivar entry, CO0801, built from an existing variety; the notebook starts from DEKALB 485 (IB1072) of the engine’s cultivar file and runs both GLUE rounds on all four treatments.

The phenology moves most: the anthesis error falls from to days. Grain yield goes from an error of to kg/ha over the four treatments. With two years and two irrigation levels, four observations of each variable carry the whole calibration; the posterior spread above shows how loosely that pins the growth coefficients down.

Calibration with in-season data: peanut UFGA8401

The second calibration exercise of the course works by hand, against growth analysis data taken during the season: the irrigated treatment of the 1984 Florunner peanut experiment UFGA8401. It asks for four statistics of four variables, tops weight, seed weight, seed number and pod harvest index: the RMSE, the intercept a and slope b of the regression of simulated on observed values (a good fit has a near 0 and b near 1), and Willmott’s d. It suggests four coefficients: LFMAX for the size of tops and seed weight, FL-SH and FL-SD moved together for the timing of seed growth, PODUR for the first rise of seed number and pod harvest index, and XFRT for the share of growth that goes to pods and seeds.

The notebook runs every combination of five values of LFMAX, five shifts of FL-SH and FL-SD, five values of PODUR and the values of XFRT, so you can move them here freely.

Of all combinations, the one with the highest mean d over the four variables has LFMAX , a shift of days, PODUR and XFRT (mean d , against for Florunner as it is). The course’s self test asks for a second pass through the coefficients starting from the improved cultivar; the sliders let you do that pass here.

2. Soil data

A DSSAT soil profile lists layers with their lower limit of plant-extractable water (SLLL, close to the wilting point), drained upper limit (SDUL, close to field capacity), saturation (SSAT), a root growth factor (SRGF), texture and organic carbon. The water a soil can store for a crop is the sum over the layers,

\[ PAW = \sum_{l} \left(DUL_l - LL_l\right)\,\Delta z_l , \]

with \(\Delta z_l\) the thickness of layer \(l\) (in mm for PAW in mm).

The shaded band is the plant-available water. Across the thirteen profiles:

Estimating water limits from texture

When only texture and organic matter are known, a pedotransfer function estimates the limits. xdssat uses the equations of Saxton and Rawls (2006) (src/soils.py), ported below; for the lower limit, with sand \(S\), clay \(C\) as fractions and organic matter \(OM\) in %:

\[ \begin{aligned} \theta_{1500t} &= -0.024S + 0.487C + 0.006\,OM \\ &\quad + 0.005\,S\,OM - 0.013\,C\,OM + 0.068\,S\,C + 0.031 \\ LL &= \theta_{1500t} + (0.14\,\theta_{1500t} - 0.02) \end{aligned} \]

and similar equations for the drained upper limit and saturation; DSSAT’s SBuild tool has its own. Move the sliders:

Applied to the layers of the soil file, the estimates miss the file’s values by a root mean square of (LL), (DUL) and (SAT) cm³/cm³. The file’s generic profiles were not made with this function, so the comparison shows how much two reasonable estimates can differ, not which one is right.

The course’s soil exercise: Umariya and Orangeburg

The soil exercise gives the laboratory sheets of two soil series and asks for a DSSAT profile of each, with the water limits filled in from texture (SBuild’s “calculate missing values”): the Umariya series of Shahdol district, India, and pedon 2 of the Orangeburg series, Peach County, Georgia (Perkins 1987, 364–65, as handed out with the course). The notebook builds both with sol.SoilProfile and Saxton and Rawls; both now appear in the profile selector and the bar chart above, and in the water-limited runs below.

A sheet can be wrong. In the Umariya sheet the 11-31 cm layer has 55.2% sand, 18.4% silt and 36.4% clay, which adds up to 110%:

Saxton and Rawls use sand and clay only, so the notebook keeps both as printed. Had the sand been 45.2% (the value that makes the sum 100%), the drained upper limit of that layer would be instead of cm³/cm³: a small difference here, but the kind of error to check for before trusting a profile.

Self test 3 compares Orangeburg’s estimated limits with the water contents the sheet measured at 1/3 bar (33 kPa) and 15 bar (1500 kPa). The sheet gives them in % by weight; times bulk density they are volumetric. Its own “available water” column is the check that the conversion is right:

The pedotransfer function puts the drained upper limit the measured 1/3 bar water by cm³/cm³ on average, and the lower limit the 15 bar water by . Where a soil was measured, measured limits beat estimated ones; the soil file already holds an Orangeburg sandy loam (IBSB910017), shown in the selector above for comparison (self test 2).

3. Water-limited production

The course’s water-limited exercise builds UFGA8212.MZX from the potential production experiment of module 1: McCurdy 84aa maize planted on 26 February 1982 (7.2 plants/m², 61 cm rows, 7 cm deep), the Millhopper fine sand, simulation from 25 February with the initial soil water the exercise lists, the water balance on and nitrogen off. Treatment 1 is rainfed (no irrigation at all); treatment 2 irrigates automatically when the available water in the top 30 cm falls below 50%. Rain and irrigation enter the soil; water runs off, drains below the profile, evaporates from the soil surface and is taken up by roots from each layer (WATBAL.for). Self test 1 adds potential production for comparison.

Creating the FileX: the water balance on. Two parts of the experiment file change from module 1. The treatment table gives the rainfed treatment irrigation level 0 (MI), and the simulation controls switch the water balance on (WATER = Y) and, for the irrigated treatment, irrigation to automatic (IRRIG = A, with the depth IMDEP and threshold ITHRL in the automatic management rows). The rainfed file:

Rainfed, the crop reaches of the potential yield; with mm of automatic irrigation in applications it reaches . Of mm of rain over the simulation, mm drained below the profile of this sandy soil and only mm passed through the rainfed crop as transpiration.

Runoff and water stress, as the engine computes them

The soil water of the profile changes each day by what comes in and what goes out:

\[ \Delta SW = P + I - R - D - E_s - E_p \]

(rain, irrigation, runoff, drainage, soil evaporation, transpiration). Two of the terms in a few lines each. Runoff uses the curve number method of the US Soil Conservation Service: with the soil’s curve number \(CN\) and the day’s water \(P\) (mm),

\[ \begin{gathered} S = 254\left(\frac{100}{CN} - 1\right) \\[4pt] R = \begin{cases} \dfrac{(P - I_a S)^2}{P + (1 - I_a)\,S} & P > I_a S \\ 0 & \text{otherwise} \end{cases} \end{gathered} \]

with \(I_a\) the initial abstraction (RNOFF.for:78-105). The engine sets Ia from how wet the top two layers are (lines 84-86): about 0.3 when they are dry, near 0 when they are saturated.

With CN , a 60 mm storm runs off mm. A soil profile carries its curve number as SLRO: 60 for the Millhopper fine sand, which is where the slider starts.

Water stress. Each day the engine compares what the roots can take up (TRWUP) with what the crop could transpire (EP1). CERES-Maize turns the ratio into two factors (MZ_GROSUB.for:1065-1076):

\[ \begin{aligned} SWFAC &= \min\!\left(1, \frac{TRWUP}{EP_1}\right) && \text{(photosynthesis)} \\[4pt] TURFAC &= \min\!\left(1, \frac{TRWUP}{RWUEP1 \cdot EP_1}\right) && \text{(leaf expansion)} \end{aligned} \]

with RWUEP1 = 1.5 in the maize species file. Expansion is hit first, while the supply still covers the demand:

At a ratio of : SWFAC , TURFAC .

Soil water, layer by layer

The fill is the plant-available water of each layer: 0 at the lower limit, 1 at the drained upper limit (above 1 the layer holds more than it can keep against drainage). Depths are those the engine simulates, which differ from the layers of the soil file: the engine keeps 5 and 15 cm at the top and splits thick layers (LYRSET2, LMATCH.for:263, ported as learnlib.engine_layers).

Water stress index: WSGD of PlantGro, the expansion and partitioning stress written as 1 minus the factor (MZ_OPGROW.for:175).

Self test 2: which soil holds the most water for the crop?

The rainfed treatment on the twelve generic profiles, the Millhopper fine sand, and the two profiles built from the course’s soil sheets, each starting at 100% of its plant-available water:

Yield rises with the soil’s storage (r = over the soils). Closest to potential production comes the , with kg/ha. Storage is not the only property that counts: the Millhopper fine sand stores mm and yields kg/ha, less than soils that store less water, and it loses mm to drainage against a median of mm.

Self test 3: when to irrigate

With IRRIG = A the engine irrigates when the available water in the top IMDEP cm falls to ITHRL percent of its capacity, and refills it to ITHRU (IRRIG.for:827). The exercise’s grid of management depths and thresholds:

The full yield of kg/ha needs least water at cm and %: mm in applications. The most grain per mm of irrigation comes at cm and %, a lower yield ( kg/ha): the best setting depends on whether water or land is the scarcer resource.

Self test 4: other years at Gainesville

The rainfed and automatically irrigated maize planted on 26 February of every year with a full Gainesville weather file in dssat-csm-data:

Over years the rainfed yield ranges from to kg/ha, the irrigated one only from to : irrigation removes most of the year-to-year variation, and what remains comes from the rest of the weather.

Paddy rice: the flood water balance

In bunded, puddled rice fields the water balance has one more store: the flood above the soil. Bunds hold rain and irrigation as standing water up to their height. The flood loses water by evaporation, by infiltration into the puddled soil at a percolation rate, and by spilling over the bund when it rises above it. The engine keeps this balance every day when the irrigation section of the experiment file sets the paddy operations, and writes it to FloodW.OUT (Management/OpFlood.for). The operations are codes of the engine’s DETAIL.CDE: IR010 puddling, IR008 percolation rate (mm/day), IR009 bund height (mm), IR011 constant flood depth (mm) and IR006 flood depth (mm).

The runs use xdssat’s own rice template, templates/XDRI8601.RIX: IRRI’s IR 58 experiment at Munoz, Philippines (IRMZ8601), with an added rainfed bunded water level. Its three water regimes, in the irrigation section below, are run in the dry season as in the experiment (transplanted early February 1986) and in the wet season (1 July 1986), with nitrogen off so that only water differs.

Lines: flood depth; dashed grey: bund height.

In the wet season the bunds alone keep the field flooded: the rainfed field has standing water on days without any irrigation, mm of rain spills over its bund, and the three regimes give . In the dry season the rainfed field has a flood on day and its crop is water-stressed (mean stress factor , against when flooded). In these runs the stressed crop takes days from planting to maturity against ; over that longer season it receives mm of rain against mm, because the 1986 rains at Munoz start in May, and its simulated yield is kg/ha below the flooded crop’s. Kept flooded, the dry-season crop receives mm of irrigation, and mm of water infiltrates from the flood into the puddled soil. These runs change only the water regime: to see how much the bund height (IR009) and the percolation rate (IR008) matter, change them in the notebook and rerun.

From one field to a grid: xdssat

Section 2 built two soil profiles by hand. For a region, xdssat builds one per cell: texture and organic carbon from SoilGrids (Poggio et al. 2021) at six depths, water limits from soils.saxton_rawls, the same function used above, and the root growth factor from soils.root_growth_factor. The plant-available water of the profiles of the rice case study:

The profiles hold between and mm of plant-available water, a median of mm, against mm for the Millhopper fine sand of the maize experiments. Estimated, not measured: what section 2 showed about the pedotransfer function holds for every cell.

Self-test

  1. GLUE improved the dates of Williams-82 more than its weights. Name two things you would change before calibrating again.
  2. Why is a GLUE posterior with a wide spread not a failure?
  3. Two soils store the same plant-available water, one 60 cm deep and one 150 cm deep. Which would you expect to yield more under rainfed conditions, and what in the model decides it?
  4. In the rainfed run, where did most of the rain go?
  5. What does ITHRL = 90% cost compared with 50%, and what does it buy?
  6. In the peanut grid, which coefficient moves the seed number curve most, and which the tops weight?

Where this goes next

Module 4 turns to the observed data files and to nitrogen. The plan for all six modules is on the training overview.

References

Anothai, J., C. M. T. Soler, A. Green, T. J. Trout, and G. Hoogenboom. 2013. “Evaluation of Two Evapotranspiration Approaches Simulated with the CSM-CERES-Maize Model Under Different Irrigation Strategies and the Impact on Maize Growth, Development and Soil Moisture Content for Semi-Arid Conditions.” Agricultural and Forest Meteorology 176: 64–76. https://doi.org/10.1016/j.agrformet.2013.03.001.
DSSAT Foundation. 2026. DSSAT-CSM Example Data (Dssat-Csm-Data), Commit 99c95b3. https://github.com/DSSAT/dssat-csm-data.
Perkins, Henry F. 1987. Characterization Data for Selected Georgia Soils. Special Publication No. 43. The Georgia Agricultural Experiment Stations, College of Agriculture, The University of Georgia.
Poggio, Laura, Luis M. de Sousa, Niels H. Batjes, et al. 2021. “SoilGrids 2.0: Producing Soil Information for the Globe with Quantified Spatial Uncertainty.” SOIL 7 (1): 217–40. https://doi.org/10.5194/soil-7-217-2021.
Saxton, K. E., and W. J. Rawls. 2006. “Soil Water Characteristic Estimates by Texture and Organic Matter for Hydrologic Solutions.” Soil Science Society of America Journal 70 (5): 1569–78. https://doi.org/10.2136/sssaj2005.0117.
Back to top