climada.entity.exposures package

climada.entity.exposures.base module

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

Bases: object

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.

property crs

Coordinate Reference System, refers to the crs attribute of the inherent GeoDataFrame

__init__(*args, **kwargs)

Creates an Exposures object from a GeoDataFrame

Parameters

• *args – Arguments of the GeoDataFrame constructor

• **kwargs – Named arguments of the GeoDataFrame constructor, additionally

• tag (climada.entity.exposures.tag.Tag) – Exopusres tag

• ref_year (int) – Reference Year

• value_unit (str) – Unit of the exposed value

• meta (dict) – Metadata dictionary

check()

Check Exposures consistency.

Reports missing columns in log messages. If no if_* column is present in the dataframe, a default column ‘if_’ is added with default impact function id 1.

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

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)

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

Parameters

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

set_lat_lon()

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>)

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, figsize=(9, 13), **kwargs)

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

  • figsize (tuple, optional) – figure size for plt.subplots

  • 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, figsize=(9, 13), **kwargs)

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

  • figsize (tuple) – figure size for plt.subplots

  • 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, figsize=(9, 13), **kwargs)

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

• figsize (tuple, optional) – figure size for plt.subplots

• 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)

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)

Write data frame and metadata in hdf5 format

Parameters

file_name (str) – (path and) file name to write to.

read_hdf5(file_name)

Read data frame and metadata in hdf5 format

Parameters

file_name (str) – (path and) file name to read from.

Optional Parameters:

additional_vars (list): list of additional variable names to read that

are not in exposures.base._metadata

read_mat(file_name, var_names=None)

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)

Wrapper of the GeoDataFrame.to_crs method.

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.

Returns

None if inplace is True else a transformed copy of the exposures object

plot(*args, **kwargs)

Plot a GeoDataFrame.

Generate a plot of a GeoDataFrame with matplotlib. If a column is specified, the plot coloring will be based on values in that column.

Parameters

• df (GeoDataFrame) – The GeoDataFrame to be plotted. Currently Polygon, MultiPolygon, LineString, MultiLineString and Point geometries can be plotted.

• column (str, np.array, pd.Series (default None)) – The name of the dataframe column, np.array, or pd.Series to be plotted. If np.array or pd.Series are used then it must have same length as dataframe. Values are used to color the plot. Ignored if color is also set.

• cmap (str (default None)) – The name of a colormap recognized by matplotlib.

• color (str (default None)) – If specified, all objects will be colored uniformly.

• ax (matplotlib.pyplot.Artist (default None)) – axes on which to draw the plot

• cax (matplotlib.pyplot Artist (default None)) – axes on which to draw the legend in case of color map.

• categorical (bool (default False)) – If False, cmap will reflect numerical values of the column being plotted. For non-numerical columns, this will be set to True.

• legend (bool (default False)) – Plot a legend. Ignored if no column is given, or if color is given.

• scheme (str (default None)) – Name of a choropleth classification scheme (requires mapclassify). A mapclassify.MapClassifier object will be used under the hood. Supported are all schemes provided by mapclassify (e.g. ‘BoxPlot’, ‘EqualInterval’, ‘FisherJenks’, ‘FisherJenksSampled’, ‘HeadTailBreaks’, ‘JenksCaspall’, ‘JenksCaspallForced’, ‘JenksCaspallSampled’, ‘MaxP’, ‘MaximumBreaks’, ‘NaturalBreaks’, ‘Quantiles’, ‘Percentiles’, ‘StdMean’, ‘UserDefined’). Arguments can be passed in classification_kwds.

• k (int (default 5)) – Number of classes (ignored if scheme is None)

• vmin (None or float (default None)) – Minimum value of cmap. If None, the minimum data value in the column to be plotted is used.

• vmax (None or float (default None)) – Maximum value of cmap. If None, the maximum data value in the column to be plotted is used.

• markersize (str or float or sequence (default None)) – Only applies to point geometries within a frame. If a str, will use the values in the column of the frame specified by markersize to set the size of markers. Otherwise can be a value to apply to all points, or a sequence of the same length as the number of points.

• figsize (tuple of integers (default None)) – Size of the resulting matplotlib.figure.Figure. If the argument axes is given explicitly, figsize is ignored.

• legend_kwds (dict (default None)) – Keyword arguments to pass to matplotlib.pyplot.legend() or matplotlib.pyplot.colorbar(). Additional accepted keywords when scheme is specified:

  fmtstring

  A formatting specification for the bin edges of the classes in the legend. For example, to have no decimals: {"fmt": "{:.0f}"}.

  labelslist-like

  A list of legend labels to override the auto-generated labels. Needs to have the same number of elements as the number of classes (k).

• categories (list-like) – Ordered list-like object of categories to be used for categorical plot.

• classification_kwds (dict (default None)) – Keyword arguments to pass to mapclassify

• missing_kwds (dict (default None)) – Keyword arguments specifying color options (as style_kwds) to be passed on to geometries with missing values in addition to or overwriting other style kwds. If None, geometries with missing values are not plotted.

• aspect (‘auto’, ‘equal’ or float (default ‘auto’)) – Set aspect of axis. If ‘auto’, the default aspect for map plots is ‘equal’; if however data are not projected (coordinates are long/lat), the aspect is by default set to 1/cos(df_y * pi/180) with df_y the y coordinate of the middle of the GeoDataFrame (the mean of the y range of bounding box) so that a long/lat square appears square in the middle of the plot. This implies an Equirectangular projection. It can also be set manually (float) as the ratio of y-unit to x-unit.

• **style_kwds (dict) – Style options to be passed on to the actual plot function, such as edgecolor, facecolor, linewidth, markersize, alpha.

Returns

ax

Return type

matplotlib axes instance

copy(deep=True)

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)

Write value data into raster file with GeoTiff format

Parameters

file_name (str) – name output file in tif format

static concat(exposures_list)

Concatenates Exposures or DataFrame objectss to one Exposures object.

Parameters

exposures_list (list of Exposures or DataFrames) – The list must not be empty with the first item supposed to be an Exposures object.

Returns

with the metadata of the first item in the list and the dataframes concatenated.

Return type

Exposures

climada.entity.exposures.base.add_sea(exposures, sea_res)

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.base.INDICATOR_IF = 'if_'

Name of the column containing the impact functions id of specified hazard

climada.entity.exposures.base.INDICATOR_CENTR = 'centr_'

Name of the column containing the centroids id of specified hazard

climada.entity.exposures.black_marble module

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

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, admin_file='admin_0_countries', **kwargs)

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 subunits) 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.

• admin_file (str) – file name, admin_0_countries or admin_0_map_subunits

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

climada.entity.exposures.crop_production module

climada.entity.exposures.crop_production.DEF_HAZ_TYPE = 'RC'

Default hazard type used in impact functions id.

climada.entity.exposures.crop_production.BBOX = [-180, -85, 180, 85]

“Default geographical bounding box of the total global agricultural land extent

climada.entity.exposures.crop_production.YEARCHUNKS = {'ISIMIP2': {'1860soc': {'endyear': 1860, 'startyear': 1661, 'yearrange': (1800, 1860)}, '2005soc': {'endyear': 2299, 'startyear': 2006, 'yearrange': (2006, 2099)}, '2100rcp26soc': {'endyear': 2299, 'startyear': 2100, 'yearrange': (2100, 2299)}, 'histsoc': {'endyear': 2005, 'startyear': 1861, 'yearrange': (1976, 2005)}, 'rcp26soc': {'endyear': 2099, 'startyear': 2006, 'yearrange': (2006, 2099)}, 'rcp60soc': {'endyear': 2099, 'startyear': 2006, 'yearrange': (2006, 2099)}}, 'ISIMIP3': {'2015soc': {'endyear': 2014, 'startyear': 1850, 'yearrange': (1983, 2013)}, 'histsoc': {'endyear': 2014, 'startyear': 1850, 'yearrange': (1983, 2013)}}}

start and end years per ISIMIP version and senario as in ISIMIP-filenames of landuse data containing harvest area per crop

climada.entity.exposures.crop_production.FN_STR_VAR = 'landuse-15crops_annual'

fix filename part in input data

climada.entity.exposures.crop_production.CROP_NAME = {'mai': {'fao': 'Maize', 'input': 'maize', 'print': 'Maize'}, 'ri1': {'fao': 'Rice, paddy', 'input': 'rice', 'print': 'Rice 1st season'}, 'ri2': {'fao': 'Rice, paddy', 'input': 'rice', 'print': 'Rice 2nd season'}, 'ric': {'fao': 'Rice, paddy', 'input': 'rice', 'print': 'Rice'}, 'soy': {'fao': 'Soybeans', 'input': 'oil_crops_soybean', 'print': 'Soybeans'}, 'swh': {'fao': 'Wheat', 'input': 'temperate_cereals', 'print': 'Spring Wheat'}, 'whe': {'fao': 'Wheat', 'input': 'temperate_cereals', 'print': 'Wheat'}, 'wwh': {'fao': 'Wheat', 'input': 'temperate_cereals', 'print': 'Winter Wheat'}}

mapping of crop names

climada.entity.exposures.crop_production.IRR_NAME = {'combined': {'name': 'combined'}, 'firr': {'name': 'irrigated'}, 'noirr': {'name': 'rainfed'}}

Conversion factor weight [tons] to nutritional value [kcal]. Based on Mueller et al. (2021), https://doi.org/10.1088/1748-9326/abd8fc :

“For the aggregation of different crops, we compute total calories, assuming net water contents of 12% for maize, spring and winter wheat, 13% for rice and 9% for soybean, according to Wirsenius (2000) and caloric contents of the “as purchased” biomass (i.e. including the water content) of 3.56kcal/g for maize, 2.8kcal/g for rice, 3.35kcal/g for soybean and of 3.34kcal/g for spring and winter wheat, following FAO (2001).” (Müller et al., 2021)

Version 1: conversion factors for crop biomass “as purchased”,

here applied as default for FAO-normalized production: Production [kcal] = Production [t] * KCAL_PER_TON [kcal/t]

climada.entity.exposures.crop_production.YEARS_FAO = (2008, 2018)

Default years from FAO used (data file contains values for 1991-2018)

class climada.entity.exposures.crop_production.CropProduction(*args, **kwargs)

Bases: climada.entity.exposures.base.Exposures

Defines agriculture exposures from ISIMIP input data and FAO crop data

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

crop

crop typee.g., ‘mai’, ‘ric’, ‘whe’, ‘soy’

Type

str

set_from_isimip_netcdf(input_dir=None, filename=None, hist_mean=None, bbox=None, yearrange=None, cl_model=None, scenario=None, crop=None, irr=None, isimip_version=None, unit=None, fn_str_var=None)

Wrapper to fill exposure from NetCDF file from ISIMIP. Requires historical mean relative cropyield module as additional input. Optional Parameters:

input_dir (Path or str): path to input data directory,

default: {CONFIG.exposures.crop_production.local_data}/Input/Exposure

filename (string): name of the landuse data file to use,

e.g. “histsoc_landuse-15crops_annual_1861_2005.nc””

hist_mean (str or array): historic mean crop yield per centroid (or path) bbox (list of four floats): bounding box:

[lon min, lat min, lon max, lat max]

yearrange (int tuple): year range for exposure set

e.g., (1990, 2010)

scenario (string): climate change and socio economic scenario

e.g., ‘1860soc’, ‘histsoc’, ‘2005soc’, ‘rcp26soc’,’rcp60soc’,’2100rcp26soc’

cl_model (string): abbrev. climate model (only for future projections of lu data)

e.g., ‘gfdl-esm2m’, ‘hadgem2-es’, ‘ipsl-cm5a-lr’,’miroc5’

crop (string): crop type

e.g., ‘mai’, ‘ric’, ‘whe’, ‘soy’

irr (string): irrigation type, default: ‘combined’

f.i ‘firr’ (full irrigation), ‘noirr’ (no irrigation) or ‘combined’= firr+noirr

isimip_version(str): ‘ISIMIP2’ (default) or ‘ISIMIP3’ unit (string): unit of the exposure (per year)

f.i ‘t/y’ (default), ‘USD/y’, or ‘kcal/y’

fn_str_var (string): FileName STRing depending on VARiable and

ISIMIP simuation round

Returns

Exposure

set_mean_of_several_isimip_models(input_dir=None, hist_mean=None, bbox=None, yearrange=None, cl_model=None, scenario=None, crop=None, irr=None, isimip_version=None, unit=None, fn_str_var=None)

Wrapper to fill exposure from several NetCDF files with crop yield data from ISIMIP.

Optional Parameters:

input_dir (string): path to input data directory historic mean (array): historic mean crop production per centroid bbox (list of four floats): bounding box:

[lon min, lat min, lon max, lat max]

yearrange (int tuple): year range for exposure set,e.g., (1976, 2005) scenario (string): climate change and socio economic scenario

e.g., ‘histsoc’ or ‘rcp60soc’

