climada.entity.exposures package

climada.entity.exposures.base module

class climada.entity.exposures.base.Exposures(*args, **kwargs)[source]

Bases: geopandas.geodataframe.GeoDataFrame

geopandas GeoDataFrame with metada and columns (pd.Series) defined in Attributes.

tag

metada - information about the source data

Type

Tag

ref_year

metada - reference year

Type

int

value_unit

metada - unit of the exposures values

Type

str

latitude

latitude

Type

pd.Series

longitude

longitude

Type

pd.Series

crs

CRS information inherent to GeoDataFrame.

Type

dict or crs

value

a value for each exposure

Type

pd.Series

if\_

e.g. if_TC. impact functions id for hazard TC. There might be different hazards defined: if_TC, if_FL, … If not provided, set to default ‘if_’ with ids 1 in check().

Type

pd.Series, optional

geometry

geometry of type Point of each instance. Computed in method set_geometry_points().

Type

pd.Series, optional

meta

dictionary containing corresponding raster properties (if any): width, height, crs and transform must be present at least (transform needs to contain upper left corner!). Exposures might not contain all the points of the corresponding raster. Not used in internal computations.

Type

dict

deductible

deductible value for each exposure

Type

pd.Series, optional

cover

cover value for each exposure

Type

pd.Series, optional

category_id

category id for each exposure

Type

pd.Series, optional

region_id

region id for each exposure

Type

pd.Series, optional

centr\_

e.g. centr_TC. centroids index for hazard TC. There might be different hazards defined: centr_TC, centr_FL, … Computed in method assign_centroids().

Type

pd.Series, optional

vars_oblig = ['value', 'latitude', 'longitude']

Name of the variables needed to compute the impact.

vars_def = ['if_']

Name of variables that can be computed.

vars_opt = ['centr_', 'deductible', 'cover', 'category_id', 'region_id', 'geometry']

Name of the variables that aren’t need to compute the impact.

__init__(*args, **kwargs)[source]

Initialize. Copy attributes of input DataFrame.

check()[source]

Check which variables are present

assign_centroids(hazard, method='NN', distance='haversine', threshold=100)[source]

Assign for each exposure coordinate closest hazard coordinate. -1 used for disatances > threshold in point distances. If raster hazard, -1 used for centroids outside raster.

Parameters

  • hazard (Hazard) – hazard to match (with raster or vector centroids)

  • method (str, optional) – interpolation method to use in vector hazard. Nearest neighbor (NN) default

  • distance (str, optional) – distance to use in vector hazard. Haversine default

  • threshold (float) – distance threshold in km over which no neighbor will be found in vector hazard. Those are assigned with a -1. Default 100 km.

set_geometry_points(scheduler=None)[source]

Set geometry attribute of GeoDataFrame with Points from latitude and longitude attributes.

Parameter:
scheduler (str): used for dask map_partitions. “threads”,

“synchronous” or “processes”

set_lat_lon()[source]

Set latitude and longitude attributes from geometry attribute.

set_from_raster(file_name, band=1, src_crs=None, window=False, geometry=False, dst_crs=False, transform=None, width=None, height=None, resampling=<Resampling.nearest: 0>)[source]

Read raster data and set latitude, longitude, value and meta

Parameters

  • file_name (str) – file name containing values

  • band (int, optional) – bands to read (starting at 1)

  • src_crs (crs, optional) – source CRS. Provide it if error without it.

  • window (rasterio.windows.Windows, optional) – window where data is extracted

  • geometry (shapely.geometry, optional) – consider pixels only in shape

  • dst_crs (crs, optional) – reproject to given crs

  • transform (rasterio.Affine) – affine transformation to apply

  • wdith (float) – number of lons for transform

  • height (float) – number of lats for transform

  • resampling (rasterio.warp,.Resampling optional) – resampling function used for reprojection to dst_crs

plot_scatter(mask=None, ignore_zero=False, pop_name=True, buffer=0.0, extend='neither', axis=None, **kwargs)[source]

Plot exposures geometry’s value sum scattered over Earth’s map. The plot will we projected according to the current crs.

Parameters
  • mask (np.array, optional) – mask to apply to eai_exp plotted.

    • ignore_zero (bool, optional) – flag to indicate if zero and negative values are ignored in plot. Default: False

    • pop_name (bool, optional) – add names of the populated places

    • buffer (float, optional) – border to add to coordinates. Default: 0.0.

    • extend (str, optional) – extend border colorbar with arrows. [ ‘neither’ | ‘both’ | ‘min’ | ‘max’ ]

    • axis (matplotlib.axes._subplots.AxesSubplot, optional) – axis to use

    • kwargs (optional) – arguments for scatter matplotlib function, e.g. cmap=’Greys’. Default: ‘Wistia’

