Write the PCRaster header in the time series outputs

[soaressgabriel]

Checklist

• Have you followed the guidelines in our Contributing document?
• Have you checked to ensure there aren't other open Pull Requests for the same update/change?
• Added tests for changed code.
• Updated documentation for changed code.

Description

• The model writes its station time series with the PCRaster header (noHeader=False in the TimeoutputTimeseries writer): the title line timeseries scalar, the number of columns, the timestep line and one line per station id, followed by the data rows. A kept .tss file is therefore readable by PCRaster's own tools, Aguila included.
• tss2csv reads that header before converting: a file without it (a first line that is not a title, a second line that is not a positive integer) is refused with a message saying the model writes headed files; a header that stops short of its announced column count, announces a column count different from the configured station ids, or lists other ids, is refused naming both sides. Only the data rows are converted, so the CSV tables are unchanged.
• Byte identity of the CSV outputs proved twice on the synthetic dataset: the nine tss_*.csv before and after the change compare equal with cmp, and the previous converter applied to the headed files with their header stripped produces the same bytes as the new converter on the headed files.
• Tests: every tss2csv fixture writes the headed form; the refusals (no header, non-integer or non-positive count, truncated header, other ids, other count, zero-byte source); the CSV text of a headed file equals the one of the previous form; a run keeping PCRasterTSS leaves a .tss whose header is timeseries scalar, 3, timestep, 1, 2 for the synthetic dataset; the converted table is exactly the column line plus one row per step.
• The file formats page documents the header of the kept .tss outputs and the derivation of the CSV; changelog entry under Changed.

Related Issue

• Resolve Write the PCRaster header in the time series outputs #347;

Motivation and context

• The headerless form PCRaster documents as incompatible with its tools forced every reader of the model's time series to guess the station ids from the column position. With the header every consumer (the CSV conversion, the calibration command's observed series reader, Aguila) reads the ids from the file. The calibration branch (Add the rubem calibrate command #344, Document the calibration method and add the dataset smoke test #346) is adapted separately to require the header in the PCRaster time series it reads.

How has this been tested

• python -m pytest -q -p no:cacheprovider --ignore=tests/integration/doc -n 2: 1011 passed, 1 skipped (Linux, Python 3.13, PCRaster 4.4.2); no .tss file is part of the goldens and the CSV goldens are byte-identical.
• uvx ruff@0.16.4 format --check . and uvx ruff@0.16.4 check .: clean.
• sphinx-build -W -b html doc/source with the documentation's Python 3.13 environment: no warnings.

Screenshots

• N/A

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.64%. Comparing base (b9c7291) to head (23fd0af).
⚠️ Report is 12 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #349      +/-   ##
==========================================
+ Coverage   92.58%   92.64%   +0.05%     
==========================================
  Files          60       60              
  Lines        3953     3985      +32     
  Branches      497      502       +5     
==========================================
+ Hits         3660     3692      +32     
  Misses        236      236              
  Partials       57       57              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.