climada.entity.exposures package

climada.entity.exposures.base module

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

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

impf_

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_

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, tag=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)

  • tag (climada.entity.exposures.tag.Tag, optional) – Exposures tag. Defaults to the entry of the same name in meta or an empty Tag object.

  • 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: geopandas.geodataframe.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 tag.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)[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).

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

See also

climada.util.coordinates.assign_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=False, geometry=False, dst_crs=False, 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 (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

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, **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.

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

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, **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’ ]

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

  • figsize (tuple) – 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.

  • kwargs (optional) – arguments for hexbin matplotlib function, e.g. reduce_C_function=np.average. Default: 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='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, 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 (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’

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]

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

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

  • kind (str) –

    The kind of plots to produce:

    • ‘geo’: Map (default)

    Pandas Kinds - ‘line’ : line plot - ‘bar’ : vertical bar plot - ‘barh’ : horizontal bar plot - ‘hist’ : histogram - ‘box’ : BoxPlot - ‘kde’ : Kernel Density Estimation plot - ‘density’ : same as ‘kde’ - ‘area’ : area plot - ‘pie’ : pie plot - ‘scatter’ : scatter plot - ‘hexbin’ : hexbin plot.

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

    intervalboolean (default False)

    An option to control brackets from mapclassify legend. If True, open/closed interval brackets are shown in the legend.

  • 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’, None 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. If None, the aspect of ax won’t be changed. 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

Examples

>>> df = geopandas.read_file(geopandas.datasets.get_path("naturalearth_lowres"))
>>> df.head()  
    pop_est      continent                      name iso_a3  gdp_md_est                                           geometry
0     920938        Oceania                      Fiji    FJI      8374.0  MULTIPOLYGON (((180.00000 -16.06713, 180.00000...
1   53950935         Africa                  Tanzania    TZA    150600.0  POLYGON ((33.90371 -0.95000, 34.07262 -1.05982...
2     603253         Africa                 W. Sahara    ESH       906.5  POLYGON ((-8.66559 27.65643, -8.66512 27.58948...
3   35623680  North America                    Canada    CAN   1674000.0  MULTIPOLYGON (((-122.84000 49.00000, -122.9742...
4  326625791  North America  United States of America    USA  18560000.0  MULTIPOLYGON (((-122.84000 49.00000, -120.0000...

>>> df.plot("pop_est", cmap="Blues")

See the User Guide page ../../user_guide/mapping for details.

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

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