Metadata-Version: 2.1
Name: geoframefiles
Version: 0.0.1
Summary: GEOframe I/O timeseries
Author-email: Riccardo Busti <riccardobusti97@gmail.com>
Project-URL: Homepage, https://github.com/pypa/sampleproject
Project-URL: Issues, https://github.com/pypa/sampleproject/issues
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# GEOframeFiles

**GEOframeFiles** is a Python package that provides utilities for reading and writing timeseries file formats used by the [GEOframe](https://geoframe.blogspot.com) hydrological modelling system.

## Supported formats

| Format | Read | Write |
|---|---|---|
| OMS CSV (`.csv`) | ✔ | ✔ |
| NetCDF (`.nc`)   | ✔ | ✔ |

## Installation

```bash
pip install geoframefiles
```

## Quick start

### OMS CSV

```python
from geoframefiles.pandas_to_oms import pandas_read_OMS_timeseries, write_OMS_timeseries

# Read
df = pandas_read_OMS_timeseries("precipitation.csv")

# Write (DataFrame with DatetimeIndex)
write_OMS_timeseries(df, 
                     "output.csv")

# Write (plain integer index – add start date and frequency)
write_OMS_timeseries(df, 
                     "output.csv",
                     has_datetime=False,
                     start_date="2020-01-01 12:00",
                     frequency="D")
```

### NetCDF

```python
from geoframefiles.pandas_to_oms import pandas_read_NC_timeseries, write_NC_timeseries

# Read
df = pandas_read_NC_timeseries("precipitation.nc")

# Write  – DataFrame with DatetimeIndex
write_NC_timeseries(df, 
                    "precipitation.nc")

# Write – plain integer index
write_NC_timeseries(df, 
                    "temperature.nc",
                    start_date="2020-01-01 12:00",
                    frequency="D")
```

## DataFrame conventions

* **Rows** – timesteps
* **Columns** – one per station; column names are used as station IDs
* **Index** – `DatetimeIndex` or plain integer index (see `start_date` / `frequency` kwargs)
* **Variablies** - (time, lat, lon, x, y, station_id, station_names, var)

Missing values are represented as `NaN` in memory and as `-9999` on disk.

## Dependencies

* `pandas >= 1.3`
* `numpy >= 1.21`
* `netCDF4 >= 1.5`

## License

GNU General Public License v3 or later – see [LICENSE](LICENSE).
