From 6a43fa79fbcc030493515e97419eb4a8bed94edc Mon Sep 17 00:00:00 2001 From: Caitlin Adams Date: Fri, 3 Nov 2023 18:14:13 +1100 Subject: [PATCH] Loading waterbodies dataset notebook and tools (#483) * Initial commit of waterbodies dataset notebook. To be updated with prod service when available * Update notebook text and have scripts point to prod WFS * Revision of the notebook to leverage the prod service with timeseries --- Datasets/Waterbodies.ipynb | 1037 +++++++++++++++++++++++++++ Tools/deafrica_tools/waterbodies.py | 129 ++++ Tools/index.rst | 1 + Tools/pyproject.toml | 2 +- 4 files changed, 1168 insertions(+), 1 deletion(-) create mode 100644 Datasets/Waterbodies.ipynb create mode 100644 Tools/deafrica_tools/waterbodies.py diff --git a/Datasets/Waterbodies.ipynb b/Datasets/Waterbodies.ipynb new file mode 100644 index 000000000..223704381 --- /dev/null +++ b/Datasets/Waterbodies.ipynb @@ -0,0 +1,1037 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "33913a41-020b-4ebc-a57b-0aa48b7bccd5", + "metadata": {}, + "source": [ + "# Waterbodies\n", + "\n", + "* **Products used:** [DE Africa Waterbodies](https://docs.digitalearthafrica.org/en/latest/data_specs/Waterbodies_specs.html)" + ] + }, + { + "cell_type": "raw", + "id": "494dd4b2-44ce-4b4a-afcf-c0f6c3ff66c9", + "metadata": { + "raw_mimetype": "text/restructuredtext", + "tags": [] + }, + "source": [ + "**Keywords**: :index:`data used; waterbodies`" + ] + }, + { + "cell_type": "markdown", + "id": "6f0e6c31-8e3f-47a4-8c5b-ae201a784afb", + "metadata": { + "jp-MarkdownHeadingCollapsed": true, + "tags": [] + }, + "source": [ + "## Background\n", + "The Digital Earth Africa continental Waterbodies Monitoring Service identifies more than 600,000 water bodies from over three decades of satellite observations. This service maps persistent and seasonal water bodies and the change in their water surface area over time. Mapped water bodies may include, but are not limited to, lakes, ponds, man-made reservoirs, wetlands, and segments of some river systems.\n", + "\n", + "On a local, regional, and continental scale, this service helps improve our understanding of surface water dynamics and water availability and can be used for monitoring water bodies such as wetlands, lakes and dams in remote and/or inaccessible locations.\n", + "\n", + "The service offers two products\n", + "\n", + "* The DE Africa Waterbodies Historical Extent\n", + "* The DE Africa Waterbodies Surface Area Change\n", + "\n", + "The DE Africa Waterbodies Historical Extent product is a static polygon-based view of the DE Africa Water Observations from Space All-Time Summary product. The historical extent represents where water has appeared in at least 5% of clear observations since 1987. It is not a capture of a water body’s true extent in any given year, but a record of where water has appeared since 1987. To be captured in the dataset, polygons must have an area of at least 4,500 metres squared (5 Landsat pixels). The historical extent polygons have been derived from the [DE Africa Water Observations from Space All-Time Summary](https://docs.digitalearthafrica.org/en/latest/data_specs/Landsat_WOfS_specs.html#WOfS-All-Time-Summary) product, which provides historical surface water observations across the African continent.\n", + "\n", + "For each water body, the Surface Area Change product provides the percentage of the historical extent that was classified as wet, dry, or invalid, for each [DE Africa Water Observation from Space Feature Layer](https://docs.digitalearthafrica.org/en/latest/data_specs/Landsat_WOfS_specs.html#WOfS-Feature-Layer) scene that captured the water body. This can be used to identify when water bodies are increasing or decreasing in wet surface area.\n", + "\n", + "**Disclaimer: DE Africa Waterbodies Surface Area Change measures the wet surface area of waterbodies as estimated from satellites. This product does not measure depth, volume, purpose of the waterbody, nor the source of the water.**\n", + "\n", + "### Applications \n", + "\n", + "* Identify and analyse persistent and seasonal water bodies \n", + "* Water resource management \n", + "* Gain insights into the severity and spatial distribution of drought" + ] + }, + { + "cell_type": "markdown", + "id": "226815d2-c7fa-4b5c-b01c-83677afbf19d", + "metadata": {}, + "source": [ + "## Description\n", + "This notebook will demonstrate how to load historical extents and wet surface area timeseries from the [DE Africa Waterbodies service](https://docs.digitalearthafrica.org/en/latest/data_specs/Waterbodies_specs.html). \n", + "\n", + "Topics covered include:\n", + "\n", + "1. Getting a list of available polygons in a given area\n", + "2. Select and plot a single polygon\n", + "3. Plotting the surface area of the polygon over time\n", + "\n", + "***" + ] + }, + { + "cell_type": "markdown", + "id": "77b66d5d-4e49-40a8-8acd-db9b262271ef", + "metadata": {}, + "source": [ + "## Getting started\n", + "\n", + "To run this analysis, run all the cells in the notebook, starting with the “Load packages” cell." + ] + }, + { + "cell_type": "markdown", + "id": "d1cc2fd0-ca95-456b-bcd4-48dfb2f6bd3f", + "metadata": { + "tags": [] + }, + "source": [ + "### Load packages\n", + "Import Python packages that are used for the analysis." + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "9556d229-746b-4d4a-ba66-38edc9c1ea2b", + "metadata": {}, + "outputs": [], + "source": [ + "import matplotlib.pyplot as plt\n", + "\n", + "from deafrica_tools.plotting import display_map\n", + "from deafrica_tools.waterbodies import (\n", + " get_geohashes,\n", + " get_waterbodies,\n", + " get_waterbody,\n", + " get_time_series,\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "522a5907-64b5-4016-88e7-b60f9b4bfd5b", + "metadata": {}, + "source": [ + "## Analysis parameters\n", + "\n", + "This section defines the analysis parameters, including:\n", + "\n", + "* `lat`, `lon`, `buffer`: center lat/lon and analysis window size for the area of interest (in degrees)\n", + "\n", + "The default area is a water body in Mauritania." + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "1ae9a549-0522-4ad2-b7a6-3c70fce1c8b3", + "metadata": {}, + "outputs": [ + { + "name": "stderr", + "output_type": "stream", + "text": [ + "/usr/local/lib/python3.10/dist-packages/deafrica_tools/plotting.py:284: FutureWarning: This function is deprecated. See: https://pyproj4.github.io/pyproj/stable/gotchas.html#upgrading-to-pyproj-2-from-pyproj-1\n", + " all_longitude, all_latitude = transform(Proj(crs), Proj(\"EPSG:4326\"), all_x, all_y)\n" + ] + }, + { + "data": { + "text/html": [ + "
Make this Notebook Trusted to load map: File -> Trust Notebook
" + ], + "text/plain": [ + "" + ] + }, + "execution_count": 2, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "# Set the central latitude and longitude\n", + "lat = 16.59285\n", + "lon = -13.64313\n", + "\n", + "# Set the buffer to load around the central coordinates\n", + "buffer = 0.1\n", + "\n", + "# Compute the bounding box coordinates\n", + "xlim = (lon-buffer, lon+buffer)\n", + "ylim = (lat+buffer, lat-buffer)\n", + "\n", + "# Preview area on a map\n", + "display_map(xlim, ylim)" + ] + }, + { + "cell_type": "markdown", + "id": "85fa0271-d929-443d-82b4-d8c9cfed9f00", + "metadata": { + "tags": [] + }, + "source": [ + "## Getting data\n", + "\n", + "The `deafrica_waterbodies` module allows you to query water bodies by location or geohash.\n", + "\n", + "### List waterbody polygons in an area\n", + "We can get a list of waterbody polygons inside a bounding box of coordinates using `get_waterbodies`." + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "id": "58a89365-c70c-4482-873e-04e632e935f3", + "metadata": {}, + "outputs": [], + "source": [ + "# Create a bounding box from study area coordinates\n", + "bbox = (xlim[0], ylim[1], xlim[1], ylim[0])\n", + "\n", + "# Select all water bodies located within the bounding box\n", + "polygons = get_waterbodies(bbox, crs=\"EPSG:4326\")" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "id": "9f8fe81a-df03-4cec-b1c8-b0aea8e33df5", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
idarea_m2UIDWB_IDperim_mtimeseriesgeometry
0DEAfrica_Waterbodies.536556.300000e+03edymc5r9653654480https://deafrica-services.s3.af-south-1.amazon...MULTIPOLYGON (((-13.65645 16.49794, -13.65614 ...
1DEAfrica_Waterbodies.536571.350000e+04edymcesu953656540https://deafrica-services.s3.af-south-1.amazon...MULTIPOLYGON (((-13.63873 16.50014, -13.63810 ...
2DEAfrica_Waterbodies.536587.470000e+04edymcm9fc536571260https://deafrica-services.s3.af-south-1.amazon...MULTIPOLYGON (((-13.65489 16.51141, -13.65303 ...
3DEAfrica_Waterbodies.536602.637000e+05edymf605w536594080https://deafrica-services.s3.af-south-1.amazon...MULTIPOLYGON (((-13.61354 16.49377, -13.61074 ...
4DEAfrica_Waterbodies.536614.230000e+04edymg5546536601140https://deafrica-services.s3.af-south-1.amazon...MULTIPOLYGON (((-13.57592 16.49769, -13.57499 ...
5DEAfrica_Waterbodies.536966.300000e+03edynz8g7z53695360https://deafrica-services.s3.af-south-1.amazon...MULTIPOLYGON (((-13.72827 16.66043, -13.72765 ...
6DEAfrica_Waterbodies.536971.710000e+04edynzgzec53696660https://deafrica-services.s3.af-south-1.amazon...MULTIPOLYGON (((-13.71210 16.67711, -13.71148 ...
7DEAfrica_Waterbodies.537262.790000e+04edyq33hrp537251500https://deafrica-services.s3.af-south-1.amazon...MULTIPOLYGON (((-13.64805 16.57537, -13.64774 ...
8DEAfrica_Waterbodies.537275.753700e+06edyq3kwze5372638220https://deafrica-services.s3.af-south-1.amazon...MULTIPOLYGON (((-13.62816 16.61287, -13.62722 ...
9DEAfrica_Waterbodies.537285.400000e+03edyq3y1v153727300https://deafrica-services.s3.af-south-1.amazon...MULTIPOLYGON (((-13.63189 16.60160, -13.63126 ...
10DEAfrica_Waterbodies.537292.700000e+04edyq538rh53728840https://deafrica-services.s3.af-south-1.amazon...MULTIPOLYGON (((-13.56752 16.53371, -13.56721 ...
11DEAfrica_Waterbodies.537303.060000e+04edyq6p387537291140https://deafrica-services.s3.af-south-1.amazon...MULTIPOLYGON (((-13.62007 16.60870, -13.61976 ...
12DEAfrica_Waterbodies.537311.890000e+04edyq6pezj53730600https://deafrica-services.s3.af-south-1.amazon...MULTIPOLYGON (((-13.61821 16.61042, -13.61696 ...
13DEAfrica_Waterbodies.537321.620000e+04edyq6pjdn53731840https://deafrica-services.s3.af-south-1.amazon...MULTIPOLYGON (((-13.61603 16.60723, -13.61572 ...
14DEAfrica_Waterbodies.537331.035000e+05edyq86wpu537323360https://deafrica-services.s3.af-south-1.amazon...MULTIPOLYGON (((-13.69034 16.62930, -13.69003 ...
15DEAfrica_Waterbodies.537343.780000e+04edyq87j4t537331560https://deafrica-services.s3.af-south-1.amazon...MULTIPOLYGON (((-13.69345 16.62954, -13.69221 ...
16DEAfrica_Waterbodies.537351.467000e+05edyqc8m45537343300https://deafrica-services.s3.af-south-1.amazon...MULTIPOLYGON (((-13.63686 16.65921, -13.63531 ...
17DEAfrica_Waterbodies.537361.197000e+05edyqdtj3d537352100https://deafrica-services.s3.af-south-1.amazon...MULTIPOLYGON (((-13.59333 16.64180, -13.59271 ...
18DEAfrica_Waterbodies.537375.940000e+04edyqdxeh8537361620https://deafrica-services.s3.af-south-1.amazon...MULTIPOLYGON (((-13.59644 16.65479, -13.59613 ...
\n", + "
" + ], + "text/plain": [ + " id area_m2 UID WB_ID perim_m \\\n", + "0 DEAfrica_Waterbodies.53655 6.300000e+03 edymc5r96 53654 480 \n", + "1 DEAfrica_Waterbodies.53657 1.350000e+04 edymcesu9 53656 540 \n", + "2 DEAfrica_Waterbodies.53658 7.470000e+04 edymcm9fc 53657 1260 \n", + "3 DEAfrica_Waterbodies.53660 2.637000e+05 edymf605w 53659 4080 \n", + "4 DEAfrica_Waterbodies.53661 4.230000e+04 edymg5546 53660 1140 \n", + "5 DEAfrica_Waterbodies.53696 6.300000e+03 edynz8g7z 53695 360 \n", + "6 DEAfrica_Waterbodies.53697 1.710000e+04 edynzgzec 53696 660 \n", + "7 DEAfrica_Waterbodies.53726 2.790000e+04 edyq33hrp 53725 1500 \n", + "8 DEAfrica_Waterbodies.53727 5.753700e+06 edyq3kwze 53726 38220 \n", + "9 DEAfrica_Waterbodies.53728 5.400000e+03 edyq3y1v1 53727 300 \n", + "10 DEAfrica_Waterbodies.53729 2.700000e+04 edyq538rh 53728 840 \n", + "11 DEAfrica_Waterbodies.53730 3.060000e+04 edyq6p387 53729 1140 \n", + "12 DEAfrica_Waterbodies.53731 1.890000e+04 edyq6pezj 53730 600 \n", + "13 DEAfrica_Waterbodies.53732 1.620000e+04 edyq6pjdn 53731 840 \n", + "14 DEAfrica_Waterbodies.53733 1.035000e+05 edyq86wpu 53732 3360 \n", + "15 DEAfrica_Waterbodies.53734 3.780000e+04 edyq87j4t 53733 1560 \n", + "16 DEAfrica_Waterbodies.53735 1.467000e+05 edyqc8m45 53734 3300 \n", + "17 DEAfrica_Waterbodies.53736 1.197000e+05 edyqdtj3d 53735 2100 \n", + "18 DEAfrica_Waterbodies.53737 5.940000e+04 edyqdxeh8 53736 1620 \n", + "\n", + " timeseries \\\n", + "0 https://deafrica-services.s3.af-south-1.amazon... \n", + "1 https://deafrica-services.s3.af-south-1.amazon... \n", + "2 https://deafrica-services.s3.af-south-1.amazon... \n", + "3 https://deafrica-services.s3.af-south-1.amazon... \n", + "4 https://deafrica-services.s3.af-south-1.amazon... \n", + "5 https://deafrica-services.s3.af-south-1.amazon... \n", + "6 https://deafrica-services.s3.af-south-1.amazon... \n", + "7 https://deafrica-services.s3.af-south-1.amazon... \n", + "8 https://deafrica-services.s3.af-south-1.amazon... \n", + "9 https://deafrica-services.s3.af-south-1.amazon... \n", + "10 https://deafrica-services.s3.af-south-1.amazon... \n", + "11 https://deafrica-services.s3.af-south-1.amazon... \n", + "12 https://deafrica-services.s3.af-south-1.amazon... \n", + "13 https://deafrica-services.s3.af-south-1.amazon... \n", + "14 https://deafrica-services.s3.af-south-1.amazon... \n", + "15 https://deafrica-services.s3.af-south-1.amazon... \n", + "16 https://deafrica-services.s3.af-south-1.amazon... \n", + "17 https://deafrica-services.s3.af-south-1.amazon... \n", + "18 https://deafrica-services.s3.af-south-1.amazon... \n", + "\n", + " geometry \n", + "0 MULTIPOLYGON (((-13.65645 16.49794, -13.65614 ... \n", + "1 MULTIPOLYGON (((-13.63873 16.50014, -13.63810 ... \n", + "2 MULTIPOLYGON (((-13.65489 16.51141, -13.65303 ... \n", + "3 MULTIPOLYGON (((-13.61354 16.49377, -13.61074 ... \n", + "4 MULTIPOLYGON (((-13.57592 16.49769, -13.57499 ... \n", + "5 MULTIPOLYGON (((-13.72827 16.66043, -13.72765 ... \n", + "6 MULTIPOLYGON (((-13.71210 16.67711, -13.71148 ... \n", + "7 MULTIPOLYGON (((-13.64805 16.57537, -13.64774 ... \n", + "8 MULTIPOLYGON (((-13.62816 16.61287, -13.62722 ... \n", + "9 MULTIPOLYGON (((-13.63189 16.60160, -13.63126 ... \n", + "10 MULTIPOLYGON (((-13.56752 16.53371, -13.56721 ... \n", + "11 MULTIPOLYGON (((-13.62007 16.60870, -13.61976 ... \n", + "12 MULTIPOLYGON (((-13.61821 16.61042, -13.61696 ... \n", + "13 MULTIPOLYGON (((-13.61603 16.60723, -13.61572 ... \n", + "14 MULTIPOLYGON (((-13.69034 16.62930, -13.69003 ... \n", + "15 MULTIPOLYGON (((-13.69345 16.62954, -13.69221 ... \n", + "16 MULTIPOLYGON (((-13.63686 16.65921, -13.63531 ... \n", + "17 MULTIPOLYGON (((-13.59333 16.64180, -13.59271 ... \n", + "18 MULTIPOLYGON (((-13.59644 16.65479, -13.59613 ... " + ] + }, + "execution_count": 4, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "# Return GeoDataFrame with selected water bodies\n", + "polygons" + ] + }, + { + "cell_type": "markdown", + "id": "55e16bad-af90-426c-ad65-41da1299cf23", + "metadata": {}, + "source": [ + "The returned geodataframe includes all the water bodies which are located within the bounding box. This dataset contains metadata for each water body in the dataset, including the ID, UID, WB_UID, area, perimeter and time series. See the [Waterbodies Historical Extent documentation](https://docs.digitalearthafrica.org/en/latest/data_specs/Waterbodies_specs.html#Waterbodies-Historical-Extent) for descriptions of each attribute." + ] + }, + { + "cell_type": "markdown", + "id": "4876f577-eb5d-4d96-a65a-f1f453b9b86e", + "metadata": {}, + "source": [ + "### Displaying the polygons\n", + "\n", + "Once the water body polygons are in memory, you can plot them directly, or explore them in an interactive window." + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "id": "3dc67cd9-ab31-4901-9743-96e0b1c2cc1a", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "" + ] + }, + "execution_count": 5, + "metadata": {}, + "output_type": "execute_result" + }, + { + "data": { + "image/png": "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", + "text/plain": [ + "
" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "# Plot the waterbody polygons located within the bounding box\n", + "polygons.plot()" + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "id": "7e17e1a5-eaf9-4e91-971a-52ba8afcf404", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
Make this Notebook Trusted to load map: File -> Trust Notebook
" + ], + "text/plain": [ + "" + ] + }, + "execution_count": 6, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "# Explore the waterbody polygons located within the bounding box\n", + "polygons.explore()" + ] + }, + { + "cell_type": "markdown", + "id": "6a1eb958-dd5f-4049-8658-707e93e1dc08", + "metadata": {}, + "source": [ + "#### Geohashes\n", + "Every water body in DE Africa Water Bodies has a unique identifier (UID) called a [_geohash_](https://en.wikipedia.org/wiki/Geohash). The geohash of a water body is derived from its position, and this process can be reversed to obtain the location from the geohash. A waterbody's geohash is contained under the UID attribute and can be obtained through [DE Africa Maps](https://maps.digitalearth.africa/) by clicking on a waterbody.\n", + "\n", + "**Note:** You might notice that these polygons have a range of similar geohash prefixes ('edyg' or 'edz'). If two geohashes have a similar prefix, this means that they are close together." + ] + }, + { + "cell_type": "markdown", + "id": "4b241a1e-9b47-46fa-900f-517025f285ef", + "metadata": {}, + "source": [ + "### Getting data for a specific water body" + ] + }, + { + "cell_type": "markdown", + "id": "b31e9882-0761-4c1d-bbd1-34b306a6a9c4", + "metadata": {}, + "source": [ + "We can use the `.explore()` function above to interactively explore the subset of water bodies located within the bounding box. Hovering over a water body will display its attributes, including the water body's geohash (UID). After noting the geohash from the `.explore()` function, we can use it to extract just that water body through the `get_waterbody()` function.\n", + "\n", + "By default, try the geohash `edyq3kwze`." + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "id": "a4479d59-e8f6-46ee-b0d4-60c951ca7d41", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
idarea_m2UIDWB_IDperim_mtimeseriesgeometry
0DEAfrica_Waterbodies.537275.753700e+06edyq3kwze5372638220https://deafrica-services.s3.af-south-1.amazon...MULTIPOLYGON (((-13.62816 16.61287, -13.62722 ...
\n", + "
" + ], + "text/plain": [ + " id area_m2 UID WB_ID perim_m \\\n", + "0 DEAfrica_Waterbodies.53727 5.753700e+06 edyq3kwze 53726 38220 \n", + "\n", + " timeseries \\\n", + "0 https://deafrica-services.s3.af-south-1.amazon... \n", + "\n", + " geometry \n", + "0 MULTIPOLYGON (((-13.62816 16.61287, -13.62722 ... " + ] + }, + "execution_count": 7, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "selected_waterbody_geohash = \"edyq3kwze\"\n", + "\n", + "selected_waterbody = get_waterbody(selected_waterbody_geohash)\n", + "selected_waterbody" + ] + }, + { + "cell_type": "markdown", + "id": "1dd90dd0-243f-4fe4-9363-f74567a91874", + "metadata": {}, + "source": [ + "#### Plot the selected water body" + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "id": "edb6b29a-b186-4efc-aa42-1f64ae24e247", + "metadata": {}, + "outputs": [ + { + "data": { + "image/png": "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QIe63Bofd6cI5/vn6p9GAeAbSJQAAABMUCgBAACYYOoNgFu0NuXmzikvptvcz91XiwdaQ6IEAABggkQJQIe6XDJAkgPAk5EoAQAAmCBRAtChzNadkCTh+1iXBE9EogQAAGCCQgkAAMAEU2+Aj/LEqS1P7BMAXAqJEgAAgAmnE6Vt27apsLBQO3fu1IkTJ/Thhx9q7NixDvvs3btXc+bM0datW/Wvf/1L8fHxWrNmjWJiYlpts7i4WA899JDDY0FBQTp9+rT9fk1NjebMmaONGzeqrq5OqampevHFF3XTTTfZ9xk5cqS2bt3q0M5///d/q6ioyNnTBDpdW9IWvmoPyfx94I2vPwu44emcTpSampo0ZMgQLVu2rNXtBw4cUEpKigYNGqQtW7Zo165dmjdvnrp3737JdoODg3XixAn77fDhw/ZthmFo7Nix+vbbb7Vu3Tp99dVXio2NVXp6upqamhzamTJlikM7S5YscfYUAQAAJLUjUcrMzFRmZqbp9rlz52r06NEOBUr//v0v267FYlF4eHir2/bv36/t27fr66+/1s033yxJ+s1vfqPw8HC98847euSRR+z79uzZ07QdwJ1c+de+NyYHwHmkSPAmLl2jZLPZVFJSogEDBigjI0NhYWFKSkrS2rVrL3tsY2OjYmNjFR0draysLO3Zs8e+rbm5WZIcUik/Pz8FBQXps88+c2jn7bffVmhoqG655Rbl5+frH//4h2tODgAAdDkuLZRqa2vV2NioxYsXa9SoUdq4caOys7M1bty4i9YOXWjgwIFavny51q1bp5UrV8pms2n48OE6evSoJGnQoEGKiYlRfn6+Tp06pZaWFj377LM6evSoTpw4YW9n4sSJWrlypTZv3qz8/Hy99dZbeuCBB0yft7m5WQ0NDQ43AACA8yyGYRjtPthicVjMffz4cUVFRem+++7TqlWr7PuNGTNGvXr10jvvvNOmds+cOaO4uDjdd999euqppyRJO3fu1OTJk/XnP/9Z/v7+Sk9Pl5+fnwzD0O9///tW2/n000911113qbKystXpv1/+8pdasGDBRY/X19crODi4TX0FLoUpMnQEb1zMzXQbOlJDQ4OsVmuHfH67NFEKDQ1Vt27dFB8f7/B4XFycqqqq2txOQECAbr31VlVWVtofS0hIUHl5uerq6nTixAmVlpbq73//u2644QbTdpKS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4osvjIEDBxpHjx61PzZr1iwjKirK+Pjjj42//OUvxuTJk42wsDDj5MmTDs//+uuvG927d/fKuNxZ7hzrrKws4+abbzb++Mc/Grt37zZ+9KMfGfHx8UZLS0vnDUAnctdYr1+/3njttdeM3bt3G/v37zdefvllo2fPnsaTTz7ZuQPQidz9b8h53jz15gx3jXdb2vU17hrr3bt3G3369DEeeOAB48SJE/ZbbW2tU/2nUHKRnJycVudoN2/ebBiGYXz66adGcnKyYbVaje7duxs33XSTMWfOHId/jM7/A3Xw4EH7Yy0tLcbPfvYzIywszLj66quN9PR04+uvv77o+ZOTk42JEyd28Fl6BneOdX19vfHwww8b11xzjRESEmJkZ2cbVVVVnXDW7uGusf79739vDB061LjqqquMXr16GUOGDDGKioqMs2fPdtKZdz53/xvy/TZ8vVBy13i3pV1f466xnj9/fqvPGxsb61T/LYbB920BAABaw+UBAAAATFAoAQAAmKBQAgAAMEGhBAAAYIJCCQAAwASFEgAAgAkKJQAAABMUSgAAACYolAAAAExQKAEAAJigUAIAADBBoQQAAGDi/wP2VEXpVEhIYwAAAABJRU5ErkJggg==", + "text/plain": [ + "
" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "selected_waterbody.plot();" + ] + }, + { + "cell_type": "markdown", + "id": "5adcec2f-abd5-4612-8a11-da8ec71e33c9", + "metadata": {}, + "source": [ + "#### Get the wet surface area time series for the selected waterbody" + ] + }, + { + "cell_type": "markdown", + "id": "b3c10b9d-8fc8-4159-b8ca-3204221dfc12", + "metadata": {}, + "source": [ + "For any given geohash or a polygon, we can also use the `get_time_series()` function to get various measures of the water body surface over time. See the [Waterbodies Historical Extent documentation](https://docs.digitalearthafrica.org/en/latest/data_specs/Waterbodies_specs.html#Waterbodies-Surface-Area-Change) for descriptions of the different surface measures." + ] + }, + { + "cell_type": "code", + "execution_count": 9, + "id": "2a1c1555-57dd-4661-a162-bcf4ab34570c", + "metadata": {}, + "outputs": [ + { + "data": { + "image/png": "iVBORw0KGgoAAAANSUhEUgAAAjsAAAG2CAYAAACZEEfAAAAAOXRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjcuMiwgaHR0cHM6Ly9tYXRwbG90bGliLm9yZy8pXeV/AAAACXBIWXMAAA9hAAAPYQGoP6dpAACCx0lEQVR4nO3dd1hTZxsG8DthywaZyhJFRXGhuMFZd+uou4pb65Zara2z2jpaZ91at35ad2ur1Vr3wAFat4goLpbsISvv9weSmoJKMCEQ7t91cbWcnCRPHpKcx/O+53klQggBIiIiIi0l1XQAREREROrEYoeIiIi0GosdIiIi0mosdoiIiEirsdghIiIircZih4iIiLQaix0iIiLSaix2iIiISKux2CEiIiKtxmKHSrUjR46gVq1aMDQ0hEQiQXx8vKZDKjKurq7o2LGj2p/n5MmTkEgkOHnypNqfq7CaNWuGZs2aaToMAP/ma8+ePZoOpUhp+m8wc+ZMSCQShW1ZWVmYNGkSnJycIJVK0blzZwCARCLBzJkzVfbcJeEzUtKx2FGRTZs2QSKRyH8MDQ3h4eGB0aNHIzIyUtPhfbDbt29j5syZePTokaZDUZmXL1+iR48eMDIywooVK7B161YYGxtrJJYdO3ZgyZIlGnnukmbmzJlwdXXVdBhKW7duHfz8/GBnZwcDAwO4ublh4MCBJfoz1axZMwwYMEDTYajNhg0b8MMPP+DTTz/F5s2bMWHCBE2HVKKdP38eM2fO1Mg/KnWL/Bm13Lfffgs3Nze8evUKZ8+exapVq/DHH3/g5s2bKFOmjKbDK7Tbt29j1qxZaNasWYk80OTn8uXLSEpKwuzZs9GqVSuNxrJjxw7cvHkT48eP12gcpD7BwcFwc3PDxx9/DEtLS4SFhWHdunU4dOgQrl+/DkdHR02HWKpNnToVX331lcK2v//+G+XKlcPixYsVtqelpUFXl4dPZZ0/fx6zZs3CgAEDYGFhUaTPzb+WirVr1w5169YFAAwZMgTW1tZYtGgRDh48iN69e3/QY6emppbogqm4iYqKAoAi/9AVFZlMhoyMDBgaGmo6FAKwcuXKPNs6d+6MunXrYsuWLXkOtFS0dHV18xQwUVFR+X4/8DNV8nAYS81atGgBAAgLC5Nv27ZtG7y9vWFkZAQrKyv06tULT548Ubhfs2bNUL16dVy9ehW+vr4oU6YMvv76awDAq1evMHPmTHh4eMDQ0BAODg7o2rUrQkND5feXyWRYsmQJqlWrBkNDQ9jZ2WH48OGIi4tTeJ7ceRtnz56Fj48PDA0NUaFCBWzZskW+z6ZNm9C9e3cAQPPmzeVDdbnjywcPHkSHDh3g6OgIAwMDuLu7Y/bs2cjOzs6TjxUrVqBChQowMjKCj48Pzpw5k+9YfXp6OmbMmIGKFSvCwMAATk5OmDRpEtLT0wuU9927d8tzXLZsWXz22Wd49uyZQn79/f0BAPXq1YNEInnr6fh//vkHEokEv/76q3zb1atXIZFIUKdOHYV927Vrh/r168t/L0humjVrht9//x2PHz+W5/bNs2cFzYVEIsHo0aOxfft2VKtWDQYGBjhy5Mh7c3X06FH5vCVPT0/s27cvzz4PHz5E9+7dYWVlhTJlyqBBgwb4/fff8+z39OlTdO7cGcbGxrC1tcWECRPyxDljxgzo6ekhOjo6z/2HDRsGCwsLvHr16r1x/1dBPlcAsHbtWri7uyu8B9+UnJwMY2NjjBs3Lt/Xp6Ojg7lz58q33bp1Cy1atICRkRHKly+POXPmYMOGDZBIJO8dosr9O7/vtH56ejo6duwIc3NznD9/vtDvydx5Kfn9vPn+L+j3hzK2bdsGHx8flClTBpaWlvD19cXRo0ffun9GRgamT58Ob29vmJubw9jYGE2bNsWJEyfy7Ltz5054e3vD1NQUZmZm8PLywtKlS+W3Z2ZmYtasWahUqRIMDQ1hbW2NJk2a4NixY/J93pyz8+jRI0gkEpw4cQK3bt3K852X35ydZ8+eYdCgQfJhymrVqmHDhg15Yi3IZ+RtHj9+jJEjR6Jy5cowMjKCtbU1unfvnud9VpDX+1/x8fHQ0dHBsmXL5NtiYmIglUphbW0NIYR8++effw57e3uF+wcGBqJt27YwNzdHmTJl4Ofnh3PnzslvnzlzJr788ksAgJubmzynRTaMK0glNm7cKACIy5cvK2xfunSpACBWr14thBBizpw5QiKRiJ49e4qVK1eKWbNmibJlywpXV1cRFxcnv5+fn5+wt7cXNjY2YsyYMWLNmjXiwIEDIisrS7Rs2VIAEL169RLLly8Xc+fOFS1atBAHDhyQ33/IkCFCV1dXDB06VKxevVpMnjxZGBsbi3r16omMjAz5fi4uLqJy5crCzs5OfP3112L58uWiTp06QiKRiJs3bwohhAgNDRVjx44VAMTXX38ttm7dKrZu3SoiIiKEEEJ07txZ9OjRQ/zwww9i1apVonv37gKAmDhxokIuVq5cKQCIpk2bimXLlomAgABhZWUl3N3dhZ+fn3y/7Oxs8dFHH4kyZcqI8ePHizVr1ojRo0cLXV1d8cknnxT4b1GvXj2xePFi8dVXXwkjIyOFHB89elQMGzZMABDffvut2Lp1qzh//ny+j5ednS0sLCzEF198Id+2ePFiIZVKhVQqFQkJCfL9zMzMFF53QXJz9OhRUatWLVG2bFl5bvfv3690LgCIqlWrChsbGzFr1iyxYsUKERwc/NY8ubi4CA8PD2FhYSG++uorsWjRIuHl5SWkUqk4evSofL+IiAhhZ2cnTE1NxTfffCMWLVokatasKaRSqdi3b598v9TUVOHh4SEMDQ3FpEmTxJIlS4S3t7eoUaOGACBOnDghhBAiJCREABA//fSTQjzp6enC0tJSDBo06K0xCyHEjBkzhIuLi8K2gn6u1q9fLwCIRo0aiWXLlonx48cLCwsLUaFCBYX3YN++fYWdnZ3IyspSeJ4FCxYIiUQiHj9+LIQQ4sWLF8LGxkZYWlqKmTNnih9++EFUqlRJ/prDwsLyxB8TEyMiIyPF5cuXRadOnQQAhXyfOHFCABC7d++W57V169bC0tJSXLp0SQhR+Pfk9evX5e+x3J/x48cLAOLLL7+UP1ZBvz/8/PyEv7//O/9eQggxc+ZMed5/+OEHsXTpUtGnTx8xefJkhcd6828QHR0tHBwcREBAgFi1apVYsGCBqFy5stDT01N4Xx89elQAEC1bthQrVqwQK1asEKNHjxbdu3eX7/P1118LiUQihg4dKtatWycWLlwoevfuLebNmyffZ8aMGSL3kJicnCy2bt0qqlSpIsqXL5/nOw+AmDFjhvy+ERERonz58sLJyUl8++23YtWqVeLjjz8WAMTixYvl+xX0M/I2u3fvFjVr1hTTp08Xa9euFV9//bWwtLQULi4uIiUlRanXm58aNWqIbt26yX/fv3+/kEqlAoD8eCCEENWqVROffvqp/Pfjx48LfX190bBhQ7Fw4UKxePFiUaNGDaGvry8CAwOFEDnvvd69e8tzkpvT5OTkd8akKix2VCT3APvXX3+J6Oho8eTJE7Fz505hbW0tjIyMxNOnT8WjR4+Ejo6O+O677xTue+PGDaGrq6uw3c/PT6FIyrVhwwYBQCxatChPDDKZTAghxJkzZwQAsX37doXbjxw5kme7i4uLACBOnz4t3xYVFSUMDAwUvkh379791g9jampqnm3Dhw8XZcqUEa9evRJC5BzIrK2tRb169URmZqZ8v02bNgkACl9yW7duFVKpVJw5c0bhMVevXi0AiHPnzuV5vlwZGRnC1tZWVK9eXaSlpcm3Hzp0SAAQ06dPl297W4Ganw4dOggfHx/57127dhVdu3YVOjo64vDhw0IIIYKCggQAcfDgQfl+BclN7uP/9wAuhHK5ACCkUqm4devWe1+PEP/+7ffu3SvflpCQIBwcHETt2rXl23IPhm/GkJSUJNzc3ISrq6vIzs4WQgixZMkSAUD88ssv8v1SUlJExYoV87x3GjZsKOrXr68Qz759+wr0hf9fBf1c5b43atWqJdLT0+X7rV27Ns978M8//xQA5H/bXDVq1FDYLzc3uV/oQuR8fszNzd9a7BgYGAgAAoCwtrYWy5YtU7j9zWInKSlJ+Pn5ibJly+YpXAv7nnxTdHS0cHZ2Fl5eXvKDjjLfHwUREhIipFKp6NKli/y9kiv3O0uIvMVOVlaWwt9JCCHi4uKEnZ2dQkE8btw4YWZmlqcwfVPNmjVFhw4d3hnnm8XOmzFVq1Ytz77/LXYGDx4sHBwcRExMjMJ+vXr1Eubm5vLvAWU+I/nJ7/vkwoULAoDYsmWLfFtBXm9+Ro0aJezs7OS/BwQECF9fX2FraytWrVolhBDi5cuXQiKRiKVLlwohcv6GlSpVEm3atFH4e6ampgo3NzfRunVr+bYffvjhrZ8LdeMwloq1atUKNjY2cHJyQq9evWBiYoL9+/ejXLly2LdvH2QyGXr06IGYmBj5j729PSpVqpTn9KyBgQEGDhyosG3v3r0oW7YsxowZk+e5c0/B7t69G+bm5mjdurXC83h7e8PExCTP83h6eqJp06by321sbFC5cmU8fPiwQK/ZyMhI/v9JSUmIiYlB06ZNkZqairt37wIArly5gpcvX2Lo0KEK4+J9+/aFpaWlwuPt3r0bVatWRZUqVRTizx0SzO80dq4rV64gKioKI0eOVBhX79ChA6pUqZLv0EtBNG3aFEFBQUhJSQEAnD17Fu3bt0etWrXkwyBnzpyBRCJBkyZNlMrNuyibCz8/P3h6ehb4dTk6OqJLly7y383MzNC/f38EBwcjIiICAPDHH3/Ax8dH4XWZmJhg2LBhePToEW7fvi3fz8HBAZ9++ql8vzJlymDYsGF5nrd///4IDAxUGHrdvn07nJyc4OfnV+D4ART4c5X73hgxYgT09fXl9x8wYADMzc0VHrNVq1ZwdHTE9u3b5dtu3ryJf/75B5999pl82x9//IEGDRrAx8dHvs3GxgZ9+/Z9a7yHDx/GH3/8gYULF8LZ2Vn+nvqvhIQEfPTRR7h79y5OnjyJWrVqKdxe2PdkruzsbPTu3RtJSUnYv3+//EpEZb8/3ufAgQOQyWSYPn06pFLFQ85/L/V+k46OjvzvJJPJEBsbi6ysLNStWxdBQUHy/SwsLJCSkvLOIRoLCwvcunULISEhSsVeEEII7N27F506dYIQQiFnbdq0QUJCgjxeZT4j+Xnz+yQzMxMvX75ExYoVYWFhkScnhXm9TZs2RWRkJO7duwcg5/3j6+uLpk2byt9TZ8+ehRBCfsy4du0aQkJC0KdPH7x8+VL+2lNSUtCyZUucPn0aMplMqTjUgROUVWzFihXw8PCArq4u7OzsULlyZfkHPCQkBEIIVKpUKd/76unpKfxerlw5hS9lAAgNDUXlypXfeSVASEgIEhISYGtrm+/tuRNzczk7O+fZx9LSssDj87du3cLUqVPx999/IzExUeG2hIQEADljzQBQsWJFhdt1dXXzXN0VEhKCO3fuwMbGpkDxvyn3eSpXrpzntipVquDs2bPvfjFv0bRpU2RlZeHChQtwcnJCVFQUmjZtilu3bikcWDw9PWFlZSW/X0Fy8y7K5sLNzU2p11WxYsU8BxwPDw8AOfMW7O3t8fjxY4V5SLmqVq0KICfn1atXx+PHj/N9vPz+Fj179sT48eOxfft2TJ8+HQkJCTh06BAmTJjwzgNgfgr6ucp9b/x3Pz09PVSoUEFhm1QqRd++fbFq1Sr5hQHbt2+HoaGhfP5a7mPml5v8XnOu5s2bA8iZS/PJJ5+gevXqMDExwejRoxX2Gz9+PF69eoXg4GBUq1Ytz+MU9j2ZK/d9+fvvv8Pd3V2+Xdnvj/cJDQ2FVCpVqgjPtXnzZixcuBB3795FZmamfPub7/ORI0fil19+Qbt27VCuXDl89NFH6NGjB9q2bSvf59tvv8Unn3wCDw8PVK9eHW3btkW/fv1Qo0YNpWP6r+joaMTHx2Pt2rVYu3Ztvvvk5kyZz0h+0tLSMHfuXGzcuBHPnj1TmEfz5vdJYV9vbgFz5swZlC9fHsHBwZgzZw5sbGzw448/ym8zMzNDzZo1AUBeUOXOgcxPQkJCnn/UFjUWOyrm4+Mjvxrrv2QyGSQSCQ4fPgwdHZ08t5uYmCj8/mYVrwyZTAZbW1uFf5W+6b8HzvxiAaDwQXqb+Ph4+Pn5wczMDN9++y3c3d1haGiIoKAgTJ48uVAVvUwmg5eXFxYtWpTv7U5OTko/5oeqW7cuDA0Ncfr0aTg7O8PW1hYeHh5o2rQpVq5cifT0dJw5c0bhLIkqcqNsLgr7nilqlpaW6Nixo7zY2bNnD9LT0xXOmhSUsp+rgurfvz9++OEHHDhwAL1798aOHTvkk4RVxd3dHbVr18b27dvzFDuffPIJdu7ciXnz5mHLli15zooU5j2Z68CBA5g/fz5mz56tUBQAyn9/qMu2bdswYMAAdO7cGV9++SVsbW3lk8PfPCNoa2uLa9eu4c8//8Thw4dx+PBhbNy4Ef3798fmzZsBAL6+vggNDcXBgwdx9OhRrF+/HosXL8bq1asxZMiQD4oz93P82WefvfWAr4qiCgDGjBmDjRs3Yvz48WjYsCHMzc0hkUjQq1cvhe+Twr5eR0dHuLm54fTp03B1dYUQAg0bNoSNjQ3GjRuHx48f48yZM2jUqJH8/Zj7vD/88EOes4+5CvsZVCUWO0XI3d0dQgi4ubnJ//VcmMcIDAxEZmZmnjNBb+7z119/oXHjxio7+L3tX9snT57Ey5cvsW/fPvj6+sq3v3n1GQC4uLgAAB48eCD/ly2Q06H00aNHCl8G7u7uuH79Olq2bKn0v/Jzn+fevXvyoZ5c9+7dk9+uLH19ffmVO87OzvJ/ATVt2hTp6enYvn07IiMjFXJQ0NwAb8/vh+SiIB48eAAhhMJj379/H8C/Vwq5uLjIT2u/KXcYLjenLi4uuHnzZp7Hy+++QE4x8cknn+Dy5cvYvn07ateune8ZjPcp6OcqN86QkBCF90ZmZibCwsLk/1LNVb16dXkhUr58eYSHh+Onn37K85j5DRW87TXnJy0tLd+rcTp37oyPPvoIAwYMgKmpKVatWqVwe2Hek0DO39ff3x+dO3eWX+H5JlV/f7i7u0Mmk+H27dtvPRjmZ8+ePahQoQL27dun8H6aMWNGnn319fXRqVMndOrUCTKZDCNHjsSaNWswbdo0+dlkKysrDBw4EAMHDkRycjJ8fX0xc+bMDy52bGxsYGpqiuzs7Pf261L2M/Jfe/bsgb+/PxYuXCjf9urVq3yv5ivs623atClOnz4NNzc31KpVC6ampqhZsybMzc1x5MgRBAUFYdasWfL9c88KmpmZvff1q+M7rKA4Z6cIde3aFTo6Opg1a1aesyZCCLx8+fK9j9GtWzfExMRg+fLleW7LfcwePXogOzsbs2fPzrNPVlZWobpX5o7n//e+uf+SfvP1ZGRk5OkpUrduXVhbW2PdunXIysqSb9++fXue4bIePXrg2bNnWLduXZ440tLS3jrHIfd5bG1tsXr1aoUDyOHDh3Hnzh106NDhPa/07Zo2bYrAwECcOHFCfmApW7Ysqlativnz58v3yVXQ3AA5+c1vWOtDclEQz58/x/79++W/JyYmYsuWLahVq5b80tL27dvj0qVLuHDhgny/lJQUrF27Fq6urvLhifbt2+P58+cKyxykpqa+9dR+u3btULZsWcyfPx+nTp0q1FkdoOCfq7p168LGxgarV69GRkaGfJ9Nmza99TPRr18/HD16FEuWLIG1tTXatWuncHv79u1x8eJFXLp0Sb4tOjo6z1mRrKysfIeFL126hBs3brz1bHD//v2xbNkyrF69GpMnT85zu7LvyeTkZHTp0gXlypXD5s2b8z34qPr7o3PnzpBKpfj222/znM1819nj/D4/gYGBCu9DAHm+N6VSqfwfT7nfAf/dx8TEBBUrVizwJd/voqOjg27dumHv3r24efNmntvfbLGg7Gckv+f6b85++umnPG0+PuT1Nm3aFI8ePcKuXbvk7x2pVIpGjRph0aJFyMzMVHhPeXt7w93dHT/++COSk5PzPN6br/9tx5GiwDM7Rcjd3R1z5szBlClT8OjRI3Tu3BmmpqYICwvD/v37MWzYMEycOPGdj9G/f39s2bIFAQEBuHTpEpo2bYqUlBT89ddfGDlyJD755BP4+flh+PDhmDt3Lq5du4aPPvoIenp6CAkJwe7du7F06VKFCXIFUatWLejo6GD+/PlISEiAgYEBWrRogUaNGsHS0hL+/v4YO3YsJBIJtm7dmucDqa+vj5kzZ2LMmDFo0aIFevTogUePHmHTpk1wd3dX+NLt168ffvnlF4wYMQInTpxA48aNkZ2djbt37+KXX37Bn3/++daDg56eHubPn4+BAwfCz88PvXv3RmRkJJYuXQpXV9cPavfetGlTfPfdd3jy5InCh93X1xdr1qyBq6srypcvL99e0NwAOV8Yu3btQkBAAOrVqwcTExN06tTpg3JREB4eHhg8eDAuX74MOzs7bNiwAZGRkdi4caN8n6+++gr/+9//0K5dO4wdOxZWVlbYvHkzwsLCsHfvXvnp7KFDh2L58uXo378/rl69CgcHB2zduvWtjTD19PTQq1cvLF++HDo6OoVuulnQz5Wenh7mzJmD4cOHo0WLFujZsyfCwsKwcePGPHN2cvXp0weTJk3C/v378fnnn+c5mzpp0iRs3boVbdu2xbhx42BsbIy1a9fCxcUF//zzj3y/5ORkODk5oWfPnqhWrRqMjY1x48YNbNy4Eebm5pg2bdpbX9/o0aORmJiIb775Bubm5gpnY5R9T86aNQu3b9/G1KlTcfDgwTx5bNiwocq/PypWrIhvvvkGs2fPRtOmTdG1a1cYGBjg8uXLcHR0VOhZ9KaOHTti37596NKlCzp06ICwsDCsXr0anp6eCgfVIUOGIDY2Fi1atED58uXx+PFj/PTTT6hVq5Z8XpmnpyeaNWsGb29vWFlZ4cqVK9izZ0+eocPCmjdvHk6cOIH69etj6NCh8PT0RGxsLIKCgvDXX38hNjYWgPKfkfxysnXrVpibm8PT0xMXLlzAX3/9BWtra4X9PuT15r6P7t27h++//16+3dfXF4cPH4aBgQHq1asn3y6VSrF+/Xq0a9cO1apVw8CBA1GuXDk8e/YMJ06cgJmZGX777TcAOd9zAPDNN9+gV69e0NPTQ6dOnYpmmZ4iu+5LyylzGfPevXtFkyZNhLGxsTA2NhZVqlQRo0aNEvfu3ZPv87ZLHoXIuaTvm2++EW5ubkJPT0/Y29uLTz/9VISGhirst3btWuHt7S2MjIyEqamp8PLyEpMmTRLPnz+X7+Pi4pLvJYr/vQxUCCHWrVsnKlSoIHR0dBQukzx37pxo0KCBMDIyEo6OjmLSpEnyS3f/eynlsmXLhIuLizAwMBA+Pj7i3LlzwtvbW7Rt21Zhv4yMDDF//nxRrVo1YWBgICwtLYW3t7eYNWuWvIfIu+zatUvUrl1bGBgYCCsrK9G3b1/x9OlThX2U+ZsJIURiYqLQ0dERpqamCpe5btu2TQAQ/fr1y3OfguYmOTlZ9OnTR1hYWAgACpehFzQXAMSoUaMK9FqE+Pdv/+eff4oaNWoIAwMDUaVKFXl/lzeFhoaKTz/9VFhYWAhDQ0Ph4+MjDh06lGe/x48fi48//liUKVNGlC1bVowbN05+yXJ+l9VeunRJABAfffRRgeN+m4J8roTI6ffk5uYmDAwMRN26dcXp06fzfb/nat++vQDw1j5M//zzj/Dz8xOGhoaiXLlyYvbs2eLnn39WuMQ2PT1djBs3TtSoUUOYmZkJPT094eLiIgYPHpznMtz/9tnJNWnSJAFALF++XL5N2fekv7+//LL3//78t19OQb4/lLFhwwb5Z9LS0lL4+fmJY8eOyW//799AJpOJ77//Xv59Ubt2bXHo0CHh7++v8PnYs2eP+Oijj4Stra3Q19cXzs7OYvjw4eLFixfyfebMmSN8fHyEhYWFMDIyElWqVBHfffedQs+gD7n0XAghIiMjxahRo4STk5P8e7lly5Zi7dq1Cvsp+xl5U1xcnBg4cKAoW7asMDExEW3atBF3794VLi4uCn+/grzed7G1tRUARGRkpHzb2bNn5X3S8hMcHCy6du0qrK2thYGBgXBxcRE9evQQx48fV9hv9uzZoly5cvL+PUV1GbpEiALMQiVSE5lMBhsbG3Tt2jXfoRrSbtevX0etWrWwZcsW9OvXT9Ph5KtLly64ceMGHjx4UOD7bNq0CQMHDkRYWJjWrCVHVJJxzg4VmVevXuUZwtmyZQtiY2PzLBdBpcO6detgYmKCrl27ajqUfL148QK///57sS3EiKhgOGeHiszFixcxYcIEdO/eHdbW1ggKCsLPP/+M6tWrK/QuIe3322+/4fbt21i7di1Gjx5dNGP2SggLC8O5c+ewfv166OnpYfjw4ZoOiYg+AIsdKjKurq5wcnLCsmXLEBsbCysrK/Tv3x/z5s3L0zyRtNuYMWMQGRmJ9u3bK1zGWlycOnUKAwcOhLOzMzZv3pxn0UMiKlk0Omfn9OnT+OGHH3D16lW8ePEC+/fvR+fOneW3CyEwY8YMrFu3DvHx8WjcuDFWrVql0AE1NjYWY8aMwW+//QapVIpu3bph6dKlxaKJEREREWmeRufspKSkoGbNmlixYkW+ty9YsEDeYyIwMBDGxsZo06YNXr16Jd+nb9++uHXrFo4dO4ZDhw7h9OnTBV5nhIiIiLRfsbkaSyKRKJzZEULA0dERX3zxhbz3TEJCAuzs7LBp0yb06tULd+7cgaenJy5fvizvNXLkyBG0b98eT58+haOjY77PlZ6ertBcKXeROWtra412eCQiIqKCE0IgKSkJjo6OeZZU+e+OxQIAsX//fvnvoaGhAoAIDg5W2M/X11eMHTtWCCHEzz//LCwsLBRuz8zMFDo6OmLfvn1vfa7cfgr84Q9/+MMf/vCn5P88efLknTVGsZ2gHBERAQCws7NT2G5nZye/LSIiIs/KvLq6urCyspLvk58pU6YgICBA/ntCQgKcnZ3x5MkTmJmZqeolEBERkRolJibCyckJpqam79yv2BY76mRgYAADA4M8283MzFjsEBERlTDvm4JSbJsK5l7qGRkZqbA9MjJSfpu9vT2ioqIUbs/KykJsbCwvFSUiIiIAxbjYcXNzg729PY4fPy7flpiYiMDAQDRs2BAA0LBhQ8THx+Pq1avyff7++2/IZDLUr1+/yGMmIiKi4kejw1jJyckK682EhYXh2rVrsLKygrOzM8aPH485c+agUqVKcHNzw7Rp0+Do6Ci/Yqtq1apo27Ythg4ditWrVyMzMxOjR49Gr1693nolFhEREZUuGi12rly5gubNm8t/z5007O/vj02bNmHSpElISUnBsGHDEB8fjyZNmuDIkSMwNDSU32f79u0YPXo0WrZsKW8quGzZsiJ/LURERFQ8FZs+O5qUmJgIc3NzJCQkcIIyERFRCVHQ43exnbNDREREpAosdoiIiEirsdghIiIircZih4iIiLQaix0iIiLSaix2iIiISKux2CEiIiKtxmKHiIiItBqLHSIiItJqLHaIiIhIq7HYISIiIq3GYoeIiIi0GosdIiIi0mosdoiIiEirsdghIiIircZih4iIiLQaix0iIiLSaix2iIiISKux2CEiIiKtxmKHiIiItBqLHSIiItJqLHaIiIhIq7HYISIiUoGrj2Nx+VGspsOgfOhqOgAiIqKSLjQ6GT3WXES2TOCzBs6Y2sEThno6mg6LXuOZHSIiog+0+mQosmUCALDtYji6rDyPh9HJGo6KcrHYISIi+gDP4tOwP/gZAGBy2yqwNtbHnReJ6PTTWRy89kzD0RHAYoeIiOiDrDv9EFkygUbu1vi8mTv+GNcUDSpYISUjG+N2XsPkPf8gLSNb02GWaix2iIiICikmOR07L4cDAEY2qwgAsDMzxPYhDTC2ZSVIJMCuK0/wyYqzCIlM0mSopRqLHSIiokLaeC4MrzJlqFneHI0rWsu360glCGjtge2D68PG1AD3I5Px8fJz2H3liQajLb1Y7BARERVC4qtMbLnwGAAwsnlFSCSSPPs0qlgWf4xtiqaVyiItMxtf7vkHAb9cQ0p6VlGHW6qx2CEiIiqEbRcfI+lVFirZmqB1Vbu37mdjaoDNA33wZZvKkEqAfUHP8PHys7jzIrEIoy3dWOwQEREp6VVmNjacDQMAfN7MHVJp3rM6b5JKJRjVvCJ2DmsIezNDhEanoPOKc9gRGA4hRFGEXKqx2CEiIlLSL1eeICY5A+UsjNCppmOB7+fjZoU/xjVF88o2SM+S4ev9NzB25zUkvcpUY7TEYoeIiEgJmdkyrDn1EAAwwq8C9HSUO5RaGevjZ/96+Lp9FehKJfjt+nN0+uksbj5LUEe4BBY7RERESvn12nM8i09DWRMDdK/rVKjHkEolGObrjl9GNEQ5CyM8epmKrivPY/P5RxzWUgMWO0RERAUkkwmsPPkAADC4idsHr39Vx9kSf4xtio887ZCRLcOMX2/h821BSEjjsJYqsdghIiIqoKO3IxAanQJTQ1181sBZJY9pXkYPa/p5Y0YnT+jpSHDkVgQ6LDuD4PA4lTw+sdghIiIqECEEVp4MBQD4N3SFqaGeyh5bIpFgYGM37P28EZytyuBpXBq6r76AFScesCePCrDYISIiKoCzD2Lwz9MEGOpJMbCxq1qeo0Z5Cxwa2wQdvByQJRP44c97aDTvb/z45z1EJ6Wr5TlLAxY7REREBbDiRM5cnd4+zrA2MVDb85gZ6mF5n9pY2L0m3MoaIyEtE8tPPEDj+X/j6/03EBaTorbn1lYSwWnfSExMhLm5ORISEmBmZqbpcIiIqJi5+jgO3Vadh56OBKe+bA5HC6Mied5smcCx25FYczoUweHxAACJBGjjaY/hfhVQ29mySOIorgp6/NYtwpiIiIhKpFWvr8DqUrtckRU6QM6Com2r26NNNTtceRyHNadC8dedKBy5FYEjtyLg42qF4X4V0Lyy7Xu7OJdmLHaIiIje4W5EIv66EwWJBBjh566RGCQSCeq5WqGeqxVCIpOw7sxD7A9+hkuPYnHpUSwq2ZpgqG8FfFLLEQa6H3Y5vDbinB0iIqJ3WPX6Cqz21R1QwcZEw9EAlexMseDTmjgzqQWG+1WAqYEuQqKSMWnPP/BdcAJrToUikctPKOCcHXDODhER5W/TuTDMOnQbQgCHxjRB9XLmmg4pj8RXmdh5KRw/nw1DZGLOFVsmBrroW98ZAxu7wd7cUMMRqk9Bj98sdsBih4iIFAkhsODPe/KzOoObuGFaR08NR/VuGVkyHLz2DGtPP0RIVDIAQE9Hgk9qlcMw3wrwsDPVcISqx2JHCSx2iIgoV2a2DF/tvYG9QU8BABM/8sCo5hUhkZSMCcAymcDJ+1FYfeohLoXFyre3rGKLYb4V4ONmVWJey/uw2FECix0iIgKA1IwsjNwehJP3oqEjlWBuFy/0qFe4xT6Lg+DwOKw9/RBHbkUg92hfy8kCI/wqoLWnPXRK+BVcLHaUwGKHiIhiUzIwcNNlXH8SD0M9KVb0qYOWVe00HZZKhMWkYN2Zh9hz9SkysmQAAFfrMhjqWwHd6pT/4AVNNYXFjhJY7BARlW5PYlPhv+ESHsakwKKMHn72rwdvF+1r2BedlI4tFx5hy4XH8pXVrY31MaCRK/o1dIFFGX0NR6gcFjtKYLFDRFR63X6eCP+NlxCdlI5yFkbYPKgeKtpq32TeN6WkZ+GXK0+w/kwYnsWnAQDK6OugR10nDG7iBierMhqOsGBY7CiBxQ4RUel0PjQGw7dcRVJ6FqrYm2LTQB+tvlT7vzKzZfjjxgusOfUQt18kAsjp2tyxhgOG+VZANcfid6n9m1jsKIHFDhFR6XPon+cI2HUdGdky+LhZYV3/ujA30tN0WBohhMDZBzFYc+ohzj6IkW9vWqkshvu6o3FF62J5BReLHSWw2CEiKl3ebBbYtpo9lvSqVWIn6arazWcJWHv6IX6/8QLZspwSwdPBDMP9KqCDlwN0dYrP4gsFPX4Xn4jzkZ2djWnTpsHNzQ1GRkZwd3fH7Nmz8WZ9JoTA9OnT4eDgACMjI7Rq1QohISEajJqIiIorIQQWHLmLmb/lFDr9GrhgRd86LHTeUL2cOZb1ro2TE5thQCNXGOnp4PaLRIzbeQ3NfjyJTefCkJqRpekwlVKsz+x8//33WLRoETZv3oxq1arhypUrGDhwIL777juMHTsWADB//nzMnTsXmzdvhpubG6ZNm4YbN27g9u3bMDQs2Lgrz+wQEWm/kt4sUFPiUjKw9eJjbDr/CLEpGQAAizJ66N/ABf0buaKsiYHGYlPrMNaZM2ewZs0ahIaGYs+ePShXrhy2bt0KNzc3NGnS5IMCf1PHjh1hZ2eHn3/+Wb6tW7duMDIywrZt2yCEgKOjI7744gtMnDgRAJCQkAA7Ozts2rQJvXr1KtDzsNghItJuqRlZGLU9CCfuRUMqAeZ29ULPes6aDqtEeZWZjT1Xn2LdmYd4/DIVAGCgK8Wn3uUxtGkFuJY1LvKY1DaMtXfvXrRp0wZGRkYIDg5GenrOomMJCQn4/vvvCx9xPho1aoTjx4/j/v37AIDr16/j7NmzaNeuHQAgLCwMERERaNWqlfw+5ubmqF+/Pi5cuPDWx01PT0diYqLCDxERaafYlAz0XheIE/eiYagnxdp+dVnoFIKhng4+a+CCv79ohpV966BmeXOkZ8mwPTAczReexMjtV3HtSbymw8yX0sXOnDlzsHr1aqxbtw56ev/OWm/cuDGCgoJUGtxXX32FXr16oUqVKtDT00Pt2rUxfvx49O3bFwAQEREBALCzU+xwaWdnJ78tP3PnzoW5ubn8x8mp5LYCJyKit3sSm4pPV53H9SfxsCijh+1DGqCVp3Z0RdYUHakE7b0ccGBUY+wc1gDNK9tACOCPGxHovOIceq65gBN3o1CcZsnoKnuHe/fuwdfXN892c3NzxMfHqyImuV9++QXbt2/Hjh07UK1aNVy7dg3jx4+Ho6Mj/P39C/24U6ZMQUBAgPz3xMREFjxERFrmzWaBjuaG2DLYR+ubBRYliUSCBhWs0aCCNe5FJGHt6Yc4eO0ZAsNiERgWCw87EwzzdcfHNR2hr6vZ66GUfnZ7e3s8ePAgz/azZ8+iQoUKKgkq15dffik/u+Pl5YV+/fphwoQJmDt3rjwWAIiMjFS4X2RkpPy2/BgYGMDMzEzhh4iItMf50Bj0XHMB0UnpqGxnin0jG7PQUaPK9qZY2KMmzkxujqFN3WBioIv7kcmYuPs6fBecwNrToUh6lamx+JQudoYOHYpx48YhMDAQEokEz58/x/bt2zFx4kR8/vnnKg0uNTUVUqliiDo6OpDJchYxc3Nzg729PY4fPy6/PTExEYGBgWjYsKFKYyEiopLh939eYMCGy0hKz4KPmxV+GdGwVHVF1iQHcyN808ET575qgcltq8DG1AARia/w/R938c/TBI3FpfQw1ldffQWZTIaWLVsiNTUVvr6+MDAwwMSJEzFmzBiVBtepUyd89913cHZ2RrVq1RAcHIxFixZh0KBBAHJOoY0fPx5z5sxBpUqV5JeeOzo6onPnziqNhYiIir/N5x9h5m+32CxQw8yN9PB5M3cMauKKg8HPceZBDBq5W2ssnkL32cnIyMCDBw+QnJwMT09PmJiYqDo2JCUlYdq0adi/fz+ioqLg6OiI3r17Y/r06dDXz1mZVQiBGTNmYO3atYiPj0eTJk2wcuVKeHh4FPh5eOk5EVHJJoTAj0fvYcWJUADAZw2cMevj6tCRsoeONuNyEUpgsUNEVHJlZsswZd8N7Lma0yzwi9YeGN2CzQJLg4Iev5UexurSpUu+byCJRAJDQ0NUrFgRffr0QeXKlZV9aCIiIqX8t1ng91280MuHPXRIkdITlM3NzfH3338jKCgIEokEEokEwcHB+Pvvv5GVlYVdu3ahZs2aOHfunDriJSIiApDTLLDP62aBBro5zQJZ6FB+lD6zY29vjz59+mD58uXyK6VkMhnGjRsHU1NT7Ny5EyNGjMDkyZNx9uxZlQdMRET0JDYV/hsv4WF0CsyN9LBhQF14u1hpOiwqppSes2NjY4Nz587lmQB8//59NGrUCDExMbhx4waaNm2q8iaD6sI5O0REJcedF4nw33AJUWwWWOqpbW2srKws3L17N8/2u3fvIjs7GwBgaGjIiWFERKRyF0JfosfqC4his0BSgtLDWP369cPgwYPx9ddfo169egCAy5cv4/vvv0f//v0BAKdOnUK1atVUGykREZVqf9x4gfE7ryEjWwYfVyus618X5mX03n9HKvWULnYWL14MOzs7LFiwQL5Mg52dHSZMmIDJkycDAD766CO0bdtWtZESEVGp9WazwDbV7LC0V202C6QC+6A+O4mJiQBQ4ue5cM4OEVHx9N9mgX3rO+PbT9gskHKorc/Om1gYEBGRumS9bha4+3WzwIDWHhjDZoFUCIUqdvbs2YNffvkF4eHhyMjIULgtKChIJYEREVHplZqRhdE7gvH33Sg2C6QPpvTVWMuWLcPAgQNhZ2eH4OBg+Pj4wNraGg8fPkS7du3UESMREZUiuc0C/74bBQNdKdawWSB9IKWLnZUrV2Lt2rX46aefoK+vj0mTJuHYsWMYO3YsEhI0t3w7ERGVfE/jUvHp6vO49iQe5kZ62D6kPlp72mk6LCrhlC52wsPD0ahRIwCAkZERkpKSAORckv6///1PtdEREVGpcedFIrquPI+H0SlwNDfEnhENUdeVXZHpwyld7Njb2yM2NhYA4OzsjIsXLwIAwsLCwAXUiYioMN5sFuhhZ4K9Ixuhkh2bBZJqKF3stGjRAr/++isAYODAgZgwYQJat26Nnj17okuXLioPkIiItNsfN17Af8MlJKVnwcfVCruHN4KDuZGmwyItonSfHZlMBplMBl3dnAu5du7cifPnz6NSpUoYPnw49PX11RKoOqmrz44QAkIAUvaDICLK15YLjzDjVzYLpMIp6PFb6WInPDwcTk5OefocCCHw5MkTODuXvBnz6ip2tlx4hNP3Y7C4Z02YGrKlORFRLiEEFh69j+UnHgAA+tR3xmw2CyQlqW0hUDc3N0RHR+fZHhsbCzc3N2UfTmvFpWRg/uG7+OtOJLqsPI+H0cmaDomIqFjIypZh8t5/5IVOQGsPfNeZhQ6pj9LFjhAi3+6VycnJMDQ0VElQ2sDSWB87hjaAvZkhHkQl45MV53DyXpSmwyIi0qi0jGwM33oVv1x5CqkEmNvVC2NbVmJXZFKrAndQDggIAABIJBJMmzYNZcqUkd+WnZ2NwMBA1KpVS+UBlmQ1nSzw65jGGLktCFcex2HgpsuY1KYKRvhV4AebiEqduJQMDNp8GcHh8TDQleKn3rXxUTV7TYdFpUCBi53g4GAAOWd2bty4oTARWV9fHzVr1sTEiRNVH2EJZ2tqiB1DG2DGr7fwv0vhmH/kLm6/SMSCbjVgpM9JeERUOjyNS0X/DZfwMDoF5kZ6+Nm/LnvoUJFReoLywIEDsXTpUq1aBLSoVj3fdvExZv56C1kyAU8HM6zt743ylmXef0ciohLszotE+G+4hKikdDiYG2LLIB/20CGVUNvVWNqoqIodALgUFouR268iJjkDVsb6WNGnDhq6W6v1OYmINOXiw5cYuuUKkl5lwcPOBJsH+bCHDqmM2oqdlJQUzJs3D8ePH0dUVBRkMpnC7Q8fPixcxBpUlMUOADyPT8OwrVdw81kidKQSTO/oif4NXTiPh4i0yuEbLzBu1zVkZMlQz9US6/vXg3kZtuEg1Sno8bvAc3ZyDRkyBKdOnUK/fv3g4ODAA3QhOFoYYc+IRvhq7z84cO05Zvx6C7eeJ2B25+ow0OU8HiIq+bZeeITpr5sFfuRph2W92SyQNEfpMzsWFhb4/fff0bhxY3XFVOSK+sxOLiEE1p8Jw9zDdyATQG1nC6z+zBt2ZryEn4hKJjYLpKKktqaClpaWsLLiDHpVkEgkGOpbAZsH+cDcSA/B4fHo9NNZBIfHaTo0IiKl/bdZ4IRWbBZIxYPSxc7s2bMxffp0pKamqiOeUqlpJRv8OroxPOxMEJWUjp5rLuKXK080HRYRUYH9t1ng9128MK4VmwVS8aD0MFbt2rURGhoKIQRcXV2hp6c42SwoKEilARYFTQ1j/Vdyeha++OUa/rwVCQAY0MgV33SoCj0dpWtSIqIiE5eSgcGbLyOIzQKpiKltgnLnzp0/JC56BxMDXazq643lJx5g0bH72HT+Ee5GJGJlX29YGZe81eSJSPs9jUuF/4ZLCGWzQCrG2GcHxefMzpuO3orAhF3XkJKRjXIWRljb3xvVHM01HRYRkdzdiJxmgZGJOc0CNw/ygQebBVIRUtsEZQCIj4/H+vXrMWXKFMTGxgLIGb569uxZ4aKlPD6qZo8DoxrD1boMnsWnoduq8/jt+nNNh0VEBAAIfPgS3VdfQGRiOirZmmDv541Y6FCxpXSx888//8DDwwPz58/Hjz/+iPj4eADAvn37MGXKFFXHV6pVsjPFwVFN4Odhg1eZMoz5XzDmH7mLbFmpPxlHRBp0+MYL9NtwCUmvslDP1RJ7RjSCowW7IlPxpXSxExAQgAEDBiAkJASGhv/2g2nfvj1Onz6t0uAIMC+jhw0D6mGEnzsAYNXJUAzefBkJaZkajoyISqOtFx9j5I4gZGTJ0NrTDlsH12dXZCr2lC52Ll++jOHDh+fZXq5cOURERKgkKFKkI5Xgq3ZVsLRXLRjqSXHyXjQ6rziHB1FJmg6NiEqJnGaB9zDtwE0IAfT2ccaqvnXYFZlKBKWLHQMDAyQmJubZfv/+fdjY2KgkKMrfJ7XKYc+IRihnYYSwmBR0XnEef92O1HRYRKTlsrJl+GrvDfz0d06zwPGtKuH7LtWhy7YYVEIo/U79+OOP8e233yIzM2cYRSKRIDw8HJMnT0a3bt1UHiApql7OHL+Oboz6blZITs/C0K1X8NPxEMg4j4eI1CAtIxsjtl3FritPIJUA33WpjvGtPNgskEoUpYudhQsXIjk5Gba2tkhLS4Ofnx8qVqwIU1NTfPfdd+qIkf7D2sQA24bUh39DFwgBLDx2H6N2BCElPUvToRGRFolLyUDf9Rfx150oGOhKseozb/St76LpsIiUVug+O+fOncP169eRnJyMOnXqoFWrVqqOrcgUxz47BbXrcjimHbiFjGwZqtibYm2/unC2LqPpsIiohHsWn4b+PwciNDoFZoa6+HlAPdRjs0AqZgp6/GZTQZTsYgcArj6Ow4htVxGdlA5zIz2s6FMHTSqV1XRYRFRCsVkglRRqayo4duxYLFu2LM/25cuXY/z48co+HKmAt4slfhvdBDWdLJCQlon+GwKx4sQD3HqegKjEV8jKlmk6RCIqIdgskLSR0md2ypUrh19//RXe3t4K24OCgvDxxx/j6dOnKg2wKJT0Mzu5XmVmY9qBm9h9VfFvIJEA1sb6KGtiABtTA9iYGKDs6/9WsDFGiyq2nGxIRDhy8wXG7ryGjCwZ6rpYYr1/XViU4bp8VHypbSHQly9fwtw87xpNZmZmiImJUfbhSIUM9XSw4NMaqOlkgR2B4YhKSkdsSjpkAohJzkBMcgbuRuTtzbOkZy10rl1OAxETUXGx9eJjTD+Y00Ontacdfupdmz10SGsoXexUrFgRR44cwejRoxW2Hz58GBUqVFBZYFQ4EokEnzVwwWcNcq6YyJYJxKZkIDopHTHJ6YhOSkd0cjpiktJx+0Uizoe+xI9H76Gdlz0MdPnFRlTaCCGw+Nh9LHvdQ6e3jzNmf1KNPXRIqyhd7AQEBGD06NGIjo5GixYtAADHjx/HwoULsWTJElXHRx9IRyrJGboyNchzW1pGNpr9eAJP49KwIzAcAxu7aSBCItKUrGwZph64iZ2XnwAAxrWshPGtKnFYm7ROoa7GWrVqFb777js8f56zCrerqytmzpyJ/v37qzzAoqAtc3YKY0dgOL7efwPWxvo4Nak5TAyUrn+JqARKy8jGmP8F4687kZBKgNmdq7OHDpU4arkaKysrC1u2bEHXrl3x9OlTREZGIjExEQ8fPiyxhU5p16NueVQoa4yXKRlYd/qhpsMhoiIQn5qBz34OxF93IqHPZoFUCihV7Ojq6mLEiBF49eoVAMDGxgYmJiZqCYyKhq6OFBPbVAYArD/zEDHJ6RqOiIjU6Vl8Gj5dfQFXH8fBzFAX24fUR5tq9poOi0itlJ6B5uPjg+DgYHXEQhrSrro9apY3R0pGNpa/nqRIRNrnXkQSuq08jwdRybA3M8TuEY3YFZlKBaUnaIwcORJffPEFnj59Cm9vbxgbGyvcXqNGDZUFR0VDIpFgctsq6LM+ENsDH2NQYzcuOUGkZQIfvsTQLVeQ+CoLFW1NsGWQDxwtjDQdFlGRUHqCslSa92SQRCKBEAISiQTZ2dkqC66olOYJym/q93MgzoTEoHMtRyzpVVvT4RCRihy5GYGxO4PZLJC0jtqaCoaFhX1QYFR8TW5bBWdCzuLg9ecY5usOT8fSW/gRaYttr5sFygTQqqodlvdhs0AqfZQudlxcOGNfW1UvZ45ONR3x2/XnWPDnXWwa6KPpkIiokPI2C3TC7E+qs1kglUqFetdv3boVjRs3hqOjIx4/fgwAWLJkCQ4ePKjS4KjofdHaA7pSCU7ei8aF0JeaDoeICiErW4av99+QFzrjWlbC9128WOhQqaX0O3/VqlUICAhA+/btER8fL5+jY2FhoZYOys+ePcNnn30Ga2trGBkZwcvLC1euXJHfLoTA9OnT4eDgACMjI7Rq1QohISEqj6O0cC1rjN4+zgCAeUfuohA9J4lIg9IysjFiWxD+d+kJpBJgTufqmNDag12RqVRTutj56aefsG7dOnzzzTfQ0fl33Ldu3bq4ceOGSoOLi4tD48aNoaenh8OHD+P27dtYuHAhLC0t5fssWLAAy5Ytw+rVqxEYGAhjY2O0adNG3guIlDemZUUY6eng+pN4/HkrQtPhEFEB/bdZ4Mq+3vJ18ohKs0JNUK5dO++VOgYGBkhJSVFJULnmz58PJycnbNy4Ub7Nze3f9ZuEEFiyZAmmTp2KTz75BACwZcsW2NnZ4cCBA+jVq5dK4yktbE0NMaSpG376+wEW/HkPrara8fQ3UTH3PD4N/TdcwoOoZJgZ6mK9fz34uLGHDhFQiDM7bm5uuHbtWp7tR44cQdWqVVURk9yvv/6KunXronv37rC1tUXt2rWxbt06+e1hYWGIiIhAq1at5NvMzc1Rv359XLhw4a2Pm56ejsTERIUfUjTMtwIsy+jhYXQK9lx9qulwiOgd7kUkoet/mgWy0CH6l9LFTkBAAEaNGoVdu3ZBCIFLly7hu+++w5QpUzBp0iSVBvfw4UOsWrUKlSpVwp9//onPP/8cY8eOxebNmwEAERE5Qyx2dnYK97Ozs5Pflp+5c+fC3Nxc/uPk5KTSuLWBqaEeRjWvCABY8lcIXmWWvP5JRKXBpbBYdF99HhGJr1DR1gR7RzZCZXtTTYdFVKwoPYw1ZMgQGBkZYerUqUhNTUWfPn3g6OiIpUuXqnzYSCaToW7duvj+++8BALVr18bNmzexevVq+Pv7F/pxp0yZgoCAAPnviYmJLHjy8VkDF2w89wjP4tOw6fwjjPBz13RIRPSGP29FYMz/cpoFertY4mc2CyTKl9JndtLT09G5c2eEhIQgOTkZERERePr0KQYPHqzy4BwcHODp6amwrWrVqggPDwcA2NvnLF4XGRmpsE9kZKT8tvwYGBjAzMxM4YfyMtTTwYTWHgCAlSceID41Q8MREVGubRcf4/NtV5GRJUOrqnbYPqQ+Cx2ityhwsRMdHY127drBxMQEZmZmaNCgAV68eAFbW1u1Bde4cWPcu3dPYdv9+/fljQ3d3Nxgb2+P48ePy29PTExEYGAgGjZsqLa4SpMutcuhsp0pEl9lYeiWK0hJz9J0SESlmhACi47dx9QDOV2Re9VzwurP6rArMtE7FLjYmTx5Mq5du4Zvv/0WP/74I+Lj4zFkyBB1xoYJEybg4sWL+P777/HgwQPs2LEDa9euxahRowDkrMk1fvx4zJkzB7/++itu3LiB/v37w9HREZ07d1ZrbKWFjlSChT1qwtRQF5cfxWHgpstIzWDBQ6QJOc0Cb2LZ8ZxeYmNbVsLcrmwWSPQ+BV4I1MnJCevXr0ebNm0AACEhIahatSpSUlJgYGCgtgAPHTqEKVOmICQkBG5ubggICMDQoUPltwshMGPGDKxduxbx8fFo0qQJVq5cCQ8PjwI/BxcCfb9rT+LRb30gktKz0LCCNTYMqAcjff5LkqiovMrMxpj/BePY7UhIJMDsT6qzhw6VegU9fhe42NHR0cGzZ88U5sIYGxvj1q1bcHV1/eCANYnFTsEEhceh/8+XkJyehcYVrfGzfz2eOicqAvGpGRi8+QquPo6Dvq4Uy3rVQtvqDpoOi0jjCnr8Vurc55sdk3N/53ICpUcdZ0tsHlQPxvo6OPfgJYZuucJL0onU7Hl8GrqvvoCrj+NgZqiLbYPrs9AhUlKBz+xIpVKYm5srrK8SHx8PMzMzSKX/1kyxsbGqj1LNeGZHOZfCYjFg4yWkZmTDz8MGa/t7w0D3/Wd4hBC4+DAWa06HIjg8Hj98WgMfVXv7VXNEpd39yCT0//kSIhJfwd7MEJsH+bCHDtEbVD6MldvI730+pP+NprDYUd7Fhy8xYOMlvMqUoUUVW6z6rM5bC55smcDRWxFYfSoU158myLcb6elg7+eN4OnInBP91+VHsRi86TISX2Whoq0JNg/yQTkLI02HRVSsqLzY0WYsdgrn/IMYDNx0Gemv+3ys7FsH+rr/nuV7lZmN/cHPsPb0Q4TF5KybZqArRY+6TngYk4xzD16inIURDo5ujLIm6pvkTlTS/HkrAmP/F4z0LBnqOFtgw4B67KFDlA8WO0pgsVN4Z0NiMHhzTsHTppodlvepg9SMbGwPfIyN5x4hOikdAGBupIf+DV3g38gVZU0MkJCaic4rzyEsJgX1XC2xfUgDhUKJqLTaHvgY01730GlV1RY/9a7DKx+J3oLFjhJY7HyYU/ejMXTzFWRky1CzvDlCo1OQ/Lr5oKO5IQY3rYBe9ZxgbKC4OsmDqGR0WXkOSa+y0LOuE+Z181KYE0ZUmgghsOSvECx93UOnVz0nzOlcnT10iN6BxY4SWOx8uBN3ozB861VkZMsAAB52Jhju646PazlC7x1f1ifvRWHQpsuQCWB6R08MauJWVCETFRtZ2TJMO3gL/7uUsxTO2BYVMaG1B4t/ovdgsaMEFjuqcTYkBnuDnqJTTQc0r2xb4C/q9WceYs7vdyCVAJsG+sDXw0bNkRIVH/9tFvjtJ9XRj80CiQqExY4SWOxolhACk/b8g91Xn8LMUBcHRjVGBRsTTYdFpHbxqRkYsvkKrrBZIFGhFPT4rfvWW97h6dOn+PXXXxEeHo6MDMWVsBctWlSYh6RSTCKRYE6X6ngYk4Krj+MwZPMV7B/VGOZGepoOjUhtnsenwX/DJYREJcPUUBfr+9dF/QrWmg6LSCspXewcP34cH3/8MSpUqIC7d++ievXqePToEYQQqFOnjjpipFLAQFcHqz/zxifLz+JhTArG/C8YG/zrcnImaaX7kUnw33AJLxJymgVuGlQPVex5VplIXZQ+kkyZMgUTJ07EjRs3YGhoiL179+LJkyfw8/ND9+7d1REjlRI2pgZY518XRno6OH0/GnMP39V0SEQqd+VRLD5ddR4vEl7B3cYYe0c2YqFDpGZKFzt37txB//79AQC6urpIS0uDiYkJvv32W8yfP1/lAVLpUs3RHIt61AQA/Hw2DL9cfqLhiIhU589bEei7PhCJr7JQx9kCe0Y0YldkoiKgdLFjbGwsn6fj4OCA0NBQ+W0xMTGqi4xKrXZeDhjfqhIA4JsDNxAcHqfhiIg+3I7AcHy+7errjuO22D6kASyN2RWZqCgoXew0aNAAZ8+eBQC0b98eX3zxBb777jsMGjQIDRo0UHmAVDqNbVEJ7arbIzNb4Ku9N5D5un8PUUmT0yzwPr7efwMyAfSs64TVn3mzKzJREVJ6gvKiRYuQnJwMAJg1axaSk5Oxa9cuVKpUiVdikcpIpRJ838ULgWGxuBeZhHVnHmJks4qaDotIKdkygWkHb2JHYE6zwDEtKiKAzQKJihz77IB9doqzfUFPEfDLdRjoSnF0gi9crI01HRJRgbzKzMbY/wXjaG6zwI+roV9DV02HRaRVCnr8LtR1vfHx8Vi/fj2mTJmC2NhYAEBQUBCePXtWuGiJ3qJL7XJoXNEa6VkyTD1wE6zNqSSIT83AZ+sDcfR2JPR1pVjVtw4LHSINUrrY+eeff+Dh4YH58+fjxx9/RHx8PABg3759mDJliqrjo1JOIpFgTmcv6OtKcSYkBr9ef67pkIje6Xl8GrqvvoArj+NgaqiLLYN82BWZSMOULnYCAgIwYMAAhISEwNDQUL69ffv2OH36tEqDIwIAt7LGGNsiZ77O7EO3EZ+a8Z57EGlGSGQSuq06j5CoZNiZGWD3iIZowK7IRBqndLFz+fJlDB8+PM/2cuXKISIiQiVBEf3XMF93VLI1QUxyBuax2SAVQ1cexeLT1Rf+bRb4OZsFEhUXShc7BgYGSExMzLP9/v37sLHhatWkHvq6Unzf1QsAsPPyE1wKi9VwRET/Ovq6WWBCWiZqv24WWN6yjKbDIqLXlC52Pv74Y3z77bfIzMwEkDOnIjw8HJMnT0a3bt1UHiBRrnquVujt4wQA+Hr/DaRnZWs4IiLgf5fCMeJ1s8CWVWyxg80CiYodpYudhQsXIjk5Gba2tkhLS4Ofnx8qVqwIU1NTfPfdd+qIkUjuq7ZVUdZEHw+ikrH21ENNh0OlmBACS/8KwZR9Oc0Ce9QtjzX92CyQqDgqdJ+dc+fO4fr160hOTkadOnXQqlUrVcdWZNhnp2Q5eO0Zxu28Bn1dKY6Ma4oKNiaaDolKGTYLJCoeCnr8VqrYyczMhJGREa5du4bq1aurJNDigMVOySKEgP/Gyzh9PxqN3K2xfUh9HmSoyLBZIFHxoZamgnp6enB2dkZ2NudKkOZIJBLM+aQ6DPWkOB/6EvuC2MxSm4XFpKDR3OPYfP6RpkNBQmom+v38ulmgjhQr+7BZIFFJoPScnW+++QZff/21vHMykSY4W5fBuJYeAIA5v99GbAp772ir0/ej8TzhFX788x6S07M0FseLhDR0X3Melx+9bhY42AftvNgskKgkUHoh0OXLl+PBgwdwdHSEi4sLjI0V1yoKCgpSWXBE7zKkqRsOXnuGuxFJ+P6PO/ixe01Nh0RqEPe6iWRSehb2XHmCAY3dijyGkMgk+G+4hOcJr2BnZoDNg3zYQ4eoBFG62OncubMawiBSnp6OFN918cKnq89jz9Wn6FanPBq6s1uttolPzZT//8bzj9C/oSuk0qKbo3XlUSwGb76ChLRMVLAxxpZBPuyhQ1TCKF3szJgx4623cS4PFTVvF0v0re+MbRfD8c3+G/hjXFMY6vHSX22SkPZvsfP4ZSr+vhuFVp52RfLcx25HYvSOIKRnyVDb2QIb/Ouxhw5RCVSoVc//6/79+5g8eTLKly+viocjUsqktlVgY2qAhzEpWHUyVNPhkIrlDmM5mOesxbfhXFiRPO//LoVj+NYrbBZIpAUKXeykpqZi48aNaNq0KTw9PXHq1CkEBASoMjaiAjEz1MPMTtUAAKtOhuJBVLKGIyJVyh3GGuHnDh2pBOdDX+LOi7xL1qgKmwUSaR+li52LFy9iyJAhcHBwwKJFi3DhwgWcOHECFy9exJdffqmOGIneq72XPVpUsUVGtgxf77+BQvbKpGIodxirqoMZ2la3BwBsVNPZnWyZwNQDN7H4r/sAgNHNK2J+txrQ1VHJSXAi0pACf4IXLlyIatWq4dNPP4WlpSVOnz6NGzduQCKRwNqak0JJsyQSCWZ9XA1Gejq4FBaL3VeeajokUpHcYSyLMnoY9PpKrAPXniMmOV2lz/MqMxsjt1/F9sDwnGaBn1TDxDaV2bCSSAsUuNiZPHkyOnfujMePH+OHH35AzZq8zJeKFyerMghondN757s/7qj8YEhFTyYT8jM7FmX0UMfZAjWdLJCRJZMv1aAKCamZ6P/zJfx5K6dZ4Io+ddCfzQKJtEaBi53Zs2dj9+7dcHNzw+TJk3Hz5k11xkVUKAMbu8LTwQwJaZn47vc7mg6HPlDSqyzkjkiaG+lBIpFgUGNXAMDWi4+hipXvXySkoceaC7j0KBamBjnNAtuzWSCRVilwsTNlyhTcv38fW7duRUREBOrXr4+aNWtCCIG4uDh1xkhUYLo6Uszt6gWJBNgf/AxnQqI1HRJ9gNwhrDL6OjDQzZkg3N7LAXZmBohOSsfv/7z4oMcPiUxCt5XncS8yCbamBvhlREM0qMBheSJto/SsOz8/P2zevBkREREYOXIkvL294efnh0aNGmHRokXqiJFIKTWdLOD/eghi6oGbeJXJ/k8lVfzrISzLMv9e8q2nI5UPMW04F1boyehXH8fi09UX8DzhFSrYGGPfyEao6sCuyETaqNCXGJiammL48OEIDAxEcHAwfHx8MG/ePFXGRlRoX3zkAXszQzx+mYqf/g7RdDhUSPGvz+yYG+kpbO/t4wwDXSluPkvElcfKn1k+djsSfdYFIiEtE7WdLbB3RCN2RSbSYiq5ntLLywtLlizBs2dcfZqKB1NDPcz8OKf3zppTD3E/MknDEVFh5PbYsSijWOxYGeuja51yAIANZ5W7DH3nG80CW1SxxfYh9dkskEjLqbR5hJ6e3vt3Iioibavbo7WnHbJkIqdBnIy9d0qa3DM7bw5j5Rr4+jL0P29F4Els6nsfSwiBZcdD8NXrZoHdvXOaBZbRV3rVHCIqYdgpi7TarI+rwVhfB1cfx2Hn5SeaDoeUlDtnx7xM3n9IediZommlspAJYMuFR+98nGyZwLSDN7Ho2L/NAhd8WgN6bBZIVCrwk05azdHCCF98VBkAMPfwHUQlvdJwRKQM+TCWUf5njXObDO68/ATJ6Vn57vMqMxujtgdh28WcZoGzPmazQKLShsUOaT3/Rq7wKmeOpFdZmH2IvXdKkncNYwGAn4cNKpQ1RtKrLOy9mrdrdkJaTrPAI7ci5M0C/Ru5qjNkIiqGClXshIaGYurUqejduzeioqIAAIcPH8atW7dUGhyRKuhIJZjb1QtSCfDb9ec4eS9K0yFRAb1rGAsApFIJBrxuMrjxXJjCvKyIhFfosfrfZoGbB7FZIFFppXSxc+rUKXh5eSEwMBD79u1DcnLOCtPXr1/HjBkzVB4gkSpUL2cun9A69cBNpGWw905JEPeeYSwA6FanPEwNdfHoZSpOvC5kH0QloevKc/JmgbuGN0RDdzYLJCqtlC52vvrqK8yZMwfHjh2Dvv6/p5ZbtGiBixcvqjQ4IlUKaO0BR3NDPI1Lw5Lj9zUdDhVAQu4w1jsuDTc20EVvH2cAOU0Grz6ORbdV/zYL3Pt5I3g6slkgUWmmdLFz48YNdOnSJc92W1tbxMTEqCQoInUwNtDFt59UBwCsPxOGOy8SNRwRvU/uMNa7zuwAQP+GLpBKgHMPXsqbBdZyssCeEY3gZMVmgUSlndLFjoWFBV68yLseTXBwMMqVK6eSoIjUpZWnHdpWs0f269472ey9U2xlv7Hi+dvm7OQqb1kGbavbAwDSs2RoXtkGO4bWhxWbBRIRClHs9OrVC5MnT0ZERAQkEglkMhnOnTuHiRMnon///uqIkUilZn5cDSYGurj2JB47Ah9rOhx6i6RXmfIVzy2M3l+0jGpeEdbG+uhb3xlr+9dls0AiklO62Pn+++9RpUoVODk5ITk5GZ6envD19UWjRo0wdepUdcRIpFL25ob4sk1O750FR+4hMpG9d4qj3B47xvo60Nd9/1dVNUdzXJ3WGt918WKzQCJSoPQ3gr6+PtatW4eHDx/i0KFD2LZtG+7evYutW7dCR0dHHTESqdxnDVxQ08kCSelZmPUbWyYUR3GvJydbvKXHDhFRQRX6PK+TkxOcnJxUGQtRkdGRSjC3ixc6LT+LP25E4PidSLSsaqfpsOgN8snJ75mvQ0T0Pkqf2enWrRvmz5+fZ/uCBQvQvXt3lQRFVBQ8Hc0wpElO753pB28h5S3LDZBmJLxlxXMiImUpXeycPn0a7du3z7O9Xbt2OH36tEqCept58+ZBIpFg/Pjx8m2vXr3CqFGjYG1tDRMTE3Tr1g2RkZFqjYO0x7hWlVDOwgjP4tOw+Bh77xQn8mGsAkxOJiJ6F6WLneTkZIVmgrn09PSQmKi+viWXL1/GmjVrUKNGDYXtEyZMwG+//Ybdu3fj1KlTeP78Obp27aq2OEi7lNHXxZwuOb13NpwLw81nCRqOiHLF88wOEamI0sWOl5cXdu3alWf7zp074enpqZKg/is5ORl9+/bFunXrYGlpKd+ekJCAn3/+GYsWLUKLFi3g7e2NjRs34vz58+/s5pyeno7ExESFHyq9mle2RYcaDpAJ4Ov97L1TXCRwzg4RqYjSxc60adMwe/Zs+Pv7Y/Pmzdi8eTP69++P7777DtOmTVNHjBg1ahQ6dOiAVq1aKWy/evUqMjMzFbZXqVIFzs7OuHDhwlsfb+7cuTA3N5f/cKI1zejoCVNDXfzzNAFbLjzSdDiEf1c85zAWEX0opYudTp064cCBA3jw4AFGjhyJL774Ak+fPsVff/2Fzp07qzzAnTt3IigoCHPnzs1zW0REBPT19WFhYaGw3c7ODhEREW99zClTpiAhIUH+8+TJE1WHTSWMrZkhJretAgD48c97eB6fpuGIKI7DWESkIoW69LxDhw7o0KGDqmPJ48mTJxg3bhyOHTsGQ0NDlT2ugYEBDAwMVPZ4pB36+DhjX9BTBIXHY+avt7C2f11Nh1Sq/XvpOc/sENGHKdZtRq9evYqoqCjUqVMHurq60NXVxalTp7Bs2TLo6urCzs4OGRkZiI+PV7hfZGQk7O3tNRM0lVhSqQRzu9aArlSCo7cjcfwOr+rTpAR5U0Ge2SGiD6N0sZOdnY0ff/wRPj4+sLe3h5WVlcKPKrVs2RI3btzAtWvX5D9169ZF37595f+vp6eH48ePy+9z7949hIeHo2HDhiqNhUqHyvamGNjYFQCw5QLXzdKk3GEsSxY7RPSBlC52Zs2ahUWLFqFnz55ISEhAQEAAunbtCqlUipkzZ6o0OFNTU1SvXl3hx9jYGNbW1qhevTrMzc0xePBgBAQE4MSJE7h69SoGDhyIhg0bokGDBiqNhUqPvvVdAABnQqIRxXWzNCJbJpD46vWK55ygTEQfSOliZ/v27Vi3bh2++OIL6Orqonfv3li/fj2mT5/+zsu91WXx4sXo2LEjunXrBl9fX9jb22Pfvn1FHgdpD9eyxqjjbAGZAH69/lzT4ZRKb654bm7EMztE9GGULnYiIiLg5eUFADAxMUFCQk4Tto4dO+L3339XbXT5OHnyJJYsWSL/3dDQECtWrEBsbCxSUlKwb98+ztehD9a1TnkAwN6gZxqOpHSKU3LFcyKid1H6W6R8+fJ48eIFAMDd3R1Hjx4FkNPhmFc4kbboWMMB+jpS3HmRiDsv2HSyqMVzxXMiUiGli50uXbrIJwSPGTMG06ZNQ6VKldC/f38MGjRI5QESaYJFGX20qGILANgfzLM7RY0rnhORKindZ2fevHny/+/ZsydcXFxw/vx5VKpUCZ06dVJpcESa1KVOORy5FYEDwc8wuW0V6Eglmg6p1IjnZedEpEIFOrNTp04dxMXFAQC+/fZbpKamym9r0KABAgICWOiQ1mle2RYWZfQQlZSOcw9iNB1OqfLvIqAcxiKiD1egYufOnTtISUkBkHPpeXJyslqDIioO9HWl6FTDEQCwL+iphqMpXeTFDq/EIiIVKNAwVq1atTBw4EA0adIEQgj8+OOPMDExyXff6dOnqzRAIk3qWqcctl58jD9vRSI5PQsmBoVaYYWUxGEsIlKlAn1zb9q0CTNmzMChQ4cgkUhw+PBh6OrmvatEImGxQ1qllpMF3MoaIywmBUduRuBT7/KaDqlUyJ2gbMlhLCJSgQIVO5UrV8bOnTsBAFKpFMePH4etra1aAyMqDiQSCbrWLoeFx+5jf/BTFjtFJHcYiw0FiUgVlLr0PDMzE/7+/vL5O0SlQefa5QAA50Nf4kVCmoajKR3YZ4eIVEmpYkdPTw/79+9XVyxExZKTVRn4uFlBCOBAMJePKAr/DmPxzA4RfTilmwp+8sknOHDggBpCISq+utXJObuzL+gpRO6iTaQ2/156zmKHiD6c0peWVKpUCd9++y3OnTsHb29vGBsbK9w+duxYlQVHVFy083LA9IO3EBKVjFvPE1G9nLmmQ9JaXPGciFRN6WLn559/hoWFBa5evYqrV68q3CaRSFjskFYyM9RDa087HPrnBfYGPWWxo0aJaf+ueM4zO0SkCkoXO2FhYeqIg6jY61qnHA798wK/XX+Or9tXhZ4OV+NWh9z5OiYGuswxEakEv0mICqhpJRuUNdFHTHIGzoREazocrRX3+kosXnZORKqi9Jmd961svmHDhkIHQ1Sc6elI0ammIzaee4R9Qc/QooqdpkPSSgmvJydbGrPYISLVULrYyV0QNFdmZiZu3ryJ+Ph4tGjRQmWBERVH3eqUx8Zzj3D0diQS0jJ59kEN4tNe99jh5GQiUhGli538+uzIZDJ8/vnncHd3V0lQRMVVNUczVLI1QUhUMg7feIFePs6aDknrxKW8vhKLk5OJSEVUMmdHKpUiICAAixcvVsXDERVbEokEXevkLBmxL/iZhqPRTmwoSESqprIJyqGhocjKylLVwxEVW51rO0IiAS6FxeJJbKqmw9E6CakcxiIi1VJ6GCsgIEDhdyEEXrx4gd9//x3+/v4qC4youHIwN0Ijd2uce/ASB4KfYUzLSpoOSavEsXsyEamY0sVOcHCwwu9SqRQ2NjZYuHDhe6/UItIWXWuXx7kHL7Ev+BlGt6gIiUSi6ZC0Ru4wFhcBJSJVUbrYOXHihDriICpR2la3x9QDNxEWk4JrT+JR29lS0yFpjX+HsXhmh4hU44Pn7Jw6dQp//PFHnkvSibSZsYEu2la3BwCsOhmq4Wi0y79ndljsEJFqFLjYmT9/PqZNmyb/XQiBtm3bonnz5ujYsSOqVq2KW7duqSVIouLo82bu0JFKcPR2JE7ei9J0OFojLuX1mR0OYxGRihS42Nm1axeqV68u/33Pnj04ffo0zpw5g5iYGNStWxezZs1SS5BExZGHnSkGNnIFAMz89RbSs7I1G5AWyFnxPOeqTp7ZISJVKXCxExYWhho1ash//+OPP/Dpp5+icePGsLKywtSpU3HhwgW1BElUXI1rVQm2pgZ49DIV604/1HQ4JV7i6yEsgGtjEZHqFLjYycrKgoGBgfz3CxcuoFGjRvLfHR0dERMTo9roiIo5U0M9fNOhKgBg+YkHeBrHvjsfIncRUFOueE5EKlTgbxN3d3ecPn0aABAeHo779+/D19dXfvvTp09hbW2t+giJirmPazqivpsVXmXKMPvQbU2HU6LlTk7mUhFEpEoFLnZGjRqF0aNHY/DgwWjXrh0aNmwIT09P+e1///03ateurZYgiYoziUSC2Z2rQ0cqwZ+3OFn5QySwoSARqUGBi52hQ4di2bJliI2Nha+vL/bu3atw+/Pnz9lUkEotTlZWjdxhLEteiUVEKqRUU8FBgwa9taBZuXKlSgIiKqnGtaqEX68/l09WHt2Cy0goK/71mR1OTiYiVeIMQCIV4WTlD8eGgkSkDix2iFSIk5U/TDxXPCciNWCxQ6RC/52sfIKTlZUSzwnKRKQGLHaIVOzNycqzOFlZKVzxnIjUQeliZ9CgQUhKSsqzPSUlhVdjEb3GzsqFE88Vz4lIDZQudjZv3oy0tLQ829PS0rBlyxaVBEVU0nGycuHkDmNZGrPYISLVKXCxk5iYiISEBAghkJSUhMTERPlPXFwc/vjjD9ja2qozVqIShZOVlZd7ZsecE5SJSIUK3GfHwsICEokEEokEHh4eeW6XSCRc9ZzoDbmTldstPSOfrNy8Mv9B8DZZ2TKueE5EalHgYufEiRMQQqBFixbYu3cvrKys5Lfp6+vDxcUFjo6OagmSqKTysDPFoMauWHcmDLN+vYVGE6xhoKuj6bCKpdxCB+CcHSJSrQIXO35+fgCAsLAwODs7QyKRqC0oIm0yrpUHDl5jZ+X3iX9jxXNdrnhORCqk9DeKi4sLzp49i88++wyNGjXCs2fPAABbt27F2bNnVR4gUUlnYqCrMFn5SSwnK+cnLpUrnhOReihd7Ozduxdt2rSBkZERgoKCkJ6eDgBISEjA999/r/IAibQBJyu/X0IaFwElIvVQutiZM2cOVq9ejXXr1kFP799/gTVu3BhBQUEqDY5IW7zZWfnobXZWzg+7JxORuihd7Ny7dw++vr55tpubmyM+Pl4VMRFppdzJygAw89dbeJXJzspviuOK50SkJkoXO/b29njw4EGe7WfPnkWFChVUEhSRthrXygO2pgZ4zM7KeSSkchiLiNRD6WJn6NChGDduHAIDAyGRSPD8+XNs374dEydOxOeff66OGIm0xpuTlVec5GTlN/27LhbP7BCRahX40vNcX331FWQyGVq2bInU1FT4+vrCwMAAEydOxJgxY9QRI5FW+bimI/53KRwXH8Zi9qHbWNu/rqZDKhY4jEVE6lLgMzthYWEAciZafvPNN4iNjcXNmzdx8eJFREdHY/bs2WoLkkibSCQSfPtJdehysrKCeA5jEZGaFLjYcXd3h5ubGwYNGoRt27YhOjoanp6e8PHxgYmJiTpjJNI6HnamGMjJygoSOIxFRGpS4GLn77//hr+/Px4+fIihQ4fC2dkZlSpVwvDhw7Fz505ERkaqM04irTOulQfszDhZOVfc6zM7LHaISNUKXOw0a9YMM2fOxMmTJxEXF4djx46hd+/euHPnDgYMGABHR0dUq1ZNnbESaRUTA1183Z6TlXP922eHw1hEpFqFWoDG0NAQLVq0wNSpUzFr1iyMHTsWJiYmuHv3rqrjI9JqH9d0RIMK7KyclS1DUu6K55ygTEQqplSxk5GRgdOnT2PWrFlo3rw5LCwsMGLECMTFxWH58uXyScyqMnfuXNSrVw+mpqawtbVF586dce/ePYV9Xr16hVGjRsHa2homJibo1q0bh9SoxOBk5RxvrnjOq7GISNUKXOy0aNEClpaWGDlyJKKiojB8+HCEhobi3r17WLduHfr16wdnZ2eVBnfq1CmMGjUKFy9exLFjx5CZmYmPPvoIKSkp8n0mTJiA3377Dbt378apU6fw/PlzdO3aVaVxEKkTJyv/O1/H1JArnhOR6kmEEKIgO+rp6cHBwQGdO3dGs2bN4OfnB2tra3XHpyA6Ohq2trY4deoUfH19kZCQABsbG+zYsQOffvopAODu3buoWrUqLly4gAYNGhTocRMTE2Fubo6EhASYmZmp8yUQ5Ss5PQstF55EZGI6RjZzx6S2VTQdUpG6+jgO3Vadh5OVEc5MaqHpcIiohCjo8bvA/4SKj4/H2rVrUaZMGcyfPx+Ojo7w8vLC6NGjsWfPHkRHR6sk8HdJSEgAAFhZWQEArl69iszMTLRq1Uq+T5UqVeDs7IwLFy689XHS09ORmJio8EOkSSYGupjRKWeC/8qToThZyoazclc8tzDi5GQiUr0CFzvGxsZo27Yt5s2bh8DAQMTExGDBggUoU6YMFixYgPLly6N69epqC1Qmk2H8+PFo3Lix/HkiIiKgr68PCwsLhX3t7OwQERHx1seaO3cuzM3N5T9OTk5qi5uooNp7OaBv/Zyh4Am7ruF5fJqGIyo6cSnssUNE6lPowXFjY2NYWVnBysoKlpaW0NXVxZ07d1QZm4JRo0bh5s2b2Llz5wc/1pQpU5CQkCD/efLkiQoiJPpw0zp6wqucOeJSMzFqRxAysmSaDqlI/LsuFs/sEJHqFbjYkclkuHTpEhYsWIB27drBwsICjRo1wsqVK2Fvb48VK1bg4UP1NEYbPXo0Dh06hBMnTqB8+fLy7fb29sjIyEB8fLzC/pGRkbC3t3/r4xkYGMDMzEzhh6g4MNTTwcq+dWBmqIvg8HjMO1w62jnkrnjOy86JSB0KvBCohYUFUlJSYG9vj+bNm2Px4sVo1qwZ3N3d1RacEAJjxozB/v37cfLkSbi5uSnc7u3tDT09PRw/fhzdunUDANy7dw/h4eFo2LCh2uIiUicnqzJY2KMWhm65gg3nwlDP1RLtvBw0HZZa5S4CaslhLCJSgwIXOz/88AOaN28ODw8PdcajYNSoUdixYwcOHjwIU1NT+Twcc3NzGBkZwdzcHIMHD0ZAQACsrKxgZmaGMWPGoGHDhgW+EouoOGrtaYfhvhWw5vRDfLnnH1RxMINbWWNNh6U2ucNY5hzGIiI1KPAw1vDhw4u00AGAVatWISEhAc2aNYODg4P8Z9euXfJ9Fi9ejI4dO6Jbt27w9fWFvb099u3bV6RxEqnDxDaVUc/VEsnpWfh821Wt7r8Tz2EsIlKjYt29SwiR78+AAQPk+xgaGmLFihWIjY1FSkoK9u3b9875OkQlhZ6OFD/1rgNrY33cjUjCjIO3NB2S2uSui2VpzGKHiFSvWBc7RKWdvbkhlvaqDYkE2HXlCfZcfarpkNQi/nWfHXP22SEiNWCxQ1TMNalUFuNb5gwhTz1wA3cjtK8J5r8rnvPMDhGpHosdohJgTIuKaFqpLF5lyjByexCS07Pef6cSgiueE5G6sdghKgGkUgmW9KwFB3NDPIxOwVd7/0EBl7Ur9hJeX4kFcMVzIlIPFjtEJYS1iQGW96kDXakEh/55ga0XH2s6JJXIveycK54Tkbrwm4WoBPF2scRX7XJWRJ996DauP4nXbEAqIL/snPN1iEhNWOwQlTCDm7ihbTV7ZGYLjNweJC8WSir5ZedsKEhEasJih6iEkUgkWNC9Blysy+BZfBq++OU6ZLKSO38nt9jhfB0iUhcWO0QlkJmhHlb2rQN9XSmO343C6tOhmg6p0OLkw1g8s0NE6sFih6iEquZojlkfVwMA/PjnPVx8+FLDERVO7tVYXASUiNSFxQ5RCdarnhO61i4HmQDG/C8YUUmvNB2S0uQNBTmMRURqwmKHqASTSCSY06U6POxMEJ2UjnH/u4bsEjZ/J3cYiyueE5G6sNghKuHK6OtiZV9vlNHXwYWHL7H42H1Nh6QUDmMRkbqx2CHSAhVtTTCvWw0AwPITD3DiXpSGIyo4rotFROrGYodIS3xc0xH9GrgAACbsuoZn8Wkajqhg5MNYXPGciNSExQ6RFpnasSpqlDdHfGomRm0PQkaWTNMhvVdCKoexiEi9WOwQaREDXR2s6FMHZoa6uPYkHnMP39F0SO+UmS1D0usV3Nlnh4jUhcUOkZZxsiqDRT1qAQA2nnuEeYfvFttL0t9c8dzMUFeDkRCRNmOxQ6SFWnna4fNm7gCA1adC0WTeCXy5+zruRiRqODJFuZOTzbjiORGpEb9diLTUpDaVsbJvHdRxtkBGtgy7rz5F2yVn0O/nQJy4F1Us1tNKSONSEUSkfjxvTKSlJBIJ2ns5oL2XA4LC4/Dz2TAcvvECZ0JicCYkBhVtTTC4iRu61C4HQz0djcTIy86JqCiw2CEqBeo4W6JOH0s8iU3F5vOPsPPyEzyISsaUfTfww5/38FkDF/Rr4AIbU4MijStOXuzwzA4RqQ+HsYhKESerMpja0RMXprTA1A5VUc7CCLEpGVh2PASN5/2NSXuu415EUpHFE5+74jnXxSIiNeKZHaJSyNRQD0OaVsCARq44ejsS6888RFB4PH658hS/XHmKppXKYnATN/h52EAikagtjtyrsTiMRUTqxGKHqBTT1ZHK5/VcfRyHDWfDcPjmv/N6KtmaYJAa5/Xkdk/mMBYRqROLHSICAHi7WMLbRXFeT4ia5/XIJyhzGIuI1IhzdohIQVHO6+EwFhEVBZ7ZIaJ8vTmv589bkVh/9iGCVTyvJ3cYy5LDWESkRix2iOiddHWk6FDDAR1qvH1ez+AmbuhciHk9ucNY5jyzQ0RqxGKHiArszXk9m84/wq7X83q+ej2vp6+S83oSOGeHiIoA5+wQkdKcrMpgWkdPnH9jXs9LJef1vLniOYexiEidWOwQUaGZvZ7Xc+rLZljRpw5qOeWsw/XLlados+Q0+v0ciFP3oyFE3nW4FFY855kdIlIjDmMR0Qf777yen88+xJGbEe+c1/Pmiuc6UvU1LiQiYrFDRCqVM6/HG09iU7Hx3CPsuhyuMK/nswYu+KyBi3ypCEtjDmERkXpJRH7nl0uZxMREmJubIyEhAWZmZpoOh0irJL7KxC+Xn2DjuUd4Fp8GANDXlaJGOXNceRyHmuXNcXB0Ew1HSUQlUUGP35yzQ0Rq9ea8nuV9aufM68mS4crjOACAOScnE5GacRiLiIqEro4UHWs4omMNR4V5PQ0rWGs6NCLScix2iKjI5c7rycqWQVeHJ5iJSL34LUNEGsNCh4iKAr9piIiISKux2CEiIiKtxmKHiIiItBqLHSIiItJqLHaIiIhIq7HYISIiIq3GYoeIiIi0GosdIiIi0mosdoiIiEirsdghIiIircZih4iIiLQaix0iIiLSaix2iIiISKux2CEiIiKtxmKHiIiItJrWFDsrVqyAq6srDA0NUb9+fVy6dEnTIREREVExoBXFzq5duxAQEIAZM2YgKCgINWvWRJs2bRAVFaXp0IiIiEjDtKLYWbRoEYYOHYqBAwfC09MTq1evRpkyZbBhwwZNh0ZEREQapqvpAD5URkYGrl69iilTpsi3SaVStGrVChcuXMj3Punp6UhPT5f/npCQAABITExUb7BERESkMrnHbSHEO/cr8cVOTEwMsrOzYWdnp7Ddzs4Od+/ezfc+c+fOxaxZs/Jsd3JyUkuMREREpD5JSUkwNzd/6+0lvtgpjClTpiAgIED+u0wmQ2xsLKytrSGRSAr1mImJiXBycsKTJ09gZmamqlC1DvOkHOZLOcxX4TBvymG+lKeunAkhkJSUBEdHx3fuV+KLnbJly0JHRweRkZEK2yMjI2Fvb5/vfQwMDGBgYKCwzcLCQiXxmJmZ8c1fAMyTcpgv5TBfhcO8KYf5Up46cvauMzq5SvwEZX19fXh7e+P48ePybTKZDMePH0fDhg01GBkREREVByX+zA4ABAQEwN/fH3Xr1oWPjw+WLFmClJQUDBw4UNOhERERkYZpRbHTs2dPREdHY/r06YiIiECtWrVw5MiRPJOW1cnAwAAzZszIMzxGipgn5TBfymG+Cod5Uw7zpTxN50wi3ne9FhEREVEJVuLn7BARERG9C4sdIiIi0mosdoiIiEirsdghIiIircZih4iIiLQaix0iKlGSk5M1HUKJw4tuqbRjsfMeMpkMAJCdna3hSIq32NhYREZGIiMjA8C/eaO3Cw0NxcyZM/HgwQNNh1IiPH78GG3atMHkyZMB8D1WUHFxcQoFIgufd8vKygLA91dBlZRjJIuddwgICMBnn30GANDR0dFwNMWTEAJjx45Fw4YN8fHHH6Ndu3aIj4+HVCrll+pbCCHw+eefo1KlSnjx4gXKly+v6ZCKNSEEhg8fjooVK+LixYs4deoUZDIZpFJ+fb3PmDFjUK9ePXTq1An9+vXDixcvCr3YcWkwbtw4dOjQAQD4/iqAknSM5F8zH8HBwWjdujW2bduGXbt24c8//wRQ/CvXovb777/D09MTV65cwfLlyzFs2DBERERgzJgxAMAv1Xz873//Q9myZXHp0iVcunQJa9asgaGhIQD+izs/ixYtgoWFBa5du4agoCB8//330NPTy7PwLylKTk5Gp06dEBwcjA0bNqBfv34ICwtDhw4dcPPmTU2HV+zcuXMHHTp0wMGDB3Hs2DFs374dAM/uvE1JPEay2MnH5cuXUa5cOWzatAl9+vTBxIkTAeRUrjwg/evkyZPo2LEjTp48idatW2Pw4MFo3rw5ypQpo+nQiq3NmzfDzMwMhw4dQt26dXHz5k0cPXoUDx8+RFpaGgAWPblCQkJw8OBBLF26FIGBgfDy8oKXlxeuX78u/1JlrvJ37do1PHz4ECtWrICvry8GDx6MX375BTdv3sSyZcvw7NkzTYdYrNy5cwcODg7YuHEjxo0bh4kTJyIzM5Nnd96iRB4jBeUREREh/vnnHyGEECdOnBAODg5i0aJFQgghsrKyNBlasRIVFSXCwsLkv0dERIh69eqJOXPmiPPnz2susGLs+vXrokKFCmLq1KmiW7duwtXVVVSvXl04ODiIPn36aDq8YiU9PV3IZDL57zKZTFy/fl24u7uLLVu2aDCy4m/fvn3C2NhYYdu1a9eEnZ2dcHd3F9u2bdNQZMVLdna2EEKIly9fitu3bwshhAgLCxOOjo7iq6++UtiH/lUSj5GlvmydO3cuJkyYgDVr1sgn19rZ2cHLywsAUKtWLfj7+2P+/PlISkqCjo5OqTy1mV+ebGxs4OrqCgD4+eefUb58eejo6OCvv/5Cp06dMGnSJPnZitIov5zVqFED7du3x4IFC6Cvr4/du3dj27ZtWLx4MQ4cOIA5c+YAKJ1nLP6bL319fUgkEvnnTSKRwMbGBunp6UhPTwdQOvP0X/m9z8qVKwdHR0dMnz5dvt/atWvRp08fGBoa4vDhwwBKZ/727duHxMREAP/Oy7GyskLVqlUBAE5OTpgyZQoWLVqE8PDwUj//UGuOkZqttTTn7t27wtPTU3h5eYmePXsKS0tL0axZM3Hx4kUhhFD4F2VwcLCoXr26GDZsmBCidFX678tTrq1bt4rjx4/L8/brr78KXV1d+b+WSpO35ezs2bNCCCESEhLE119/LR4+fKhwvx9++EFYWFiIzMxMTYStMQV9j+V+7po0aSL8/f2FEIqf09Imv7z5+vqK4OBgkZ2dLZYuXSokEolo1KiRMDMzExUrVhSJiYli69atwtLSUtPhF7kTJ06IypUrC4lEItasWfPOfaOjo0XdunVF586diyi64kfbjpGltthZuHChaNiwofzA8uLFC1GzZk3Ro0cP8eDBAyGEkN/26tUrsXz5cmFqaipu3bolhBDi5MmTIjY2VjPBF6GC5EmIvAedR48eCX19fbFv374ijbc4eFfO7t27J4TIKXj+a8eOHcLW1lZ+eri0KMh7LPfLMz09XQwaNEi0b99eJCUlaSzm4uBteevevbu8kD558qRYsWKFOHTokPx+K1asEN7e3iImJkYjcWvC7du3Rc+ePcWoUaPEsGHDhLOzs3j+/Pk77/Pbb78JiUQiTp06JYQQ4s8//5R/fksDbTtGlsphrKysLNy6dQu2trbyy+Xs7e3xzTffIDw8HD///DMAQFdXF0IIGBgYoH379mjSpAn69u2LJk2aoH379oiKitLky1C7guYJyHvl1YEDB9CwYUO0aNGiSGPWtPflbNOmTQAAMzOzPPe9cOECGjRoID89XBoU9D0mlUohk8mgr6+PsmXL4sWLFzAxMSm1wwvvy9vatWsBAH5+fhg5cqT8curs7GycO3cONWrUgLW1tcbiL2pWVlZo3bo1Ro0ahR9//BHZ2dlYuHDhO+/TsmVL9OzZE/7+/mjQoAE6d+6M+Pj4oglYw7TxGFkqix1dXV2kp6cjLS0NMplMfmVH9+7d4e3tjcDAQAQHBwP4d0w7KysLsbGxuH79OqpUqYKIiAhUrlxZY6+hKCiTJwB48uQJwsLCMGbMGMybNw+9evWCubl5qTogKZuz8PBwPHr0CKNHj8aBAwfQv39/AKVnLoUy+cqdB9CyZUtcv34doaGhpba9wbvyVrduXVy6dEnhfRYSEoLQ0FCMGjUKZ8+eRb9+/QCUnveZnZ0dBg4ciKpVq8LU1BSzZ8/G8uXLcf369bfe59mzZ3j58iUeP34MLy8vREZGwsfHpwij1hytPEZq7qSSZuTOFD9x4oSQSqUiODhYCPHv6biTJ0+KihUril9++UV+n8uXLwsPDw9Rq1Yt+Sk6badsnkJCQsSUKVOEs7OzaNSokbh+/bpG4tYkZXN2//598cUXXwh7e3vRsGHDUjd8VZjPohBC7NmzRwwePFjExMSUyjk7hcnbypUrhYeHh6hfv36pe5+96c33S/369cXHH3+c7xy5u3fvinr16olq1aqJmzdvFmWIGqetx0itLHbeNcEz97a0tDTh5+cnWrVqJYRQ/BC4u7uLb7/9Vv57TEyMfHKpNlFFnmbNmiXf79y5c/LxbW2lypylpqaKEydOiOPHj6sxYs1S5Wcx90u4NBQ4qv4Oe/nypbh8+bKaotW8guQrV26eTp8+LaRSqfj111+FEDnvr+joaCGEEPHx8eLatWtqilbz/jvf7c33jrYeI7VqGCsjIwOTJk3CsGHDEBAQgIcPH8pvy13vRFdXF9nZ2UhISMCsWbNw6tQprF69Wn4qLi4uDsbGxrCysgKQc4rO2toajRs3LvoXpCaqzFPuuL+hoSEaNWoEX1/fon9BRUAdOTMyMkKzZs20cl6TOj6LuXMHtHnoSh15A3LmrNStW7doX0wRKGi+srKy5F23c98/TZs2Re/evTFr1iwcP34cHTp0wNKlS5Geng5zc3PUrFmz6F+QmmVkZGDMmDHo3Lkzunbtil27dkEIAYlEgszMTABafIzUWJmlYr/88otwdHQUzZs3F9OmTROOjo6idevW4ty5cwr7LV26VOjr64tNmzYJIYSYM2eOsLW1FUOGDBGnT58WEyZMEG5ubuLOnTuaeBlqxzwpjzlTDvNVOMybcpTJl4GBgdi4cWOes4Lnz58XEolESCQS0aZNm2J19ZCqbdmyRTg4OIhmzZqJLVu2iFatWomGDRuKw4cPK+ynre8vrSh2goODRbt27cTcuXPl28LDw4Wbm5vYsWOHECLntGTfvn2Fo6Oj2Lx5s8KbftmyZaJp06bCy8tL1KxZUwQGBhb5aygKzJPymDPlMF+Fw7wpR9l8bdmyRSFfWVlZYvPmzUJPT0/Ur19fBAUFFflrKEr37t0Tn376qVi8eLF826NHj4SdnZ04duyYECInX3369NHa95dWFDuBgYHiiy++EM+ePRNCCJGRkSGEEKJOnTpi6tSpQoic8cdLly4p9Dd5s/FRdnZ2niZv2oZ5Uh5zphzmq3CYN+UUNl+5UlJSxJIlS97bXFBbxMbGisDAQBEXFyffFhQUJD766CNx4cIF+TydwMBArX1/lchiZ/fu3eLYsWPyN3p+4uPjReXKlfOcoitNmCflMWfKYb4Kh3lTDvOlnNx8va1x4qhRo4Surq6oVauWKFu2rGjXrp04c+aMEKL4rm31oUpUsbNlyxZha2srfHx8hI2NjWjcuLG8Q69MJlOoQh8/fiwqVaqk0OW3tGCelMecKYf5KhzmTTnMl3Lela83c9WrVy9x5MgRkZycLM6dOyd69OghGjZsqKmwi0SJKHYyMzPFkiVLRNWqVcX69etFenq6OHfunOjfv79o166dePXqlXzf3HHGTZs2iYoVK4rU1FT5bS9fvlTYR9swT8pjzpTDfBUO86Yc5ks5Bc1X7nDVf/MxdepUUbt27XeeOSvpSsSl5ykpKYiOjoa/vz8GDhwIfX19NGrUCJ6enkhMTJRfYgj8e1nhwYMH0bFjRxgZGeHatWv46KOPMHv2bPlldtqIeVIec6Yc5qtwmDflMF/KKWi+cpd3eDMf2dnZCA0Nhbe3NxwdHTX1EtSu2BY7ISEh8uv6zc3N8emnn2LixInyNXIAwMnJCSkpKdDT01O4b0pKChISElC/fn2MHDkSdevWha2tLRYsWKB1b3rmSXnMmXKYr8Jh3pTDfCmnsPnKzUdaWhqePXuGESNGICgoCH379gWgxUuIaOBs0jvt2rVLuLq6isqVKwsfHx+xfv16hdvfHHfs06ePGDBggBBCsUvmtWvX5L0TGjRoIG7fvl00wRch5kl5zJlymK/CYd6Uw3wpp7D5enPi8d69e8XYsWOFnZ2daNasmQgJCSma4DWoWBU7R48eFa6urmLFihXiyJEjIiAgQOjp6Ym1a9eKtLQ0IUTOWKNMJhNpaWmiRo0aYuvWrXke5/Tp06JZs2by/gHahnlSHnOmHOarcJg35TBfylFVvm7duiV+/PFH8ddffxX1S9CYYlHs5E6WmjVrlvD29pb3TBBCiJEjR4q6devKZ5TnevbsmXB1dRX3798XQuQsqjh+/PiiC1oDmCflMWfKYb4Kh3lTDvOlHObrwxWLOTu5Y4i3b9+Gu7s79PT05Ot0zJkzB4aGhjh48CAiIiLk9/nrr7/g5OQEBwcHjBs3Dp6enggPD0dmZqZ8vFLbME/KY86Uw3wVDvOmHOZLOarOl9DWeTnvookK6+jRo2LMmDFi8eLFCm2n165dK0xNTeVji7nV69q1a4WHh4c4ceKEECKnyu3evbuwtLQU1tbWolq1alq5oi/zpDzmTDnMV+Ewb8phvpTDfKlekRY7z58/Fx07dhS2traib9++wsvLS5ibm8v/mPfu3RPlypUT06ZNE0IIkZ6eLr+vvb29fF2PlJQU0bFjR1G+fHmxc+fOonwJRYJ5Uh5zphzmq3CYN+UwX8phvtSnyIqdlJQU4e/vL3r27KmwvoaPj498tnhiYqKYM2eOMDIyEuHh4UKIf8cq/fz8xJAhQ+T3u3LlSlGFXqSYJ+UxZ8phvgqHeVMO86Uc5ku9imzOTpkyZWBgYIABAwbAzc1N3uSoffv2uHPnDoQQMDU1RZ8+fVCnTh306NEDjx8/hkQiQXh4OKKiotC5c2f543l7exdV6EWKeVIec6Yc5qtwmDflMF/KYb7USyJE0c1UyszMlDc3kslkkEql6Nu3L4yNjbF27Vr5fs+ePUOzZs2QlZWFunXr4vz586hSpQp27NgBOzu7ogpXY5gn5TFnymG+Cod5Uw7zpRzmS32KtNjJT5MmTTB06FD4+/vLZ9RLpVI8ePAAV69eRWBgIGrWrAl/f39NhqlxzJPymDPlMF+Fw7wph/lSDvOlIhoaPhNCCBEaGirs7OwUxhbfnHBFOZgn5TFnymG+Cod5Uw7zpRzmS3U00mdHvD6ZdPbsWZiYmMjHFmfNmoVx48YhKipKE2EVO8yT8pgz5TBfhcO8KYf5Ug7zpXq6mnjS3AZJly5dQrdu3XDs2DEMGzYMqamp2Lp1K2xtbTURVrHDPCmPOVMO81U4zJtymC/lMF9qoKlTSmlpaaJixYpCIpEIAwMDMW/ePE2FUqwxT8pjzpTDfBUO86Yc5ks5zJdqaXSCcuvWrVGpUiUsWrQIhoaGmgqj2GOelMecKYf5KhzmTTnMl3KYL9XRaLGTnZ0NHR0dTT19icE8KY85Uw7zVTjMm3KYL+UwX6qj8UvPiYiIiNSpWKx6TkRERKQuLHaIiIhIq7HYISIiIq3GYoeIiIi0GosdIiIi0mosdoiIiEirsdghohKtWbNmGD9+vKbDIKJijMUOEZUaJ0+ehEQiQXx8vKZDIaIixGKHiIiItBqLHSIqMVJSUtC/f3+YmJjAwcEBCxcuVLh969atqFu3LkxNTWFvb48+ffogKioKAPDo0SM0b94cAGBpaQmJRIIBAwYAAGQyGebOnQs3NzcYGRmhZs2a2LNnT5G+NiJSHxY7RFRifPnllzh16hQOHjyIo0eP4uTJkwgKCpLfnpmZidmzZ+P69es4cOAAHj16JC9onJycsHfvXgDAvXv38OLFCyxduhQAMHfuXGzZsgWrV6/GrVu3MGHCBHz22Wc4depUkb9GIlI9ro1FRCVCcnIyrK2tsW3bNnTv3h0AEBsbi/Lly2PYsGFYsmRJnvtcuXIF9erVQ1JSEkxMTHDy5Ek0b94ccXFxsLCwAACkp6fDysoKf/31Fxo2bCi/75AhQ5CamoodO3YUxcsjIjXS1XQAREQFERoaioyMDNSvX1++zcrKCpUrV5b/fvXqVcycORPXr19HXFwcZDIZACA8PByenp75Pu6DBw+QmpqK1q1bK2zPyMhA7dq11fBKiKiosdghIq2QkpKCNm3aoE2bNti+fTtsbGwQHh6ONm3aICMj4633S05OBgD8/vvvKFeunMJtBgYGao2ZiIoGix0iKhHc3d2hp6eHwMBAODs7AwDi4uJw//59+Pn54e7du3j58iXmzZsHJycnADnDWG/S19cHAGRnZ8u3eXp6wsDAAOHh4fDz8yuiV0NERYnFDhGVCCYmJhg8eDC+/PJLWFtbw9bWFt988w2k0pzrLJydnaGvr4+ffvoJI0aMwM2bNzF79myFx3BxcYFEIsGhQ4fQvn17GBkZwdTUFBMnTsSECRMgk8nQpEkTJCQk4Ny5czAzM4O/v78mXi4RqRCvxiKiEuOHH35A06ZN0alTJ7Rq1QpNmjSBt7c3AMDGxgabNm3C7t274enpiXnz5uHHH39UuH+5cuUwa9YsfPXVV7Czs8Po0aMBALNnz8a0adMwd+5cVK1aFW3btsXvv/8ONze3In+NRKR6vBqLiIiItBrP7BAREZFWY7FDREREWo3FDhEREWk1FjtERESk1VjsEBERkVZjsUNERERajcUOERERaTUWO0RERKTVWOwQERGRVmOxQ0RERFqNxQ4RERFptf8DK7ElPdYYIkgAAAAASUVORK5CYII=", + "text/plain": [ + "
" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "# Get time series for the selected water body\n", + "selected_waterbody_timeseries = get_time_series(waterbody=selected_waterbody.iloc[0])\n", + "\n", + "# Select only the wet percentage surface measure\n", + "wet_percentage_timeseries = selected_waterbody_timeseries[\"pc_wet\"]\n", + "\n", + "# Plot the wet percentage time series and customise the y-axis label\n", + "wet_percentage_timeseries.plot()\n", + "plt.title(f\"Percentage of water body '{selected_waterbody_geohash}' classified as wet\")\n", + "plt.ylabel(\"Wet Surface Area Percentage\");\n", + "plt.ylim(0, 100);" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.10.12" + }, + "widgets": { + "application/vnd.jupyter.widget-state+json": { + "state": {}, + "version_major": 2, + "version_minor": 0 + } + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/Tools/deafrica_tools/waterbodies.py b/Tools/deafrica_tools/waterbodies.py new file mode 100644 index 000000000..185e25ed2 --- /dev/null +++ b/Tools/deafrica_tools/waterbodies.py @@ -0,0 +1,129 @@ +""" +Loading and processing DE Africa Water Bodies data. +Last modified: November 2023 +""" + +# Import required packages +import geopandas as gpd +from owslib.wfs import WebFeatureService +from owslib.fes import PropertyIsEqualTo +from owslib.etree import etree +import pandas as pd + +# URL for the DE Africa Water Bodies data on Dev Geoserver. +WFS_ADDRESS = "https://geoserver.digitalearth.africa/geoserver/wfs" +WFS_LAYER = "waterbodies:DEAfrica_Waterbodies" + +def get_waterbody(geohash: str) -> gpd.GeoDataFrame: + """Gets a waterbody polygon and metadata by geohash. + + Parameters + ---------- + geohash : str + The geohash/UID for a waterbody in DE Africa Water Bodies. + + Returns + ------- + gpd.GeoDataFrame + A GeoDataFrame with the polygon. + """ + + wfs = WebFeatureService(url=WFS_ADDRESS, version="1.1.0") + filter_ = PropertyIsEqualTo(propertyname="UID", literal=geohash) + filterxml = etree.tostring(filter_.toXML()).decode("utf-8") + response = wfs.getfeature( + typename=WFS_LAYER, + filter=filterxml, + outputFormat="json", + ) + wb_gpd = gpd.read_file(response) + return wb_gpd + + +def get_waterbodies(bbox: tuple, crs="EPSG:4326") -> gpd.GeoDataFrame: + """Gets the polygons and metadata for multiple water bodies by bbox. + + Parameters + ---------- + bbox : (xmin, ymin, xmax, ymax) + Bounding box. + crs : str + Optional CRS for the bounding box. + + Returns + ------- + gpd.GeoDataFrame + A GeoDataFrame with the polygons and metadata. + """ + + wfs = WebFeatureService(url=WFS_ADDRESS, version="1.1.0") + response = wfs.getfeature( + typename=WFS_LAYER, + bbox=tuple(bbox) + (crs,), + outputFormat="json", + ) + wb_gpd = gpd.read_file(response) + return wb_gpd + + +def get_geohashes(bbox: tuple = None, crs: str = "EPSG:4326") -> [str]: + """Gets all waterbody geohashes. + + Parameters + ---------- + bbox : (xmin, ymin, xmax, ymax) + Optional bounding box. + crs : str + Optional CRS for the bounding box. + + Returns + ------- + [str] + A list of geohashes. + """ + + wfs = WebFeatureService(url=WFS_ADDRESS, version="1.1.0") + if bbox is not None: + bbox = bbox + (crs,) + response = wfs.getfeature( + typename=WFS_LAYER, + propertyname="UID", + outputFormat="json", + bbox=bbox, + ) + wb_gpd = gpd.read_file(response) + return list(wb_gpd["UID"]) + + +def get_time_series(geohash: str = None, waterbody: pd.Series = None) -> pd.DataFrame: + """Gets the time series for a waterbody. Specify either a GeoDataFrame row or a geohash. + + Parameters + ---------- + geohash : str + The geohash/UID for a waterbody in DE Africa Water Bodies. + waterbody : pd.Series + One row of a GeoDataFrame representing a waterbody. + + Returns + ------- + pd.DataFrame + A time series for the waterbody. + """ + if waterbody is not None and geohash is not None: + raise ValueError("One of waterbody and geohash must be None") + if waterbody is None and geohash is None: + raise ValueError("One of waterbody and geohash must be specified") + + if geohash is not None: + wb = get_waterbody(geohash) + url = wb.timeseries[0] + else: + url = waterbody.timeseries + wb_timeseries = pd.read_csv(url) + # Tidy up the dataframe. + wb_timeseries.dropna(inplace=True) + wb_timeseries.columns = ["date", "pc_wet", "px_wet", "area_wet_m2", "pc_dry", "px_dry", "area_dry_m2", "pc_invalid", "px_invalid", "area_invalid_m2"] + wb_timeseries = wb_timeseries.set_index("date") + wb_timeseries.index = pd.to_datetime(wb_timeseries.index) + return wb_timeseries diff --git a/Tools/index.rst b/Tools/index.rst index b6324b075..664843386 100644 --- a/Tools/index.rst +++ b/Tools/index.rst @@ -24,6 +24,7 @@ Core modules deafrica_tools.plotting deafrica_tools.spatial deafrica_tools.temporal + deafrica_tools.waterbodies deafrica_tools.wetlands Apps and widgets diff --git a/Tools/pyproject.toml b/Tools/pyproject.toml index b1b56c4b9..ea6e38ef6 100644 --- a/Tools/pyproject.toml +++ b/Tools/pyproject.toml @@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta" [project] name = "deafrica-tools" -version = "2.1.2" +version = "2.2.0" description = "Functions and algorithms for analysing Digital Earth Africa data." authors = [{name = "Digital Earth Africa", email = "systems@digitalearthafrica.org"}] maintainers = [{name = "Digital Earth Africa", email = "systems@digitalearthafrica.org"}]