# pygal_maps_ua
### Ukraine maps for pygal
[🇺🇦 **Читати українською**](https://github.com/Golova1111/pygal_maps_ua/blob/master/README_ua.md)
Ukraine map plugin for [Pygal](https://www.pygal.org/en/stable/)
Allows you to create first level division administrative map of Ukraine
At the first level Ukraine is divided into **27** regions: **24** oblasts (regions), **1** autonomous republic (Crimea) and **2** cities with special status (Kyiv, Sevastopol)
## Install
```
pip install pygal_maps_ua
```
## Usage
This package is a plugin for an open-source data visualization library Pygal, so please refer the [Pygal](https://www.pygal.org/en/stable/) and [Pygal / Chart types / Maps](https://www.pygal.org/en/stable/documentation/types/maps/index.html) documentation for deeper understanding of the code below
```python
from pygal.maps.ua import Regions
map = Regions()
map.title = 'Regions with highly confused name'
map.add('Cherkasy', ['cherkasy'])
map.add('Сhernihiv', ['chernihiv'])
map.add('Сhernivtsi', ['chernivtsi'])
map.render_to_png('chart.png')
```
Result:
You can also specify a value for the region
```python
from pygal_maps_ua.maps import Regions, REGIONS_UA
map = Regions()
map.title = 'Number of letters in the region name'
map.add(
"Letters count",
{x: len(y) for x, y in REGIONS_UA.items()}
)
map.render_to_png('chart.png')
```
Result:
## Temporarily occupied territories
It is possible to render a map with the **schematic visualization** of temporarily occupied territories of Donetsk and Luhansk regions (known as ORDLO). This area refers to territories [occupied by Russia in the 2014 year](https://en.wikipedia.org/wiki/Russian-occupied_territories_of_Ukraine#Before_February_2022)) and don't refer to territories, occupied by Russia during full-scale [Russian invasion of Ukraine in 2022](https://en.wikipedia.org/wiki/Russian_invasion_of_Ukraine)
You can use such a template by calling the ``RegionsOrdlo`` class and refer the occupied regions area and ``ordlo`` key respectively
```python
from pygal.maps.ua import RegionsOrdlo
map = RegionsOrdlo()
```
> **⚠ Warning**
>
> It should be a **valid reason** to use such a map template instead of Regions template
>
> The straight use-case is to visualize some statistical data from 2014 and clearly display that you have no data from the temporarily occupied territories
>
> It is **strictly forbidden** to use this map template to dispute in any way the sovereignty and territorial integrity of Ukraine (including marking occupied territories as "disputed", "unrecognised", "self-proclaimed" or using any other formulations except "occupied" or "temporarily occupied" according to the UN resolutions [73/194](https://www.un.org/press/en/2018/ga12108.doc.htm), [ES-11/4](https://en.wikipedia.org/wiki/United_Nations_General_Assembly_Resolution_ES-11/4) and common sense).
The example of using the ``RegionsOrdlo`` for the use-case of visualizing the population of Ukraine on 1 Jan 2020 is provided below:
[(data source)](https://ukrstat.gov.ua/operativ/operativ2019/ds/kn/kn_u/kn1219_u.html)
```python
from pygal.maps.ua import RegionsOrdlo
population_2020_by_region = {
"vinnytsia" :1545416,
"volyn" :1031421,
"dnipropetrovsk" :3176648,
"donetsk" :4131808,
"zhytomir" :1208212,
"zakarpattia" :1253791,
"zaporizhzhia" :1687401,
"ivano-frankivsk" :1368097,
"kyiv" :1781044,
"kirovohrad" :933109,
"luhansk" :2135913,
"lviv" :2512084,
"mykolaiv" :1119862,
"odesa" :2377230,
"poltava" :1386978,
"rivne" :1152961,
"sumy" :1068247,
"ternopil" :1038695,
"kharkiv" :2658461,
"kherson" :1027913,
"khmelnitskyi" :1254702,
"cherkasy" :1192137,
"chernivtsi" :901632,
"chernihiv" :991294,
"kyivcity" :2967360,
}
map = RegionsOrdlo(legend_at_bottom=True)
map.title = 'Population by region on 01 Jan 2020'
map.add('Population', population_2020_by_region)
map.add('Temporarily occupied territories', ['ordlo', 'crimea', 'sevastopolcity'])
map.render_to_png('chart.png')
```
Result:
## List of available regions
List of available regions is set as variables `REGIONS_UA` and `REGIONS_ENG` respectively and listed below:
| key | description [ua] | description [en] |
|----------------|-----------------------------|-------------------------------|
| cherkasy | Черкаська область | Cherkasy Oblast |
| chernihiv | Чернігівська область | Chernihiv Oblast |
| chernivtsi | Чернівецька область | Chernivtsi Oblast |
| crimea | Автономна Республіка Крим | Autonomous Republic of Crimea |
| dnipropetrovsk | Дніпропетровська область | Dnipropetrovsk Oblast |
| donetsk | Донецька область | Donetsk Oblast |
| ivano-frankivsk | Івано-Франківська область | Ivano-Frankivsk Oblast |
| kharkiv | Харківська область | Kharkiv Oblast |
| kherson | Херсонська область | Kherson Oblast |
| khmelnitskyi | Хмельницька область | Khmelnytskyi Oblast |
| kyiv | Київська область | Kyiv Oblast |
| kyivcity | Київ | Kyiv |
| kirovohrad | Кіровоградська область | Kirovohrad Oblast |
| lviv | Львівська область | Lviv Oblast |
| luhansk | Луганська область | Luhansk Oblast |
| mykolaiv | Миколаївська область | Mykolaiv Oblast |
| odesa | Одеська область | Odesa Oblast |
| poltava | Полтавська область | Poltava Oblast |
| rivne | Рівненська область | Rivne Oblast |
| sevastopolcity | Севастополь | Sevastopol |
| sumy | Сумська область | Sumy Oblast |
| ternopil | Тернопільська область | Ternopil Oblast |
| vinnytsia | Вінницька область | Vinnytsia Oblast |
| volyn | Волинська область | Volyn Oblast |
| zakarpattia | Закарпатська область | Zakarpattia Oblast |
| zaporizhzhia | Запорізька область | Zaporizhzhia Oblast |
| zhytomir | Житомирська область | Zhytomyr Oblast |
If you need to update the region names for your purposes (e.g. use only city names), use the `set_regions` or `set_regions_eng` functions
##### If you would like to support the author consider donating to the [United24](https://u24.gov.ua/) charity foundation
###### Data Source for Ukraine ADM1 borders:
Hijmans, Robert J.. University of California, Berkeley. Museum of Vertebrate Zoology. First-level Administrative Divisions, Ukraine, 2015. [Shapefile]. University of California, Berkeley. Museum of Vertebrate Zoology. Retrieved from https://maps.princeton.edu/catalog/stanford-gg870xt4706
Raw data
{
"_id": null,
"home_page": "http://github.com/Golova1111/pygal_maps_ua",
"name": "pygal-maps-ua",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "svg,chart,graph,maps,ukraine,pygal",
"author": "Vadym Holovashchenko",
"author_email": "vadym.holovashchenko@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/c2/d0/1a825289447a088be8604c31b07bc69f9a6d97a91739a55d6aacc5ebf771/pygal_maps_ua-1.0.2.tar.gz",
"platform": "Any",
"description": "# pygal_maps_ua\n### Ukraine maps for pygal\n\n[\ud83c\uddfa\ud83c\udde6 **\u0427\u0438\u0442\u0430\u0442\u0438 \u0443\u043a\u0440\u0430\u0457\u043d\u0441\u044c\u043a\u043e\u044e**](https://github.com/Golova1111/pygal_maps_ua/blob/master/README_ua.md)\n\nUkraine map plugin for [Pygal](https://www.pygal.org/en/stable/) \n\nAllows you to create first level division administrative map of Ukraine\n\nAt the first level Ukraine is divided into **27** regions: **24** oblasts (regions), **1** autonomous republic (Crimea) and **2** cities with special status (Kyiv, Sevastopol)\n\n## Install\n\n```\npip install pygal_maps_ua\n```\n\n## Usage\n\nThis package is a plugin for an open-source data visualization library Pygal, so please refer the [Pygal](https://www.pygal.org/en/stable/) and [Pygal / Chart types / Maps](https://www.pygal.org/en/stable/documentation/types/maps/index.html) documentation for deeper understanding of the code below\n\n```python\nfrom pygal.maps.ua import Regions\n\nmap = Regions()\nmap.title = 'Regions with highly confused name'\nmap.add('Cherkasy', ['cherkasy'])\nmap.add('\u0421hernihiv', ['chernihiv'])\nmap.add('\u0421hernivtsi', ['chernivtsi'])\n\nmap.render_to_png('chart.png')\n```\n\nResult:\n\n\n\nYou can also specify a value for the region\n\n```python\nfrom pygal_maps_ua.maps import Regions, REGIONS_UA\n\nmap = Regions()\nmap.title = 'Number of letters in the region name'\nmap.add(\n \"Letters count\", \n {x: len(y) for x, y in REGIONS_UA.items()}\n)\n\nmap.render_to_png('chart.png')\n```\n\nResult:\n\n\n\n## Temporarily occupied territories\n\nIt is possible to render a map with the **schematic visualization** of temporarily occupied territories of Donetsk and Luhansk regions (known as ORDLO). This area refers to territories [occupied by Russia in the 2014 year](https://en.wikipedia.org/wiki/Russian-occupied_territories_of_Ukraine#Before_February_2022)) and don't refer to territories, occupied by Russia during full-scale [Russian invasion of Ukraine in 2022](https://en.wikipedia.org/wiki/Russian_invasion_of_Ukraine)\n\nYou can use such a template by calling the ``RegionsOrdlo`` class and refer the occupied regions area and ``ordlo`` key respectively\n\n```python\nfrom pygal.maps.ua import RegionsOrdlo\n\nmap = RegionsOrdlo()\n```\n\n> **\u26a0 Warning**\n> \n> It should be a **valid reason** to use such a map template instead of Regions template\n> \n> The straight use-case is to visualize some statistical data from 2014 and clearly display that you have no data from the temporarily occupied territories\n> \n> It is **strictly forbidden** to use this map template to dispute in any way the sovereignty and territorial integrity of Ukraine (including marking occupied territories as \"disputed\", \"unrecognised\", \"self-proclaimed\" or using any other formulations except \"occupied\" or \"temporarily occupied\" according to the UN resolutions [73/194](https://www.un.org/press/en/2018/ga12108.doc.htm), [ES-11/4](https://en.wikipedia.org/wiki/United_Nations_General_Assembly_Resolution_ES-11/4) and common sense).\n\nThe example of using the ``RegionsOrdlo`` for the use-case of visualizing the population of Ukraine on 1 Jan 2020 is provided below:\n\n[(data source)](https://ukrstat.gov.ua/operativ/operativ2019/ds/kn/kn_u/kn1219_u.html)\n\n```python\nfrom pygal.maps.ua import RegionsOrdlo\n\npopulation_2020_by_region = {\n \"vinnytsia\" :1545416,\n \"volyn\" :1031421,\n \"dnipropetrovsk\" :3176648,\n \"donetsk\" :4131808,\n \"zhytomir\" :1208212,\n \"zakarpattia\" :1253791,\n \"zaporizhzhia\" :1687401,\n \"ivano-frankivsk\" :1368097,\n \"kyiv\" :1781044,\n \"kirovohrad\" :933109,\n \"luhansk\" :2135913,\n \"lviv\" :2512084,\n \"mykolaiv\" :1119862,\n \"odesa\" :2377230,\n \"poltava\" :1386978,\n \"rivne\" :1152961,\n \"sumy\" :1068247,\n \"ternopil\" :1038695,\n \"kharkiv\" :2658461,\n \"kherson\" :1027913,\n \"khmelnitskyi\" :1254702,\n \"cherkasy\" :1192137,\n \"chernivtsi\" :901632,\n \"chernihiv\" :991294,\n \"kyivcity\" :2967360,\n}\n\n\nmap = RegionsOrdlo(legend_at_bottom=True)\n\nmap.title = 'Population by region on 01 Jan 2020'\nmap.add('Population', population_2020_by_region)\nmap.add('Temporarily occupied territories', ['ordlo', 'crimea', 'sevastopolcity'])\n\nmap.render_to_png('chart.png')\n```\n\nResult:\n\n\n\n\n## List of available regions\n\nList of available regions is set as variables `REGIONS_UA` and `REGIONS_ENG` respectively and listed below:\n\n| key | description [ua] | description [en] |\n|----------------|-----------------------------|-------------------------------|\n| cherkasy | \u0427\u0435\u0440\u043a\u0430\u0441\u044c\u043a\u0430 \u043e\u0431\u043b\u0430\u0441\u0442\u044c | Cherkasy Oblast |\n| chernihiv | \u0427\u0435\u0440\u043d\u0456\u0433\u0456\u0432\u0441\u044c\u043a\u0430 \u043e\u0431\u043b\u0430\u0441\u0442\u044c | Chernihiv Oblast |\n| chernivtsi | \u0427\u0435\u0440\u043d\u0456\u0432\u0435\u0446\u044c\u043a\u0430 \u043e\u0431\u043b\u0430\u0441\u0442\u044c | Chernivtsi Oblast |\n| crimea | \u0410\u0432\u0442\u043e\u043d\u043e\u043c\u043d\u0430 \u0420\u0435\u0441\u043f\u0443\u0431\u043b\u0456\u043a\u0430 \u041a\u0440\u0438\u043c | Autonomous Republic of Crimea |\n| dnipropetrovsk | \u0414\u043d\u0456\u043f\u0440\u043e\u043f\u0435\u0442\u0440\u043e\u0432\u0441\u044c\u043a\u0430 \u043e\u0431\u043b\u0430\u0441\u0442\u044c | Dnipropetrovsk Oblast |\n| donetsk | \u0414\u043e\u043d\u0435\u0446\u044c\u043a\u0430 \u043e\u0431\u043b\u0430\u0441\u0442\u044c | Donetsk Oblast |\n| ivano-frankivsk | \u0406\u0432\u0430\u043d\u043e-\u0424\u0440\u0430\u043d\u043a\u0456\u0432\u0441\u044c\u043a\u0430 \u043e\u0431\u043b\u0430\u0441\u0442\u044c | Ivano-Frankivsk Oblast |\n| kharkiv | \u0425\u0430\u0440\u043a\u0456\u0432\u0441\u044c\u043a\u0430 \u043e\u0431\u043b\u0430\u0441\u0442\u044c | Kharkiv Oblast |\n| kherson | \u0425\u0435\u0440\u0441\u043e\u043d\u0441\u044c\u043a\u0430 \u043e\u0431\u043b\u0430\u0441\u0442\u044c | Kherson Oblast |\n| khmelnitskyi | \u0425\u043c\u0435\u043b\u044c\u043d\u0438\u0446\u044c\u043a\u0430 \u043e\u0431\u043b\u0430\u0441\u0442\u044c | Khmelnytskyi Oblast |\n| kyiv | \u041a\u0438\u0457\u0432\u0441\u044c\u043a\u0430 \u043e\u0431\u043b\u0430\u0441\u0442\u044c | Kyiv Oblast |\n| kyivcity | \u041a\u0438\u0457\u0432 | Kyiv |\n| kirovohrad | \u041a\u0456\u0440\u043e\u0432\u043e\u0433\u0440\u0430\u0434\u0441\u044c\u043a\u0430 \u043e\u0431\u043b\u0430\u0441\u0442\u044c | Kirovohrad Oblast |\n| lviv | \u041b\u044c\u0432\u0456\u0432\u0441\u044c\u043a\u0430 \u043e\u0431\u043b\u0430\u0441\u0442\u044c | Lviv Oblast |\n| luhansk | \u041b\u0443\u0433\u0430\u043d\u0441\u044c\u043a\u0430 \u043e\u0431\u043b\u0430\u0441\u0442\u044c | Luhansk Oblast |\n| mykolaiv | \u041c\u0438\u043a\u043e\u043b\u0430\u0457\u0432\u0441\u044c\u043a\u0430 \u043e\u0431\u043b\u0430\u0441\u0442\u044c | Mykolaiv Oblast |\n| odesa | \u041e\u0434\u0435\u0441\u044c\u043a\u0430 \u043e\u0431\u043b\u0430\u0441\u0442\u044c | Odesa Oblast |\n| poltava | \u041f\u043e\u043b\u0442\u0430\u0432\u0441\u044c\u043a\u0430 \u043e\u0431\u043b\u0430\u0441\u0442\u044c | Poltava Oblast |\n| rivne | \u0420\u0456\u0432\u043d\u0435\u043d\u0441\u044c\u043a\u0430 \u043e\u0431\u043b\u0430\u0441\u0442\u044c | Rivne Oblast |\n| sevastopolcity | \u0421\u0435\u0432\u0430\u0441\u0442\u043e\u043f\u043e\u043b\u044c | Sevastopol |\n| sumy | \u0421\u0443\u043c\u0441\u044c\u043a\u0430 \u043e\u0431\u043b\u0430\u0441\u0442\u044c | Sumy Oblast |\n| ternopil | \u0422\u0435\u0440\u043d\u043e\u043f\u0456\u043b\u044c\u0441\u044c\u043a\u0430 \u043e\u0431\u043b\u0430\u0441\u0442\u044c | Ternopil Oblast |\n| vinnytsia | \u0412\u0456\u043d\u043d\u0438\u0446\u044c\u043a\u0430 \u043e\u0431\u043b\u0430\u0441\u0442\u044c | Vinnytsia Oblast |\n| volyn | \u0412\u043e\u043b\u0438\u043d\u0441\u044c\u043a\u0430 \u043e\u0431\u043b\u0430\u0441\u0442\u044c | Volyn Oblast |\n| zakarpattia | \u0417\u0430\u043a\u0430\u0440\u043f\u0430\u0442\u0441\u044c\u043a\u0430 \u043e\u0431\u043b\u0430\u0441\u0442\u044c | Zakarpattia Oblast |\n| zaporizhzhia | \u0417\u0430\u043f\u043e\u0440\u0456\u0437\u044c\u043a\u0430 \u043e\u0431\u043b\u0430\u0441\u0442\u044c | Zaporizhzhia Oblast |\n| zhytomir | \u0416\u0438\u0442\u043e\u043c\u0438\u0440\u0441\u044c\u043a\u0430 \u043e\u0431\u043b\u0430\u0441\u0442\u044c | Zhytomyr Oblast |\n\nIf you need to update the region names for your purposes (e.g. use only city names), use the `set_regions` or `set_regions_eng` functions\n\n##### If you would like to support the author consider donating to the [United24](https://u24.gov.ua/) charity foundation\n\n###### Data Source for Ukraine ADM1 borders:\n\nHijmans, Robert J.. University of California, Berkeley. Museum of Vertebrate Zoology. First-level Administrative Divisions, Ukraine, 2015. [Shapefile]. University of California, Berkeley. Museum of Vertebrate Zoology. Retrieved from https://maps.princeton.edu/catalog/stanford-gg870xt4706\n",
"bugtrack_url": null,
"license": "GNU LGPL v3+",
"summary": "Ukraine maps for pygal",
"version": "1.0.2",
"project_urls": {
"Homepage": "http://github.com/Golova1111/pygal_maps_ua"
},
"split_keywords": [
"svg",
"chart",
"graph",
"maps",
"ukraine",
"pygal"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a3de7a096a198142c38dec436e830d207a88ad2c69ab8be11a81b5456f0bf590",
"md5": "d633f50f56e06eaad24eb401fa52670b",
"sha256": "2303e86da759d46512fa1b6edd8e6fedbd6b9662f723bd0030886efc27999b03"
},
"downloads": -1,
"filename": "pygal_maps_ua-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d633f50f56e06eaad24eb401fa52670b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 239275,
"upload_time": "2023-06-15T21:20:36",
"upload_time_iso_8601": "2023-06-15T21:20:36.778506Z",
"url": "https://files.pythonhosted.org/packages/a3/de/7a096a198142c38dec436e830d207a88ad2c69ab8be11a81b5456f0bf590/pygal_maps_ua-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c2d01a825289447a088be8604c31b07bc69f9a6d97a91739a55d6aacc5ebf771",
"md5": "499e87ca197b420392271312580e638a",
"sha256": "818b3351e17219a9f86fcdd3909a005927b916c7d5a86c7c561cc9e529765aa5"
},
"downloads": -1,
"filename": "pygal_maps_ua-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "499e87ca197b420392271312580e638a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 235572,
"upload_time": "2023-06-15T21:20:39",
"upload_time_iso_8601": "2023-06-15T21:20:39.749035Z",
"url": "https://files.pythonhosted.org/packages/c2/d0/1a825289447a088be8604c31b07bc69f9a6d97a91739a55d6aacc5ebf771/pygal_maps_ua-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-15 21:20:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Golova1111",
"github_project": "pygal_maps_ua",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pygal-maps-ua"
}
JSON
