Metadata-Version: 2.4
Name: HdkgcPy
Version: 1.0.0
Summary: High-Definition Köppen-Geiger Climate Classification and Downscaling library
Author-email: Chris Nicolaas <chris.nicolaas@example.com>
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: matplotlib
Requires-Dist: cartopy
Requires-Dist: xarray
Requires-Dist: scipy
Requires-Dist: pandas
Requires-Dist: pillow
Requires-Dist: netcdf4
Dynamic: license-file

# HdkgcPy

**HdkgcPy** is a high-performance, high-definition Köppen-Geiger Climate Classification and Downscaling library for Python. It provides high-quality climate lookups, grid interpolation, and cartographic plotting with custom scaling up to 250x resolution.

## Features
- **Point Lookup**: Billinear, nearest-neighbor, and bicubic interpolation of monthly climate variables to classify any point coordinate.
- **Grid Downscaling**: Spatial downscaling of global temperature and precipitation climatologies onto custom bounding boxes at high resolutions (e.g. 100 meters).
- **Memory-Safe Execution**: Automatically partitions massive grids (like the whole world at 0.025° resolution, ~103.7 million cells) in latitude chunks to prevent memory exhaustion.
- **Custom Datasets**: Allows registering and evaluating custom local climate simulations or future projections (NetCDF files).
- **Publication-Quality Mapping**: Optimized map rendering for SIDS and regional scopes using Cartopy with clean axis coordinates, optional dashed gridlines, and high-resolution 10-meter vector ocean/coastline masking.

## Installation
```bash
pip install HdkgcPy
```

## Quick Start

### 1. Point Climate Lookup
```python
import hdkgcpy

# Perform bilinear interpolation of monthly variables to a coordinate point
zone = hdkgcpy.lookup_cz(lat=12.52, lon=-70.03, method='bilinear')
print(f"Climate Zone: {zone}")  # Outputs: 'BSh'
```

### 2. High-Definition Grid Generation
```python
import hdkgcpy

# Bounding box for Aruba [lon_min, lon_max, lat_min, lat_max]
aruba_bbox = [-70.07, -69.84, 12.39, 12.64]

# Downscale to 0.001 deg (~100m resolution) using bilinear interpolation
lats, lons, grid = hdkgcpy.generate_grid(extent=aruba_bbox, resolution=0.001, method='linear')
```

### 3. Render and Save a Map
```python
import hdkgcpy

hdkgcpy.plot_map(
    lats, lons, grid, aruba_bbox,
    title="Aruba Climate Map\nERA5 Climatology (2000-2025)",
    output_file="aruba_map.png",
    cities={"Oranjestad": (-70.0358, 12.5186)},
    show_gridlines=False,  # Keep dashed grid lines hidden
    mask_ocean=True,        # Mask ocean blocky pixels with 10m vector coastline
    show_cities=True,      # Toggle capital/city markers on or off
    map_style=2,           # Map style: 1 (legend outside) or 2 (expanded box, legend inside)
    legend_shift=0.65      # Shift factor for Map Style 2 (fraction of map width)
)
```

### 4. Custom Climatology Registration
```python
import hdkgcpy

# Register a custom future projection NetCDF dataset
hdkgcpy.load_climatology_file(
    "future_projection_2050.nc", 
    temp_var="temp", 
    precip_var="precip", 
    temp_in_kelvin=True
)

# Any lookup or grid generation will now evaluate your custom dataset
future_zone = hdkgcpy.lookup_cz(12.52, -70.03)
```

## Author
Developed and maintained by **Chris Nicolaas**.

## License
MIT License.