Returns:

cartopy.mpl.geoaxes.GeoAxesSubplot

plot_hexbin(mask=None, ignore_zero=False, pop_name=True, buffer=0.0, extend='neither', axis=None, **kwargs)[source]

Plot exposures geometry’s value sum binned over Earth’s map. An other function for the bins can be set through the key reduce_C_function. The plot will we projected according to the current crs.

Parameters
  • mask (np.array, optional) – mask to apply to eai_exp plotted.

    • ignore_zero (bool, optional) – flag to indicate if zero and negative values are ignored in plot. Default: False

    • pop_name (bool, optional) – add names of the populated places

    • buffer (float, optional) – border to add to coordinates. Default: 0.0.

    • extend (str, optional) – extend border colorbar with arrows. [ ‘neither’ | ‘both’ | ‘min’ | ‘max’ ]

    • axis (matplotlib.axes._subplots.AxesSubplot, optional) – axis to use

    • kwargs (optional) – arguments for hexbin matplotlib function, e.g. reduce_C_function=np.average. Default: reduce_C_function=np.sum

Returns:

cartopy.mpl.geoaxes.GeoAxesSubplot

plot_raster(res=None, raster_res=None, save_tiff=None, raster_f=<function Exposures.<lambda>>, label='value (log10)', scheduler=None, axis=None, **kwargs)[source]

Generate raster from points geometry and plot it using log10 scale: np.log10((np.fmax(raster+1, 1))).

Parameters

  • res (float, optional) – resolution of current data in units of latitude and longitude, approximated if not provided.

  • raster_res (float, optional) – desired resolution of the raster

  • save_tiff (str, optional) – file name to save the raster in tiff format, if provided

  • raster_f (lambda function) – transformation to use to data. Default: log10 adding 1.

  • label (str) – colorbar label

  • scheduler (str) – used for dask map_partitions. “threads”, “synchronous” or “processes”

  • axis (matplotlib.axes._subplots.AxesSubplot, optional) – axis to use

  • kwargs (optional) – arguments for imshow matplotlib function

Returns

matplotlib.figure.Figure, cartopy.mpl.geoaxes.GeoAxesSubplot

plot_basemap(mask=None, ignore_zero=False, pop_name=True, buffer=0.0, extend='neither', zoom=10, url='http://tile.stamen.com/terrain/tileZ/tileX/tileY.png', axis=None, **kwargs)[source]

Scatter points over satellite image using contextily

Parameters

  • mask (np.array, optional) – mask to apply to eai_exp plotted. Same size of the exposures, only the selected indexes will be plot.

  • ignore_zero (bool, optional) – flag to indicate if zero and negative values are ignored in plot. Default: False

  • pop_name (bool, optional) – add names of the populated places

  • buffer (float, optional) – border to add to coordinates. Default: 0.0.

  • extend (str, optional) – extend border colorbar with arrows. [ ‘neither’ | ‘both’ | ‘min’ | ‘max’ ]

  • zoom (int, optional) – zoom coefficient used in the satellite image

  • url (str, optional) – image source, e.g. ctx.sources.OSM_C

  • axis (matplotlib.axes._subplots.AxesSubplot, optional) – axis to use

  • kwargs (optional) – arguments for scatter matplotlib function, e.g. cmap=’Greys’. Default: ‘Wistia’

Returns

matplotlib.figure.Figure, cartopy.mpl.geoaxes.GeoAxesSubplot

write_hdf5(file_name)[source]

Write data frame and metadata in hdf5 format

read_hdf5(file_name)[source]

Read data frame and metadata in hdf5 format

read_mat(file_name, var_names={'field_name': 'assets', 'sup_field_name': 'entity', 'var_name': {'ass': 'centroid_index', 'cat': 'Category_ID', 'cov': 'Cover', 'ded': 'Deductible', 'imp': 'DamageFunID', 'lat': 'lat', 'lon': 'lon', 'ref': 'reference_year', 'reg': 'Region_ID', 'uni': 'Value_unit', 'val': 'Value'}})[source]

Read MATLAB file and store variables in exposures.

Parameters

  • file_name (str) – absolute path file

  • var_names (dict, optional) – dictionary containing the name of the MATLAB variables. Default: DEF_VAR_MAT.