cl_model (string): abbrev. climate model (only when landuse data is future projection)

e.g., ‘gfdl-esm2m’ etc.

crop (string): crop type

e.g., ‘mai’, ‘ric’, ‘whe’, ‘soy’

irr (string): irrigation type

f.i ‘rainfed’, ‘irrigated’ or ‘combined’= rainfed+irrigated

isimip_version(str): ‘ISIMIP2’ (default) or ‘ISIMIP3’ unit (string): unit of the exposure (per year)

f.i ‘t/y’ (default), ‘USD/y’, or ‘kcal/y’

fn_str_var (string): FileName STRing depending on VARiable and

ISIMIP simuation round

Returns

Exposure

set_value_to_kcal(biomass=True)

Converts the exposure value from tonnes to kcalper year using conversion factor per crop type.

Optional Parameter:

biomass (bool): if true, KCAL_PER_TON[‘biomass’] is used (default,

for FAO normalized crop production). If False, KCAL_PER_TON[‘drymatter’] is used (best for crop model output in dry matter, default for raw crop model output)

Returns

Exposure with unit kcal/y

set_value_to_usd(input_dir=None, yearrange=None)

Calculates the exposure in USD using country and year specific data published by the FAO.

Optional Parameters:

input_dir (Path or str): directory containing the input (FAO pricing) data,

default: {CONFIG.exposures.crop_production.local_data}/Input/Exposure

yearrange (array): year range for prices, can also be set to a single year

Default is set to the arbitrary time range (2000, 2018) The data is available for the years 1991-2018

crop (str): crop type

e.g., ‘mai’, ‘ric’, ‘whe’, ‘soy’

Returns

Exposure

aggregate_countries()

Aggregate exposure data by country.

Returns

country codes (numerical ISO3) country_values (array): aggregated exposure value

Return type

list_countries (list)

climada.entity.exposures.crop_production.init_full_exp_set_isimip(input_dir=None, filename=None, hist_mean_dir=None, output_dir=None, bbox=None, yearrange=None, unit=None, isimip_version=None, return_data=False)

Generates CropProduction instances (exposure sets) for all files found in the

input directory and saves them as hdf5 files in the output directory. Exposures are aggregated per crop and irrigation type.

Parameters: input_dir (str or Path): path to input data directory,

default: {CONFIG.exposures.crop_production.local_data}/Input/Exposure

filename (string): if not specified differently, the file

‘histsoc_landuse-15crops_annual_1861_2005.nc’ will be used

output_dir (string): path to output data directory bbox (list of four floats): bounding box:

[lon min, lat min, lon max, lat max]

yearrange (array): year range for hazard set, e.g., (1976, 2005) isimip_version(str): ‘ISIMIP2’ (default) or ‘ISIMIP3’ unit (str): unit in which to return exposure (e.g., t/y or USD/y) return_data (boolean): returned output

False: returns list of filenames only, True: returns also list of data

Returns

all filenames of saved initiated exposure files output_list (list): list containing all inisiated Exposure instances

Return type

filename_list (list)

climada.entity.exposures.crop_production.normalize_with_fao_cp(exp_firr, exp_noirr, input_dir=None, yearrange=None, unit=None, return_data=True)

Normalize (i.e., bias correct) the given exposures countrywise with the mean crop production quantity documented by the FAO. Refer to the beginning of the script for guidance on where to download the required crop production data from FAO.Stat.

Parameters

• exp_firr (crop_production) – exposure under full irrigation

• exp_noirr (crop_production) – exposure under no irrigation

Optional Parameters:

input_dir (Path or str): directory containing exposure input data,

default: {CONFIG.exposures.crop_production.local_data}/Input/Exposure

yearrange (array): the mean crop production in this year range is used to normalize

the exposure data Default is set to the arbitrary time range (2008, 2018) The data is available for the years 1961-2018

unit (str): unit in which to return exposure (t/y or USD/y) return_data (boolean): returned output

True: returns country list, ratio = FAO/ISIMIP, normalized exposures, crop production per country as documented by the FAO and calculated by the ISIMIP dataset False: country list, ratio = FAO/ISIMIP, normalized exposures

Returns

List of country codes (numerical ISO3) ratio (list): List of ratio of FAO crop production and aggregated exposure

for each country

exp_firr_norm (CropProduction): Normalized CropProduction (full irrigation) exp_noirr_norm (CropProduction): Normalized CropProduction (no irrigation)

