dpest.spe#

dpest.spe.spe(species_file_path=None, output_path=None, new_template_file_extension=None, tpl_first_line=None, mrk='~', **parameters_grouped)[source]#

Creates a PEST template file (.TPL) for species-level parameters based on a DSSAT species file (.SPE) (e.g. SBGRO048.SPE, WHCER048.SPE).

Unlike cultivar (.CUL) and ecotype (.ECO) files, species files do not follow a strictly tabular structure. Parameters are often arranged in blocks, tuples, or vectors, and may lack explicit column headers. This module therefore relies on user-specified parameter locations (line number and column position) to build the template.

Each parameter to be calibrated is provided as a keyword argument, where the keyword is the user-defined parameter name, and the value describes the location and bounds of that parameter. Two input formats are supported:

  1. Tuple / list syntax (no explicit keys):

    PARMAX = (line, column, min_value, max_value, group_name)

    For example:

    PARMAX = (5, 1, 20.0, 60.0, 'PHOTOSYN')

    where:

    • line (int): 1-based line number in the .SPE file where the parameter value (to calibrate) is located.

    • column (int): 1-based column index of the parameter value (to calibrate) within that line, counting numeric entries from left to right.

    • min_value (float): Minimum value of the parameter search range to be used in the PEST calibration.

    • max_value (float): Maximum value of the parameter search range to be used in the PEST calibration.

    • group_name (str, optional): Name of the PEST parameter group to which this parameter belongs. If omitted, the group name defaults to the parameter name (e.g. PARMAX).

  2. Dictionary syntax (explicit keys):

    PARMAX = {
    'line': 5,
    'column': 1,
    'min': 20.0,
    'max': 60.0,
    'group': 'PHOTOSYN',
}

    If 'group' is not provided, it defaults to the parameter name.

The function replaces the original numeric values at the specified locations with PEST template markers, truncating or padding parameter identifiers as needed to fit within the available space, and ensuring that each truncated identifier is unique (e.g. ~PM0~, ~PM1~). The resulting template file is written alongside the original species file (or to output_path if provided).

Required Arguments:#

  • species_file_path (str):

    Full path to the DSSAT species file (.SPE). For example:

    • C:/DSSAT48/Genotype/WHCER048.SPE

    • C:/DSSAT48/Genotype/SBGRO048.SPE

Optional Arguments:#

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

    Directory to save the generated PEST template file (.TPL).

  • new_template_file_extension (str, default: “TPL”):

    Extension for the generated PEST template file (.TPL). This is the PEST default value and should not be changed without good reason.

  • tpl_first_line (str, default: “ptf”):

    First line to include in the PEST template file (.TPL). This is the PEST default value and should not be changed without good reason.

  • mrk (str, default: “~”):

    Primary marker delimiter character for the template file. Must be a single character and cannot be A–Z, a–z, 0–9, !, [, ], (, ), :, space, tab, or &.

  • parameters_grouped (dict, optional):

    Species parameters to calibrate, passed as keyword arguments. Each keyword corresponds to a parameter name (used as the PEST parameter identifier before truncation), and its value is either:

    • A tuple/list: (line, column, min_value, max_value[, group_name])

    • A dictionary with keys: 'line', 'column', 'min', 'max', and optional 'group'.

    For example:

    from dpest import spe

species_parameters, species_tpl_path = spe(
    species_file_path = 'C:/DSSAT48/Genotype/WHCER048.SPE',
    PGERM = (15, 1, 0.0, 20.0, 'Phase_dur'),
    P0    = (15, 3, -5.0, 5.0, 'Phase_dur'),
    Fac   = (19, 1, 0.0, 2.0,  'Phase_dur'),
    h     = (19, 2, 10.0, 30.0, 'Phase_dur'),
    GrStg = (19, 3, 0.0, 4.0,  'Phase_dur'),
    LWLOS = (30, 3, 0.0, 6.0,  'Phase_dur'),
)

    In this case, several CERES-Wheat species parameters from different sections of the WHCER048.SPE file are selected for calibration in a single template.

Returns:#

  • tuple: A tuple containing:

    • dict: A dictionary containing:

      • 'parameters':

        Current parameter values at the specified locations. Keys are the truncated parameter identifiers that are written into the template file.

      • 'minima_parameters':

        User-specified minimum values for each parameter, keyed by the truncated parameter identifiers. These values define the lower limits of the parameter ranges explored by PEST.

      • 'maxima_parameters':

        User-specified maximum values for each parameter, keyed by the truncated parameter identifiers. These values define the upper limits of the parameter ranges explored by PEST.

      • 'parameters_grouped':

        Parameter group definitions, with each group containing a comma-separated list of the truncated parameter identifiers used in the template file.

    • str:

      The full path to the generated PEST template file (.TPL).

Notes:#

  • Line numbering convention:

    This function assumes that the user-provided line values are 1-based (i.e. the first line in the file is line 1). Internally, these values are converted to 0-based indices when accessing the file content.

  • Column indexing:

    The column argument is interpreted as a 1-based index of the numeric entry within the specified line, counting from left to right. Internally, the line is split into entries using default whitespace separation in order to locate the corresponding value.

Examples:#

  1. CERES-Wheat species file (WHCER048.SPE):

    from dpest import spe

species_parameters, species_tpl_path = spe(
    species_file_path = 'C:/DSSAT48/Genotype/WHCER048.SPE',
    PGERM = (15, 1, 0.0, 20.0, 'Phase_dur'),
    P0    = (15, 3, -5.0, 5.0, 'Phase_dur'),
    Fac   = (19, 1, 0.0, 2.0,  'Phase_dur'),
    h     = (19, 2, 10.0, 30.0, 'Phase_dur'),
    GrStg = (19, 3, 0.0, 4.0,  'Phase_dur'),
    LWLOS = (30, 3, 0.0, 6.0,  'Phase_dur'),
)

    The returned species_parameters dictionary can be used to define PEST parameter groups and parameter ranges in the PEST control file using the pst module, and species_tpl_path is used in the input_output_file_pairs argument of the pst module to match the original WHCER048.SPE file to the template file.

  2. Soybean species file (SBGRO048.SPE) using dictionary syntax:

    from dpest import spe

species_parameters, species_tpl_path = spe(
    species_file_path = 'C:/DSSAT48/Genotype/SBGRO048.SPE',
    PARMAX = {
        'line': 5,
        'column': 1,
        'min': 20.0,
        'max': 60.0,
        'group': 'PHOTOSYN',
    },
    PHTMAX = {
        'line': 5,
        'column': 2,
        'min': 40.0,
        'max': 80.0,
        'group': 'PHOTOSYN',
    },
    XLMAXT_2 = {
        'line': 11,
        'column': 2,
        'min': 0.0,
        'max': 20.0,
        'group': 'TEMP_RESP',
    },
    XPGSLW_3 = {
        'line': 18,
        'column': 3,
        'min': 0.0,
        'max': 0.01,
        'group': 'SLW_SHAPE',
    },
    RTDEPI = {
        'line': 40,
        'column': 1,
        'min': 10.0,
        'max': 40.0,
        'group': 'ROOTS',
    },
)

    This example illustrates the dictionary syntax for specifying parameter locations and bounds in the soybean SBGRO048.SPE file, where several parameters are stored in tuple or vector‑like blocks rather than simple scalar entries.

On this page

This Page