to_crs(crs=None, epsg=None, inplace=False)[source]

Transform geometries to a new coordinate reference system.

Transform all geometries in a GeoSeries to a different coordinate reference system. The crs attribute on the current GeoSeries must be set. Either crs in string or dictionary form or an EPSG code may be specified for output.

This method will transform all points in all objects. It has no notion or projecting entire geometries. All segments joining points are assumed to be lines in the current projection, not geodesics. Objects crossing the dateline (or other projection boundary) will have undesirable behavior.

Parameters

  • crs (dict or str) – Output projection parameters as string or in dictionary form.

  • epsg (int) – EPSG code specifying output projection.

  • inplace (bool, optional, default: False) – Whether to return a new GeoDataFrame or do the transformation in place.

copy(deep=True)[source]

Make a copy of this Exposures object.

Parameters

deep (bool) (Make a deep copy, i.e. also copy data. Default True.)

Returns

Return type

Exposures

write_raster(file_name, value_name='value', scheduler=None)[source]

Write value data into raster file with GeoTiff format

Parameters

file_name (str) – name output file in tif format

climada.entity.exposures.base.add_sea(exposures, sea_res)[source]

Add sea to geometry’s surroundings with given resolution. region_id set to -1 and other variables to 0.

Parameters

sea_res (tuple) – (sea_coast_km, sea_res_km), where first parameter is distance from coast to fill with water and second parameter is resolution between sea points

Returns

Exposures

climada.entity.exposures.black_marble module

class climada.entity.exposures.black_marble.BlackMarble(*args, **kwargs)[source]

Bases: climada.entity.exposures.base.Exposures

Defines exposures from night light intensity, GDP and income group. Attribute region_id is defined as: - United Nations Statistics Division (UNSD) 3-digit equivalent numeric code - 0 if country not found in UNSD. - -1 for water

set_countries(countries, ref_year=2016, res_km=None, from_hr=None, **kwargs)[source]

Model countries using values at reference year. If GDP or income group not available for that year, consider the value of the closest available year.

Parameters

  • countries (list or dict) – list of country names (admin0) or dict with key = admin0 name and value = [admin1 names]

  • ref_year (int, optional) – reference year. Default: 2016

  • res_km (float, optional) – approx resolution in km. Default: nightlights resolution.

  • from_hr (bool, optional) – force to use higher resolution image, independently of its year of acquisition.

  • kwargs (optional) – ‘gdp’ and ‘inc_grp’ dictionaries with keys the country ISO_alpha3 code. ‘poly_val’ polynomial transformation [1,x,x^2,…] to apply to nightlight (DEF_POLY_VAL used if not provided). If provided, these are used.

climada.entity.exposures.litpop module

climada.entity.exposures.litpop.LOGGER = <Logger climada.entity.exposures.litpop (INFO)>

Define LitPop class.

climada.entity.exposures.litpop.WORLD_BANK_INC_GRP = 'http://databank.worldbank.org/data/download/site-content/OGHIST.xls'

Income group historical data from World bank.

climada.entity.exposures.litpop.DEF_RES_NASA_KM = 0.5

Default approximate resolution for NASA’s nightlights in km.

climada.entity.exposures.litpop.DEF_RES_GPW_KM = 1

Default approximate resolution for the GPW dataset in km.

climada.entity.exposures.litpop.DEF_RES_NASA_ARCSEC = 15

Default approximate resolution for NASA’s nightlights in arcsec.

climada.entity.exposures.litpop.DEF_RES_GPW_ARCSEC = 30

Default approximate resolution for the GPW dataset in arcsec.

climada.entity.exposures.litpop.DEF_HAZ_TYPE = ''

Default hazard type used in impact functions id, i.e. TC

class climada.entity.exposures.litpop.LitPop(*args, **kwargs)[source]

Bases: climada.entity.exposures.base.Exposures

Defines exposure values from nightlight intensity (NASA), Gridded Population data (SEDAC); distributing produced capital (World Bank), GDP (World Bank) or non-financial wealth (Global Wealth Databook by the Credit Suisse Research Institute.)

Calling sequence example: ent = LitPop() country_name = [‘Switzerland’, ‘Austria’] ent.set_country(country_name) ent.plot()

clear()[source]

Appending the base class clear attribute to also delete attributes which are only used here.

set_country(countries, **args)[source]

Get LitPop based exposre for one country or multiple countries using values at reference year. If produced capital, GDP, or income group, etc. not available for that year, consider the value of the closest available year.

