API Reference

class talsimpy.TalsimDataset(path, name)

Class for handling and manipulating a Talsim ASCII dataset

Instantiates a new TalsimDataset instance

Parameters:

• path (Path | str) – path to directory containing the dataset

• name (str) – name of the dataset

copy(destination, include_results=False)

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

Parameters:

• destination (Path | str) – destination directory

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

Returns:

the destination dataset

Return type:

TalsimDataset

process_templates(variables)

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 format specifiers (e.g. {variable_name:formatspec}) are allowed 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) – dict of variable names and values {name: value, ...}

Return type:

None

write_varfile(file_var, vars)

Creates a Talsim VAR file containing the given variables

Parameters:

• file_var (str) – filename of VAR file to write

• vars (dict[slice(<class 'str'>, talsimpy.timeseries.Timeseries | bool, None)]) – dictionary with identifiers as keys and variables as values. Values may be of type Timeseries or bool.

Return type:

None

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

property errors: str | None

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

copy_result_files(dir_dest)

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 (Path | str) – destination directory

Return type:

None

file_to_dataframe(file)

Reads a dataset file as a pandas DataFrame

Parameters:

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

Returns:

the contents of the file as a pandas DataFrame

Return type:

DataFrame

calculate_average_soil_properties()

Calculates the average soil properties for soil types over all layers

Returns:

pandas Dataframe

Return type:

DataFrame

property sim_start: datetime

Returns the simulation start date as set in the ALL file

property sim_end: datetime

Returns the simulation end date as set in the ALL file

get_sim_options()

Gets all options set in the ALL file

Returns:

dictionary of keys and values as strings

Return type:

dict

set_sim_options(options)

Sets new options in the ALL file

Parameters:

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

Return type:

None

set_calibration_parameters(parameters)

Sets calibration parameters in the KAL file

Parameters:

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

Return type:

None

results_to_xarray(element_type, system_state, epsg=None)

Converts simulation results to a xarray.DataArray

Parameters:

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

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

• epsg (int) – optional coordinate reference system to set

Returns:

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

Return type:

xr.DataArray

class talsimpy.TalsimDatabase(path)

Class for handling a Talsim 5 database

Parameters:

path (Path | str)

open_scenario(scenario_id)

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

Parameters:

scenario_id (int)

Return type:

TalsimScenario

class talsimpy.TalsimScenario(path, scenario_id)

Bases: TalsimDataset

Class for handling and manipulating a scenario in a database

Instantiates a new TalsimScenario instance

Parameters:

• path (Path | str) – path to database containing the scenario

• scenario_id (int) – scenario id

db = None

Path to the database file

id = None

Scenario id

sim_id = None

Currently active simulation id

simulations = {}

Dictionary of existing simulations {id: name, ...}

property active_simulation: int | None

Returns the currently active simulation

Returns:

active simulation id or None if not set

set_active_simulation(sim_id)

Sets the active simulation id

Parameters:

sim_id (int) – the simulation id to set

Return type:

None

copy(destination, include_results=False)

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

Parameters:

• destination (Path | str) – destination directory

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

Returns:

the destination scenario

Return type:

TalsimScenario

property sim_start: datetime

Returns the simulation start date of the currently active simulation

set_sim_start(sim_start)

Sets the simulation start date for the currently active simulation

Parameters:

sim_start (datetime)

Return type:

None

property sim_end: datetime

Returns the simulation end date for the currently active simulation

set_sim_end(sim_end)

Sets the simulation end date for the currently active simulation

Parameters:

sim_end (datetime)

Return type:

None

set_parameter(table, id, field, value)

Sets an arbitrary value in the database

Parameters:

• table (str) – name of the database table

• id (int) – Id of the row

• field (str) – name of the field

• value (int | float | str) – new value to set

Return type:

None

class talsimpy.TalsimEngine(path)

Class for carrying out simulations with Talsim

Instantiate a new TalsimEngine instance

Parameters:

path (Path | str) – path to directory containing the engine executable

property exe_file: Path

Returns the path to the executable

property version: str

Returns the Talsim engine version number

simulate(dataset, name=None, variation_id=0, language='de', path_timeseries=None, sim_id=None, path_output=None)

Carries out a simulation

Parameters:

• dataset (TalsimDataset | TalsimScenario) – TalsimDataset or TalsimScenario instance to simulate

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

• variation_id (int) – optional Variation ID (default: 0)

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

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

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

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

Returns:

boolean success

Return type:

bool

launch(runfile)

Launches the Talsim engine with a given run file

Parameters:

runfile (Path | str) – path to run file

Returns:

return code of the process

Return type:

int

ktrcheck(dataset, language='de', path_output=None)

Carries out a KTRCheck run

Parameters:

• dataset (TalsimDataset | TalsimScenario) – TalsimDataset or TalsimScenario instance to check

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

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

Returns:

boolean success

Return type:

bool

static read_runfile(runfile)

Reads a run file and returns the settings as a dictionary

Parameters:

runfile (Path | str) – path to run file

Returns:

dictionary with settings

Return type:

dict[str, str]

class talsimpy.Timeseries(title='')

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

Instantiates a new Timeseries object

Parameters:

title (str) – Optional title

class Interpretation(*values)

Enum of interpretations as defined in sydrodomain.ini

Instantaneous = 1

BlockRight = 2

BlockLeft = 3

Cumulative = 4

CumulativePerTimestep = 5

Undefined = 99

add_node(timestamp, value)

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 (datetime) – the timestamp of the node

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

Raises:

ValueError – if timestamp is not a valid datetime object

Return type:

None

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

copy()

create a copy of the time series

Returns:

a copy of the Timeseries instance

Return type:

Timeseries

copy_metadata(ts)

copies metadata from a second time series to this timeseries

Parameters:

ts (Timeseries) – the time series from which to copy metadata

Return type:

None

property start: datetime

Returns the time series start date

Returns:

start date or None if the time series is empty

property end: datetime

Returns the time series end date

Returns:

end date or None if the time series is empty

cut(start, end)

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

Parameters:

• start (datetime) – start date (inclusive)

• end (datetime) – end date (inclusive)

Return type:

None

write_to_file(filename, options={})

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 | str) – path to file to write to. The file extension determines the format.

• options (dict) –

  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

Return type:

None

property dates: list[datetime]

returns a sorted list of the dates contained in the timeseries

Returns:

list of datetime objects

property values: list[float]

returns a list of the timeseries’ values sorted by date

Returns:

list of values

fill_gaps(dt='M')

Fills date gaps with NaN values

Parameters:

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

Return type:

None

count_value_nodes()

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

Returns:

number of non-NaN values (int)

Return type:

int

delete_nan_nodes()

Deletes nodes with NaN values from the time series

Return type:

None

delete_negative_nodes()

Deletes nodes with negative values from the time series

Return type:

None

static read_file(filename, format=None)

Reads a timeseries from a file

Supported formats:

• uvf

• zrx

• bin

Note

title is not read from the file

Parameters:

• filename (Path | str) – path to file to read

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

Return type:

Timeseries

static read_wbl(filename, series=[])

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

Parameters:

• filename (Path | str) – path to WBL file

• series (str | list[str]) – 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

Return type:

list[Timeseries]

static read_wel(filename, series=[])

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

Parameters:

• filename (Path | str) – path to WEL/WBL file

• series (str | list[str]) – 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

Return type:

list[Timeseries]

static read_wel_to_dataframe(filename, series=[])

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

Parameters:

• filename (Path | str) – path to WEL file

• series (str | list[str]) – series name or list of series names to read, if no series names are passed, all series will be read

Returns:

pandas DataFrame

Return type:

DataFrame

static read_fews(filename)

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 | str) – path to xml input file

Returns:

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

Return type:

dict

static write_fews(filename, ts_dict)

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 | str) – path to XML file to write

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

Return type:

None

static synchronize(ts1, ts2)

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

Parameters:

• ts1 (Timeseries) – 1st Timeseries

• ts2 (Timeseries) – 2nd Timeseries

Returns:

tuple of two new synchronized Timeseries

Return type:

tuple[Timeseries, Timeseries]

static to_dataframe(timeseries)

Converts a list of Timeseries to a pandas.DataFrame

Parameters:

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

Returns:

the DataFrame

Return type:

DataFrame

static from_series(series)

Converts a pandas Series to a Timeseries

Parameters:

series (Series) – the Series to convert

Returns:

the Timeseries

Return type:

Timeseries