dpest.ts#

dpest.ts.ts(ts_file_path=None, treatment=None, variables=None, output_path=None, experiment=None, suffix=None, variables_classification=None, ts_ins_first_line=None, mrk='~', smk='!')[source]#

Creates a PEST instruction file (.INS) for DSSAT time-series output files. This instruction file contains directions for PEST to read simulated time-series values from daily DSSAT outputs (e.g. PlantGro.OUT, PlantN.OUT, PlantC.OUT, PlantGrf.OUT, SoilNi.OUT, SoilWat.OUT, SoilTemp.OUT) and to match them with the corresponding measured values stored in the DSSAT T file.

The time-series output files supported by this function share a common tabular format where the first three columns are:

@YEAR DOY DAS

The PEST instruction file (.INS) guides PEST in extracting specific model-generated observations at specific time points for the variables specified by the user. Additionally, this module creates a tuple containing:

  1. A DataFrame with the MEASURED observations (entered by the user in the DSSAT T file) for the specified variables.

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

Required Arguments

  • ts_file_path (str):

    Path to the DSSAT time-series output file to read. This can be any daily DSSAT output with @YEAR DOY DAS as the first three header columns, for example:

    • C:/DSSAT48/Soybean/PlantGro.OUT

    • C:/DSSAT48/Soybean/PlantN.OUT

    • C:/DSSAT48/Soybean/PlantC.OUT

    • C:/DSSAT48/Soybean/SoilNi.OUT

    • C:/DSSAT48/Soybean/SoilWat.OUT

  • treatment (str):

    Name of the treatment for which the cultivar is being calibrated. This must match exactly the treatment name as shown in the DSSAT interface when an experiment is selected (i.e. the value that appears in the TREATMENT line of the output header).

    Example: "164.0 KG N/HA IRRIG" or "76 Equidist BRAGG".

  • variables (list or str):

    Variable code(s) from the DSSAT T file (and thus present in the header of the selected time-series output file) that PEST will extract. The instruction file uses these codes to read the model output at the specified dates.

    • A single variable can be provided as a string, e.g. "LAID".

    • Multiple variables can be provided as a list, e.g. ["LWAD", "SWAD", "GWAD", "RWAD", "CWAD", "HIAD", "PWAD"].

Optional Arguments#

  • output_path (str, default: current working directory):

    Directory where the generated PEST instruction file (.INS) will be saved. If not provided, the current working directory is used.

  • 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 time-series 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") identifies different treatments used for calibrating the same cultivar in the same calibration process. It must be 1–4 characters long and alphanumeric.

    For example, if suffix="TRT1" and ts_file_path="C:/DSSAT48/Wheat/PlantGro.OUT", the output file will be named PlantGro_TRT1.ins and markers will look like !LAID_75167_TRT1!.

  • variables_classification (dict, optional):

    Mapping of variable codes to their respective categories (groups). When provided, this dictionary is used directly, with the format:

    {"LAID": "lai", "CWAD": "biomass", ...}

    When variables_classification is None, the function loads a global classification from the package configuration file (dpest/arguments.yml, key VARIABLES_CLASSIFICATION_GLOBAL), and maps each variable code to its group from that dictionary.

  • ts_ins_first_line (str, default: “pif”):

    First line of the PEST instruction file (.INS). By default this is read from the package configuration (key INS_FILE_VARIABLES in dpest/arguments.yml) when not provided.

  • 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 &.

Internal behaviour#

  • The function parses the header of the selected time-series file to determine the experiment code, model, and crop name for the specified treatment.

  • From the crop name and the SIMULATION_CROP_MODELS section in dpest/arguments.yml, it infers the DSSAT crop code (e.g. WH, SB, MZ) and constructs the name of the T file as <EXPCODE>.<CROPCODE>T (e.g. SWSW7501.WHT, CLMO8501.SBT).

  • The T file is then read to obtain the measured time-series values for the requested variables and dates, which are used to build the DataFrame and the .INS file.

Returns#

  • tuple:

    • pandas.DataFrame:

      A DataFrame containing the measured values for the selected variables and dates, with columns:

      • variable_name (including date and optional suffix)

      • value_measured (float)

      • group (classification group)

    • str:

      Full path to the generated PEST instruction file (.INS).

Examples#

  1. PlantGro time series (Soybean)

    from dpest import ts

plantgro_observations, plantgro_ins_path = ts(
    treatment='76 Equidist BRAGG',
    ts_file_path='C:/DSSAT48/Soybean/PlantGro.OUT',
    variables=['LWAD', 'SWAD', 'GWAD', 'RWAD', 'CWAD',
               'HIAD', 'PWAD', 'LN%D', 'SH%D', 'HIPD', 'SLAD'],
)

    This creates a PlantGro.ins file and a DataFrame with the measured values for the selected plant growth variables for treatment "76 Equidist BRAGG".

  2. PlantN time series (Soybean)

    from dpest import ts

plantn_observations, plantn_ins_path = ts(
    treatment='76 Equidist BRAGG',
    ts_file_path='C:/DSSAT48/Soybean/PlantN.OUT',
    variables=['LN%D', 'SN%D'],
)

    This reads nitrogen-related time-series variables from PlantN.OUT and creates a matching instruction file and DataFrame. Global variable classifications are used unless a custom mapping is supplied.

  3. Soil water time series

    from dpest import ts

soilwat_observations, soilwat_ins_path = ts(
    treatment='76 Equidist BRAGG',
    ts_file_path='C:/DSSAT48/Soybean/SoilWat.OUT',
    variables=['SW1D', 'SW2D', 'SW3D'],
)

    This reads daily soil water content in the top layers from SoilWat.OUT and builds a PEST instruction file for those variables.

On this page

This Page