Parameters

countries (str or list) – list of countries or single county as a sting. Countries can either be country names (‘France’) or country codes (‘FRA’), even a mix is possible in the list.

args: Keyword arguments. The following keywords are recognised:

res_km (float, optional): approx resolution in km. Default: 1km. res_arcsec (float, optional): resolution in arc-sec. Overrides

res_km if both are delivered

check_plot (boolean, optional): choose if a plot is shown at the

end of the operation.

exponents (list of two integers, default = [1, 1]) defining

power with which lit (nightlights) and pop (gpw) go into LitPop. To get nightlights^3 alone: [3, 0]. To use population count alone: [0, 1].

fin_mode (str, optional): define what total country economic value

is to be used as an asset base and distributed to the grid: - ‘gdp’: gross-domestic product (Source: World Bank) - ‘income_group’: gdp multiplied by country’s income group+1 - ‘nfw’: non-financial wealth (Source: Credit Suisse, of households only) - ‘tw’: total wealth (Source: Credit Suisse, of households only) - ‘pc’: produced capital (Source: World Bank), incl. manufactured or

built assets such as machinery, equipment, and physical structures (pc is in constant 2014 USD)

  • ‘norm’: normalized by country

  • ‘none’: LitPop per pixel is returned unchanged

admin1_calc (boolean): distribute admin1-level GDP if available?

(default False)

conserve_cntrytotal (boolean): given admin1_calc, conserve national total asset value (default True) reference_year (int) adm1_scatter (boolean): produce scatter plot for admin1 validation?

plot_log(admin1_plot=1)[source]
Plots the LitPop data with the color scale reprenting the values

in a logarithmic scale.

Parameters

admin1_plot (boolean) – whether admin1 borders should be plotted. Default=1

climada.entity.exposures.litpop.read_bm_file(bm_path, filename)[source]

Reads a single NASA BlackMarble GeoTiff and returns the data. Run all required checks first.

Parameters

  • bm_path (str) – absolute path where files are stored.

  • filename (str) – filename of the file to be read.

Returns

Raw BM data curr_file (gdal GeoTiff File): Additional info from which

coordinates can be calculated.

Return type

arr1 (array)

climada.entity.exposures.litpop.get_bm(required_files=array([1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0]), **parameters)[source]

Potential TODO: put cutting before zooming (faster), but with expanding bbox in order to preserve additional pixels for interpolation…

climada.entity.exposures.litpop.admin1_validation(country, methods, exponents, **args)[source]

Get LitPop based exposre for one country or multiple countries using values at reference year. If GDP or income group not available for that year, consider the value of the closest available year.

Parameters

  • country (str) – list of countries or single county as a string. Countries can either be country names (‘France’) or country codes (‘FRA’), even a mix is possible in the list.

  • methods_name (list of str) –

    • [‘LitPop’ for LitPop,

    • [‘Lit’, ‘Pop’] for Lit and Pop,

    • [‘Lit3’] for cube of night lights (Lit3)

  • exponents (list of 2-vectors) –

    • [[1, 1]] for LitPop,

    • [[1, 0], [0, 1]] for Lit and Pop,

    • [[3, 0]] for cube of night lights (Lit3)

args: Keyword arguments. The following keywords are recognised:

res_km (float, optional): approx resolution in km. Default: 1km. res_arcsec (float, optional): resolution in arc-sec. Overrides

res_km if both are delivered

check_plot (boolean, optional): choose if a plot is shown at the

end of the operation.

climada.entity.exposures.litpop.exposure_set_admin1(exposure, res_arcsec)[source]

add admin1 ID and name to exposure dataframe.

Parameters

  • exposure – exposure instance

  • res_arcsec – resolution in arc seconds, needs to match exposure resolution

Returns

exposure instance with 2 extra columns: admin1 & admin1_ID

Return type

exposure

climada.entity.exposures.open_street_map module

climada.entity.exposures.open_street_map.get_features_OSM(bbox, types, save_path='/home/docs/checkouts/readthedocs.org/user_builds/climada-python/checkouts/v1.4.2/doc', check_plot=1)[source]

Get shapes from all types of objects that are available on Open Street Map via an API query and save them as geodataframe.

Parameters

  • bbox (array) – List of coordinates in format [South, West, North, East]

  • types (list) – List of features items that should be downloaded from OSM, e.g. {‘natural’,’waterway’,’water’, ‘landuse=forest’,’landuse=farmland’, ‘landuse=grass’,’wetland’}

  • save_path (str) – String with absolute path for saving output. Default is cwd

  • check_plot – default is 1 (yes), else 0.

Returns

combined GeoDataframe with all features saved as “OSM_features_lat_lon”. Shapefiles with correct geometry (LineStrings,Polygons, MultiPolygons)

for each of requested OSM feature saved as “item_gdf_all_lat_lon”

Return type

OSM_features_gdf_combined(gdf)

Example 1:

Houses_47_8 = get_features_OSM([47.16, 8.0, 47.3, 8.0712], {‘building’}, save_path = save_path, check_plot=1)

Example 2:
Low_Value_gdf_47_8 = get_features_OSM([47.16, 8.0, 47.3, 8.0712], {‘natural’,’water’, ‘waterway’,

‘landuse=forest’, ‘landuse=farmland’, ‘landuse=grass’, ‘wetland’}, save_path = save_path, check_plot=1)

climada.entity.exposures.open_street_map.get_highValueArea(bbox, save_path='/home/docs/checkouts/readthedocs.org/user_builds/climada-python/checkouts/v1.4.2/doc', Low_Value_gdf=None, check_plot=1)[source]

In case low-value features were queried with get_features_OSM(), calculate the “counter-shape” representig high value area for a given bounding box.

Parameters

  • bbox (array) – List of coordinates in format [South, West, North, East]

  • save_path (str) – path for results

  • Low_Value_gdf (str) – absolute path of gdf of low value items which is to be inverted. If left empty, searches for OSM_features_gdf_combined_lat_lon.shp in save_path.

  • checkplot

Returns

GeoDataFrame of High Value Area as High_Value_Area_lat_lon

Return type

High_Value_Area (gdf)

Example

High_Value_gdf_47_8 = get_highValueArea([47.16, 8.0, 47.3, 8.0712], save_path = save_path, Low_Value_gdf = save_path+’/Low_Value_gdf_combined_47_8.shp’)

important: Use same bbox and save_path as for get_features_OSM().

climada.entity.exposures.open_street_map.get_osmstencil_litpop(bbox, country, mode, highValueArea=None, save_path='/home/docs/checkouts/readthedocs.org/user_builds/climada-python/checkouts/v1.4.2/doc', check_plot=1, **kwargs)[source]

Generate climada-compatible exposure by downloading LitPop exposure for a bounding box, corrected for centroids which lie inside a certain high-value multipolygon area from previous OSM query.

Parameters

  • bbox (array) – List of coordinates in format [South, West, North, East]

  • Country (str) – ISO3 code or name of country in which bbox is located

  • highValueArea (str) – path of gdf of high-value area from previous step. If empty, searches for cwd/High_Value_Area_lat_lon.shp

  • mode (str) – mode of re-assigning low-value points to high-value points. “nearest”, “even”, or “proportional”

  • kwargs (dict) – arguments for LitPop set_country method

Returns

(CLIMADA-compatible) with re-allocated asset

values with name exposure_high_lat_lon

Return type

exp_sub_high_exp (Exposure)

Example

exposure_high_47_8 = get_osmstencil_litpop([47.16, 8.0, 47.3, 8.0712], ‘CHE’,”proportional”, highValueArea = save_path + ‘/High_Value_Area_47_8.shp’ , save_path = save_path)

climada.entity.exposures.open_street_map.make_osmexposure(highValueArea, mode='default', country=None, save_path='/home/docs/checkouts/readthedocs.org/user_builds/climada-python/checkouts/v1.4.2/doc', check_plot=1, **kwargs)[source]

Generate climada-compatiple entity by assigning values to midpoints of individual house shapes from OSM query, according to surface area and country.

Parameters

  • highValueArea (str) – absolute path for gdf of building features queried from get_features_OSM()

  • mode (str) – “LitPop” or “default”: Default assigns a value of 5400 Chf to each m2 of building, LitPop assigns total LitPop value for the region proportionally to houses (by base area of house)

  • Country (str) – ISO3 code or name of country in which entity is located. Only if mode = LitPop

  • kwargs (dict) – arguments for LitPop set_country method

Returns

(CLIMADA-compatible) with allocated asset values.

Saved as exposure_buildings_mode_lat_lon.h5

Return type

exp_building (Exposure)

Example

buildings_47_8 = make_osmexposure(save_path+ ‘/OSM_features_47_8.shp’, mode=”default”, save_path = save_path, check_plot=1)