climada.entity.exposures package#

climada.entity.exposures.base module#

class climada.entity.exposures.base.Exposures(*args, meta=None, description=None, ref_year=2018, value_unit='USD', crs=None, **kwargs)[source]#

Bases: object

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

description#

metadata - description of content and origin of the data

Type:

str

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

value#

a value for each exposure

Type:

pd.Series

impf_SUFFIX#

e.g. impf_TC. impact functions id for hazard TC. There might be different hazards defined: impf_TC, impf_FL, … If not provided, set to default impf_ 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_SUFFIX#

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 = ['impf_', '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, meta=None, description=None, ref_year=2018, value_unit='USD', crs=None, **kwargs)[source]#

Creates an Exposures object from a GeoDataFrame

Parameters:
  • args – Arguments of the GeoDataFrame constructor

  • kwargs – Named arguments of the GeoDataFrame constructor, additionally

  • meta (dict, optional) – Metadata dictionary. Default: {} (empty dictionary)

  • description (str, optional) – Default: None

  • ref_year (int, optional) – Reference Year. Defaults to the entry of the same name in meta or 2018.

  • value_unit (str, optional) – Unit of the exposed value. Defaults to the entry of the same name in meta or ‘USD’.

  • crs (object, anything accepted by pyproj.CRS.from_user_input) – Coordinate reference system. Defaults to the entry of the same name in meta, or to the CRS of the GeoDataFrame (if provided) or to ‘epsg:4326’.

check()[source]#

Check Exposures consistency.

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

set_crs(crs=None)[source]#

Set the Coordinate Reference System. If the epxosures GeoDataFrame has a ‘geometry’ column it will be updated too.

Parameters:

crs (object, optional) – anything anything accepted by pyproj.CRS.from_user_input if the original value is None it will be set to the default CRS.

set_gdf(gdf: GeoDataFrame, crs=None)[source]#

Set the gdf GeoDataFrame and update the CRS

Parameters:
  • gdf (GeoDataFrame)

  • crs (object, optional,) – anything anything accepted by pyproj.CRS.from_user_input, by default None, then gdf.crs applies or - if not set - the exposure’s current crs

get_impf_column(haz_type='')[source]#

Find the best matching column name in the exposures dataframe for a given hazard type,

Parameters:

haz_type (str or None) – hazard type, as in the hazard’s.haz_type which is the HAZ_TYPE constant of the hazard’s module

Returns:

a column name, the first of the following that is present in the exposures’ dataframe:

  • impf_[haz_type]

  • if_[haz_type]

  • impf_

  • if_

Return type:

str

Raises:

ValueError – if none of the above is found in the dataframe.

assign_centroids(hazard, distance='euclidean', threshold=100, overwrite=True)[source]#

Assign for each exposure coordinate closest hazard coordinate. The Exposures gdf will be altered by this method. It will have an additional (or modified) column named centr_[hazard.HAZ_TYPE] after the call.

Uses the utility function u_coord.match_centroids. See there for details and parameters.

The value -1 is used for distances larger than threshold in point distances. In case of raster hazards the value -1 is used for centroids outside of the raster.

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

  • distance (str, optional) – Distance to use in case of vector centroids. Possible values are “euclidean”, “haversine” and “approx”. Default: “euclidean”

  • threshold (float) – If the distance (in km) to the nearest neighbor exceeds threshold, the index -1 is assigned. Set threshold to 0, to disable nearest neighbor matching. Default: 100 (km)

  • overwrite (bool) – If True, overwrite centroids already present. If False, do not assign new centroids. Default is True.

See also

climada.util.coordinates.match_grid_points

method to associate centroids to exposure points when centroids is a raster

climada.util.coordinates.match_coordinates

method to associate centroids to exposure points

Notes

The default order of use is:

  1. if centroid raster is defined, assign exposures points to the closest raster point.

  2. if no raster, assign centroids to the nearest neighbor using euclidian metric

Both cases can introduce innacuracies for coordinates in lat/lon coordinates as distances in degrees differ from distances in meters on the Earth surface, in particular for higher latitude and distances larger than 100km. If more accuracy is needed, please use ‘haversine’ distance metric. This however is slower for (quasi-)gridded data, and works only for non-gridded data.

set_geometry_points(scheduler=None)[source]#

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

Parameters:

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

set_lat_lon()[source]#

Set latitude and longitude attributes from geometry attribute.

set_from_raster(*args, **kwargs)[source]#

This function is deprecated, use Exposures.from_raster instead.

classmethod from_raster(file_name, band=1, src_crs=None, window=None, geometry=None, dst_crs=None, transform=None, width=None, height=None, resampling=Resampling.nearest)[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 (list of shapely.geometry, optional) – consider pixels only within these 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

Return type:

Exposures

plot_scatter(mask=None, ignore_zero=False, pop_name=True, buffer=0.0, extend='neither', axis=None, figsize=(9, 13), adapt_fontsize=True, title=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, by default True.

  • 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

  • adapt_fontsize (bool, optional) – If set to true, the size of the fonts will be adapted to the size of the figure. Otherwise the default matplotlib font size is used. Default is True.

  • title (str, optional) – a title for the plot. If not set self.description is used.

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

Return type:

cartopy.mpl.geoaxes.GeoAxesSubplot

plot_hexbin(mask=None, ignore_zero=False, pop_name=True, buffer=0.0, extend='neither', axis=None, figsize=(9, 13), adapt_fontsize=True, title=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, by default True.

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

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

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

  • figsize (tuple) – figure size for plt.subplots Default is (9, 13).

  • adapt_fontsize (bool, optional) – If set to true, the size of the fonts will be adapted to the size of the figure. Otherwise the default matplotlib font size is used. Default is True.

  • title (str, optional) – a title for the plot. If not set self.description is used.

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

Return type:

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), fill=True, adapt_fontsize=True, **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

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

  • fill (bool, optional) – If false, the areas with no data will be plotted in white. If True, the areas with missing values are filled as 0s. The default is True.

  • adapt_fontsize (bool, optional) – If set to true, the size of the fonts will be adapted to the size of the figure. Otherwise the default matplotlib font size is used. Default is True.

  • kwargs (optional) – arguments for imshow matplotlib function

Return type:

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={'attribution': '(C) OpenStreetMap contributors (C) CARTO', 'html_attribution': '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors &copy; <a href="https://carto.com/attributions">CARTO</a>', 'max_zoom': 20, 'name': 'CartoDB.Positron', 'subdomains': 'abcd', 'url': 'https://{s}.basemaps.cartocdn.com/{variant}/{z}/{x}/{y}{r}.png', 'variant': 'light_all'}, 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, by default True.

  • 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 (Any, optional) – image source, e.g., ctx.providers.OpenStreetMap.Mapnik. Default: ctx.providers.CartoDB.Positron

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

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

Return type:

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

write_hdf5(file_name)[source]#

Write data frame and metadata in hdf5 format

Parameters:

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

read_hdf5(*args, **kwargs)[source]#

This function is deprecated, use Exposures.from_hdf5 instead.

classmethod from_hdf5(file_name)[source]#

Read data frame and metadata in hdf5 format

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

  • additional_vars (list) – list of additional variable names to read that are not in exposures.base._metadata

Return type:

Exposures

read_mat(*args, **kwargs)[source]#

This function is deprecated, use Exposures.from_mat instead.

classmethod from_mat(file_name, var_names=None)[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.

Return type:

Exposures

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

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.

Return type:

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

plot(*args, **kwargs)[source]#

Wrapper of the GeoDataFrame.plot() method

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

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

static concat(exposures_list)[source]#

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

centroids_total_value(hazard)[source]#

Compute value of exposures close enough to be affected by hazard

Deprecated since version 3.3: This method will be removed in a future version. Use affected_total_value() instead.

This method computes the sum of the value of all exposures points for which a Hazard centroid is assigned.

Parameters:

hazard (Hazard) – Hazard affecting Exposures

Returns:

Sum of value of all exposures points for which a centroids is assigned

Return type:

float

affected_total_value(hazard: Hazard, threshold_affected: float = 0, overwrite_assigned_centroids: bool = True)[source]#

Total value of the exposures that are affected by at least one hazard event (sum of value of all exposures points for which at least one event has intensity larger than the threshold).

Parameters:
  • hazard (Hazard) – Hazard affecting Exposures

  • threshold_affected (int or float) – Hazard intensity threshold above which an exposures is considere affected. The default is 0.

  • overwrite_assigned_centroids (boolean) – Assign centroids from the hazard to the exposures and overwrite existing ones. The default is True.

Returns:

Sum of value of all exposures points for which a centroids is assigned and that have at least one event intensity above threshold.

Return type:

float

See also

Exposures.assign_centroids

method to assign centroids.

Note

The fraction attribute of the hazard is ignored. Thus, for hazards with fraction defined the affected values will be overestimated.

climada.entity.exposures.base.add_sea(exposures, sea_res, scheduler=None)[source]#

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

Parameters:
  • exposures (Exposures) – the Exposures object without sea surroundings.

  • sea_res (tuple (float,float)) – (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

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

Return type:

Exposures

climada.entity.exposures.base.INDICATOR_IMPF = 'impf_'#

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