Commit f2197c39 authored by Tara Evaz Zadeh's avatar Tara Evaz Zadeh
Browse files

Edited the manual

parent aa4057af
Pipeline #21333 passed with stage
in 1 minute and 58 seconds
# losscalculator # losscalculator
This program computes the probabilities of occurrence (PoE) of damage states for real or scenario This program computes the probabilities of occurrence (PoE) of damage states for real or scenario
...@@ -32,7 +31,7 @@ Definitions in this terminology section are taken from the `Glossary` section of ...@@ -32,7 +31,7 @@ Definitions in this terminology section are taken from the `Glossary` section of
To run the program please call: To run the program please call:
`python3 damage_calculator.py [OPTIONS] -c filepath -e filepath -f pathname -g filepath -p filepath -t filepath` `python3 damage_calculator.py [OPTIONS] -e filepath -f pathname -g filepath -p filepath -t filepath`
Use Use
...@@ -48,38 +47,34 @@ for information on how to use the program input options. ...@@ -48,38 +47,34 @@ for information on how to use the program input options.
Defines the path to the exposure model file. Defines the path to the exposure model file.
File example extract: File example extract:
id,lon,lat,taxonomy,number,structural,night,occupancy,admin_name,admin_id,origin_id
GDE_Ind_8344,23.6835236228,38.2808067265,CR/LFINF+CDM/H:2,0.225062972292, "id","lon","lat","taxonomy","number","structural","night","occupancy","admin_name","admin_ID","tile_id","tile_geometry","building_id","building_geometry"
402000.816015,0.0,Ind,Oropos,GR_3514913,OSM_502509057 "GDE_Ind_65386",23.6317973417,38.063296952,"CR/LFINF+CDM/H:2",0.224973135611,401840.352396,0.0,"Ind","Aspropyrgos","GR_3515002",2423204507,"POLYGON ((23.63055555555556 38.0611111111111, 23.63333333333335 38.0638888888889, 23.63055555555556 38.0611111111111))",222934686,"POLYGON ((23.63084695460133 38.06460056593416, 23.63101592770628 38.062811746918, 23.63084695460133 38.06460056593416))"
GDE_Ind_8345,23.6835236228,38.2808067265,CR/LFM+CDM/H:2,0.225062972292, "GDE_Com_940036",23.6319444444,38.0625,"CR/LDUAL+CDM/H:1/8.0",12.5,61.8328463283,0.0,"Com","Aspropyrgos","GR_3515002",2423204507,"POLYGON ((23.63055555555556 38.0611111111111, 23.63333333333335 38.0611111111111, 23.63333333333335 38.0638888888889, 23.63055555555556 38.0638888888889, 23.63055555555556 38.0611111111111))",-1,"POINT EMPTY"
402000.816015,0.0,Ind,Oropos,GR_3514913,OSM_502509057
...
GDE_Ind_201281,23.8998942292,37.4896629325,W/LWAL+CDL/H:1,0.00944510035419,
15263.838681,0.0,Ind,Lavreotiki,GR_3514905,OSM_506291001
Exposure items definition: Exposure items definition:
Please note that the assets of the region of interest can be presented differently in an exposure model. One way is to divide the region of interest into a grid and all the assets inside each cell will be represented by aggregated assets in the center of that cell. In the other way, all assets (buildings) will be given with their exact location (building centroid). Please note that the assets of the region of interest can be presented differently in an exposure model. One way is to divide the region of interest into a grid and all the assets inside each tile will be represented by aggregated assets in the center of that tile. In the other way, all assets (buildings) will be given with their exact location (building centroid).
id: id:
Unique ID for each asset in the exposure model. It can consist of both letters and numbers. The ID relates each asset in the exposure model to the respective entries in the results. IDs can be freely defined as long as they contain numbers, letters and `_` only. Unique ID for each asset in the exposure model. It can consist of both letters and numbers. The ID relates each asset in the exposure model to the respective entries in the results. IDs can be freely defined as long as they contain numbers, letters and `_` only.
lon: lon:
Longitude of the asset (centroid of either a building or a cell, depending on the exposure type). Longitude of the asset (centroid of either a building or a tile, depending on the exposure type).
lat: lat:
Latitude of the asset (centroid of either a building or a cell, depending on the exposure type). Latitude of the asset (centroid of either a building or a tile, depending on the exposure type).
taxonomy: taxonomy:
Explained above in Section `Terminology`. Explained above in Section `Terminology`.
number: number:
Number of buildings for the given asset (float). Due to the probabilistic assessment of building types, each building’s possible structural type is represented by a different asset with a respective frequency. Also, the distribution of aggregated exposure models to cells can cause non-cardinal building numbers per cell. Number of buildings for the given asset (float). Due to the probabilistic assessment of building types, each building’s possible structural type is represented by a different asset with a respective frequency. Also, the distribution of aggregated exposure models to tiles can cause non-cardinal building numbers per tile.
structural: structural:
Reconstruction cost of the asset in an undefined currency. The user needs to make sure that only one currency is used. Reconstruction cost of the asset in an undefined currency. The user needs to make sure that only one currency is used.
night: night:
Number of people expected at night-time in the asset (building). Number of people expected at night-time in the asset.
occupancy: occupancy:
Occupancy type of the asset. Common types are _industrial_, _commercial_, and _residential_, but other types are possible. Occupancy type of the asset. Common types are _industrial_, _commercial_, and _residential_, but other types are possible.
...@@ -87,57 +82,20 @@ Please note that the assets of the region of interest can be presented different ...@@ -87,57 +82,20 @@ Please note that the assets of the region of interest can be presented different
admin_name: admin_name:
Name of the administrative unit of the asset location. Name of the administrative unit of the asset location.
admin_id: admin_ID:
ID of the administrative unit of the asset location. ID of the administrative unit of the asset location.
origin_id: tile_id:
An ID code used to trace back each asset in its data source. Thus the total number of origin IDs is equal to the number of unique asset locations in the exposure file. Origin IDs can be freely defined as long as they contain numbers, letters and `_` only. An ID used to trace back each asset into the tile in which the asset is located. An asset, regardless of being defined by its exact location centroid or in center of a tile, has a tile ID. `tile_id`s can be freely defined as long as they contain numbers, letters and `_` only.
**`-c`, `--cell-ids=filepath`** tile_geometry:
Defines the path to the file that contains the exposure model cell IDs. geometry of each tile.
File example extract: building_id:
An ID code used to trace back each asset into its source building. In this case, if an asset originates from a tile (not coming from a building), `building_id` is set to `-1`. `building_id`s can be freely defined as long as they contain numbers, letters and `_` only.
unique_cell_ids
cell_2423204507 building_geometry:
cell_2423204508 Geometry of each building asset. In case of `building_id` being `-1`, the geometry is defined as `"POINT EMPTY"`.
...
cell_2413743765
**`-p` `--geometry=filepath`**
Filepath of the geometry definitions.
This file contains the geometries (polygons) for either cells (in case of
`--exposure-type = 'cell'`) or buildings (in case of `--exposure-type = 'building'`).
Please note that in case of `--exposure-type = 'building'`, this file should not only contain the geometry, but also the `cell_id` for each `origin_id`.
File example extract:
in case of `--exposure-type = 'cell'`
origin_id;geometry
cell_2410244527;POLYGON ((23.68611111111113 38.3388888888889, 23.6888888888889
38.3388888888889,23.6888888888889 38.34166666666667, 23.68611111111113
38.34166666666667, 23.68611111111113 38.3388888888889))
...
cell_2527791597;POLYGON ((23.32500000000002 35.81944444444444, 23.32777777777778
35.81944444444444, 23.32777777777778 35.82222222222222, 23.32500000000002
35.82222222222222, 23.32500000000002 35.81944444444444))
in case of `--exposure-type = 'building'`
origin_id;geometry;cell_id
OSM_517924352;POLYGON((2641289.26886243 4582010.12482994,2641299.67723482
4582007.12923406,2641304.17454225 4582019.8887829,2641294.42295486
4582023.47785041,2641291.51751615 4582013.47368108,2641290.54903658
4582013.85519583,2641289.26886243 4582010.12482994));cell_2425278141
...
OSM_585772157;POLYGON((2644395.16 4566329.71,2644395.62 4566343.61,2644412.41
4566343.04,2644411.94 4566329.27,2644406.98 4566329.44,2644406.93 4566328.05,
2644398.08 4566328.24,2644396.22 4566328.38,2644396.26 4566329.68,2644395.16
4566329.71));cell_2430462151
Please note that the delimiter is `;`.
**`-f` `--fragilities=pathname`** **`-f` `--fragilities=pathname`**
Path to the directory with fragility-function files. Path to the directory with fragility-function files.
...@@ -195,45 +153,28 @@ If set, an existing result file will be overwritten, otherwise the program will ...@@ -195,45 +153,28 @@ If set, an existing result file will be overwritten, otherwise the program will
**`-r` `--results=filepath`** **`-r` `--results=filepath`**
Result filepath. Default is `damage_result.csv`. Result filepath. Default is `damage_result.csv`.
**`-x`, `--exposure-type={cell, building}`**
Defines the exposure type. Default is `cell`.
The assets of the region of interest can be presented differently in an exposure model.
In case of `--exposure-type='cell'`, the region of interest is divided into a grid and all the assets inside each cell will be represented by aggregation of the assets in the center of that cell.
In case of `--exposure-type='building'`, all assets will be given with their exact location (building centroid).
## Output ## Output
An example extract of the information stored in the result file is as follows: An example extract of the information stored in the result file is as follows:
geometry;origin_id;asset_id;lon;lat;taxonomy;gm_value;PoEs;PoOs;tot_num_buildings;structural_no_damage;structural_slight;structural_moderate;structural_extensive;structural_complete id,lon,lat,taxonomy,number,structural,night,occupancy,admin_name,admin_ID,tile_id,tile_geometry,building_id,building_geometry,gm_value,gm_type,PoES,PoOS,structural_no_damage,structural_slight,structural_moderate,structural_extensive,structural_complete
POLYGON ((23.63055555555556 38.0611111111111, 23.63333333333335 38.0611111111111, 23.63333333333335 38.0638888888889, 23.63055555555556 38.0638888888889, 23.63055555555556 38.0611111111111));cell_2423204507;GDE_Com_940022;23.631944444400002;38.0625;CR/LDUAL+CDH/H:2/15.0;0.251555124927799;[0.03603927982796303, 0.00025610377660166176, 1.647100804402403e-05, 2e-06];[0.9639607201720369, 0.03578317605136137, 0.00023963276855763774, 1.447100804402403e-05, 2e-06];0.00010009166233800001;9.648443091055484e-05;3.5815975747140713e-06;2.398524215559118e-08;1.4484272508329352e-09;2.0018332467600002e-10 GDE_Ind_65386,23.6317973417,38.063296951999995,CR/LFINF+CDM/H:2,0.224973135611,401840.352396,0.0,Ind,Aspropyrgos,GR_3515002,2423204507,"POLYGON ((23.63055555555556 38.0611111111111, 23.63333333333335 38.0638888888889, 23.63055555555556 38.0611111111111))",222934686,"POLYGON ((23.63084695460133 38.06460056593416, 23.63101592770628 38.062811746918, 23.63084695460133 38.06460056593416))",0.25303021062670217,gmv_SA(0.3),"[0.10903076520646712, 0.0016772034759250452, 0.00013973096336734918, 2.273581971606073e-05]","[0.8909692347935328, 0.10735356173054207, 0.001537472512557696, 0.00011699514365128846, 2.273581971606073e-05]",0.20044414248443435,0.0241516674015291,0.0003458900120658274,2.6320764318489743e-05,5.114948652208578e-06
... GDE_Com_940019,23.631944444400002,38.0625,CR/LDUAL+CDH/H:1/15.0,28.3,61.8328463283,0.0,Com,Aspropyrgos,GR_3515002,2423204507,"POLYGON ((23.63055555555556 38.0611111111111, 23.63333333333335 38.0611111111111, 23.63333333333335 38.0638888888889, 23.63055555555556 38.0638888888889, 23.63055555555556 38.0611111111111))",28.299760160977932,0.00023983902206814323,-0.0,-0.0,0.0
### Output information definition ### Output information definition
**`geometry`:** The output items
Well-Known-Text representation of the geometry of either a building or a cell, depending on the input exposure type. `id,lon,lat,taxonomy,number,structural,night,occupancy,admin_name,admin_ID,tile_id,tile_geometry,building_id,building_geometry,gm_value,gm_type,PoES,PoOS,structural_no_damage,structural_slight,structural_moderate,structural_extensive,structural_complete`
are explained above and the rest of the items are explained below.
**`origin_id`:**
Explained above in the section `Exposure items definition`.
**`asset_id`:**
Unique ID for each asset in the exposure model. This parameter is named `id` in the exposure model file. Using `asset_id`, each asset can be traced back to the exposure model.
**`lon`:**
Explained above in the section `Exposure items definition`.
**`lat`:**
Explained above in the section `Exposure items definition`.
**`taxonomy`:**
Explained above in the section `Terminology`.
**`gm_value`:** **`gm_value`:**
The ground-motion value at the asset location. The ground-motion value at the asset location.
Although the ground-motion-field file might contain more than one ground-motion type for each location, only one can be assigned to each asset in the result file. The type of the ground-motion value assigned to each asset matches the ground-motion type mentioned in the fragility-function relevant to the asset.
**`gm_type`**
Type of the ground-motion value assigned to the asset.
Although the ground-motion-field file might contain more than one ground-motion type for each location, only one can be assigned to each asset in the result file. The type of the ground-motion value assigned to each asset matches the ground-motion type mentioned in the fragility-function relevant to the asset.
In the example above, for the taxonomy "CR/LDUAL+CDH/H:2/15.0" the respective fragility function file is "CR_LDUAL-DUM_H2.csv" (as mentioned in the `--taxonomy-map` input section, the relevant fragility function for each taxonomy can be found using the `--taxonomy-map`) and includes information as below: In the example above, for the taxonomy "CR/LFINF+CDM/H:2" the respective fragility function file is "CR_LFINF-DUM_H2.csv" (as mentioned in the `--taxonomy-map` input section, the relevant fragility function for each taxonomy can be found using the `--taxonomy-map`) and includes information as below:
SA(0.3),0.018144 ,0.019294 ,0.020518... SA(0.3),0.018144 ,0.019294 ,0.020518...
slight,0.000000 ,0.000000 ,0.000000 ... slight,0.000000 ,0.000000 ,0.000000 ...
...@@ -241,17 +182,16 @@ In the example above, for the taxonomy "CR/LDUAL+CDH/H:2/15.0" the respective fr ...@@ -241,17 +182,16 @@ In the example above, for the taxonomy "CR/LDUAL+CDH/H:2/15.0" the respective fr
extensive,0.000000 ,0.000000 ,0.000000 ... extensive,0.000000 ,0.000000 ,0.000000 ...
complete,0.000000 ,0.000000 ,0.000000 ... complete,0.000000 ,0.000000 ,0.000000 ...
Because this fragility function contains the probabilities of exceeding damage states based on `SA(0.3)`, the ground-motion value of the asset in the result file is the interpolated value of the column `SA(0.3)` from the ground-motion-field file. Because this fragility function contains the probabilities of exceeding damage states based on `SA(0.3)`, the ground-motion value of the asset in the result file is the interpolated value of the column `SA(0.3)` from the ground-motion-field file. Thus the ground-motion type in this case is `gmv_SA(0.3)`. `gmv` is abbreviation for ground-motion value.
**`PoE`:** **`PoE`:**
Probability of exceeding (PoE) a particular damage state for an asset with a specific ground-motion value is calculated using linear interpolation on the PoE values of the same damage state given in the respective fragility function. Probability of exceeding (PoE) a particular damage state for an asset with a specific ground-motion value is calculated using linear interpolation on the PoE values of the same damage state given in the respective fragility function.
**`PoO`:** **`PoO`:**
Probability of occurrence (PoO) of a damage state. Probability of occurrence (PoO) of a damage state.
As an example, using the PoEs for the four damage states _slight_, _moderate_, _extensive_ and _complete_, the PoOs are computed as follows: As an example, using the PoEs for the four damage states _slight_, _moderate_, _extensive_ and _complete_, the PoOs are computed as follows:
PoO[_no damage_] = 1 – PoE[_slight_] PoO[_no_damage_] = 1 – PoE[_slight_]
PoO[_slight_] = PoE[_slight_] - PoE[_moderate_] PoO[_slight_] = PoE[_slight_] - PoE[_moderate_]
...@@ -261,9 +201,6 @@ PoO[_extensive_] = PoE[_extensive_] - PoE[_complete_] ...@@ -261,9 +201,6 @@ PoO[_extensive_] = PoE[_extensive_] - PoE[_complete_]
PoO[_complete_] = PoE[_complete_] PoO[_complete_] = PoE[_complete_]
**`num_buildings`:**
Number of buildings for the given asset.
**`structural_no_damage`:** **`structural_no_damage`:**
Number of structural undamaged buildings for the given asset. Number of structural undamaged buildings for the given asset.
...@@ -278,4 +215,89 @@ PoO[_complete_] = PoE[_complete_] ...@@ -278,4 +215,89 @@ PoO[_complete_] = PoE[_complete_]
**`structural_complete`:** **`structural_complete`:**
Number of structural completely-damaged buildings for the given asset. Number of structural completely-damaged buildings for the given asset.
# Preprocessor
This program imports a CSV exposure model into a database for damage calculation using the `losscalculator`.
The `losscalculator` computes earthquake-related damage in a building-specific way. For a building-specific calculation, the exposure model needs to include both the geometries of tiles ( As explained above in the section `-e` input, each asset in an exposure model can be represented either by their exact locations or in center of a tile.) and the buildings in addition to the data provided by
an OpenQuake-compatible exposure model (An OpenQuake-compatible exposure model CSV file with minimum information provided, has the headers: `id,lon,lat,taxonomy,number,structural,night,occupancy`). In fact, this program puts the geometries of both tiles and buildings together along with the OpenQuake-compatible exposure model information in a database format.
In addition to the `import` command (which use is explained above), the `preprocessor.py` provides an `export` command, using which the database exposure model is written to an output CSV file format.
## Usage
To import an input CSV exposure model file to database, execute:
`python3 preprocessor.py import -d ../example_preprocessor/augmented_exposure.db
-i ../example_preprocessor/data/exposure_*.csv
-g ../example_preprocessor/data/building_to_cellid_map.csv`
To export a database to a CSV output exposure model, execute:
`python3 preprocessor.py export -d ../example_preprocessor/augmented_exposure.db
-o ../example_preprocessor/augmented_exposure.csv`
## Program input parameters
**`-i`, `--import-search-pattern`**: str, optional
Search pattern for the input CSV exposure model files (e.g. '*.csv').
Each input CSV exposure model file should follow the format below:
`id,lon,lat,taxonomy,number,structural,night,occupancy,admin_name,admin_ID,origin_id`
Where `origin_id` is a unique ID which enables us to trace an asset back to either the tile or the building it is originated from.
Only required when using `import` command.
**`-d`, `--exposure-database`**: str, required
Defines the path to an exposure model database file.
When using `import` command, it points to a file where the exposure database file is to be stored.
When using `export` command, it points an existing exposure database file from which an output CSV
exposure file with header
`id,lon,lat,taxonomy,number,structural,night,occupancy,admin_name,admin_ID, tile_id,
tile_geometry, building_id ,building_geometry` is exported.
**`-g`, `--building-geometries`**: str, optional
Filepath of the geometry definitions.
OR
Defines the path to the file which maps building IDs (`origin-id` column in an input OpenQuake-compatible CSV exposure model file points to building IDs if the asset is originated from a building or tile IDs if the asset is defined by center of a tile) to both the building geometries and the tile IDs in which the building centroids are located.
Only required if there are building assets in the `-i` input file (the input OpenQuake-compatible CSV exposure model file).
Building geometries file example extract:
origin_id;geometry;tile_id
OSM_517924352;POLYGON((2641289.26886243 4582010.12482994,2641299.67723482
4582007.12923406,2641304.17454225 4582019.8887829,2641294.42295486
4582023.47785041,2641291.51751615 4582013.47368108,2641290.54903658
4582013.85519583,2641289.26886243 4582010.12482994));cell_2425278141
...
OSM_585772157;POLYGON((2644395.16 4566329.71,2644395.62 4566343.61,2644412.41
4566343.04,2644411.94 4566329.27,2644406.98 4566329.44,2644406.93 4566328.05,
2644398.08 4566328.24,2644396.22 4566328.38,2644396.26 4566329.68,2644395.16
4566329.71));cell_2430462151
Please note that the delimiter is `;`.
**`-o`, `--export-filepath`**: str, optional
Defines the path to a file, to which, the database exposure model is exported in CSV format.
The exported CSV exposure model file, follows the format below:
`id,lon,lat,taxonomy,number,structural,night,occupancy,admin_name,admin_ID, tile_id,
tile_geometry, building_id ,building_geometry`
Only required when using `export` module.
**`-s`, `--spatialite-extension`**: str, optional
Defines the file path of the spatialite extension. (default: mod_spatialite)
**`-w`** overwrite existing result file: optional
To overwrite an existing exposure model file.
In order to use this program, please note that:
The spacing of the grid is 10 arc-seconds. The tile ID starts from North-West corner of the
world, moves East by row, and finishes at the South-East corner of the world. First tile ID
is 0, last tile ID is 8,398,079,999 (total number of cells is 8,398,080,000).
## Output
### Using import command
The output using import command is a database exposure model file. An example of the database exposure model is available at ....
### Using export command
A CSV exposure model file (OQ-compatible) exported from a database exposure model with headers as below:
`id,lon,lat,taxonomy,number,structural,night,occupancy,admin_name,admin_ID, tile_id,
tile_geometry, building_id ,building_geometry`
Definition of each column of the header is defined above under `-e` input parameter `losscalculator` section.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment