interoperable-csv 0.2.1

Read, write, and transform iCSV files.

icsv

icsv is a Python package for reading, writing, validating, and transforming interoperable CSV (iCSV) files.

Note: this repository provides the Python interface for iCSV. The iCSV format specification itself is maintained in EnviDat/icsv: https://gitlabext.wsl.ch/EnviDat/icsv

It supports:

• Standard iCSV files (# iCSV 1.0 UTF-8)
• 2D timeseries application profile files (# iCSV 1.0 UTF-8 2DTIMESERIES)
• Conversion of SMET-like objects into iCSV structures

Installation

pip install interoperable-csv

Import path stays:

import icsv

What Is iCSV?

iCSV is a text-based, self-describing data format for environmental time series. It combines CSV data rows with structured header metadata.

An iCSV file is organized in sections:

• [METADATA]: global attributes (station info, geometry, delimiter, etc.)
• [FIELDS]: column definitions and per-column attributes
• [DATA]: tabular data rows

Typical header example:

# iCSV 1.0 UTF-8
# [METADATA]
# field_delimiter = ,
# geometry = POINTZ(9.81 46.831 2540.0)
# srid = EPSG:4326
# [FIELDS]
# fields = timestamp,hs
# [DATA]

Required metadata keys for standard files:

• field_delimiter
• geometry
• srid

Quickstart

import icsv

f = icsv.read("input.icsv")
print(f.get_field("fields"))
print(f.get_metadata("station_id"))
f.write("copy.icsv")

Create a new file:

import pandas as pd
import icsv

f = icsv.iCSVFile()
f.set_metadata("field_delimiter", ",")
f.set_metadata("geometry", "POINTZ(8.0 47.0 1200)")
f.set_metadata("srid", "EPSG:4326")
f.set_metadata("station_id", "WFJ")
f.set_fields("fields", ["timestamp", "hs"])
f.setData(pd.DataFrame({"timestamp": ["2024-01-01T00:00:00"], "hs": [40.2]}))
f.write("out.icsv")

2D timeseries profile support:

• icsv.iCSV2DTimeseries for read/write of [DATE=...] blocks
• icsv.append_timepoint(...) to append profile timesteps

Core API:

• icsv.read(path) auto-detects standard vs 2D profile format
• icsv.iCSVFile standard iCSV object
• icsv.iCSV2DTimeseries profile object
• icsv.from_smet(smet_obj) SMET to iCSV conversion

Documentation

Project documentation:

• GitLab Pages docs: https://git-pages.wsl.ch/patrick.leibersperger/icsv/
• Official iCSV format/spec website (GitLab Pages): https://gitlabext.wsl.ch/EnviDat/icsv/-/pages
• Format/spec repository: https://gitlabext.wsl.ch/EnviDat/icsv

For iCSV format specification changes, open issues at:

• https://gitlabext.wsl.ch/EnviDat/icsv/-/issues