Commit 836f70c8 authored by Tara Evaz Zadeh's avatar Tara Evaz Zadeh
Browse files

Added manual for damage calculation

parent 7a7f812f
Pipeline #19748 passed with stage
in 1 minute and 42 seconds
# losscalculator
This program computes the probabilities of occurrence (PoE) of damage states for real or scenario
earthquakes, given a ground-motion field, an exposure model representing the assets in the
region of interest and fragility functions that model the probability of exceeding defined
damage states given a set of ground-motion values of a specific type.
## Terminology
**Asset:**
An asset is something of value, which can include buildings and population. For example, an asset can include an individual building at a given location, or a number of buildings that are grouped and co-located at a single location and are classified with the same taxonomy. Please note that, due to probabilistic assessment of building types, each building’s structural types can be represented by a different asset with the respective frequency.
**Exposure model:**
A set of assets grouped together, according to their geographical location, taxonomy and value. Each line of the exposure model file represents information for an asset.
**Fragility function:**
The probability of exceeding a set of damage states, given a set of ground-motion values of a specific type. These functions are defined in csv files.
**Ground-motion field:**
The geographic distribution of ground-motion values (of a real or scenario earthquake).
**Damage states:**
Damage states describe some predefined types and extent of damage which structures can experience after an earthquake. The damage states used in this program are defined by the fragility functions. Often, these are _slight_, _moderate_, _extensive_ and _complete_. Please note that this program computes damage for only four damage states (probabilities of exceeding four damage states is calculated regardless of the damage states names in the fragility functions, but the result file header for the number of buildings of each damage states remain as: structural_no_damage, structural_slight, structural_moderate, structural_extensive and structural_complete)
**Taxonomy:**
Schema used to classify assets. For buildings, the classification schema considers a number of attributes including lateral-load resisting system and the building’s material, height and year of construction. Please see the [GEM taxonomy](https://taxonomy.openquake.org/) for a good example.
Definitions in this terminology section are taken from the `Glossary` section of the [OpenQuake documentation](https://docs.openquake.org/manuals/OpenQuake%20Manual%20%28latest%29.pdf).
## Usage
To run the program please call:
`python3 damage_calculator.py [OPTIONS] -c filepath -e filepath -f pathname -g filepath -p filepath -t filepath`
Use
`python3 damage_calculator.py --help`
for information on how to use the program input options.
## Program input parameters
### Required parameters
**`-e`, `--exposure=filepath`**
Defines the path to the exposure model file.
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,
402000.816015,0.0,Ind,Oropos,GR_3514913,OSM_502509057
GDE_Ind_8345,23.6835236228,38.2808067265,CR/LFM+CDM/H:2,0.225062972292,
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:
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).
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.
lon:
Longitude of the asset (centroid of either a building or a cell, depending on the exposure type).
lat:
Latitude of the asset (centroid of either a building or a cell, depending on the exposure type).
taxonomy:
Explained above in Section `Terminology`.
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.
structural:
Reconstruction cost of the asset in an undefined currency. The user needs to make sure that only one currency is used.
night:
Number of people expected at night-time in the asset (building).
occupancy:
Occupancy type of the asset. Common types are _industrial_, _commercial_, and _residential_, but other types are possible.
admin_name:
Name of the administrative unit of the asset location.
admin_id:
ID of the administrative unit of the asset location.
origin_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.
**`-c`, `--cell-ids=filepath`**
Defines the path to the file that contains the exposure model cell IDs.
File example extract:
unique_cell_ids
cell_2423204507
cell_2423204508
...
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`**
Path to the directory with fragility-function files.
Please note that this option points to a directory containing all the fragility-function files related to the taxonomies used in the computation.
Fragility-function file example extract:
PGA,0.050000 ,0.052179 ,0.054454 ,0.056827 ,... ,3.271841 ,3.414451
slight,0.000000 ,0.000000 ,0.000000 ,0.000000 ,... ,0.873138 ,0.887882
moderate,0.000000 ,0.000000 ,0.000000 ,0.000000 ,... ,0.440287 ,0.469610
extensive,0.000000 ,0.000000 ,0.000000 ,0.000000 ,... ,0.222803 ,0.245484
complete,0.000000 ,0.000000 ,0.000000 ,0.000000 ,... ,0.121331 ,0.136897
In a fragility function, sets of probabilities of exceedance (one row per damage state) are defined for a set of ground-motion values (first row).
Each fragility function can be defined based on any ground-motion type such as `PGA`, `SA(0.3)`, `SA(0.6)`, `SA(1.0)` etc.
**`-t` `--taxonomy-map=filepath`**
Path to the file that maps taxonomies to their relevant fragility-function names. Knowing `taxonomy` of an asset, the relevant fragility-function file name can be created by adding a `.csv` extension to the fragility-function names (2nd column in the taxonomy-mapping file).
File example extract:
taxonomy,fragility_function_name
CR/LDUAL+CDM/HBET:6-/11.0,CR_LDUAL-DUM_H6
CR/LDUAL+CDM/HBET:6-/5.0,CR_LDUAL-DUL_H6
...
CR/LDUAL+CDM/HBET:6-/SOS/11.0,CR_LDUAL-DUL_H6
**`-g` `--ground-motion-field=filepath`**
Path to the file that contains the ground-motion field.
The ground-motion field needs to include values for all ground-motion types present in all fragility functions used for a computation.
File example extract:
lon,lat,gmv_PGA,gmv_SA(0.3),gmv_SA(0.6),gmv_SA(1.0)
23.62917,38.06528,0.1291617,0.2559737,0.1626296,0.08834055
...
23.63472,38.05972,0.1246124,0.2471472,0.1570672,0.08533953
The ground-motion values at asset locations are estimated through interpolation, thus the ground-motion field needs to extend further around the the asset locations.
## Optional Parameters
**`-h`, `--help`**
Provides information on the inputs and terminates the program.
**`-i`, `--interpolation-method={linear, nearest, cubic}`**
Defines the method for interpolating ground-motion values. Default is `linear`.
The ground-motion values are interpolated at the asset locations using this method.
**`-o`, `--overwrite`**
If set, an existing result file will be overwritten, otherwise the program will terminate.
**`-r` `--results=filepath`**
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
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
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
...
### Output information definition
**`geometry`:**
Well-Known-Text representation of the geometry of either a building or a cell, depending on the input exposure type.
**`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`:**
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.
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:
SA(0.3),0.018144 ,0.019294 ,0.020518...
slight,0.000000 ,0.000000 ,0.000000 ...
moderate,0.000000 ,0.000000 ,0.000000 ...
extensive,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.
**`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.
**`PoO`:**
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:
PoO[_no damage_] = 1 – PoE[_slight_]
PoO[_slight_] = PoE[_slight_] - PoE[_moderate_]
PoO[_moderate_] = PoE[_moderate_] - PoE[_extensive_]
PoO[_extensive_] = PoE[_extensive_] - PoE[_complete_]
PoO[_complete_] = PoE[_complete_]
**`num_buildings`:**
Number of buildings for the given asset.
**`structural_no_damage`:**
Number of structural undamaged buildings for the given asset.
**`structural_slight`:**
Number of structural slightly-damaged buildings for the given asset.
**`structural_moderate`:**
Number of structural moderately-damaged buildings for the given asset.
**`structural_extensive`:**
Number of structural extensively-damaged buildings for the given asset.
**`structural_complete`:**
Number of structural completely-damaged buildings for the given asset.
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