Polygons

Polygons#

Import resources#

[1]:

import pyku
import pyku.resources as resources
import pyku.analyse as analyse

Download directory#

Polygons are mostly downloaded on-the-fly. The download takes place only one time and the downloaded data are reused if the polygons are called twice. The download path can be shown with. If you set the environment variable PYKU_DATA_DIR, the data will automatically be downloaded in that directory. If you do not set that environment variable, data are downloaded by default in the standard directory /home/kudev/.local/share/pyku

[2]:

pyku.config

[2]:

{'pre_existing_data_dir': PosixPath('/home/runner/work/pyku/pyku/pyku_cache'),
 'data_dir': PosixPath('/home/runner/work/pyku/pyku/pyku_cache'),
 'cache_dir': PosixPath('/tmp/pyku_cache_dir'),
 'repo_data_dir': PosixPath('/home/runner/work/pyku/pyku/.venv/lib/python3.12/site-packages/pyku/data'),
 'downloaders': {}}

List of available polygons#

The identifier of all available polygons can be accessed like so:

[3]:

resources.get_polygon_identifiers()

/home/runner/work/pyku/pyku/.venv/lib/python3.12/site-packages/pyku/resources.py:228: FutureWarning: Function 'get_polygon_identifiers' is deprecated. Use 'list_polygon_identifiers'
  warnings.warn(

[3]:

['ne_10m_admin_0_countries',
 'ne_10m_coastline',
 'ne_10m_rivers',
 'ne_10m_lakes',
 'germany',
 'austria',
 'german_states',
 'german_cities',
 'ne_10m_geography_regions_polys',
 'eobs_mask',
 'prudence',
 'natural_areas_of_germany',
 'natural_areas_of_germany_merged4',
 'german_directions']

Germany#

[4]:

geodf = resources.get_geodataframe('germany')

print(f"{resources.pyku_resources.get('polygons').get('germany').get('description')}")

analyse.regions(
    geodf,
    area_def='HYR-GER-LAEA-5',
    size_inches=(5, 5)
)

/home/runner/work/pyku/pyku/.venv/lib/python3.12/site-packages/tqdm/auto.py:21: TqdmWarning: IProgress not found. Please update jupyter and ipywidgets. See https://ipywidgets.readthedocs.io/en/stable/user_install.html
  from .autonotebook import tqdm as notebook_tqdm

Germany selected from https://www.naturalearthdata.com/downloads/10m-cultural-vectors/10m-admin-0-countries/
../_images/tutorials_polygons_8_2.png

German cities#

[5]:

# Get German cities
# -----------------

geodf = resources.get_geodataframe('german_cities')

# Get description
# ---------------

print(f"{resources.pyku_resources.get('polygons').get('german_cities').get('description')}")

# Select 'Kreisfreie Stadt'
# -------------------------

geodf = geodf.query("BEZ == 'Kreisfreie Stadt'")

# Select cities
# -------------

geodf = geodf[geodf['GEN'].isin(['Frankfurt', 'Offenbach', 'Berlin', 'Hamburg', 'München'])]

# Plot
# ----

analyse.regions(
    geodf,
    area_def='HYR-GER-LAEA-5',
    size_inches=(5, 5)
)

See https://gdz.bkg.bund.de/index.php/default/digitale-geodaten/verwaltungsgebiete/verwaltungsgebiete-1-250-000-stand-01-01-vg250-01-01.html
../_images/tutorials_polygons_10_1.png

The alps#

Load regions with

[6]:

geodf = resources.get_geodataframe('ne_10m_geography_regions_polys')

Search any rows that would contain the word alps

[7]:

rows = (geodf.map(lambda x: str(x).lower() == 'alps')).any(axis=1)
geodf.loc[rows]

[7]:
FEATURECLA NAME NAMEALT REGION SUBREGION MIN_LABEL MAX_LABEL SCALERANK LABEL WIKIDATAID ... NAME_TR NAME_VI NAME_ZH NE_ID NAME_FA NAME_HE NAME_UK NAME_UR NAME_ZHT geometry
712 Range/mtn ALPS None Europe None 2.0 8.0 1 ALPS Q1286 ... Alpler Anpơ 阿尔卑斯山 1159104297 آلپ הרי האלפים Альпи الپس 阿尔卑斯山 POLYGON ((15.31483 46.43159, 15.26673 46.40217...

1 rows × 38 columns

[8]:

# Get the Alps
# ------------

geodf = geodf.query("NAME == 'ALPS'")

# Plot
# ----

analyse.regions(
    geodf,
    area_def='euradcom_ps',
    size_inches=(5, 5)
)
../_images/tutorials_polygons_15_0.png

Natural areas of Germany#

[9]:

geodf = resources.get_geodataframe('natural_areas_of_germany')

# Plot
# ----

analyse.regions(
    geodf,
    area_def='HYR-LAEA-5',
    size_inches=(8, 8),
)
../_images/tutorials_polygons_17_0.png

The merged polygons can be accessed with:

[10]:

geodf = resources.get_geodataframe('natural_areas_of_germany_merged4')

display(geodf)

# Plot
# ----

analyse.regions(
    geodf,
    area_def='HYR-LAEA-5',
    size_inches=(8, 8),
)
index geometry NAME DIRECTION
0 0 POLYGON ((3620123.5 5271088, 3620109 5270726, ... Suedwestdeutsche Mittelgebirge, Alpen, Alpenvo... South
1 0 POLYGON ((3920531.75 5696475, 3920604.5 569651... Oestliche Mittelgebirge, Ostdeutsche Becken un... East
2 0 MULTIPOLYGON (((3786207 6069685, 3786176.5 606... Nordostdeutsches Tiefland, Nordwestdeutsches T... North
3 0 POLYGON ((3496914.5 5596087, 3496785 5596087, ... Linksrheinische Mittelgebirge, Oberrheinisches... West
../_images/tutorials_polygons_19_1.png

Germany split into western, northern, easter and south Germany#

[11]:

geodf = resources.get_geodataframe('german_directions')

# Plot
# ----

analyse.regions(
    geodf,
    area_def='HYR-GER-LAEA-5',
    size_inches=(8, 8),
)
../_images/tutorials_polygons_21_0.png

German states#

[12]:

geodf = resources.get_geodataframe('german_states')

analyse.regions(
    geodf,
    area_def='HYR-GER-LAEA-5',
    size_inches=(8, 8),
)
../_images/tutorials_polygons_23_0.png

World#

Polygons for the whole world is quite easy.

[13]:

geodf = resources.get_geodataframe('ne_10m_coastline')

analyse.regions(
    geodf,
    area_def='world_360x180',
    size_inches=(8, 8),
)
../_images/tutorials_polygons_25_0.png

Configuration file#

The data are configured per yaml file. Users do not need to worry about it unless new polygons are needed. The source of the data is available in the description. You can get the configuration as a python dictionary like so

[14]:

import pyku.resources as resources
resources.pyku_resources

[14]:

{'polygons': {'ne_10m_admin_0_countries': {'description': 'See https://www.naturalearthdata.com/downloads/10m-cultural-vectors/10m-admin-0-countries/\n',
   'base_url': 'https://naturalearth.s3.amazonaws.com/10m_cultural/',
   'archive_file': 'ne_10m_admin_0_countries.zip',
   'target_file': 'ne_10m_admin_0_countries.shp',
   'query': None,
   'aliases': ['countries']},
  'ne_10m_coastline': {'description': 'See https://www.naturalearthdata.com/downloads/10m_physical/ne_10m_coastline/\n',
   'base_url': 'https://naturalearth.s3.amazonaws.com/10m_physical/',
   'archive_file': 'ne_10m_coastline.zip',
   'target_file': 'ne_10m_coastline.shp',
   'query': None},
  'ne_10m_rivers': {'description': 'See https://www.naturalearthdata.com/downloads/10m-physical-vectors/10m-rivers-lake-centerlines/\n',
   'base_url': 'https://naturalearth.s3.amazonaws.com/10m_physical/',
   'archive_file': 'ne_10m_rivers_lake_centerlines.zip',
   'target_file': 'ne_10m_rivers_lake_centerlines.shp',
   'query': None},
  'ne_10m_lakes': {'description': 'See https://www.naturalearthdata.com/downloads/10m-physical-vectors/10m-lakes/\n',
   'base_url': 'https://naturalearth.s3.amazonaws.com/10m_physical/',
   'archive_file': 'ne_10m_lakes.zip',
   'target_file': 'ne_10m_lakes.shp',
   'query': None},
  'germany': {'description': 'Germany selected from https://www.naturalearthdata.com/downloads/10m-cultural-vectors/10m-admin-0-countries/\n',
   'base_url': 'https://naturalearth.s3.amazonaws.com/10m_cultural/',
   'archive_file': 'ne_10m_admin_0_countries.zip',
   'target_file': 'ne_10m_admin_0_countries.shp',
   'query': "SOVEREIGNT == 'Germany'"},
  'austria': {'description': 'Austria selected from https://www.naturalearthdata.com/downloads/10m-cultural-vectors/10m-admin-0-countries/\n',
   'base_url': 'https://naturalearth.s3.amazonaws.com/10m_cultural/',
   'archive_file': 'ne_10m_admin_0_countries.zip',
   'target_file': 'ne_10m_admin_0_countries.shp',
   'query': "SOVEREIGNT == 'Austria'"},
  'german_states': {'description': 'German states selected from https://www.naturalearthdata.com/downloads/10m-cultural-vectors/10m-admin-1-states-provinces/\n',
   'base_url': 'https://naturalearth.s3.amazonaws.com/10m_cultural/',
   'archive_file': 'ne_10m_admin_1_states_provinces.zip',
   'target_file': 'ne_10m_admin_1_states_provinces.shp',
   'query': "iso_a2 == 'DE'"},
  'german_cities': {'description': 'See https://gdz.bkg.bund.de/index.php/default/digitale-geodaten/verwaltungsgebiete/verwaltungsgebiete-1-250-000-stand-01-01-vg250-01-01.html\n',
   'base_url': 'https://daten.gdz.bkg.bund.de/produkte/vg/vg250_ebenen_0101/aktuell/',
   'archive_file': 'vg250_01-01.tm32.shape.ebenen.zip',
   'target_file': 'VG250_KRS.shp',
   'query': None},
  'ne_10m_geography_regions_polys': {'description': 'See https://www.naturalearthdata.com/downloads/10m-physical-vectors/10m-physical-labels/\n',
   'base_url': 'https://naturalearth.s3.amazonaws.com/10m_physical/',
   'archive_file': 'ne_10m_geography_regions_polys.zip',
   'target_file': 'ne_10m_geography_regions_polys.shp',
   'query': None,
   'aliases': ['geographic_regions']},
  'eobs_mask': {'description': '\nMask for the usage of E-OBS data in anlyses like pyku.ana.mean_vs_time. It was generated using E-OBS v27.0 ensemble mean data at 0.1 deg resolution. It is the minimum overlap of valid data of all available variables, averaged over the year 1979.\nREFERENCES\n* https://www.ecad.eu/download/ensembles/download.php *  Cornes, R. C., van der Schrier, G., van den Besselaar, E. J. M., & Jones, P. D. (2018).\n   An ensemble version of the E-OBS temperature and precipitation data sets.\n   JGR: Atmospheres, 123, 9391-9409. https://doi.org/10.1029/2017JD028200\n',
   'base_url': None,
   'archive_file': None,
   'target_file': 'eobs_mask.geojson.zip',
   'query': None},
  'prudence': {'description': '\nPrudence polygons, used in climatology, are spatial divisions developed during the PRUDENCE project (Prediction of Regional scenarios and Uncertainties for Defining EuropeaN Climate change risks and Effects). These polygons are defined to represent consistent and climatically homogeneous regions across Europe, facilitating regional climate change analyses. They are widely used for studying the impacts of climate models at sub-continental scales and are essential for evaluating regional climate projections under various scenarios. The polygons provide a framework for aggregating climate model data, aiding in the comparison of regional impacts under different climate conditions. These regions correspond to specific areas that experience similar climatic patterns and help in better understanding variability and extreme events under modeled and observed datasets.\nREFERENCES\n* https://ensemblesrt3.dmi.dk/quicklook/regions.html * https://www.wcrp-climate.org/modelling-wgcm-mip-catalogue/modelling-wgcm-mips-2/288-modelling-wgcm-catalogue-prudence * Christensen, J.H., Christensen, O.B. A summary of the PRUDENCE model\n  projections of changes in European climate by the end of this century.\n  Climatic Change 81 (Suppl 1), 7-30 (2007).\n  https://doi.org/10.1007/s10584-006-9210-7\n',
   'base_url': None,
   'archive_file': None,
   'target_file': 'prudence.geojson.zip',
   'query': None},
  'natural_areas_of_germany': {'description': 'Not documented',
   'base_url': None,
   'archive_file': None,
   'target_file': 'Regionen_NationalerKlimareport_2015_Namen.geojson.zip',
   'query': None},
  'natural_areas_of_germany_merged4': {'description': 'Natural areas of Germany divided into western, northern, eastern and southern states.\nWestern  - Linksrheinische Mittelgebirge, Oberrheinisches Tiefland,\n           Rechtsrheinische Mittelgebirge, Westdeutsche Tieflandsbucht\nNorthern - Nordostdeutsches Tiefland, Nordwestdeutsches Tiefland Eastern  - Oestliche Mittelgebirge, Ostdeutsche Becken und Huegel,\n           Zentrale Mittelgebirge und Harz\nSouthern - Suedwestdeutsche Mittelgebirge, Alpen, Alpenvorland\nThese polygons are built on-the-fly from Natural Areas of Germany data available in pyku. See the source code in resources.py\n',
   'base_url': None,
   'archive_file': None,
   'target_file': None,
   'query': None},
  'german_directions': {'description': "Germany divided into western, northern, eastern and southern states.\nWestern states  - Rheinland-Pfalz, Saarland, Nordrhein-Westfalen,\n                  Hessen,\nNorthern states - Schleswig-Holstein, Hamburg, Bremen, Niedersachsen,\n                  Mecklenburg-Vorpommern'\nEastern states  - Berlin, Brandenburg, Sachsen, Sachsen-Anhalt,\n                  Thüringen\nSouthern states - Bayern, Baden-Württemberg,\nThese polygons are built on-the-fly from German states data available in ne_10m_admin_1_states_provinces. See the source code in resources.py\n",
   'base_url': None,
   'archive_file': None,
   'target_file': None,
   'query': None}}}