Merge pull request #150 from Deltares/#64FlexibleAggregationArea

#64 flexible aggregation area

docs/user_guide/user_guide_overview.rst

@@ -54,6 +54,52 @@ Raster data
 This option will be implemented at a later stage.
 
 
+Aggregation Zones
+-----------------------
+In spatial analysis and urban planning the division of objects into spatial zones, such as land-use or accommodation type, is a pivotal tool to facilitate analysis and/or visualization. The `FIAT toolbox <https://github.com/Deltares/fiat_toolbox>`_ offers simple tools to assign aggregation labels to the exposure.csv file, after calculating damages with `FIAT toolbox <https://github.com/Deltares/delft-fiat>`_. Subsequental, the `FIAT toolbox <https://github.com/Deltares/fiat_toolbox>`_ can be used to automatically calculate metrics over the aggregation areas. The user can add multiple aggregation labels at once by providing vector files for each zone (e.g., *.shp* or *.gpkg*). 
+
+To associate the original exposure data with the aggregation zones, the **"join_exposure_aggregation_areas"** function can be utilized. This function seamlessly links each geometry in the original exposure data to its corresponding spatial aggregation zone.
+To prepare the data, an aggregation configuration file (*.yml*) must be created with the following information (case-sensitive):   
+
+Input yaml file: 
+   - **new_root**: Path to the output folder
+   - **aggregation_area_fn**: Path to the aggregation file
+   - **attribute_names**: Name of the zone attribute in your file 
+   - **label_names**: Desired aggregation label for newly created aggregation zone
+
+In case the user wants to add several aggregation zones at once, multiple aggregation files can be provided in a list. Each variable (file path, attribute name, label name) must follow the same order to assure that attribute and label names are assigned to the correct aggregation file:: 
+
+   [Example configuration yaml file for two aggregation zone files.]
+
+   Title: "Base_zones and Land_use aggregation zones"
+   new_root: "./fiat_model/output/aggregation_zones"
+   configuration:
+     setup_aggregation_areas:
+       aggregation_area_fn:
+         - "./agg_zones/base_zone_aggregation.shp"
+         - "./agg_zones/land_use_aggregation.shp"
+       attribute_names:
+         - "ZONE_BASE"
+         - "LAND_USE"
+       label_names:
+         - "Base Zone"
+         - "Land Use"
+
+After loading the configuration file (*.yml*) and executing the **FIAT Hydro MT** model builder, the user receives a file (*.csv*) with the original exposure data and an additional column with the aggregation label(s) as output. The `FIAT toolbox <https://github.com/Deltares/delft-fiat>`_ will automatically prepend "*Aggregation Label*" to the prior specified aggregation label, therefore the aggregation labels can be identified as such.
+
+   Aggregation Label: {label_name}
+
+*Note: It may occur that polygons overlap in the aggregation vector files. In this case the information for the affected Object ID will be merged and both aggregation zones will be assigned to the object.* ::
+
+   Object ID   Zone
+   
+   1           Base Zone 1
+   2           Land Use 1, Land Use 3    >  two zones (polygons) in the land-use aggregation file overlap and object 
+                                            falls into both zones
+   3           Land Use 2
+
+
+
 Vulnerability
 =======================
 Vulnerability data can be build from a data_catalog_ or by supplying an absolute path 

examples/data/aggregation_zones_example/aggregation_test_1_output/settings.toml

@@ -0,0 +1,22 @@
+[global]
+crs = "epsg:4326"
+
+[output]
+path = "output"
+
+[output.csv]
+name = "output.csv"
+
+[output.geom]
+name1 = "spatial.gpkg"
+
+[vulnerability]
+file = "./vulnerability/vulnerability_curves.csv"
+unit = "feet"
+step_size = 0.1
+
+[exposure.geom]
+csv = "./exposure/exposure.csv"
+crs = "EPSG:4326"
+unit = "ft"
+file1 = "./exposure/buildings.gpkg"

examples/data/aggregation_zones_example/aggregation_test_1_output/vulnerability/vulnerability_curves.csv