Return type

country_list (list)

Returns (optional):

fao_crop_production (list): FAO crop production value per country exp_tot_production(list): Exposure crop production value per country

(before normalization)

climada.entity.exposures.crop_production.normalize_several_exp(input_dir=None, output_dir=None, yearrange=None, unit=None, return_data=True)

Multiple exposure sets saved as HDF5 files in input directory are normalized (i.e. bias corrected) against FAO statistics of crop production.

Optional Parameters:

input_dir (Path or str): directory containing exposure input data output_dir (Path or str): directory containing exposure datasets (output of

exposure creation)

yearrange (array): the mean crop production in this year range is used to normalize

the exposure data (default 2008-2018)

unit (str): unit in which to return exposure (t/y or USD/y) return_data (boolean): returned output

True: lists containing data for each exposure file. Lists: crops, country list,

ratio = FAO/ISIMIP, normalized exposures, crop production per country as documented by the FAO and calculated by the ISIMIP dataset

False: lists containing data for each exposure file. Lists: crops, country list,

ratio = FAO/ISIMIP, normalized exposures

Returns:

crop_list (list): List of crops country_list (list): List of country codes (numerical ISO3) ratio (list): List of ratio of FAO crop production and aggregated exposure

for each country

exp_firr_norm (list): List of normalized CropProduction Exposures (full irrigation) exp_noirr_norm (list): List of normalize CropProduction Exposures (no irrigation)

Returns (optional):

fao_crop_production (list): FAO crop production value per country exp_tot_production(list): Exposure crop production value per country

(before normalization)

climada.entity.exposures.crop_production.semilogplot_ratio(crop, countries, ratio, output_dir=None, save=True)

Plot ratio = FAO/ISIMIP against country codes.

Parameters

• crop (str) – crop to plot

• countries (list) – country codes of countries to plot

• ratio (array) – ratio = FAO/ISIMIP crop production data of countries to plot

Optional Parameters:

save (boolean): True saves figure, else figure is not saved. output_dir (str): directory to save figure

Returns

fig (plt figure handle) axes (plot axes handle)

climada.entity.exposures.gdp_asset module

class climada.entity.exposures.gdp_asset.GDP2Asset(*args, **kwargs)

Bases: climada.entity.exposures.base.Exposures

set_countries(countries=[], reg=[], ref_year=2000, path=None)

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) – list of country names ISO3

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

• path (string) – path to exposure dataset (ISIMIP)

climada.entity.exposures.gpw_import module

climada.entity.exposures.gpw_import.check_bounding_box(coord_list)

Check if a bounding box is valid. :Parameters: coord_list (4x1 array) – bounding box to be checked.

OUTPUT:

isCorrectType (boolean): True if bounding box is valid, false otehrwise

climada.entity.exposures.gpw_import.get_box_gpw(**parameters)

Reads data from GPW GeoTiff file and cuts out the data along a chosen

bounding box.

Parameters

• gpw_path (pathlib.Path) – Absolute path where files are stored. Default: SYSTEM_DIR

• resolution (int) – The resolution in arcsec in which the data output is created.

• country_cut_mode (int) – Defines how the country is cut out: If 0, the country is only cut out with a bounding box. If 1, the country is cut out along it’s borders Default: 0. #TODO: Unimplemented

• cut_bbox (array-like, shape (1,4)) – Bounding box (ESRI type) to be cut out. The layout of the bounding box corresponds to the bounding box of the ESRI shape files and is as follows: [minimum longitude, minimum latitude, maximum longitude, maxmimum latitude] If country_cut_mode = 1, the cut_bbox is overwritten/ignored.

• return_coords (int) – Determines whether latitude and longitude are delievered along with gpw data (0) or only gpw_data is returned. Default: 0.

• add_one (boolean) – Determine whether the integer one is added to all cells to eliminate zero pixels. Default: 0. #TODO: Unimplemented

• reference_year (int) – reference year, available years are: 2000, 2005, 2010, 2015 (default), 2020

Returns

• tile_temp (pandas.arrays.SparseArray) – GPW data

• lon (list) – List with longitudinal infomation on the GPW data. Same dimensionality as tile_temp (only returned if return_coords is 1).

• lat (list) – list with latitudinal infomation on the GPW data. Same dimensionality as tile_temp (only returned if return_coords is 1).

climada.entity.exposures.litpop module

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

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()

