TSV Files (Time Series)

TSV and CSV files for time series in VICUS Districts: where they are used (building demand, ground temperature, results), separators, header and units.

VICUS Districts Page 9 of 9 in this chapter

Overview

TSV (Tab-Separated Values) is the simple text format that VICUS Districts uses to exchange time series. It serves both as an input format – for example to read a building demand or a ground temperature from a file – and as an output format for simulation results. A TSV file is plain text and can be opened and edited in any text editor as well as in any spreadsheet application (Excel, LibreOffice). As input, CSV files (*.csv, e.g. saved from Excel) are accepted as well.

Where TSV files are used

As input (referencing a time series from a file):

  • Building demand from file – the heating, cooling or domestic hot water demand of a consumer as a time series (see Building demands, mode Custom time series from file).
  • Heat exchange with the ground or the surroundings – a temperature time series from a file (see Heat exchange types).
  • Schedules and set-point time series of plants – e.g. prescribed supply temperatures of an energy plant.

These files are read only at simulation time. Changes to the file therefore take effect without re-importing the time series – only the file path is stored in the project.

As output (results):

  • Simulation results in text format – one file per result quantity following the pattern <network name>-<network ID>.<quantity>.tsv; power and flux quantities are written as mean values with the suffix -mean. TSV is the text-based alternative to the more compact binary format .btf; you choose between them when defining the outputs.
  • Exporting tables and charts – chart data of the line charts, the bill of materials and the result summary can be saved as TSV.

Structure of the format

A TSV file is organized as a table:

  • Separator: a tab between the columns (hence the name). If the header line contains no tab, the file is read as CSV and split at semicolons (;) or commas (,).
  • Header line: the first line contains a name and the unit in square brackets for each column, e.g. Time [h] or Qdot [W].
  • First column = time axis: monotonically increasing time values. The permitted time units are [s], [h] and [d].
  • Further columns = data: each with its own unit in the header. The units are converted automatically to the internally required unit on reading (e.g. [W] ↔ [kW]).
  • Decimal separator: a period (.) or a comma (,). The decimal comma is recognized unless the columns themselves are separated by commas – then the period must be used.
  • Empty rows are skipped.

Example of a demand file with a time and a power column:

Time [h]	HeatingDemand [W]
0	6717.01
1	5563.95
2	5396.58

Selecting a column

If a file contains several data columns, choose the desired one under Select the column in the data file when referencing it. Name and unit of each column are shown; columns with an unknown unit are grayed out and cannot be selected. A small preview displays the chosen time series as a chart, so you can check the file and column before the simulation.

Interpolation and repetition

Between the data points the values are interpolated linearly. If the time series covers a shorter period than the simulation, it is repeated cyclically – a daily or annual profile thus continues automatically.

File path and placeholders

The path to the TSV file can be given relative to the project using placeholders such as ${Project Directory}. This keeps the project portable and lets the file travel with a project package.

Practical tip

The easiest way to create a demand file is in a spreadsheet and save it as Text (tab-separated) or as CSV – the Excel variant with semicolons and decimal commas is read as well. What matters is the unit in square brackets in every header cell; without it, the column cannot be selected. For custom time series from values, the Copy header for import button provides the correctly formatted header ready to use.

Stay up to date

New features, tutorials and updates delivered to your inbox.