climada.entity.exposures package

climada.entity.exposures package#

climada.entity.exposures.litpop package

climada.entity.exposures.base module#

class climada.entity.exposures.base.Exposures(data=None, index=None, columns=None, dtype=None, copy=False, geometry=None, crs=None, meta=None, description=None, ref_year=None, value_unit=None, value=None, lat=None, lon=None)[source]#

Bases: object

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

description#

metadata - description of content and origin of the data

Type:: str

ref_year#

metadata - reference year

Type:: int

value_unit#

metadata - unit of the exposures values

Type:: str

data#

containing at least the columns ‘geometry’ and ‘value’ for locations and assets optionally more, a.o., ‘region_id’, ‘category_id’, columns for (hazard specific) assigned centroids and (hazard specific) impact funcitons.

Type:: GeoDataFrame

vars_oblig = ['value', 'geometry']#: 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

property gdf#: Inherent GeoDataFrame

property latitude#: Latitude array of exposures

property longitude#: Longitude array of exposures

property geometry#: Geometry array of exposures

property value#: Geometry array of exposures

property region_id#

Region id for each exposure

Return type:: np.array of int

property category_id#

Category id for each exposure

Return type:: np.array

property cover#

Cover value for each exposures

Return type:: np.array of float

property deductible#

Deductible value for each exposures

Return type:: np.array of float

hazard_impf(haz_type='')[source]#

Get impact functions for a given hazard

Parameters:: haz_type (str) – hazard type, as in the hazard’s.haz_type which is the HAZ_TYPE constant of the hazard’s module
Returns:: impact functions for the given hazard
Return type:: np.array of int

hazard_centroids(haz_type='')[source]#

Get centroids for a given hazard

Parameters:: haz_type (str) – hazard type, as in the hazard’s.haz_type which is the HAZ_TYPE constant of the hazard’s module
Returns:: centroids index for the given hazard
Return type:: np.array of int

derive_raster()[source]#: Metadata dictionary, containing raster information, derived from the geometry

__init__(data=None, index=None, columns=None, dtype=None, copy=False, geometry=None, crs=None, meta=None, description=None, ref_year=None, value_unit=None, value=None, lat=None, lon=None)[source]#

Parameters:

data (dict, iterable, DataFrame, GeoDataFrame, ndarray) – data of the initial DataFrame, see pandas.DataFrame(). Used to initialize values for “region_id”, “category_id”, “cover”, “deductible”, “value”, “geometry”, “impf_[hazard type]”.
columns (Index or array, optional) – Columns of the initial DataFrame, see pandas.DataFrame(). To be provided if data is an array
index (Index or array, optional) – Columns of the initial DataFrame, see pandas.DataFrame(). can optionally be provided if data is an array or for defining a specific row index
dtype (dtype, optional) – data type of the initial DataFrame, see pandas.DataFrame(). Can be used to assign specific data types to the columns in data
copy (bool, optional) – Whether to make a copy of the input data, see pandas.DataFrame(). Default is False, i.e. by default data may be altered by the Exposures object.
geometry (array, optional) – Geometry column, see geopandas.GeoDataFrame(). Must be provided if lat and lon are None and data has no “geometry” column.
crs (value, optional) – Coordinate Reference System, see geopandas.GeoDataFrame().
meta (dict, optional) – Metadata dictionary. Default: {} (empty dictionary). May be used to provide any of description, ref_year, value_unit and crs
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’.
value (array, optional) – Exposed value column. Must be provided if data has no “value” column
lat (array, optional) – Latitude column. Can be provided together with lon, alternative to geometry
lon (array, optional) – Longitude column. Can be provided together with lat, alternative to geometry

check()[source]#

Check Exposures consistency.

Reports missing columns in log messages.

set_crs(crs='EPSG:4326')[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.

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:

if centroid raster is defined, assign exposures points to the closest raster point.
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]#: obsolete and deprecated since climada 5.0

Deprecated since version Obsolete: method call. As of climada 5.0, geometry points are set during object initialization

set_lat_lon()[source]#: Set latitude and longitude attributes from geometry attribute.

Deprecated since version latitude: and longitude columns are no longer meaningful in Exposures` GeoDataFrames. They can be retrieved from Exposures.latitude and .longitude properties

set_from_raster(*args, **kwargs)[source]#: This function is deprecated, use Exposures.from_raster instead.

Deprecated since version The: use of Exposures.set_from_raster 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
width (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': '© <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors © <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, other than the attributes of the Exposures class, whose values are to be read into the Exposures object class.

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

climada.entity.exposures package

Contents

climada.entity.exposures package#

climada.entity.exposures.base module#