dpest 3.1.0

A Python package for automating PEST (Parameter ESTimation) file creation for DSSAT crop model calibration using time series data. It generates template, instruction, and control files for parameter estimation, including tools for extending time series data.

dpest

A Python package for automating PEST (Parameter ESTimation) input file creation for DSSAT crop model calibration using time series and end-of-season data.

What is dpest?

dpest is a Python package designed to automate the creation of PEST (Parameter Estimation and Uncertainty Analysis) input files for calibrating DSSAT (Decision Support System for Agrotechnology Transfer) crop models. It generates template files for cultivar and ecotype parameters, instruction files for DSSAT output files (end-of-season and time series), and the main PEST control file. A utility module is also included to post-process DSSAT time-series outputs and to conveniently edit model-independent PEST settings.

Originally developed for CERES-Wheat, dpest now supports any DSSAT model.

Documentation

For detailed usage instructions and module references, see the full documentation on: dpest.readthedocs.io/en/latest.

Key Features

• Automated generation of PEST control files (.PST).
• Support for multiple DSSAT crops and models, not only CERES-Wheat.
• Creation of PEST template files (.TPL) for cultivar and ecotype parameters.
• Generation of PEST instruction files (.INS) for:
  • end-of-season outputs (e.g. OVERVIEW.OUT)
  • time-series outputs (e.g. PlantGro.OUT, PlantN.OUT, PlantC.OUT and other DSSAT time-series files)
• Utility modules to post-process DSSAT time-series outputs and edit common PEST settings directly in .pst files.

Installation

dpest can be installed via pip from PyPI.

pip install dpest

How to Cite

If you use dpest in your research, please cite our article in the Journal of Open Source Software:

APA:

Vargas-Rojas, L., & Wang, D. R. (2025). dpest: Streamlining Creation of PEST input files for DSSAT Crop Model Calibration. Journal of Open Source Software, 10(111), 8188. https://doi.org/10.21105/joss.08188

BibTeX:

