Cecilia Nievas · 5c50ec2e
--- a/README.md

+ 92

− 0
+++ b/README.md

+ 92

− 0
 # gde-core

+Creates the Global Dynamic Exposure (GDE) model.
+
+## Description
+
+`gde-core` creates the Global Dynamic Exposure (GDE) model by bringing 
+together:
+- aggregated exposure models distributed on zoom level 18 tiles (output 
+of [gde-importer](https://git.gfz-potsdam.de/dynamicexposure/globaldynamicexposure/gde-importer)),
+- OpenBuildingMap (OBM) buildings (output of 
+[rabotnik-obm](https://git.gfz-potsdam.de/dynamicexposure/openbuildingmap/rabotnik-obm)),
+- automatically-calculated completeness of OpenBuildingMap (OBM) (output of 
+[obmgapanalysis](https://git.gfz-potsdam.de/dynamicexposure/openbuildingmap/obmgapanalysis)).
+
+## Installing gde-core
+
+### Software dependencies
+
+- Python 3.7, 3.8 or 3.9
+
+### Python libraries
+
+- `numpy`
+- `shapely`
+- `gde-importer`
+
+### Install
+
+```bash
+git clone https://git.gfz-potsdam.de/dynamicexposure/globaldynamicexposure/gde-core.git
+cd gde-core
+pip3 install -e .
+```
+
+## Preparation
+
+### Run the previous steps
+
+`gde-core` requires that the following software be run in advance for the geographic area and 
+input aggregated exposure models of interest:
+
+1. [rabotnik-obm](https://git.gfz-potsdam.de/dynamicexposure/openbuildingmap/rabotnik-obm): 
+processing of [OpenStreetMap (OSM)](https://www.openstreetmap.org) data to generate the 
+`OpenBuildingMap` (OBM).
+2. [obmgapanalysis](https://git.gfz-potsdam.de/dynamicexposure/openbuildingmap/obmgapanalysis): 
+estimation of completeness of `OpenBuildingMap` by means of an automatic comparison between 
+remote-sensing-derived built-up area (from the 
+[Global Human Settlement Layer](https://data.jrc.ec.europa.eu/dataset/jrc-ghsl-10007)) and 
+OBM-derived built-up area.
+3. [gde-importer](https://git.gfz-potsdam.de/dynamicexposure/globaldynamicexposure/gde-importer): 
+import of aggregated exposure models and their distribution on zoom level 18 tiles.
+
+This requisite implies as well that the database tables that are output of these software exist 
+and are populated with relevant data. The databases associated with these software are:
+
+- [GDE Tiles](https://git.gfz-potsdam.de/dynamicexposure/globaldynamicexposure/database-gdetiles)
+- [OBM Tiles](https://git.gfz-potsdam.de/dynamicexposure/openbuildingmap/database-obmtiles)
+- [OBM Buildings](https://git.gfz-potsdam.de/dynamicexposure/openbuildingmap/database-obmbuildings)
+
+### Configuration
+
+Copy the file `config_example.yml` to your working directory as `config.yml` and provide the 
+necessary parameters. Required parameters are:
+
+- `model_name`: Name of the input aggregated exposure model to be processed. It needs to have 
+been imported by 
+[gde-importer](https://git.gfz-potsdam.de/dynamicexposure/globaldynamicexposure/gde-importer) 
+already.
+- `database_gde_tiles`: Credentials for the 
+[GDE Tiles](https://git.gfz-potsdam.de/dynamicexposure/globaldynamicexposure/database-gdetiles) 
+database where information on the GDE tiles is stored.
+- `exposure_entities_to_run`: List of names of exposure entities for which the code will be run. 
+Currently supported options:
+  - "all": The list of names associated with `model_name` will be retrieved from the 
+  [GDE Tiles](https://git.gfz-potsdam.de/dynamicexposure/globaldynamicexposure/database-gdetiles) 
+database.
+  - A comma-space-separated list of entity names: This list of names will be used.
+  - A full path to a .txt or .csv file:  The list of names will be retrieved from the indicated 
+  .txt/.csv file.
+- `exposure_entities_code`: Either "ISO3" or a nested structure with exposure entities names 
+and 3-character codes. When running `model_name=esrm20`, "ISO3" is the preferred option.
+- `occupancies_to_run`: List of occupancies for which the code will be run, separated by ", " 
+(comma and space). They need to exist for the indicated `exposure format`. Currently supported 
+values: residential, commercial, industrial.
+
+## Running gde-core
+
+From the working directory (where you placed `config.yml`), run the code by typing:
+
+```
+gdecore
+```
+
 ## Copyright and copyleft

 Copyright (C) 2022