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]orQdot [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.