README.md 6.5 KB
Newer Older
Felix Delattre's avatar
Felix Delattre committed
1
2
# gde-core

Cecilia Nievas's avatar
Cecilia Nievas committed
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
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`
26
- `geopandas`
Cecilia Nievas's avatar
Cecilia Nievas committed
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
- `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.
- `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.
84
85
86
87
88
89
- `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.
- `database_obm_buildings`: Credentials for the 
[OBM Buildings](https://git.gfz-potsdam.de/dynamicexposure/openbuildingmap/database-obmbuildings) 
database where information on the OBM buildings is stored.
90
91
92
93
- `database_completeness`: Credentials for the 
[OBM Tiles](https://git.gfz-potsdam.de/dynamicexposure/openbuildingmap/database-obmtiles)
database where information on the OSM-completeness of tiles is stored.
- `number_cores`: Number of cores used for parallelisation.
Cecilia Nievas's avatar
Cecilia Nievas committed
94

Cecilia Nievas's avatar
Cecilia Nievas committed
95
96
97
Further details on the meaning and use of these parameters can be found in the
[documentation](docs/04_Configuration.md).

Cecilia Nievas's avatar
Cecilia Nievas committed
98
99
100
101
102
103
104
105
## Running gde-core

From the working directory (where you placed `config.yml`), run the code by typing:

```
gdecore
```

Felix Delattre's avatar
Felix Delattre committed
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
## Copyright and copyleft

Copyright (C) 2022

* Helmholtz-Zentrum Potsdam Deutsches GeoForschungsZentrum GFZ

This program is free software: you can redistribute it and/or modify it
under the terms of the GNU Affero General Public License as published by
the Free Software Foundation, either version 3 of the License, or (at
your option) any later version.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero
General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program. If not, see http://www.gnu.org/licenses/.

Also add information on how to contact you by electronic and paper mail.

If your software can interact with users remotely through a computer
network, you should also make sure that it provides a way for users to
get its source. For example, if your program is a web application, its
interface could display a "Source" link that leads users to an archive
of the code. There are many ways you could offer source, and different
solutions will be better for different programs; see section 13 for the
specific requirements.

See the [LICENSE](./LICENSE) for the full license text.
Cecilia Nievas's avatar
Cecilia Nievas committed
136
137
138
139
140
141
142
143
144
145
146
147
148
149

## Acknowledgements

This project is partially funded by:

- the Real-time Earthquake Risk Reduction for a Resilient Europe (RISE) project, which has
received funding from the European Union’s Horizon 2020 research and innovation programme under
grant agreement No 821115;
- the Large-scale EXecution for Industry and Society (LEXIS) project, which has received funding
from the European Union’s Horizon 2020 research and innovation programme under grant agreement
No 825532;
- the Airborne Observation of Critical Infrastructures (Luftgestützte Observation Kritischer
Infrastrukturen, LOKI in German) project, which has received funding from the German Federal
Ministry for Education and Research (BMBF) under funding code (FKZ) 03G0890D.