@@ -0,0 +1,37 @@
+#UNIT=feet
+#METHOD,max,mean,mean,mean,mean,mean,mean,mean,mean,mean,mean,mean,mean,mean,mean,mean,mean,mean,mean,mean,mean,mean,mean,mean,mean,mean,mean,mean,mean,mean,mean,mean,mean,mean,mean,mean,mean,mean
+water depth [feet],AGR1,COM1,COM10,COM2,COM3,COM4,COM5,COM6,COM7,COM8,COM9,EDU1,EDU2,GOV1,GOV2,IND1,IND2,IND3,IND4,IND5,IND6,REL1,RES1-1SNB,RES1-1SWB,RES1-2SNB,RES1-2SWB,RES1-3SNB,RES1-3SWB,RES2,RES3A,RES3B,RES3C,RES3D,RES3E,RES3F,RES4,RES5,RES6
+-9.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0
+-8.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,1e-06,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0
+-7.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.008,0.0,0.01,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0
+-6.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.021,0.0,0.023,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0
+-5.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.037,0.0,0.037,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0
+-4.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.057,0.0,0.052,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0
+-3.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.08,0.0,0.068,0.0,0.05,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0
+-2.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.105,0.0,0.084,0.0,0.07,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0
+-1.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.024,0.132,0.01,0.101,0.0,0.08,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0
+0.0,0.06,0.02,0.0,0.03,0.004,0.0,0.0,0.0,0.0,0.13,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.02,0.15,0.02,0.0,0.0,0.081,0.16,0.05,0.119,0.06,0.14,0.03,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0
+1.0,0.2,0.26,0.11,0.16,0.164,0.2,0.5,0.146,0.28,0.45,0.04,0.217,0.27,0.3,0.08,0.15,0.193,0.2,0.2,0.2,0.2,0.293,0.133,0.189,0.087,0.138,0.11,0.18,0.27,0.217,0.217,0.217,0.217,0.217,0.217,0.161,0.15,0.38
+2.0,0.43,0.42,0.17,0.27,0.289,0.3,0.74,0.27,0.51,0.55,0.06,0.304,0.38,0.59,0.2,0.24,0.31,0.41,0.26,0.41,0.35,0.484,0.179,0.218,0.122,0.157,0.15,0.22,0.49,0.304,0.304,0.304,0.304,0.304,0.304,0.263,0.25,0.6
+3.0,0.58,0.56,0.2,0.36,0.409,0.4,0.83,0.37,0.6,0.64,0.08,0.39,0.53,0.74,0.38,0.34,0.423,0.51,0.31,0.51,0.47,0.6,0.22,0.247,0.155,0.177,0.19,0.25,0.64,0.39,0.39,0.39,0.39,0.39,0.39,0.341,0.4,0.73
+4.0,0.65,0.68,0.23,0.49,0.577,0.575,1.0,0.534,0.63,0.73,0.09,0.45,0.64,0.83,0.55,0.41,0.523,0.62,0.37,0.62,0.56,0.693,0.257,0.274,0.185,0.198,0.23,0.29,0.7,0.45,0.45,0.45,0.45,0.45,0.45,0.397,0.5,0.81
+5.0,0.66,0.78,0.25,0.57,0.633,0.7,1.0,0.7,0.67,0.77,0.1,0.479,0.68,0.9,0.7,0.47,0.607,0.67,0.4,0.67,0.59,0.764,0.288,0.3,0.213,0.22,0.26,0.31,0.76,0.479,0.479,0.479,0.479,0.479,0.479,0.487,0.58,0.88
+6.0,0.66,0.83,0.29,0.63,0.707,0.8,1.0,0.791,0.71,0.8,0.12,0.519,0.7,1.0,0.81,0.52,0.72,0.71,0.44,0.71,0.66,0.814,0.315,0.324,0.239,0.243,0.29,0.34,0.78,0.519,0.519,0.519,0.519,0.519,0.519,0.524,0.65,0.94
+7.0,0.67,0.85,0.35,0.69,0.793,0.838,1.0,0.856,0.72,0.82,0.17,0.557,0.72,1.0,0.89,0.57,0.821,0.73,0.48,0.73,0.69,0.884,0.338,0.345,0.263,0.267,0.32,0.36,0.79,0.557,0.557,0.557,0.557,0.557,0.557,0.584,0.78,1.0
+8.0,0.7,0.87,0.42,0.72,0.843,1.0,1.0,0.925,0.74,0.83,0.22,0.593,0.75,1.0,0.98,0.6,0.907,0.76,0.53,0.76,0.71,0.943,0.357,0.363,0.284,0.291,0.35,0.39,0.81,0.593,0.593,0.593,0.593,0.593,0.593,0.613,0.9,1.0
+9.0,0.75,0.88,0.51,0.76,0.871,1.0,1.0,0.956,0.77,0.85,0.3,0.606,0.79,1.0,1.0,0.63,0.943,0.78,0.56,0.78,0.72,0.971,0.372,0.377,0.303,0.317,0.41,0.44,0.83,0.606,0.606,0.606,0.606,0.606,0.606,0.631,0.9,1.0
+10.0,0.76,0.89,0.63,0.8,0.871,1.0,1.0,0.963,0.81,0.87,0.41,0.634,0.83,1.0,1.0,0.64,0.95,0.79,0.57,0.79,0.78,0.971,0.384,0.386,0.32,0.344,0.43,0.46,0.83,0.634,0.634,0.634,0.634,0.634,0.634,0.649,0.92,1.0
+11.0,0.76,0.9,0.77,0.82,0.871,1.0,1.0,0.963,0.86,0.89,0.57,0.634,0.88,1.0,1.0,0.66,0.95,0.82,0.6,0.82,0.79,0.971,0.392,0.391,0.334,0.372,0.45,0.47,0.83,0.634,0.634,0.634,0.634,0.634,0.634,0.649,0.92,1.0
+12.0,0.76,0.91,0.93,0.84,0.871,1.0,1.0,0.963,0.92,0.9,0.66,0.634,0.94,1.0,1.0,0.68,0.95,0.83,0.62,0.83,0.8,0.971,0.397,0.391,0.347,0.4,0.48,0.5,0.83,0.634,0.634,0.634,0.634,0.634,0.634,0.649,0.92,1.0
+13.0,0.77,0.92,1.0,0.86,0.871,1.0,1.0,0.963,0.94,0.91,0.73,0.634,1.0,1.0,1.0,0.69,0.95,0.84,0.63,0.84,0.8,0.971,0.4,0.391,0.356,0.43,0.5,0.52,0.83,0.634,0.634,0.634,0.634,0.634,0.634,0.649,0.92,1.0
+14.0,0.77,0.92,1.0,0.87,0.871,1.0,1.0,0.963,0.97,0.92,0.79,0.634,1.0,1.0,1.0,0.72,0.95,0.86,0.63,0.86,0.81,0.971,0.4,0.391,0.364,0.461,0.52,0.53,0.83,0.634,0.634,0.634,0.634,0.634,0.634,0.649,0.92,1.0
+15.0,0.77,0.92,1.0,0.87,0.871,1.0,1.0,0.963,0.99,0.93,0.84,0.634,1.0,1.0,1.0,0.73,0.95,0.87,0.63,0.87,0.81,0.971,0.4,0.391,0.369,0.493,0.54,0.55,0.83,0.634,0.634,0.634,0.634,0.634,0.634,0.649,0.92,1.0
+16.0,0.78,0.93,1.0,0.88,0.871,1.0,1.0,0.963,1.0,0.94,0.9,0.634,1.0,1.0,1.0,0.73,0.95,0.87,0.64,0.87,0.81,0.971,0.4,0.391,0.372,0.526,0.56,0.57,0.83,0.634,0.634,0.634,0.634,0.634,0.634,0.649,0.92,1.0
+17.0,0.78,0.93,1.0,0.89,0.871,1.0,1.0,0.963,1.0,0.95,0.97,0.634,1.0,1.0,1.0,0.73,0.95,0.88,0.65,0.88,0.82,0.971,0.4,0.391,0.372,0.526,0.58,0.58,0.83,0.634,0.634,0.634,0.634,0.634,0.634,0.649,0.92,1.0
+18.0,0.78,0.94,1.0,0.89,0.871,1.0,1.0,0.963,1.0,0.96,0.98,0.634,1.0,1.0,1.0,0.74,0.95,0.88,0.65,0.88,0.82,0.971,0.4,0.391,0.372,0.526,0.6,0.6,0.83,0.634,0.634,0.634,0.634,0.634,0.634,0.649,0.92,1.0
+19.0,0.79,0.94,1.0,0.89,0.871,1.0,1.0,0.963,1.0,0.96,1.0,0.634,1.0,1.0,1.0,0.74,0.95,0.88,0.65,0.88,0.82,0.971,0.4,0.391,0.372,0.526,0.6,0.6,0.83,0.634,0.634,0.634,0.634,0.634,0.634,0.649,0.92,1.0
+20.0,0.79,0.94,1.0,0.89,0.871,1.0,1.0,0.963,1.0,0.96,1.0,0.634,1.0,1.0,1.0,0.74,0.95,0.88,0.65,0.88,0.83,0.971,0.4,0.391,0.372,0.526,0.6,0.6,0.83,0.634,0.634,0.634,0.634,0.634,0.634,0.649,0.92,1.0
+21.0,0.79,0.94,1.0,0.89,0.871,1.0,1.0,0.963,1.0,0.96,1.0,0.634,1.0,1.0,1.0,0.74,0.95,0.88,0.65,0.88,0.83,0.971,0.4,0.391,0.372,0.526,0.6,0.6,0.83,0.634,0.634,0.634,0.634,0.634,0.634,0.649,0.92,1.0
+22.0,0.79,0.94,1.0,0.89,0.871,1.0,1.0,0.963,1.0,0.96,1.0,0.634,1.0,1.0,1.0,0.75,0.95,0.88,0.65,0.88,0.83,0.971,0.4,0.391,0.372,0.526,0.6,0.6,0.83,0.634,0.634,0.634,0.634,0.634,0.634,0.649,0.92,1.0
+23.0,0.8,0.94,1.0,0.89,0.871,1.0,1.0,0.963,1.0,0.96,1.0,0.634,1.0,1.0,1.0,0.75,0.95,0.88,0.65,0.88,0.83,0.971,0.4,0.391,0.372,0.526,0.6,0.6,0.83,0.634,0.634,0.634,0.634,0.634,0.634,0.649,0.92,1.0
+24.0,0.8,0.94,1.0,0.89,0.871,1.0,1.0,0.963,1.0,0.96,1.0,0.634,1.0,1.0,1.0,0.75,0.95,0.88,0.65,0.88,0.83,0.971,0.4,0.391,0.372,0.526,0.6,0.6,0.83,0.634,0.634,0.634,0.634,0.634,0.634,0.649,0.92,1.0

examples/data/aggregation_zones_example/config_aggregation.yml

@@ -0,0 +1,25 @@
+cases:
+  test1_single_aggregation:
+    new_root: "./data/Aggregation_zones_example/output/aggregation_zones_test1"
+    configuration:
+      setup_aggregation_areas:
+       aggregation_area_fn: "./data/Aggregation_zones_example/aggregation_zones/base_zones.gpkg"
+       attribute_names: ZONE_BASE
+       label_names: Base_zones
+
+  test2_multiple_aggregation:
+    new_root: "./data/Aggregation_zones_example/output/aggregation_zones_test2"
+    configuration:
+      setup_aggregation_areas:
+        aggregation_area_fn:
+          - "./data/Aggregation_zones_example/aggregation_zones/base_zones.gpkg"
+          - "./data/Aggregation_zones_example/aggregation_zones/land_use.gpkg"
+          - "./data/Aggregation_zones_example/aggregation_zones/accomodation_type.gpkg"
+        attribute_names: 
+          - ZONE_BASE
+          - LAND_USE
+          - ACCOM
+        label_names:
+          - Base_zones
+          - Land_use
+          - Accommodation_type