Metadata-Version: 2.4
Name: urbanplot
Version: 0.1.2
Summary: Urban-scale climate visualization and ICON model plotting framework
Author-email: KIT / IMKTRO <imktro-climate-modelling@lists.kit.edu>
License: Apache-2.0
Project-URL: Repository, https://gitlab.dkrz.de/clm-community/public/evasuite-addons/evasuite_urbanplots
Project-URL: Homepage, https://gitlab.dkrz.de/clm-community/public/evasuite-addons/evasuite_urbanplots
Keywords: climate,ICON,visualization,geospatial,urban
Classifier: Programming Language :: Python :: 3.11
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: AUTHORS.TXT
Requires-Dist: numpy<2.3,>=1.26
Requires-Dist: xarray>=2024.1
Requires-Dist: Cartopy>=0.22
Requires-Dist: Flask>=3.0
Requires-Dist: scipy>=1.11
Requires-Dist: xclim>=0.45
Requires-Dist: osmnx>=1.6
Requires-Dist: imageio>=2.31
Requires-Dist: netCDF4>=1.6
Requires-Dist: h5netcdf>=1.3
Requires-Dist: h5py>=3.10
Dynamic: license-file

# UrbanPlot

**UrbanPlot** is a Python-based visualization and analysis framework for urban-scale climate data, with a focus on ICON model outputs and observational datasets.

It provides a configurable pipeline for:

* reading and harmonizing climate datasets
* computing statistics and differences
* generating publication-quality maps with geographic context (OpenStreetMap)
* producing multi-panel comparison plots

---

## Features

* ICON model + reference dataset comparison (e.g. E-OBS)
* Flexible configuration system (main + icon + OSM/layout configs)
* High-quality cartographic visualization (Cartopy + OSMnx)
* Multi-panel plots (MODEL / OBS / DIFF)
* Automatic runtime directory management
* CLI-based workflow

---

## Installation

### From PyPI

```bash
pip install urbanplot
```

### From TestPyPI (development)

```bash
pip install \
  --index-url https://test.pypi.org/simple/ \
  --extra-index-url https://pypi.org/simple \
  urbanplot
```

---

## Quick Start

### 1. Create a working directory

```bash
mkdir run_case
cd run_case
```

### 2. Generate default configs

```bash
urbanplot --init-configs
```

This creates:

```text
main_config.py
icon_maps.py
osm_maps.py
```

---

### 3. Provide input data

Place your data inside:

```text
DATA/
```

Example:

```text
DATA/eobs_v28/rr_ens_mean_*.nc
DATA/out03_1km/*.nc
```

---

### 4. Run the pipeline

```bash
urbanplot \
  --config main_config.py \
  --config-icon icon_maps.py \
  --config-osm osm_maps.py
```

---

## Project Structure (runtime)

After execution:

```text
run_case/
├── DATA/
├── FIGURES/
├── LOGS/
├── cache/
```

---

## Configuration System

UrbanPlot uses three configuration layers:

### 1. Main config (`main_config.py`)

Controls:

* data paths
* variable selection
* processing pipeline
* plotting metadata

---

### 2. ICON config (`icon_maps.py`)

Controls:

* colorbars
* colormaps
* triangular grid rendering

Example:

```python
CONFIG = {
    "tripcolor_setting": {
        "shading": "gouraud"
    }
}
```

---

### 3. OSM/Layout config (`osm_maps.py`)

Controls:

* map layout
* OpenStreetMap layers
* legend, scalebar, styling

---

## Command Line Interface

```bash
urbanplot --help
```

### Main options

```text
--config            Path to main config
--config-icon       Path to ICON config
--config-osm        Path to OSM/layout config

--init-configs      Generate all config templates
--init-main-config  Generate main config only
--init-icon-config  Generate ICON config only
--init-osm-config   Generate OSM config only
```

---

## Typical Workflow

```bash
urbanplot --init-configs
# edit configs
urbanplot --config main_config.py
```

---

## Dependencies

UrbanPlot relies on:

* numpy
* xarray
* scipy
* Cartopy
* OSMnx
* xclim
* netCDF4 / h5netcdf

---

## Development

Clone repository:

```bash
git clone https://gitlab.dkrz.de/clm-community/public/evasuite-addons/evasuite_urbanplots
cd evasuite_urbanplots
pip install -e .
```

---

## License

Apache-2.0

---

## Authors

KIT / IMKTRO
Climate modelling group

---

## Notes

* Runtime directories (`DATA`, `FIGURES`, `LOGS`, `cache`) are created automatically.
* Configuration files are user-defined and not part of the package.
* Designed for scientific workflows and HPC environments.

---
