API Reference

class talsimpy.TalsimDataset(path: Path | str, name: str)

Class for handling and manipulating a Talsim ASCII dataset

calculate_average_soil_properties() → DataFrame

Calculates the average soil properties for soil types over all layers

Returns:

pandas Dataframe

copy(destination: Path | str, include_results: bool = False) → TalsimDataset

Copies the dataset to a destination directory, optionally including result files

Parameters:

• destination – destination directory

• include_results – if True, also copy result files (default: False)

Returns:

the destination dataset

copy_result_files(dir_dest: Path | str) → None

Copy all result files to a destination directory

Copies all files with stem corresponding to the dataset name and one of the extensions in RESULT_EXTENSIONS

Parameters:

dir_dest – destination directory

property errors: str | None

Returns the errors from the last simulation run or None if none exist

file_to_dataframe(file: str) → DataFrame

Reads a dataset file as a pandas DataFrame

Parameters:

file – file to read: “BOA”, “BOD”, “EFL” or “EZG”

Returns:

the contents of the file as a pandas DataFrame

get_sim_options() → dict

Gets all options set in the ALL file

Returns:

dictionary of keys and values as strings

process_templates(variables: dict) → None

Processes template files in a Talsim dataset by replacing the appropriate parameter values

NOTES:

• Template files must be named like the original file but with an additional extension “template”, e.g. “dataset.ALL.template” and will replace the original file after variable substitution.

• Template files must contain placeholders for variables enclosed with curly braces, e.g. {variable_name}

• Standard Python string format specifiers (e.g. {variable_name:formatspec}) are allowed https://docs.python.org/3/library/string.html#format-specification-mini-language but behave slightly differently than the default: * floats: the given precision may be automatically reduced in order to fit the specified length * strings: strings may be cut to the specified length if too long

Parameters:

variables – dict of variable names and values {name: value, …}

results_to_xarray(element_type: str, system_state: str, epsg: int = None) → xr.DataArray

Converts simulation results to a xarray.DataArray

Parameters:

• element_type – element type to process, must be one of “catchment”, “transport”, “system” or “hru”

• system_state – system state to process, e.g. “1AB”, “BOF”, etc.

• epsg – optional coordinate reference system to set

Returns:

a xarray.DataArray containing the specified system state as a variable

set_calibration_parameters(parameters: dict) → None

Sets calibration parameters in the KAL file

Parameters:

parameters – dictionary of keys and values to set. Keys must correspond to existing parameters in the KAL file

set_sim_options(options: dict) → None

Sets new options in the ALL file

Parameters:

options – dictionary of keys and values to set. Keys must correspond to existing options in the ALL file

property sim_end: datetime

Returns the simulation end date as set in the ALL file

property sim_start: datetime

Returns the simulation start date as set in the ALL file

property timeseries_result_files: list[Path]

Returns a list of available timeseries result files

property warnings: str | None

Returns the warnings from the last simulation run or None if none exist

write_varfile(file_var: str, vars: dict[slice(<class 'str'>, talsimpy.timeseries.Timeseries | bool, None)]) → None

Creates a Talsim VAR file containing the given variables

Parameters:

• file_var – filename of VAR file to write

• vars – dictionary with identifiers as keys and variables as values. Values may be of type Timeseries or bool.

class talsimpy.TalsimDatabase(path: Path | str)

CLass for handling a Talsim 5 database

open_scenario(scenario_id: int) → TalsimScenario

Opens a scenario from the database, returning a corresponding TalsimScenario instance

class talsimpy.TalsimScenario(path: Path | str, scenario_id: int)

Class for handling and manipulating a scenario in a database

property active_simulation: int | None

Returns the currently active simulation

Returns:

active simulation id or None if not set

copy(destination: Path | str, include_results: bool = False) → TalsimScenario

Copies the scenario (i.e. the whole database) to a destination directory, optionally including result files

Parameters:

• destination – destination directory

• include_results – if True, also copy result files (default: False)

Returns:

the destination scenario

db = None

Path to the database file

id = None

Scenario id

set_active_simulation(sim_id: int) → None

Sets the active simulation id

