Updates

Author: matamadio

docs/images/GUI_BV.jpg

@@ -1,66 +1,34 @@
-# Bi-variate mapping
+# Bivariate mapping of Risk and Poverty 
 
-WIP
+This tool calculates population-weighted wealth index scores and combines those with hazard index scores into a bivariate choropleth map. The scores are calculated by quantile ranking.
 
 ## Input data management
 
-This script is meant for custom input from the user on all three risk components. It can still fetch national and sub-national boundaries from the [WB ArcGIS repository](https://services.arcgis.com/iQ1dY19aHwbSDYIF/ArcGIS/rest/services/World_Bank_Global_Administrative_Divisions_VIEW/FeatureServer).
-
-The [**exposure data**](global-exposure.md) and the [**hazard data**](global-hazard.md) selected by the user need to be manually downloaded and placed in the respecive folders; in case of tiled data, use the [pre-processing script](https://github.com/GFDRR/CCDR-tools/blob/main/tools/code/F3/) to merge those into country-sized data. Each dataset is expected as a raster file (`.tif`).<br>
-
-Exampe:
-
-  ```
-  Work dir/
-   - GUI.ipynb		Place the notebooks and related files in the main work directory
-   - common.py
-   - ...
-   - Data/
-     - HZD/country_hazard.tif				Hazard layers
-     - EXP/country_exposure.tif				Exposure layers
-     - RSK/						Output directory
-  ```
-
-  ```{caution}
-  All spatial data must use the same CRS: `EPSG 4326` (WGS 84)
-  ```
-<hr>
+Input data should consist of a GeoPackage file with administrative boundaries containing fields for: Unit ID, Unit NAME, Unit POP, wealth index (e.g. RWI), and hazard score (e.g., EAI).
 
 ## Running the analysis
 
-- Select the country first. Sub-national boundaries for level 1 and 2 can be fetched automatically. Else, you can load custom boundaries as geopackage (WGS 84). You will need to specify the field to be used to run zonal statistics, and related label name (e.g. ADM3_PCODE and ADM3_EN).
-    ```{figure} images/GUI_F3_country.png
-    ---
-    width: 100%
-    align: center
-    ---
-    ```
-- Move to Hazard tab: select the hazard process, the minimum hazard intensity threshold, the time period and climate scenario. Select one or more Return Periods (CTRL+Click / drag mouse).
-    ```{figure} images/GUI_F3_hzd.png
+- Data tab: select the vector file containing all the required input at boundary level. Select the appropriate field for each attribute - they should be found automatically, but check they are correct.
+    ```{figure} images/GUI_BV.jpg
     ---
     width: 100%
     align: center
     ---
     ```
-- Select one or more Exposure categories (CTRL+Click / drag mouse). You can select a custom exposure layer for each selected category (.tif raster, WGS 84).
-    ```{figure} images/GUI_F3_exp.png
+- Bivatiate tab: select the number of classes to consider for each index, the bivariate color palette and the maximum exposure to hazard threshold (anything above this value will be considered on the top class). Use the **normalisation** checkbox to normalise the wealth index using population count from the input dataset. This is suggested when using unweighted indices.
+    ```{figure} images/GUI_BV2.jpg
     ---
     width: 100%
     align: center
     ---
     ```
-- Select the approach to use for the analysis:
-  - When using "function", the best impact function is selected for the selected country and exposure categories.
-  - When using "classes", hazard intensity thresholds must be specified by the user.
-    ```{figure} images/GUI_F3_vln.png
-    ---
-    width: 100%
-    align: center
-    ---
-    ```
-- Check "Preview results" to generate map and charts output in the GUI.
 
-```{figure} images/GUI_F3_rsk.png
+- Check "Preview results" to generate map and charts output in the GUI, or "Export Maps as PNG" to have those saved in the output folder. "Export data" will create a copy of the input data with added bivariate combination scores.
+
+- Click the red button to start the processing.
+
+
+```{figure} images/GUI_BV3.jpg
 ---
 width: 100%
 align: center

docs/images/GUI_BV2.jpg

@@ -6,7 +6,7 @@ This script is meant for custom input from the user on all three risk components
 
 The [**exposure data**](global-exposure.md) and the [**hazard data**](global-hazard.md) selected by the user need to be manually downloaded and placed in the respecive folders; in case of tiled data, use the [pre-processing script](https://github.com/GFDRR/CCDR-tools/blob/main/tools/code/F3/) to merge those into country-sized data. Each dataset is expected as a raster file (`.tif`).<br>
 
-Exampe:
+Example:
 
   ```
   Work dir/

docs/images/GUI_BV3.jpg

@@ -5,7 +5,7 @@ Additional tools to help collect, view and process risk data.
 ## Merge tiles
 Large raster datasets often comes as a collection of regular tiles.
 In order to run the raster analysis offered in our tools, they often need to be merged into one file.
-The function is provided as [**jupyter notebook**](https://github.com/GFDRR/CCDR-tools/tree/main/tools/code/F3) you can download and run on your python environment.
+The function is provided as [**jupyter notebook**](https://github.com/GFDRR/CCDR-tools/tree/main/tools/code/F3) you can download and run on your python environment. Please refer to the main codebase setup.
 
 (fetch_wsf19)=
 ## Fetch WSF 2019 and resample as 100 m