========== User Guide ========== Introduction ------------ HazImp is used to simulate the loss of value to structures from natural hazards using vulnerability curves. Generally the input information is hazard, such as a wind speed raster and exposure. The exposure information is currently supplied as a csv file, with structure locations given in latitude and longitude. This is combined with vulnerability curve information, described in an xml file. Figure 1.1 is an example of a vulnerability curve, showing a hazard value of the x-axis and the loss associated with that hazard on the y-axis: .. figure:: ../examples/diagrams/example_vuln_curve.png :align: center *An example vulnerability curve.* HazImp calculates a loss ratio value for each asset, based on the asset's vulnerability and the magnitude of the hazard at the location of the asset. The loss ratio is the cost of repair divided by the total replacement cost of the asset. The loss ratio is also referred to as the damage ratio, or damage index. .. math:: LR = \frac{\mathrm{Repair\: cost}}{\mathrm{Replacement\: cost}} Quick how-to ------------ Follow the install notes in the README.md file. A configuration file can be used to define a HazImp simulation. The configuration file is described using yaml, a data serialisation format. HazImp can also be used by another Python application, by passing the configuration infomation in as a dictionary. For example, to run a wind example do:: cd examples/wind python ../../hazimp/main.py -c wind_v5.yaml The -c specifies the configuration file. HazImp can also be ran in parallel, using mpirun. For example:: mpirun -np 4 python ../../hazimp/main.py -c wind_v5.yaml There are a suite of HazImp tests to test the install and code during software developemnt. To run these, in the root HazImp directory do;:: ./all_tests Templates --------- The simplest way to use HazImp is with a template. There is currently a wind template and a flood template. Templates take into account internal vulnerability curves and the data flow needed to produce loss information, simplifying the configuration file. .. NOTE:: The order of key/value pairs in the sample configuration files is important. The code will raise a `RuntimeError` if the order is incorrect. Wind Template ------------- Given gust information from TCRM and point exposure data the loss associated with each site is calculated using the wind template. Here is the example wind configuration file (from examples/wind), which uses the wind template. .. code-block:: yaml # python hazimp.py -c wind_nc.yaml - template: wind_nc - vulnerability: filename: domestic_wind_vuln_curves.xml vulnerability_set: domestic_wind_2012 vulnerability_method: 'mean' - load_exposure: file_name: WA_Wind_Exposure_2013_Test_only.csv exposure_latitude: LATITUDE exposure_longitude: LONGITUDE - load_wind: file_list: gust01.nc file_format: nc variable: wndgust10m - calc_struct_loss: replacement_value_label: REPLACEMENT_VALUE - save: wind_impact.csv - aggregate: boundaries: SA1_2016_AUST.shp boundarycode: SA1_MAIN16 impactcode: SA1_CODE save: gust01_impact.shp - save_agg: wind_impact_add.csv The first line is a comment, so this is ignored. The rest of the file can be understood by the following key value pairs; *template* The type of template to use. This example describes the *wind_nc* template. *load_exposure* This loads the exposure data. It has 3 sub-sections: *file_name* The name of the csv exposure file to load. The first row of the csv file is the title row. *exposure_latitude* The title of the csv column with latitude values. *exposure_longitude* The title of the csv column with longitude values. There are some pre-requisites for the exposure data. It must have a column called ``WIND_VULNERABILITY_FUNCTION_ID`` which describe the vulnerability functions to be used. It must also have a column called "WIND_VULNERABILITY_SET" which describes the vulnerability set to use (see below for more details). *load_wind* This loads the hazard data. It can have up to three subsections; *file_list* A list of raster wind hazard files (one or more). The file format can be ascii grid, geotiff or netcdf (or potentially any raster format recognised by GDAL, but these are all that have ben tested to date). *file_format* This specifies the data format - specifically used for netcdf, where the string 'nc' should be used. *variable_name* For use when the file format is 'nc'. This specifies the name of the variable in the netcdf file that contains the hazard data. The values in the file must represent ``0.2s gust at 10m height m/s``, since that is the axis of the HazImp wind vulnerability curves. *vulnerability* *filename* The path to a correctly formatted vulnerability curve file. This is an xml file produced using `hazimp_preprocessing/curve_data/create_vuln_xml.py` *vulnerability_set* This defines the suite of vulnerability curves to use. A vulnerability file may contain a large number of different vulnerability functions that can be applied to the same exposure assets. This option defines which set to use from that vulnearbility file. The vulnerability set is used to calculate the ``structural_loss_ratio`` given the ``0.2s gust at 10m height m/s``. *vulnerability_method* Whether to use the mean loss ratio ("mean") or to vary around the mean with standard normal distribution ("normal"), based on the mean value plus a coefficient of variation (CoV). CoV values must be included in the vulnerability curve file, in the form of alpha and beta values (sample mean and standard deviation) *calc_struct_loss* This will multiply the replacement value and the ``structural`` to get the ``structural_loss``. *replacement_value_label* The title of the exposure data column that has the replacement values. *save* The file where the results will be saved. All the results to calculate the damage due to the wind hazard are saved to file. The above example saves to a csv file, since the file name ends in *.csv*. This has the disadvantage of averaging data from multiple wind hazards. The information can also be saved as numpy arrays. This can be done by using the *.npz* extension. This data can be accessed using Python scripts and is not averaged. Output ~~~~~~ HazImp will calculate the loss ratio for each exposure asset and append that value to the record for the asset as the ``structural`` attribute. The resulting data are saved to a csv-format file defined in the configuration file: .. code-block:: yaml - save: wind_impact.csv If the ``calc_struct_loss`` configuration option is included, then HazImp will calculate the loss value as the product of the loss ratio and the replacement value of the asset. This will appear in the output file under the attribute ``structural_loss``, and will be available for inclusion in any aggregation:: - calc_struct_loss: replacement_value_label: REPLACEMENT_VALUE Aggregation ~~~~~~~~~~~ *aggregation* This determines the way HazImp will aggregate results *groupby* The exposure attribute that will be used to aggregate results. It is strongly recommended to use the same attribute as used for the exposure permutation. *kwargs* A list of fields that will be aggregated to the level identified above. Each entry under this section must match an output field (``structural``, ``structural_loss``, ``REPLACEMENT_VALUE``), followed by a Python-style list of statisticts to calculate: e.g. ``mean``, ``std`` or ``sum``:: kwargs: structural: [mean, std] structural_loss: [mean, sum] REPLACEMENT_VALUE: [mean, sum] *save_agg* The file where the aggregated results will be saved. This will save data to a csv-format file:: - save_agg: olwyn_agg.csv This option has only been implemented in the ``wind_nc`` and ``wind_v5`` templates at this time (June 2020). Flood Template - Structural Damage ---------------------------------- The structural damage flood template is very similar to the the wind template. This is an example structural damage flood template;:: # python ../../hazimp/hazimp.py -c list_flood_v2.yaml # Don't have a scenario test automatically run this. # Since the file location is not absolute, - template: flood_fabric_v2 - vulnerability: filename: fabric_flood_vul_curve.xml vulnearbility_set: structural_domestic_flood_2012 - floor_height_(m): .3 - load_exposure: file_name: small_exposure.csv exposure_latitude: LATITUDE exposure_longitude: LONGITUDE - hazard_raster: depth_small_synthetic.txt - calc_struct_loss: replacement_value_label: REPLACEMENT_VALUE - save: flood_impact.csv The first 4 lines are comments, so they are ignored. The new key value pairs are; *floor_height_(m)* This is used to calculate the water depth above ground floor; water depth(m) - floor height(m) = water depth above ground floor(m) *hazard_raster* A list of ascii grid hazard files to load or a single file. The file format is grid ascii. The values in the file must be ``water depth(m)``, since that is the axis of the vulnerability curves. Vulnerability functions ----------------------- See the :ref:`vulnerability` section for guidance on preparing vulnerability functions for use in HazImp. Provenance tracking ------------------- The provenance of information used in generating an impact analysis is tracked using the `Prov `_ module. This information is stored in an xml-format file alongside the other output files. A graphical representation of the connections between the components is also created. Contributions to the code base should incorporate appropriate provenance statements to ensure consistency.