Parameters:

sim_id – the simulation id to set

set_parameter(table: str, id: int, field: str, value: int | float | str) → None

Sets an arbitray value in the database

Parameters:

• table – name of the database table

• id – Id of the row

• field – name of the field

• value – new value to set

set_sim_end(sim_end: datetime) → None

Sets the simulation end date for the currently active simulation

set_sim_start(sim_start: datetime) → None

Sets the simulation start date for the currently active simulation

property sim_end: datetime

Returns the simulation end date for the currently active simulation

sim_id = None

Currently active simulation id

property sim_start: datetime

Returns the simulation start date of the currently active simulation

simulations = {}

name, …}

Type:

Dictionary of existing simulations {id

class talsimpy.TalsimEngine(path: Path | str)

Class for carrying out simulations with Talsim

property exe_file: Path

Returns the path to the executable

ktrcheck(dataset: TalsimDataset | TalsimScenario, language: str = 'de', path_output=None) → bool

Carries out a KTRCheck run

Parameters:

• dataset – TalsimDataset or TalsimScenario instance to check

• language – optional language (default: “de”)

• path_output – optional output path (only relevant for TalsimScenario instances)

Returns:

boolean success

launch(runfile: Path | str) → int

Launches the Talsim engine with a given run file

Parameters:

runfile – path to run file

Returns:

return code of the process

static read_runfile(runfile: Path | str) → dict[str, str]

Reads a run file and returns the settings as a dictionary

Parameters:

runfile – path to run file

Returns:

dictionary with settings

simulate(dataset: TalsimDataset | TalsimScenario, name: str = None, variation_id: int = 0, language: str = 'de', path_timeseries: Path | str = None, sim_id: int = None, path_output: Path | str = None) → bool

Carries out a simulation

Parameters:

• dataset – TalsimDataset or TalsimScenario instance to simulate

• name – optional name for the output files (only relevant for TalsimScenario instances, defaults to scenario name)

• variation_id – optional Variation ID (default: 0)

• language – optional language (default: “de”)

• path_timeseries – optional path to time series files (only relevant for TalsimScenario instances)

• sim_id – optional simulation id (only relevant for TalsimScenario instances, defaults to active simulation id)

• path_output – optional output path (only relevant for TalsimScenario instances)

Returns:

boolean success

property version: str

Returns the Talsim engine version number

class talsimpy.Timeseries(title: str = '')

Class for storing and manipulating time series

title

time series title

Type:

str

station_id

station ID

Type:

str

station_name

station name

Type:

str

param

parameter which the time series represents (e.g. “P”, “Q”, etc.)

Type:

str

unit

unit of the time series values

Type:

str

location

location name

Type:

str

lat

latitude coordinate

Type:

float

lon

longitude coordinate

Type:

float

z

altitude

Type:

float

interpretation

interpretation code as defined in sydrodomain.ini

Type:

int

nodes

dictionary of timestamps and corresponding values (is not automatically sorted by date!)

Type:

dict

class Interpretation(*values)

Enum of interpretations as defined in sydrodomain.ini

add_node(timestamp: datetime, value: float) → None

Adds a new node consisting of timestamp, value to the timeseries

If a timestamp already exists, it is overwritten and a corresponding warning log message is emitted

Parameters:

• timestamp – the timestamp of the node

• value – the value of the node (can be np.nan for Nan-values)

Raises:

ValueError – if timestamp is not a valid datetime object

copy() → Timeseries

create a copy of the time series

Returns:

a copy of the Timeseries instance

copy_metadata(ts: Timeseries) → None

copies metadata from a second time series to this timeseries

Parameters:

ts – the time series from which to copy metadata

count_value_nodes() → int

Returns the number of nodes with non-NaN values in the time series

Returns:

number of non-NaN values (int)

cut(start: datetime, end: datetime) → None

cuts the time series to the period defined by start and end (inclusively)

Parameters:

• start – start date (inclusive)

• end – end date (inclusive)

property dates: list[datetime]

returns a sorted list of the dates contained in the timeseries

Returns:

list of datetime objects

delete_nan_nodes() → None

Deletes nodes with NaN values from the time series

delete_negative_nodes() → None

Deletes nodes with negative values from the time series

property end: datetime

the time series end date or None if the time series is empty

Type:

returns

fill_gaps(dt: str = 'M') → None

Fills date gaps with NaN values

Parameters:

dt – timestep, either “d” for day or “M” for month (default)

static from_series(series: Series) → Timeseries

Converts a pandas Series to a Timeseries

Parameters:

series – the Series to convert

Returns:

the Timeseries

plot(ax=None, **kwargs)

Creates a simple line plot of the time series

Parameters:

• ax – an optional matplotlib.axes.Axes object to use

• kwargs – keyword arguments passed to matplotlib.plot()

Returns:

list of Line2D objects

static read_fews(filename: Path | str) → dict

Reads timeseries from a FEWS PI Timeseries XML file

Schema: http://fews.wldelft.nl/schemas/version1.0/pi-schemas/pi_timeseries.xsd

Parameters:

filename – path to xml input file

Returns:

dict of nested timeseries {location_id: {parameter_id: Timeseries, …}, …}

static read_file(filename: Path | str, format: str = None) → Timeseries

Reads a timeseries from a file

supported formats: * uvf * zrx * bin

Parameters:

• filename – path to file to read

• format – optional format such as “uvf”, “zrx”, etc. If not provided, the file extension is used instead

NOTE: title is not read from the file

static read_wbl(filename: Path | str, series: str | list[str] = []) → list[Timeseries]

Class method for reading one or more series from a WBL file

Parameters:

• filename – path to WBL wile

• series – series name or list of series names to read, if no series names are passed, all series will be read

Returns:

list of Timeseries instances in the same order as the series names

static read_wel(filename: Path | str, series: str | list[str] = []) → list[Timeseries]

Class method for reading one or more series from a WEL file Also supports WBL files

Parameters:

• filename – path to WEL/WBL file

• series – series name or list of series names to read, if no series names are passed, all series will be read

Returns:

list of Timeseries instances in the same order as the series names

static read_wel_to_dataframe(filename: Path | str, series: str | list[str] = []) → DataFrame

Class method for reading one or more series from a WEL file as a pandas Dataframe

Parameters:

• filename – path to WEL file

• series – series name or list of series names to read, if no series names are passed, all series will be read

Returns:

pandas DataFrame

property start: datetime

the time series start date or None if the time series is empty

Type:

returns

static synchronize(ts1: Timeseries, ts2: Timeseries) → tuple[Timeseries, Timeseries]

Synchronizes two time series by only keeping the nodes with identical dates/times.

Parameters:

• ts1 – 1st Timeseries

• ts2 – 2nd Timeseries

Returns:

tuple of two new synchronized Timeseries

static to_dataframe(timeseries: Timeseries | list[Timeseries]) → DataFrame

Converts a list of Timeseries to a pandas.DataFrame

Parameters:

timeseries – a Timeseries object (or list of Timeseries objects) to convert

Returns:

the DataFrame

property values: list[float]

returns a list of the timeseries’ values sorted by date

Returns:

list of values

static write_fews(filename: Path | str, ts_dict: dict) → None

Writes timeseries to a FEWS PI Timeseries XML file

Schema: http://fews.wldelft.nl/schemas/version1.0/pi-schemas/pi_timeseries.xsd

Parameters:

• filename – path to XML file to write

• ts_dict – nested dictionary of timeseries to write {location_id: {parameter_id: Timeseries, …}, …}

write_to_file(filename: Path | str, options: dict = {}) → None

Writes the timeseries to a file

Supported formats: * txt (with dateformat YYYYMMddHHmmss) * csv (with dateformat YYYY-MM-dd HH:mm:ss and comma as separator) * uvf * zrx * bin

Parameters:

• filename – path to file to write to. The file extension determines the format.

• options –

  optional dictionary with options, which can be format-specific

  Supported options:

  • ZRX format: * “REXCHANGE”: a string that is used for setting the REXCHANGE header value

  • UVF format: * any key-value pair can be passed and will be written as an additional header entry in the format “key: value”