@article{Vargas-Rojas_dpest_Streamlining_Creation_2025, author = {Vargas-Rojas, Luis and Wang, Diane R.}, title = {dpest: Streamlining Creation of PEST input files for DSSAT Crop Model Calibration}, journal = {Journal of Open Source Software}, year = {2025}, volume = {10}, number = {111}, pages = {8188}, doi = {10.21105/joss.08188}, url = {https://joss.theoj.org/papers/10.21105/joss.08188}, month = jul }

For additional citation formats, see the CITATION.cff file in this repository or use the "Cite this repository" button in the GitHub About section.

Prerequisites

1. DSSAT Software: DSSAT (version 4.8) must be installed on your system.
2. DSSAT Experiment Data: You'll need a DSSAT experiment to work with. The example below uses the SWSW7501WH N RESPONSE wheat experiment.
3. PEST Software: You’ll need to have PEST (version 18) installed.

How to Use dpest?

Jupyter notebook example

To quickly explore how dpest works in practice, you can open and run the example Jupyter notebook included in the repository:

examples/wheat/ceres/usage_example.ipynb

This notebook walks through:

• Loading DSSAT outputs (OVERVIEW.OUT, PlantGro.OUT)
• Generating template (.TPL) and instruction (.INS) files
• Creating the main PEST control file (.PST)
• Validating the setup using PEST check commands

To run the notebook:

  pip install dpest[notebook]
  jupyter notebook examples/wheat/ceres/usage_example.ipynb

Note: The [notebook] extra installs ipykernel and notebook dependencies required to open the notebook.

Read the Docs

For a detailed, step-by-step example, please refer to the official documentation:
Complete Example on Read the Docs

Basic Usage

The following steps provide a brief overview of how to use dpest.

1. Locate DSSAT Genotype Files: The cultivar (.CUL) and ecotype (.ECO) files are typically included with the DSSAT installation. These are usually found in the C:\DSSAT48\Genotype\ directory.

2. Run a DSSAT Simulation: Execute a DSSAT simulation for your chosen wheat experiment using the CERES model. This will generate the necessary output files (OVERVIEW.OUT and PlantGro.OUT), typically found in the C:\DSSAT48\Wheat\ directory.

   2.1. Launch DSSAT.
   2.2. Click "Selector".
   2.3. Expand "Crops" and select "Wheat".
   2.4. In the "Data" panel select the "SWSW7501.WHX" experiment.
   2.5. Click "Run" button in the toolbar.
   2.6. In the "Simulation" popup window, choose "CERES" as the crop model.
   2.7. Click "Run Model" and wait for the simulation to finish.
   

3. Import the dpest Package:

   • To import the entire dpest package:

   import dpest
   

   • To import specific modules:

   from dpest.wheat.ceres import cul, eco
   from dpest import overview, ts, spe, pst, uts
   
   # Now you can use the functions directly:
   cul(...)
   eco(...)
   overview(...)
   ts(...)
   spe(...)
   pst(...)
   uts(...)
   

4. Use the Modules

   • cul(): Creates PEST template files (.TPL) for cultivar parameters based on DSSAT .CUL genotype files.
   • eco(): Creates PEST template files (.TPL) for ecotype parameters based on DSSAT .ECO genotype files.
   • spe(): Creates PEST instruction files (.INS) for ecotype parameters based on DSSAT .SPE genotype files.
   • overview(): Creates PEST instruction files (.INS) for reading observed (measured) values of key end-of-season crop performance metrics and phenology from the OVERVIEW.OUT file.
   • ts(): Creates PEST instruction files (.INS) for reading time-series data from DSSAT output files such as PlantGro.OUT, PlantN.OUT, PlantC.OUT and other time-series .OUT files, using user-selected variables and treatments.
   • pst(): Generates the main PEST control file (.PST) and integrates template files, instruction files, parameters, observations, and the model command line.
   • uts(): Post-processes DSSAT time-series outputs (e.g. PlantGro.OUT) to prevent PEST errors when simulated crop maturity occurs before the final measured observation, ensuring complete time-series comparison.

5. Create Template Files and Instruction Files: Use the dpest modules to generate PEST template files (.TPL) for cultivar and ecotype parameters, and PEST instruction files (.INS) for the OVERVIEW.OUT and PlantGro.OUT files.

import dpest

# 1. Create CULTIVAR parameters TPL file
cultivar_parameters, cultivar_tpl_path = dpest.cul(
    P = 'P1D, P5', # How the user should enter the parameters
    G = 'G1, G2, G3', 
    PHINT = 'PHINT',
    cultivar = 'MANITOU',
    cul_file_path = 'C:/DSSAT48/Genotype/WHCER048.CUL'
)

# 2. Create OVERVIEW observations INS file
overview_observations,  overview_ins_path = dpest.overview(
    treatment = '164.0 KG N/HA IRRIG', #Treatment Name
    overview_file_path = 'C:/DSSAT48/Wheat/OVERVIEW.OUT' #Path to the OVERVIEW.OUT file
)
# 3. Create PlantGro observations INS file
plantgro_observations, plantgro_ins_path = dpest.ts(
    treatment = '164.0 KG N/HA IRRIG', #Treatment Name
    variables = ['LAID', 'CWAD', 'T#AD'] #Variables to calibrate
    plantgro_file_path = 'C:/DSSAT48/Wheat/PlantGro.OUT', #Path to the PlantGro.OUT file
)

6. Create the PEST Control File: Use the dpest.pst() module to generate the main PEST control file (.PST).

# 4. Create the PST file
dpest.pst(
    cultivar_parameters = cultivar_parameters,
    dataframe_observations = [overview_observations, plantgro_observations],
    model_comand_line = r'py "C:\pest18\run_dssat.py"', #Command line to run the model
    input_output_file_pairs = [
        (cultivar_tpl_path, 'C://DSSAT48/Genotype/WHCER048.CUL'), #Template file and the file to be modified
        (overview_ins_path , 'C://DSSAT48/Wheat/OVERVIEW.OUT'), #Instruction file and the file to be modified
        (plantgro_ins_path , 'C://DSSAT48/Wheat/PlantGro.OUT') #Instruction file and the file to be modified
    ]
)

7. Run PEST: Calibrate the model using PEST.

---

Utilities for Editing PEST Control Files

In addition to automating the creation of PEST control and template files for DSSAT CERES-Wheat model calibration, dpest includes a growing set of utility functions under dpest.utils for directly modifying existing .pst (PEST control) files.

Why use dpest.utils?

Unlike libraries such as pyEMU, which parse .pst files into Python objects and rewrite the entire file when saving any change, dpest.utils performs lightweight, line-by-line edits to preserve the original structure and untouched content.

These utilities:

• Edit existing .pst files in place, without reconstructing or redefining unrelated fields.
• Are model-agnostic: they work with any .pst file, not just DSSAT-related ones.
• Only modify model-independent control parameters (e.g., optimization settings), leaving parameter and data blocks untouched.

This makes them ideal for quickly tuning optimization settings or cleaning up .pst files generated by dpest or other tools.

Example Usage

# Load the dpest.utils
from dpest.utils import noptmax, rmv_splitcols

# Path to the .pst file
pst_file_path = './ENTRY1/PEST_CONTROL.pst'

# Increase the number of optimization iterations (NOPTMAX) in a .pst file
noptmax(pst_file_path, new_value=50)

# Remove SPLITTHRESH/SPLITRELDIFF/SPLITACTION columns from a .pst file parameter groups section
rmv_splitcols(“PEST_CONTROL.pst”)

Full List of Utility Functions:
For the complete reference of available utility functions and their descriptions, see the dpest ReadTheDocs Utils page.

Test Coverage

A detailed and up-to-date test coverage report for the dpest codebase is available on Codecov:

View detailed coverage report on Codecov

Developer and Tester Setup Instructions for dpest

These instructions will guide you through setting up your environment, installing dependencies, and running tests for the dpest package.

Prerequisites

• Python 3.10 or higher installed
• Git installed

Step 1: Clone the Repository

git clone https://github.com/DS4Ag/dpest.git
cd dpest

Step 2: Create and Activate a Virtual Environment

On Windows:

py -3.10 -m venv .venv
.\.venv\Scripts\activate

On macOS/Linux:

python3.10 -m venv .venv
source .venv/bin/activate

Step 3: Install PDM (Python Development Master)

PDM is a modern Python package and dependency manager recommended for development and testing.

Install PDM using pipx (recommended):

python -m pip install --user pipx
pipx ensurepath
pipx install pdm

Or install PDM using pip:

pip install --user pdm

Step 4: Install Project Dependencies

pdm install

Step 5: Install Development Dependencies (for testing)

pdm install --dev

Step 6: Run the Test Suite

pdm run pytest tests/ -v

Community Guidelines

We welcome contributions from the community!

• To report issues or request features, please use GitHub Issues.
• To contribute code, fork the repository, create a branch, and submit a pull request.
• For questions or support, open an issue or participate in GitHub Discussions if enabled.
• All participants are expected to follow the Contributor Covenant Code of Conduct
• For detailed instructions on how to contribute, please see our contribution guidelines.

License

dpest is released under the GNU General Public License v3.0 only.