Metadata-Version: 2.1
Name: interoperable-csv
Version: 0.2.1
Summary: Read, write, and transform iCSV files.
License: GPL-3.0-only
Keywords: icsv,snow,timeseries,geospatial,climate
Author: Patrick Leibersperger
Author-email: patrick.leibersperger@slf.ch
Requires-Python: >=3.9,<4.0
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Dist: pandas (>=2.0,<3.0)
Requires-Dist: xarray (>=2024.3.0,<2025.0.0)
Description-Content-Type: text/markdown

# icsv

<img src="docs/assets/icsv_logo.png" alt="iCSV logo" width="140" />

`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

```bash
pip install interoperable-csv
```

Import path stays:

```python
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:

```text
# 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

```python
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:

```python
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

