dpest.overview#

dpest.overview.overview(treatment=None, overview_file_path=None, output_path=None, experiment=None, suffix=None, variables=None, variables_classification=None, overview_ins_first_line=None, mrk='~', smk='!')[source]#

Creates a PEST instruction file (.INS). This instruction file contains directions for PEST to read the simulated values from the OVERVIEW.OUT file and compare them with the corresponding observed values (originally entered in the DSSAT “A file”). The PEST instruction file (.INS) guides PEST in extracting specific model-generated observations from the OVERVIEW.OUT file, which includes a list of end-of-season crop performance metrics, and critical phenological observations used for model evaluation. Additionally, this module creates a tuple containing:

  1. A DataFrame with the MEASURED observations from the OVERVIEW.OUT file (originally entered in the DSSAT “A file”).

  2. The path to the generated PEST instruction file (.INS).

Required Arguments:#

  • treatment (str): The name of the treatment for which the cultivar is being calibrated. This should match exactly the treatment name as shown in the DSSAT application interface when an experiment is selected. For example, "164.0 KG N/HA IRRIG" is a treatment of the SWSW7501WH.WHX experiment.

  • overview_file_path (str): Path to the OVERVIEW.OUT file to read. Usually the file is in C:\DSSAT48\Wheat\OVERVIEW.OUT.

Optional Arguments:#

  • output_path (str, default: current working directory): Directory where the generated PEST instruction file (.INS) will be saved.

  • experiment (str, optional): Experiment code as shown in the PlantGro.OUT header (e.g. "AZMC9311"). When the same treatment name appears in more than one experiment within the same OVERVIEW.OUT file, this argument is used to select the correct experiment block. If not provided and the treatment is unique in the file, the function will use the unique experiment automatically. If the treatment appears in multiple experiments and experiment is not specified, it will the variables for that treatment that appear in the last part of the file.

  • suffix (str, default: “”): Suffix to append to the output filename and variable names in the .INS file. This short code (e.g., TRT1, TRT2, TRT3) identifies different treatments used for calibrating the same cultivar (or ecotype) in the same calibration process. It must be 1–4 characters long, containing only uppercase letters and/or numbers. For example, if suffix="TRT1", the output file will be named OVERVIEW_TRT1.ins and variable markers will include the suffix (e.g., !Anthesis_DAP_TRT1!). This ensures that PEST can distinguish between variables from different treatments, as PEST does not allow variables with the same name.

  • variables (list or str): Variable(s) from the OVERVIEW.OUT file that PEST will extract in case the user does not want to use all the variables present in the DSSAT “A file” for the calibration. The PEST instruction file will use these to read the model output. You may specify a single variable as a string (e.g., 'Anthesis (DAP)') or multiple variables as a list (e.g., ['Anthesis (DAP)', 'Maturity (DAP)', 'Product wt (kg dm/ha;no loss)', 'Maximum leaf area index', 'Canopy (tops) wt (kg dm/ha)', 'Above-ground N (kg/ha)']).

  • variables_classification (dict): Mapping of variable names to their respective categories. If provided, it is used directly to classify variables. If not provided, the function will attempt to load crop- and model-specific classification from a configuration file located at dpest/<crop>/<model>/arguments.yml.

  • overview_ins_first_line (str, default: “pif”): First line of the PEST instruction file (.INS). This is the PEST default value and is obtained from the package configuration file (dpest/arguments.yml) when not provided by the user.

  • mrk (str, default: “~”): Primary marker delimiter character for the instruction file. Must be a single character and cannot be A–Z, a–z, 0–9, !, [, ], (, ), :, space, tab, or &.

  • smk (str, default: “!”): Secondary marker delimiter character for the instruction file. Must be a single character and cannot be A–Z, a–z, 0–9, [, ], (, ), :, space, tab, or &.

Returns:#

  • tuple: A tuple containing:

    • pandas.DataFrame: A filtered DataFrame used to generate the PEST instruction file (.INS).

    • str: The full path to the generated PEST instruction file (.INS).

Examples:#

  1. Basic Usage (Required arguments only, crop/model-based defaults):

    from dpest import overview

overview_observations, overview_ins_path = overview(
    treatment='164.0 KG N/HA DRY',
    overview_file_path='C:/DSSAT48/Wheat/OVERVIEW.OUT',
    crop='wheat',
    model='ceres',
)

  2. Specifying Variable Classifications Manually:

    from dpest import overview

overview(
    treatment='164.0 KG N/HA DRY',
    overview_file_path='C:/DSSAT48/Wheat/OVERVIEW.OUT',
    variables=[
        'Anthesis (DAP)', 'Maturity (DAP)',
        'Product wt (kg dm/ha;no loss)',
        'Maximum leaf area index',
        'Canopy (tops) wt (kg dm/ha)',
        'Above-ground N (kg/ha)',
    ],
    variables_classification={
        'Anthesis (DAP)': 'phenology',
        'Maturity (DAP)': 'phenology',
        'Product wt (kg dm/ha;no loss)': 'yield',
        'Maximum leaf area index': 'lai',
        'Canopy (tops) wt (kg dm/ha)': 'biomass',
        'Above-ground N (kg/ha)': 'nitrogen',
    },
)
On this page

This Page