Configuration Converter API

6.8. Configuration Converter API#

The converter module provides Python functions for converting SUEWS configurations between different formats and versions.

6.8.1. Key Features#

Format Conversion: Convert table-based inputs to YAML configuration
Version Migration: Update table files between SUEWS versions
Auto-detection: Automatically detect input format and version
Python Integration: Direct Python API for tool integration (e.g., QGIS plugins)

For CLI usage, see SUEWS Format Converter.

6.8.2. Functions#

6.8.2.1. Table to YAML Conversion#

supy.util.converter.convert_to_yaml(input_file: str, output_file: str, from_ver: str | None = None, debug_dir: str | None = None, validate_profiles: bool = True)[source]#

Convert SUEWS input to YAML configuration.

Supports both: 1. Table-based input (RunControl.nml) 2. df_state input (CSV or pickle files)

Parameters:

input_file – Path to input file (RunControl.nml or df_state CSV/pickle)
output_file – Output YAML file path
from_ver – Source version (for table conversion, ignored for df_state)
debug_dir – Directory for debug files (optional)
validate_profiles – Whether to validate profiles

Return type:

None

6.8.2.2. Table Version Conversion#

supy.util.converter.convert_table(fromDir, toDir, fromVer, toVer, debug_dir=None, validate_profiles=True)[source]#

Convert SUEWS table files between versions.

This function performs chained conversion between SUEWS table versions, automatically handling intermediate version transitions when needed.

Parameters:

fromDir – Path to directory containing source SUEWS table files
toDir – Path to directory where converted tables will be saved
fromVer – Source version (e.g., ‘2016a’, ‘2020a’, ‘2024a’)
toVer – Target version (e.g., ‘2024a’, ‘2025a’)
debug_dir – Optional directory to save intermediate conversion files
validate_profiles – Whether to validate and auto-create missing profile entries

Return type:

None

Note

If fromVer == toVer, the function only cleans/reformats files without conversion.

The conversion process: 1. Reads input files from fromDir (using paths in RunControl.nml) 2. Performs chained conversion through intermediate versions if needed 3. Writes converted files to toDir in the target version format

With debug_dir specified, intermediate conversion steps are preserved for inspection.

Examples

>>> from supy.util.converter import convert_table
>>>
>>> # Convert from 2016a to 2024a
>>> convert_table(
...     fromDir="path/to/old_data",
...     toDir="path/to/new_data",
...     fromVer="2016a",
...     toVer="2024a",
... )
>>>
>>> # Convert with debug output
>>> convert_table(
...     fromDir="path/to/old_data",
...     toDir="path/to/new_data",
...     fromVer="2020a",
...     toVer="2024a",
...     debug_dir="debug_output",
... )

6.8.2.3. Utility Functions#

supy.util.converter.detect_input_type(input_file: str | Path) → str[source]#

Detect input type based on file.

Parameters:: input_file – Path to input file (must be a file, not directory)
Returns:: ‘nml’ for RunControl.nml (table conversion) ‘df_state’ for CSV/pickle files
Raises:: ValueError – If input is not a file or has unknown extension

supy.util.converter.detect_table_version(input_dir)[source]#

Auto-detect the version of SUEWS table files.

Detection is based on: - File existence (e.g., AnthropogenicEmission vs AnthropogenicHeat) - Column presence/absence in specific tables - Parameters in RunControl.nml (for 2024a+) - Optional files like SPARTACUS.nml

Each version has unique characteristics that allow precise identification.

Parameters:: input_dir – Path to the directory containing SUEWS table files
Returns:: str
Return type:: Detected version (e.g., ‘2016a’, ‘2024a’) or None if unable to detect

Note

Detection checks versions from newest to oldest using unique characteristics of each version. Some versions (e.g., 2018a/b/c, 2020a/2021a) are identical in structure; any detection among them is acceptable.

6.8.3. Quick Examples#

Convert table-based input to YAML:

from supy.util.converter import convert_to_yaml

# Auto-detect version and convert
convert_to_yaml(
    input_file='path/to/RunControl.nml',
    output_file='config.yml'
)

# Specify version explicitly
convert_to_yaml(
    input_file='path/to/RunControl.nml',
    output_file='config.yml',
    from_ver='2024a'
)

Convert between table versions:

from supy.util.converter import convert_table

# Convert from old to new version
convert_table(
    fromDir='path/to/old_data',
    toDir='path/to/new_data',
    fromVer='2016a',
    toVer='2024a'
)

Auto-detect input format:

from supy.util.converter import detect_input_type, detect_table_version
from pathlib import Path

# Detect input type
input_path = Path('path/to/RunControl.nml')
input_type = detect_input_type(input_path)  # Returns 'nml'

# Detect table version
if input_type == 'nml':
    version = detect_table_version(input_path.parent)
    print(f"Detected version: {version}")

6.8.4. Error Handling#

The converter functions raise informative exceptions on errors:

from supy.util.converter import convert_to_yaml
from pathlib import Path

try:
    convert_to_yaml(
        input_file='path/to/RunControl.nml',
        output_file='config.yml'
    )
except ValueError as e:
    # Input validation errors
    print(f"Input error: {e}")
except FileNotFoundError as e:
    # Missing files
    print(f"File not found: {e}")
except Exception as e:
    # Other conversion errors
    print(f"Conversion failed: {e}")