set_country(countries, **args)

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)

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.nightlight module

climada.entity.exposures.nightlight.NOAA_SITE = 'https://ngdc.noaa.gov/eog/data/web_data/v4composites/'

NOAA’s URL used to retrieve nightlight satellite images.

climada.entity.exposures.nightlight.NOAA_RESOLUTION_DEG = 0.008333333333333333

NOAA nightlights coordinates resolution in degrees.

climada.entity.exposures.nightlight.NASA_RESOLUTION_DEG = 0.004166666666666667

NASA nightlights coordinates resolution in degrees.

climada.entity.exposures.nightlight.NASA_TILE_SIZE = (21600, 21600)

NASA nightlights tile resolution.

climada.entity.exposures.nightlight.NOAA_BORDER = (-180, -65, 180, 75)

NOAA nightlights border (min_lon, min_lat, max_lon, max_lat)

climada.entity.exposures.nightlight.NASA_SITE = 'https://www.nasa.gov/specials/blackmarble/*/tiles/georeferrenced/'

NASA nightlight web url.

climada.entity.exposures.nightlight.BM_FILENAMES = ['BlackMarble_*_A1_geo_gray.tif', 'BlackMarble_*_A2_geo_gray.tif', 'BlackMarble_*_B1_geo_gray.tif', 'BlackMarble_*_B2_geo_gray.tif', 'BlackMarble_*_C1_geo_gray.tif', 'BlackMarble_*_C2_geo_gray.tif', 'BlackMarble_*_D1_geo_gray.tif', 'BlackMarble_*_D2_geo_gray.tif']

Nightlight NASA files which generate the whole earth when put together.

climada.entity.exposures.nightlight.check_required_nl_files(bbox, *coords)

Determines which of the satellite pictures are necessary for

a certain bounding box (e.g. country)

Parameters

• either –

  bbox (1x4 tuple): bounding box from shape (min_lon, min_lat,

  max_lon, max_lat)

• or – min_lon (float): (=min_lon) Western-most point in decimal degrees min_lat (float): Southern-most point in decimal degrees max_lon (float): Eastern-most point in decimal degrees max_lat (float): Northern-most point in decimal degrees

Returns

Array indicating the required files for the current

operation with a Boolean value (1: file is required, 0: file is not required).

Return type

req_files (array)

climada.entity.exposures.nightlight.check_nl_local_file_exists(required_files=array([1., 1., 1., 1., 1., 1., 1., 1.]), check_path=PosixPath('/home/docs/climada/data'), year=2016)

Checks if BM Satellite files are avaialbe and returns a vector denoting the missing files.

Parameters

• check_path (str or Path) – absolute path where files are stored. Default: SYSTEM_DIR

• required_files (array) – Boolean array of dimension (8,) with which some files can be skipped. Only files with value 1 are checked, with value zero are skipped

• year (int) – year of the image

Returns

Denotes if the all required files exist

(Boolean values)

Return type

files_exist (array)

climada.entity.exposures.nightlight.download_nl_files(req_files=array([1., 1., 1., 1., 1., 1., 1., 1.]), files_exist=array([0., 0., 0., 0., 0., 0., 0., 0.]), dwnl_path=PosixPath('/home/docs/climada/data'), year=2016)

Attempts to download nightlight files from NASA webpage.

Parameters

• req_files (array) – Boolean array which indicates the files required for the current operation (0-> skip, 1-> download). Can be obtained by check_required_nightlight_files

• files_exists (array) – Boolean array which indicates if the files already exist locally and should not be downloaded (0-> download, 1-> skip). Can be obtained by function check_nightlight_local_file_exists

• dwnl_path (str)

Returns

Path to download directory.

Return type

path_str (Path)

climada.entity.exposures.nightlight.load_nightlight_nasa(bounds, req_files, year)

Get nightlight from NASA repository that contain input boundary.

Parameters

• bounds (tuple) – min_lon, min_lat, max_lon, max_lat

• req_files (np.array) – array with flags for NASA files needed

• year (int) – nightlight year

Returns

nightlight (sparse.csr_matrix), coord_nl (np.array)

climada.entity.exposures.nightlight.unzip_tif_to_py(file_gz)

Unzip image file, read it, flip the x axis, save values as pickle and remove tif.

Parameters

file_gz (str) – file fith .gz format to unzip

Returns

str (file_name of unzipped file) sparse.csr_matrix (nightlight)

