HdkgcPy 1.0.0

High-Definition Köppen-Geiger Climate Classification and Downscaling library

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

pip install HdkgcPy

Quick Start

1. Point Climate Lookup

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

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

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

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.