climada.entity.exposures.nightlight.untar_noaa_stable_nightlight(f_tar_ini)

Move input tar file to SYSTEM_DIR and extract stable light file. Returns absolute path of stable light file in format tif.gz.

Parameters

f_tar_ini (str) – absolute path of file

Returns

f_tif_gz (str)

climada.entity.exposures.nightlight.load_nightlight_noaa(ref_year=2013, sat_name=None)

Get nightlight luminosites. Nightlight matrix, lat and lon ordered such that nightlight[1][0] corresponds to lat[1], lon[0] point (the image has been flipped).

Parameters

• ref_year (int) – reference year

• sat_name (str, optional) – satellite provider (e.g. ‘F10’, ‘F18’, …)

Returns

nightlight (sparse.csr_matrix), coord_nl (np.array), fn_light (str)

climada.entity.exposures.open_street_map module

climada.entity.exposures.open_street_map.get_features_OSM(bbox, types, save_path=None, check_plot=1)

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 or pathlib.Path) – 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=None, Low_Value_gdf=None, check_plot=1)

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 or pathlib.Path) – 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=None, check_plot=1, **kwargs)

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=None, check_plot=1, **kwargs)

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)

climada.entity.exposures.spam_agrar module

climada.entity.exposures.spam_agrar.DEF_HAZ_TYPE = 'CP'

Default hazard type used in impact functions id.

climada.entity.exposures.spam_agrar.FILENAME_SPAM = 'spam2005V3r2_global'

Add Docstring!

Type

TODO

climada.entity.exposures.spam_agrar.FILENAME_CELL5M = 'cell5m_allockey_xy.csv'

Add Docstring!

Type

TODO

climada.entity.exposures.spam_agrar.FILENAME_PERMALINKS = 'spam2005V3r2_download_permalinks.csv'

Add Docstring!

Type

TODO

climada.entity.exposures.spam_agrar.BUFFER_VAL = -340282306073709652508363335590014353408

Hard coded value which is used for NANs in original data

climada.entity.exposures.spam_agrar.SPAM_URL = 'https://dataverse.harvard.edu/api/access/datafile/:persistentId?persistentId=doi:10.7910/DVN/DHXBJX/'

URL stem for accessing data set files through api

climada.entity.exposures.spam_agrar.SPAM_DATASET = 'https://dataverse.harvard.edu/dataset.xhtml?persistentId=doi:10.7910/DVN/DHXBJX'

Data files can be downloaded from this location if api access fails

class climada.entity.exposures.spam_agrar.SpamAgrar(*args, **kwargs)

Bases: climada.entity.exposures.base.Exposures

Defines agriculture exposures from SPAM (Global Spatially-Disaggregated Crop Production Statistics Data for 2005 Version 3.2 ) https://dataverse.harvard.edu/dataset.xhtml?persistentId=doi:10.7910/DVN/DHXBJX

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

init_spam_agrar(**parameters)

initiates agriculture exposure from SPAM data:

https://dataverse.harvard.edu/ dataset.xhtml?persistentId=doi:10.7910/DVN/DHXBJX

Optional parameters:

data_path (str): absolute path where files are stored.

Default: SYSTEM_DIR

country (str): Three letter country code of country to be cut out.

No default (global)

name_adm1 (str): Name of admin1 (e.g. Federal State) to be cut out.

No default

name_adm2 (str): Name of admin2 to be cut out.

No default

spam_variable (str): select one agricultural variable:

‘A’ physical area ‘H’ harvested area ‘P’ production ‘Y’ yield ‘V_agg’ value of production, aggregated to all crops,

food and non-food (default)

Warning: for A, H, P and Y, currently all crops are summed up

spam_technology (str): select one agricultural technology type:

‘TA’ all technologies together, ie complete crop (default) ‘TI’ irrigated portion of crop ‘TH’ rainfed high inputs portion of crop ‘TL’ rainfed low inputs portion of crop ‘TS’ rainfed subsistence portion of crop ‘TR’ rainfed portion of crop (= TA - TI, or TH + TL + TS) ! different impact_ids are assigned to each technology (1-6)

save_name_adm1 (Boolean): Determines how many aditional data are saved:

False: only basics (lat, lon, total value), region_id per country True: like 1 + name of admin1

haz_type (str): hazard type abbreviation, e.g.

‘DR’ for Drought or ‘CP’ for CropPotential

Returns: