climada.util package

climada.util.checker module

climada.util.checker.size(exp_len, var, var_name)

Check if the length of a variable is the expected one.

Raises

ValueError –

climada.util.checker.shape(exp_row, exp_col, var, var_name)

Check if the length of a variable is the expected one.

Raises

ValueError –

climada.util.checker.array_optional(exp_len, var, var_name)

Check if array has right size. Warn if array empty. Call check_size.

Parameters

• exp_len (str) – expected array size

• var (np.array) – numpy array to check

• var_name (str) – name of the variable. Used in error/warning msg

Raises

ValueError –

climada.util.checker.array_default(exp_len, var, var_name, def_val)

Check array has right size. Set default value if empty. Call check_size.

Parameters

• exp_len (str) – expected array size

• var (np.array) – numpy array to check

• var_name (str) – name of the variable. Used in error/warning msg

• def_val (np.array) – nump array used as default value

Raises

ValueError –

Returns

Filled array

climada.util.config module

climada.util.config.setup_logging(log_level='DEBUG')

Setup logging configuration

climada.util.constants module

climada.util.constants.SYSTEM_DIR = PosixPath('/home/docs/climada/data')

Folder containing the data used internally

climada.util.constants.DEMO_DIR = PosixPath('/home/docs/climada/demo/data')

Folder containing the data used for tutorials

climada.util.constants.ENT_DEMO_TODAY = PosixPath('/home/docs/climada/demo/data/demo_today.xlsx')

Entity demo present in xslx format.

climada.util.constants.ENT_DEMO_FUTURE = PosixPath('/home/docs/climada/demo/data/demo_future_TEST.xlsx')

Entity demo future in xslx format.

climada.util.constants.HAZ_DEMO_MAT = PosixPath('/home/docs/climada/demo/data/atl_prob_nonames.mat')

hurricanes from 1851 to 2011 over Florida with 100 centroids.

Type

Hazard demo from climada in MATLAB

climada.util.constants.HAZ_DEMO_FL = PosixPath('/home/docs/climada/demo/data/SC22000_VE__M1.grd.gz')

Raster file of flood over Venezuela. Model from GAR2015

climada.util.constants.HAZ_DEMO_FLDDPH = PosixPath('/home/docs/climada/demo/data/flddph_2000_DEMO.nc')

NetCDF4 Flood depth from isimip simulations

climada.util.constants.HAZ_DEMO_FLDFRC = PosixPath('/home/docs/climada/demo/data/fldfrc_2000_DEMO.nc')

NetCDF4 Flood fraction from isimip simulations

climada.util.constants.ENT_TEMPLATE_XLS = PosixPath('/home/docs/climada/data/entity_template.xlsx')

Entity template in xls format.

climada.util.constants.HAZ_TEMPLATE_XLS = PosixPath('/home/docs/climada/data/hazard_template.xlsx')

Hazard template in xls format.

climada.util.constants.ONE_LAT_KM = 111.12

Mean one latitude (in degrees) to km

climada.util.constants.EARTH_RADIUS_KM = 6371

Earth radius in km

climada.util.constants.GLB_CENTROIDS_MAT = PosixPath('/home/docs/climada/data/GLB_NatID_grid_0360as_adv_2.mat')

Global centroids

climada.util.constants.GLB_CENTROIDS_NC = PosixPath('/home/docs/climada/data/NatID_grid_0150as.nc')

For backwards compatibility, it remains available under its old name.

climada.util.constants.ISIMIP_GPWV3_NATID_150AS = PosixPath('/home/docs/climada/data/NatID_grid_0150as.nc')

Compressed version of National Identifier Grid in 150 arc-seconds from ISIMIP project, based on GPWv3. Location in ISIMIP repository:

ISIMIP2a/InputData/landuse_humaninfluences/population/ID_GRID/Nat_id_grid_ISIMIP.nc

More references:

• https://www.isimip.org/gettingstarted/input-data-bias-correction/details/13/

• https://sedac.ciesin.columbia.edu/data/set/gpw-v3-national-identifier-grid

climada.util.constants.NATEARTH_CENTROIDS = {150: PosixPath('/home/docs/climada/data/NatEarth_Centroids_150as.hdf5'), 360: PosixPath('/home/docs/climada/data/NatEarth_Centroids_360as.hdf5')}

Global centroids at XXX arc-seconds resolution, including region ids from Natural Earth. The 360 AS file includes distance to coast from NASA.

climada.util.constants.DEMO_GDP2ASSET = PosixPath('/home/docs/climada/demo/data/gdp2asset_CHE_exposure.nc')

Exposure demo file for GDP2Asset

climada.util.constants.RIVER_FLOOD_REGIONS_CSV = PosixPath('/home/docs/climada/data/NatRegIDs.csv')

Look-up table for river flood module

climada.util.constants.TC_ANDREW_FL = PosixPath('/home/docs/climada/demo/data/ibtracs_global_intp-None_1992230N11325.csv')

Tropical cyclone Andrew in Florida

climada.util.constants.HAZ_DEMO_H5 = PosixPath('/home/docs/climada/demo/data/tc_fl_1990_2004.h5')

IBTrACS from 1990 to 2004 over Florida with 2500 centroids.

Type

Hazard demo in hdf5 format

climada.util.constants.EXP_DEMO_H5 = PosixPath('/home/docs/climada/demo/data/exp_demo_today.h5')

Exposures over Florida

climada.util.constants.WS_DEMO_NC = [PosixPath('/home/docs/climada/demo/data/fp_lothar_crop-test.nc'), PosixPath('/home/docs/climada/demo/data/fp_xynthia_crop-test.nc')]

Winter storm in Europe files. These test files have been generated using the netCDF kitchen sink:

>>> ncks -d latitude,50.5,54.0 -d longitude,3.0,7.5 ./file_in.nc ./file_out.nc

climada.util.coordinates module

climada.util.coordinates.NE_EPSG = 4326

Natural Earth CRS EPSG

climada.util.coordinates.NE_CRS = {'init': 'epsg:4326', 'no_defs': True}

Natural Earth CRS

climada.util.coordinates.TMP_ELEVATION_FILE = PosixPath('/home/docs/climada/data/tmp_elevation.tif')

Path of elevation file written in set_elevation

climada.util.coordinates.DEM_NODATA = -9999

Value to use for no data values in DEM, i.e see points

climada.util.coordinates.MAX_DEM_TILES_DOWN = 300

Maximum DEM tiles to dowload

climada.util.coordinates.latlon_to_geosph_vector(lat, lon, rad=False, basis=False)

Convert lat/lon coodinates to radial vectors (on geosphere)

Parameters

• lat, lon (ndarrays of floats, same shape) – Latitudes and longitudes of points.

• rad (bool, optional) – If True, latitude and longitude are not given in degrees but in radians.

• basis (bool, optional) – If True, also return an orthonormal basis of the tangent space at the given points in lat-lon coordinate system. Default: False.

Returns

• vn (ndarray of floats, shape (…, 3)) – Same shape as lat/lon input with additional axis for components.

• vbasis (ndarray of floats, shape (…, 2, 3)) – Only present, if basis is True. Same shape as lat/lon input with additional axes for components of the two basis vectors.

climada.util.coordinates.lon_normalize(lon, center=0.0)

Normalizes degrees such that always -180 < lon - center <= 180

The input data is modified in place!

Parameters

• lon (np.array) – Longitudinal coordinates

• center (float, optional) – Central longitude value to use instead of 0. If None, the central longitude is determined automatically.

Returns

lon – Normalized longitudinal coordinates. Since the input lon is modified in place (!), the returned array is the same Python object (instead of a copy).

Return type

np.array

climada.util.coordinates.lon_bounds(lon, buffer=0.0)

Bounds of a set of degree values, respecting the periodicity in longitude

The longitudinal upper bound may be 180 or larger to make sure that the upper bound is always larger than the lower bound. The lower longitudinal bound will never lie below -180 and it will only assume the value -180 if the specified buffering enforces it.

Note that, as a consequence of this, the returned bounds do not satisfy the inequality lon_min <= lon <= lon_max in general!

Usually, an application of this function is followed by a renormalization of longitudinal values around the longitudinal middle value:

>>> bounds = lon_bounds(lon)
>>> lon_mid = 0.5 * (bounds[0] + bounds[2])
>>> lon = lon_normalize(lon, center=lon_mid)
>>> np.all((bounds[0] <= lon) & (lon <= bounds[2]))

Example

>>> lon_bounds(np.array([-179, 175, 178]))
(175, 181)
>>> lon_bounds(np.array([-179, 175, 178]), buffer=1)
(174, 182)

Parameters

• lon (np.array) – Longitudinal coordinates

• buffer (float, optional) – Buffer to add to both sides of the bounding box. Default: 0.0.

Returns

bounds – Bounding box of the given points.

Return type

tuple (lon_min, lon_max)

climada.util.coordinates.latlon_bounds(lat, lon, buffer=0.0)

Bounds of a set of degree values, respecting the periodicity in longitude

See lon_bounds for more information about the handling of longitudinal values crossing the antimeridian.

Example

>>> latlon_bounds(np.array([0, -2, 5]), np.array([-179, 175, 178]))
(175, -2, 181, 5)
>>> latlon_bounds(np.array([0, -2, 5]), np.array([-179, 175, 178]), buffer=1)
(174, -3, 182, 6)

Parameters

• lat (np.array) – Latitudinal coordinates

• lon (np.array) – Longitudinal coordinates

• buffer (float, optional) – Buffer to add to all sides of the bounding box. Default: 0.0.

Returns

bounds – Bounding box of the given points.

Return type

tuple (lon_min, lat_min, lon_max, lat_max)

climada.util.coordinates.dist_approx(lat1, lon1, lat2, lon2, log=False, normalize=True, method='equirect', units='km')

Compute approximation of geodistance in specified units

Parameters

• lat1, lon1 (ndarrays of floats, shape (nbatch, nx)) – Latitudes and longitudes of first points.

• lat2, lon2 (ndarrays of floats, shape (nbatch, ny)) – Latitudes and longitudes of second points.

• log (bool, optional) – If True, return the tangential vectors at the first points pointing to the second points (Riemannian logarithm). Default: False.

• normalize (bool, optional) – If False, assume that lon values are already between -180 and 180. Default: True

• method (str, optional) – Specify an approximation method to use: * “equirect”: Distance according to sinusoidal projection. Fast, but inaccurate for large

  distances and high latitudes.

  • “geosphere”: Exact spherical distance. Much more accurate at all distances, but slow.

  Note that ellipsoidal distances would be even more accurate, but are currently not implemented. Default: “equirect”.

• units (str, optional) – Specify a unit for the distance. One of: * “km”: distance in km. * “degree”: angular distance in decimal degrees. * “radian”: angular distance in radians. Default: “km”.

Returns

• dists (ndarray of floats, shape (nbatch, nx, ny)) – Approximate distances in specified units.

• vtan (ndarray of floats, shape (nbatch, nx, ny, 2)) – If log is True, tangential vectors at first points in local lat-lon coordinate system.

climada.util.coordinates.get_gridcellarea(lat, resolution=0.5, unit='km2')

The area covered by a grid cell is calculated depending on the latitude

1 degree = ONE_LAT_KM (111.12km at the equator) longitudal distance in km = ONE_LAT_KM*resolution*cos(lat) latitudal distance in km = ONE_LAT_KM*resolution area = longitudal distance * latitudal distance

Parameters

• lat (np.array) – Latitude of the respective grid cell

• resolution (int, optional) – raster resolution in degree (default: 0.5 degree)

• unit (string, optional) – unit of the output area (default: km2, alternative: m2)

climada.util.coordinates.grid_is_regular(coord)

Return True if grid is regular. If True, returns height and width.

Parameters

coord (np.array) – Each row is a lat-lon-pair.

Returns

• regular (bool) – Whether the grid is regular. Only in this case, the following width and height are reliable.

• height (int) – Height of the supposed grid.

• width (int) – Width of the supposed grid.

climada.util.coordinates.get_coastlines(bounds=None, resolution=110)

Get Polygones of coast intersecting given bounds

Parameters

• bounds (tuple) – min_lon, min_lat, max_lon, max_lat in EPSG:4326

• resolution (float, optional) – 10, 50 or 110. Resolution in m. Default: 110m, i.e. 1:110.000.000

Returns

coastlines – Polygons of coast intersecting given bounds.

Return type

GeoDataFrame

climada.util.coordinates.convert_wgs_to_utm(lon, lat)

Get EPSG code of UTM projection for input point in EPSG 4326

Parameters

• lon (float) – longitude point in EPSG 4326

• lat (float) – latitude of point (lat, lon) in EPSG 4326

Returns

epsg_code – EPSG code of UTM projection.

Return type

int

climada.util.coordinates.utm_zones(wgs_bounds)

Get EPSG code and bounds of UTM zones covering specified region

Parameters

wgs_bounds (tuple) – lon_min, lat_min, lon_max, lat_max

Returns

zones – EPSG code and bounding box in WGS coordinates.

Return type

list of pairs (zone_epsg, zone_wgs_bounds)

climada.util.coordinates.dist_to_coast(coord_lat, lon=None, signed=False)

Compute (signed) distance to coast from input points in meters.

Parameters

• coord_lat (GeoDataFrame or np.array or float) – One of the following: * GeoDataFrame with geometry column in epsg:4326 * np.array with two columns, first for latitude of each point

  and second with longitude in epsg:4326

  • np.array with one dimension containing latitudes in epsg:4326

  • float with a latitude value in epsg:4326

• lon (np.array or float, optional) – One of the following: * np.array with one dimension containing longitudes in epsg:4326 * float with a longitude value in epsg:4326

• signed (bool) – If True, distance is signed with positive values off shore and negative values on land. Default: False

Returns

dist – (Signed) distance to coast in meters.

Return type

np.array

climada.util.coordinates.dist_to_coast_nasa(lat, lon, highres=False, signed=False)

Read interpolated (signed) distance to coast (in m) from NASA data

Note: The NASA raster file is 300 MB and will be downloaded on first run!

Parameters

• lat (np.array) – latitudes in epsg:4326

• lon (np.array) – longitudes in epsg:4326

• highres (bool, optional) – Use full resolution of NASA data (much slower). Default: False.

• signed (bool) – If True, distance is signed with positive values off shore and negative values on land. Default: False

Returns

dist – (Signed) distance to coast in meters.

Return type

np.array

climada.util.coordinates.get_land_geometry(country_names=None, extent=None, resolution=10)

Get union of the specified (or all) countries or the points inside the extent.

Parameters

• country_names (list, optional) – list with ISO3 names of countries, e.g [‘ZWE’, ‘GBR’, ‘VNM’, ‘UZB’]

• extent (tuple, optional) – (min_lon, max_lon, min_lat, max_lat)

• resolution (float, optional) – 10, 50 or 110. Resolution in m. Default: 10m, i.e. 1:10.000.000

Returns

geom – Polygonal shape of union.

Return type

shapely.geometry.multipolygon.MultiPolygon

climada.util.coordinates.coord_on_land(lat, lon, land_geom=None)

Check if points are on land.

Parameters

• lat (np.array) – latitude of points in epsg:4326

• lon (np.array) – longitude of points in epsg:4326

• land_geom (shapely.geometry.multipolygon.MultiPolygon, optional) – If given, use these as profiles of land. Otherwise, the global landmass is used.

Returns

on_land – Entries are True if corresponding coordinate is on land and False otherwise.

Return type

np.array(bool)

climada.util.coordinates.nat_earth_resolution(resolution)

Check if resolution is available in Natural Earth. Build string.

Parameters

resolution (int) – resolution in millions, 110 == 1:110.000.000.

Returns

res_name – Natural Earth name of resolution (e.g. ‘110m’)

Return type

str

Raises

ValueError –

climada.util.coordinates.get_country_geometries(country_names=None, extent=None, resolution=10)

Natural Earth country boundaries within given extent

If no arguments are given, simply returns the whole natural earth dataset.

Take heed: we assume WGS84 as the CRS unless the Natural Earth download utility from cartopy starts including the projection information. (They are saving a whopping 147 bytes by omitting it.) Same goes for UTF.

Parameters

• country_names (list, optional) – list with ISO3 names of countries, e.g [‘ZWE’, ‘GBR’, ‘VNM’, ‘UZB’]

• extent (tuple (min_lon, max_lon, min_lat, max_lat), optional) – Extent, assumed to be in the same CRS as the natural earth data.

• resolution (float, optional) – 10, 50 or 110. Resolution in m. Default: 10m

Returns

geom – Natural Earth multipolygons of the specified countries, resp. the countries that lie within the specified extent.

Return type

GeoDataFrame

climada.util.coordinates.get_region_gridpoints(countries=None, regions=None, resolution=150, iso=True, rect=False, basemap='natearth')

Get coordinates of gridpoints in specified countries or regions

Parameters

• countries (list, optional) – ISO 3166-1 alpha-3 codes of countries, or internal numeric NatID if iso is set to False.

• regions (list, optional) – Region IDs.

• resolution (float, optional) – Resolution in arc-seconds, either 150 (default) or 360.

• iso (bool, optional) – If True, assume that countries are given by their ISO 3166-1 alpha-3 codes (instead of the internal NatID). Default: True.

• rect (bool, optional) – If True, a rectangular box around the specified countries/regions is selected. Default: False.

• basemap (str, optional) – Choose between different data sources. Currently available: “isimip” and “natearth”. Default: “natearth”.

Returns

• lat (np.array) – Latitude of points in epsg:4326.

• lon (np.array) – Longitude of points in epsg:4326.

climada.util.coordinates.mapping_point2grid(x, y, xmin, ymax, res)

Given the coordinates of a point, find the index of a grid cell from a raster into which it falls.

Note

Coordinates of the point and of the raster need to have the same CRS (e.g. both in lat/lon, EPSG:4326)

Parameters

• x (float) – x-coordinate of point

• y (float) – y-coordinate of point

• xmin (float) – coords top left corner of raster file - x

• ymax (float) – coords of top left corner of raster file - y

• res (float or tuple) – resolution of raster file. Float if res_x=res_y else (res_x, res_y).

Returns

col, row – column index and row index in grid matrix where point falls into

Return type

tuple

Raises

ValueError if Point outside of top left corner of raster –

climada.util.coordinates.mapping_grid2flattened(col, row, matrix_shape)

given a col and row index and the initial 2D matrix shape, return the 1-dimensional index of the same point in the flattened matrix - assumes concatenation along the row-axis (x-direction)

Parameters

• col (int) – Column Index of an entry in the original matrix

• row (int) – Row index of an entry in the original matrix

• matrix_shape ((int, int)) – Shape of the matrix (n_rows, n_cols)

Returns

Return type

index (1D) of the point in the flattened array (int)

climada.util.coordinates.region2isos(regions)

Convert region names to ISO 3166 alpha-3 codes of countries

Parameters

regions (str or list of str) – Region name(s).

Returns

isos – Sorted list of iso codes of all countries in specified region(s).

Return type

list of str

climada.util.coordinates.country_iso_alpha2numeric(isos)

Convert ISO 3166-1 alpha-3 to numeric-3 codes

Parameters

isos (str or list of str) – ISO codes of countries (or single code).

Returns

nums – Will only return a list if the input is a list.

Return type

int or list of int

climada.util.coordinates.country_natid2iso(natids)

Convert internal NatIDs to ISO 3166-1 alpha-3 codes

Parameters

natids (int or list of int) – Internal NatIDs of countries (or single ID).

Returns

isos – Will only return a list if the input is a list

Return type

str or list of str

climada.util.coordinates.country_iso2natid(isos)

Convert ISO 3166-1 alpha-3 codes to internal NatIDs

Parameters

isos (str or list of str) – ISO codes of countries (or single code).

Returns

natids – Will only return a list if the input is a list.

Return type

int or list of int

climada.util.coordinates.natearth_country_to_int(country)

Integer representation (ISO 3166, if possible) of Natural Earth GeoPandas country row

Parameters

country (GeoSeries) – Row from GeoDataFrame.

Returns

iso_numeric – Integer representation of given country.

Return type

int

climada.util.coordinates.get_country_code(lat, lon, gridded=False)

Provide numeric (ISO 3166) code for every point.

Oceans get the value zero. Areas that are not in ISO 3166 are given values in the range above 900 according to NATEARTH_AREA_NONISO_NUMERIC.

Parameters

• lat (np.array) – latitude of points in epsg:4326

• lon (np.array) – longitude of points in epsg:4326

• gridded (bool) – If True, interpolate precomputed gridded data which is usually much faster. Default: False.

Returns

country_codes – Numeric code for each point.

Return type

np.array(int)

climada.util.coordinates.get_admin1_info(country_names)

Provide Natural Earth registry info and shape files for admin1 regions

Parameters

country_names (list) – list with ISO3 names of countries, e.g. [‘ZWE’, ‘GBR’, ‘VNM’, ‘UZB’]

Returns

• admin1_info (dict) – Data according to records in Natural Earth database.

• admin1_shapes (dict) – Shape according to Natural Earth.

climada.util.coordinates.get_resolution_1d(coords, min_resol=1e-08)

Compute resolution of scalar grid

Parameters

• coords (np.array) – scalar coordinates

• min_resol (float, optional) – minimum resolution to consider. Default: 1.0e-8.

Returns

res – Resolution of given grid.

Return type

float

climada.util.coordinates.get_resolution(*coords, min_resol=1e-08)

Compute resolution of n-d grid points

Parameters

• X, Y, … (np.array) – Scalar coordinates in each axis

• min_resol (float, optional) – minimum resolution to consider. Default: 1.0e-8.

Returns

resolution – Resolution in each coordinate direction.

Return type

pair of floats

climada.util.coordinates.pts_to_raster_meta(points_bounds, res)

Transform vector data coordinates to raster.

If a raster of the given resolution doesn’t exactly fit the given bounds, the raster might have slightly larger (but never smaller) bounds.

Parameters

• points_bounds (tuple) – points total bounds (xmin, ymin, xmax, ymax)

• res (tuple) – resolution of output raster (xres, yres)

Returns

• nrows (int) – Number of rows.

• ncols (int) – Number of columns.

• ras_trans (affine.Affine) – Affine transformation defining the raster.

climada.util.coordinates.raster_to_meshgrid(transform, width, height)

Get coordinates of grid points in raster

Parameters

• transform (affine.Affine) – Affine transform defining the raster.

• width (int) – Number of points in first coordinate axis.

• height (int) – Number of points in second coordinate axis.

Returns

• x (np.array) – x-coordinates of grid points.

• y (np.array) – y-coordinates of grid points.

climada.util.coordinates.to_crs_user_input(crs_obj)

Returns a crs string or dictionary from a hdf5 file object.

bytes are decoded to str if the string starts with a ‘{‘ it is assumed to be a dumped string from a dictionary and ast is used to parse it.

Parameters

crs_obj (int, dict or str or bytes) – the crs object to be converted user input

Returns

to eventually be used as argument of rasterio.crs.CRS.from_user_input and pyproj.crs.CRS.from_user_input

Return type

str or dict

Raises

ValueError – if type(crs_obj) has the wrong type

climada.util.coordinates.equal_crs(crs_one, crs_two)

Compare two crs

Parameters

• crs_one (dict, str or int) – user crs

• crs_two (dict, str or int) – user crs

Returns

equal – Whether the two specified CRS are equal according tho rasterio.crs.CRS.from_user_input

Return type

bool

climada.util.coordinates.read_raster(file_name, band=None, src_crs=None, window=None, geometry=None, dst_crs=None, transform=None, width=None, height=None, resampling=<Resampling.nearest: 0>)

Read raster of bands and set 0-values to the masked ones.

Parameters

• file_name (str) – name of the file

• band (list(int), optional) – band number to read. Default: 1

• window (rasterio.windows.Window, optional) – window to read

• 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

Returns

• meta (dict) – Raster meta (height, width, transform, crs).

• data (np.array) – Each row corresponds to one band (raster points are flattened, can be reshaped to height x width).

climada.util.coordinates.read_raster_bounds(path, bounds, res=None, bands=None)

Read raster file within given bounds and refine to given resolution

Makes sure that the extent of pixel centers covers the specified regions

Parameters

• path (str) – Path to raster file to open with rasterio.

• bounds (tuple) – (xmin, ymin, xmax, ymax)

• res (float, optional) – Resolution of output. Default: Resolution of input raster file.

• bands (list of int, optional) – Bands to read from the input raster file. Default: [1]

Returns

• data (3d np.array) – First dimension is for the selected raster bands. Second dimension is y (lat) and third dimension is x (lon).

• transform (rasterio.Affine) – Affine transformation defining the output raster data.

climada.util.coordinates.read_raster_sample(path, lat, lon, intermediate_res=None, method='linear', fill_value=None)

Read point samples from raster file.

Parameters

• path (str) – path of the raster file

• lat (np.array) – latitudes in file’s CRS

• lon (np.array) – longitudes in file’s CRS

• intermediate_res (float, optional) – If given, the raster is not read in its original resolution but in the given one. This can increase performance for files of very high resolution.

• method (str, optional) – The interpolation method, passed to scipy.interp.interpn. Default: ‘linear’.

• fill_value (numeric, optional) – The value used outside of the raster bounds. Default: The raster’s nodata value or 0.

Returns

values – Interpolated raster values for each given coordinate point.

Return type

np.array of same length as lat

climada.util.coordinates.interp_raster_data(data, interp_y, interp_x, transform, method='linear', fill_value=0)

Interpolate raster data, given as array and affine transform

Parameters

• data (np.array) – 2d numpy array containing the values

• interp_y (np.array) – y-coordinates of points (corresp. to first axis of data)

• interp_x (np.array) – x-coordinates of points (corresp. to second axis of data)

• transform (affine.Affine) – affine transform defining the raster

• method (str, optional) –

  The interpolation method, passed to

  scipy.interp.interpn. Default: ‘linear’.

• fill_value (numeric, optional) –

  The value used outside of the raster

  bounds. Default: 0.

Returns

values – Interpolated raster values for each given coordinate point.

Return type

np.array

climada.util.coordinates.refine_raster_data(data, transform, res, method='linear', fill_value=0)

Refine raster data, given as array and affine transform

Parameters

• data (np.array) – 2d array containing the values

• transform (affine.Affine) – affine transform defining the raster

• res (float or pair of floats) – new resolution

• method (str, optional) –

  The interpolation method, passed to

  scipy.interp.interpn. Default: ‘linear’.

Returns

• new_data (np.array) – 2d array containing the interpolated values.

• new_transform (affine.Affine) – Affine transform defining the refined raster.

climada.util.coordinates.read_vector(file_name, field_name, dst_crs=None)

Read vector file format supported by fiona.

Parameters

• file_name (str) – vector file with format supported by fiona and ‘geometry’ field.

• field_name (list(str)) – list of names of the columns with values.

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

Returns

• lat (np.array) – Latitudinal coordinates.

• lon (np.array) – Longitudinal coordinates.

• geometry (GeoSeries) – Shape geometries.

• value (np.array) – Values associated to each shape.

climada.util.coordinates.write_raster(file_name, data_matrix, meta, dtype=<class 'numpy.float32'>)

Write raster in GeoTiff format.

Parameters

• file_name (str) – File name to write.

• data_matrix (np.array) – 2d raster data. Either containing one band, or every row is a band and the column represents the grid in 1d.

• meta (dict) – rasterio meta dictionary containing raster properties: width, height, crs and transform must be present at least. Include compress=”deflate” for compressed output.

• dtype (numpy dtype, optional) – A numpy dtype. Default: np.float32

climada.util.coordinates.points_to_raster(points_df, val_names=None, res=0.0, raster_res=0.0, scheduler=None)

Compute raster (as data and transform) from GeoDataFrame.

Parameters

• points_df (GeoDataFrame) – contains columns latitude, longitude and those listed in the parameter val_names.

• val_names (list of str, optional) – The names of columns in points_df containing values. The raster will contain one band per column. Default: [‘value’]

• 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

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

Returns

• data (np.array) – 2d array containing the raster values.

• transform (affine.Affine) – Affine transform defining the raster coordinates.

climada.util.coordinates.set_df_geometry_points(df_val, scheduler=None)

Set given geometry to given dataframe using dask if scheduler.

Parameters

• df_val (DataFrame or GeoDataFrame) – contains latitude and longitude columns

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

climada.util.coordinates.fao_code_def()

Generates list of FAO country codes and corresponding ISO numeric-3 codes.

Returns

• iso_list (list) – list of ISO numeric-3 codes

• faocode_list (list) – list of FAO country codes

climada.util.coordinates.country_faocode2iso(input_fao)

Convert FAO country code to ISO numeric-3 codes.

Parameters

input_fao (int or array) – FAO country codes of countries (or single code)

Returns

output_iso – ISO numeric-3 codes of countries (or single code)

Return type

int or array

climada.util.coordinates.country_iso2faocode(input_iso)

Convert ISO numeric-3 codes to FAO country code.

Parameters

input_iso (int or array) – ISO numeric-3 codes of countries (or single code)

Returns

output_faocode – FAO country codes of countries (or single code)

Return type

int or array

climada.util.dates_times module

climada.util.dates_times.date_to_str(date)

Compute date string in ISO format from input datetime ordinal int. :Parameters: date (int or list or np.array) – input datetime ordinal

Returns

str or list(str)

climada.util.dates_times.str_to_date(date)

Compute datetime ordinal int from input date string in ISO format. :Parameters: date (str or list) – idate string in ISO format, e.g. ‘2018-04-06’

Returns

int

climada.util.dates_times.datetime64_to_ordinal(datetime)

Converts from a numpy datetime64 object to an ordinal date. See https://stackoverflow.com/a/21916253 for the horrible details. :Parameters: datetime (np.datetime64, or list or np.array) – date and time

Returns

int

climada.util.dates_times.last_year(ordinal_vector)

Extract first year from ordinal date

Parameters

ordinal_vector (list or np.array) – input datetime ordinal

Returns

int

climada.util.dates_times.first_year(ordinal_vector)

Extract first year from ordinal date

Parameters

ordinal_vector (list or np.array) – input datetime ordinal

Returns

int

climada.util.dwd_icon_loader module

climada.util.dwd_icon_loader.download_icon_grib(run_datetime, model_name='icon-eu-eps', parameter_name='vmax_10m', max_lead_time=None, download_dir=None)

download the gribfiles of a weather forecast run for a certain weather parameter from opendata.dwd.de/weather/nwp/.

Parameters

• run_datetime (datetime) – The starting timepoint of the forecast run

• model_name (str) – the name of the forecast model written as it appears in the folder structure in opendata.dwd.de/weather/nwp/ or ‘test’

• parameter_name (str) – the name of the meteorological parameter written as it appears in the folder structure in opendata.dwd.de/weather/nwp/

• max_lead_time (int) – number of hours for which files should be downloaded, will default to maximum available data

• download_dir – (str or Path): directory where the downloaded files should be saved in

Returns

a list of filenames that link to all just

downloaded or available files from the forecast run, defined by the input parameters

Return type

file_names (list)

climada.util.dwd_icon_loader.delete_icon_grib(run_datetime, model_name='icon-eu-eps', parameter_name='vmax_10m', max_lead_time=None, download_dir=None)

delete the downloaded gribfiles of a weather forecast run for a certain weather parameter from opendata.dwd.de/weather/nwp/.

Parameters

• run_datetime (datetime) – The starting timepoint of the forecast run

• model_name (str) – the name of the forecast model written as it appears in the folder structure in opendata.dwd.de/weather/nwp/

• parameter_name (str) – the name of the meteorological parameter written as it appears in the folder structure in opendata.dwd.de/weather/nwp/

• max_lead_time (int) – number of hours for which files should be deleted, will default to maximum available data

• download_dir (str or Path) – directory where the downloaded files are stored at the moment

climada.util.dwd_icon_loader.download_icon_centroids_file(model_name='icon-eu-eps', download_dir=None)

create centroids based on netcdf files provided by dwd, links found here: https://www.dwd.de/DE/leistungen/opendata/neuigkeiten/opendata_dez2018_02.html https://www.dwd.de/DE/leistungen/opendata/neuigkeiten/opendata_aug2020_01.html

Parameters

• model_name (str) – the name of the forecast model written as it appears in the folder structure in opendata.dwd.de/weather/nwp/

• download_dir (str or Path) – directory where the downloaded files should be saved in

Returns

absolute path and filename of the downloaded

and decompressed netcdf file

Return type

file_name (str)

climada.util.earth_engine module

climada.util.files_handler module

climada.util.files_handler.to_list(num_exp, values, val_name)

Check size and transform to list if necessary. If size is one, build a list with num_exp repeated values.

Parameters

• num_exp (int) – number of expect list elements

• values (object or list(object)) – values to check and transform

• val_name (str) – name of the variable values

Returns

list

climada.util.files_handler.get_file_names(file_name)

Return list of files contained. Supports globbing.

Parameters

file_name (str or list(str)) – Either a single string or a list of strings that are either

• a file path

• or the path of the folder containing the files

• or a globbing pattern.

Returns

list(str)

climada.util.finance module

climada.util.finance.net_present_value(years, disc_rates, val_years)

Compute net present value.

Parameters

• years (np.array) – array with the sequence of years to consider.

• disc_rates (np.array) – discount rate for every year in years.

• val_years (np.array) – chash flow at each year.

Returns

float

climada.util.finance.income_group(cntry_iso, ref_year, shp_file=None)

Get country’s income group from World Bank’s data at a given year, or closest year value. If no data, get the natural earth’s approximation.

Parameters

• cntry_iso (str) – key = ISO alpha_3 country

• ref_year (int) – reference year

• shp_file (cartopy.io.shapereader.Reader, optional) – shape file with INCOME_GRP attribute for every country. Load Natural Earth admin0 if not provided.

climada.util.finance.gdp(cntry_iso, ref_year, shp_file=None, per_capita=False)

Get country’s (current value) GDP from World Bank’s data at a given year, or closest year value. If no data, get the natural earth’s approximation.

Parameters

• cntry_iso (str) – key = ISO alpha_3 country

• ref_year (int) – reference year

• shp_file (cartopy.io.shapereader.Reader, optional) – shape file with INCOME_GRP attribute for every country. Load Natural Earth admin0 if not provided.

• per_capita (boolean, optional) – If True, GDP is returned per capita

Returns

float

climada.util.hdf5_handler module

climada.util.hdf5_handler.read(file_name, with_refs=False)

Load a hdf5 data structure from a file.

Parameters

• file_name – file to load

• with_refs – enable loading of the references. Default is unset, since it increments the execution time considerably.

Returns

dictionary structure containing all the variables.

Return type

contents

Examples

Contents contains the Matlab data in a dictionary.

>>> contents = read("/pathto/dummy.mat")

Contents contains the Matlab data and its reference in a dictionary.

>>> contents = read("/pathto/dummy.mat", True)

Raises

Exception while reading –

climada.util.hdf5_handler.get_string(array)

Form string from input array of unisgned integers.

Parameters

array – array of integers

Returns

string

climada.util.hdf5_handler.get_str_from_ref(file_name, var)

Form string from a reference HDF5 variable of the given file.

Parameters

• file_name – matlab file name

• var – HDF5 reference variable

Returns

string

climada.util.hdf5_handler.get_list_str_from_ref(file_name, var)

Form list of strings from a reference HDF5 variable of the given file.

Parameters

• file_name – matlab file name

• var – array of HDF5 reference variable

Returns

string

climada.util.hdf5_handler.get_sparse_csr_mat(mat_dict, shape)

Form sparse matrix from input hdf5 sparse matrix data type.

Parameters

• mat_dict – dictionary containing the sparse matrix information.

• shape – tuple describing output matrix shape.

Returns

sparse csr matrix

climada.util.interpolation module

climada.util.interpolation.interpol_index(centroids, coordinates, method='NN', distance='haversine', threshold=100)

Returns for each coordinate the centroids indexes used for interpolation.

Parameters

• centroids (2d array) – First column contains latitude, second column contains longitude. Each row is a geographic point

• coordinates (2d array) – First column contains latitude, second column contains longitude. Each row is a geographic point

• method (str, optional) – interpolation method to use. NN default.

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

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

Returns

numpy array with so many rows as coordinates containing the

centroids indexes

climada.util.interpolation.dist_sqr_approx(lats1, lons1, cos_lats1, lats2, lons2)

Compute squared equirectangular approximation distance. Values need to be sqrt and multiplicated by ONE_LAT_KM to obtain distance in km.

climada.util.interpolation.DIST_DEF = ['approx', 'haversine']

Distances

climada.util.interpolation.METHOD = ['NN']

Interpolation methods

climada.util.plot module

climada.util.plot.geo_bin_from_array(array_sub, geo_coord, var_name, title, pop_name=True, buffer=1.0, extend='neither', proj=<cartopy.crs.PlateCarree object>, axes=None, figsize=(9, 13), **kwargs)

Plot array values binned over input coordinates.

Parameters

• array_sub (np.array(1d or 2d) or list(np.array)) – Each array (in a row or in the list) are values at each point in corresponding geo_coord that are binned in one subplot.

• geo_coord (2d np.array or list(2d np.array)) – (lat, lon) for each point in a row. If one provided, the same grid is used for all subplots. Otherwise provide as many as subplots in array_sub.

• var_name (str or list(str)) – label to be shown in the colorbar. If one provided, the same is used for all subplots. Otherwise provide as many as subplots in array_sub.

• title (str or list(str)) – subplot title. If one provided, the same is used for all subplots. Otherwise provide as many as subplots in array_sub.

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

• buffer (float, optional) – border to add to coordinates, by default BUFFER

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

• proj (ccrs, optional) – coordinate reference system of the given data, by default ccrs.PlateCarree()

• axes (Axes or ndarray(Axes), optional) – by default None

• figsize (tuple, optional) – figure size for plt.subplots, by default (9, 13)

• **kwargs – arbitrary keyword arguments for hexbin matplotlib function

Returns

Return type

cartopy.mpl.geoaxes.GeoAxesSubplot

Raises

ValueError –

climada.util.plot.geo_im_from_array(array_sub, coord, var_name, title, proj=None, smooth=True, axes=None, figsize=(9, 13), **kwargs)

Image(s) plot defined in array(s) over input coordinates.

Parameters

• array_sub (np.array(1d or 2d) or list(np.array)) – Each array (in a row or in the list) are values at each point in corresponding geo_coord that are ploted in one subplot.

• coord (2d np.array) – (lat, lon) for each point in a row. The same grid is used for all subplots.

• var_name (str or list(str)) – label to be shown in the colorbar. If one provided, the same is used for all subplots. Otherwise provide as many as subplots in array_sub.

• title (str or list(str)) – subplot title. If one provided, the same is used for all subplots. Otherwise provide as many as subplots in array_sub.

• proj (ccrs, optional) – coordinate reference system used in coordinates, by default None

• smooth (bool, optional) – smooth plot to RESOLUTIONxRESOLUTION, by default True

• axes (Axes or ndarray(Axes), optional) – by default None

• figsize (tuple, optional) – figure size for plt.subplots, by default (9, 13)

• **kwargs – arbitrary keyword arguments for pcolormesh matplotlib function

Returns

Return type

cartopy.mpl.geoaxes.GeoAxesSubplot

Raises

ValueError –

climada.util.plot.make_map(num_sub=1, figsize=(9, 13), proj=<cartopy.crs.PlateCarree object>)

Create map figure with cartopy.

Parameters

• num_sub (int or tuple) – number of total subplots in figure OR number of subfigures in row and column: (num_row, num_col).

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

• proj (cartopy.crs projection, optional) – geographical projection, The default is PlateCarree default.

Returns

fig, axis_sub

Return type

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

climada.util.plot.add_shapes(axis)

Overlay Earth’s countries coastlines to matplotlib.pyplot axis.

Parameters

• axis (cartopy.mpl.geoaxes.GeoAxesSubplot) – Cartopy axis

• projection (cartopy.crs projection, optional) – Geographical projection. The default is PlateCarree.

climada.util.plot.add_populated_places(axis, extent, proj=<cartopy.crs.PlateCarree object>)

Add city names.

Parameters

• axis (cartopy.mpl.geoaxes.GeoAxesSubplot) – cartopy axis.

• extent (list) – geographical limits [min_lon, max_lon, min_lat, max_lat]

• proj (cartopy.crs projection, optional) – geographical projection, The default is PlateCarree.

climada.util.plot.add_cntry_names(axis, extent, proj=<cartopy.crs.PlateCarree object>)

Add country names.

Parameters: axis : cartopy.mpl.geoaxes.GeoAxesSubplot

Cartopy axis.

extentlist

geographical limits [min_lon, max_lon, min_lat, max_lat]

projcartopy.crs projection, optional

Geographical projection. The default is PlateCarree.

climada.util.save module

climada.util.save.save(out_file_name, var)

Save variable with provided file name. Uses configuration save_dir folder if no absolute path provided.

Parameters

• out_file_name (str) – file name (absolute path or relative to configured save_dir)

• var (object) – variable to save in pickle format

climada.util.save.load(in_file_name)

Load variable contained in file. Uses configuration save_dir folder if no absolute path provided.

Parameters

in_file_name (str)

Returns

object

climada.util.scalebar_plot module

climada.util.scalebar_plot.scale_bar(ax, location, length, metres_per_unit=1000, unit_name='km', tol=0.01, angle=0, color='black', linewidth=3, text_offset=0.005, ha='center', va='bottom', plot_kwargs=None, text_kwargs=None, **kwargs)

Add a scale bar to CartoPy axes.

For angles between 0 and 90 the text and line may be plotted at slightly different angles for unknown reasons. To work around this, override the ‘rotation’ keyword argument with text_kwargs.

Parameters

• ax – CartoPy axes.

• location – Position of left-side of bar in axes coordinates.

• length – Geodesic length of the scale bar.

• metres_per_unit – Number of metres in the given unit. Default: 1000

• unit_name – Name of the given unit. Default: ‘km’

• tol – Allowed relative error in length of bar. Default: 0.01

• angle – Anti-clockwise rotation of the bar.

• color – Color of the bar and text. Default: ‘black’

• linewidth – Same argument as for plot.

• text_offset – Perpendicular offset for text in axes coordinates. Default: 0.005

• ha – Horizontal alignment. Default: ‘center’

• va – Vertical alignment. Default: ‘bottom’

• **plot_kwargs – Keyword arguments for plot, overridden by **kwargs.

• **text_kwargs – Keyword arguments for text, overridden by **kwargs.

• **kwargs – Keyword arguments for both plot and text.

climada.util.select module

climada.util.select.get_attributes_with_matching_dimension(obj, dims)

Get the attributes of an object that have len(dims) number of dimensions or more, and all dims are individual parts of the attribute’s shape.

Parameters

• obj (object of any class) – The object from which matching attributes are returned

• dims (list[int]) – List of dimensions size to match

Returns

list_of_attrs – List of names of the attributes with matching dimensions

Return type

list[str]

climada.util.value_representation module

climada.util.value_representation.sig_dig(x, n_sig_dig=16)

Rounds x to n_sig_dig number of significant digits. 0, inf, Nan are returned unchanged. Examples: n_sig_dig = 5

1.234567 -> 1.2346, 123456.89 -> 123460.0

Parameters

• x (float) – number to be rounded

• n_sig_dig (int, optional) – Number of significant digits. The default is 16.

Returns

Rounded number

Return type

float

climada.util.value_representation.sig_dig_list(iterable, n_sig_dig=16)

Vectorized form of sig_dig. Rounds a list of float to a number of significant digits

Parameters

• iterable (iter(float)) – iterable of numbers to be rounded

• n_sig_dig (int, optional) – Number of significant digits. The default is 16.

Returns

list of rounded floats

Return type

list

climada.util.value_representation.value_to_monetary_unit(values, n_sig_dig=None, abbreviations=None)

Converts list of values to closest common monetary unit 0, Nan and inf have not unit.

Parameters

• values (int or float, list(int or float) or np.ndarray(int or float)) – Values to be converted

• n_sig_dig (int, optional) – Number of significant digits to return. Examples n_sig_di=5: 1.234567 -> 1.2346, 123456.89 -> 123460.0 Default: all digits are returned.

• abbreviations (dict, optional) – Name of the abbreviations for the money 1000s counts Default:

  {

  1:’’, 1000: ‘K’, 1000000: ‘M’, 1000000000: ‘Bn’, 1000000000000: ‘Tn’}

Returns

• mon_val (np.ndarray) – Array of values in monetary unit

• name (string) – Monetary unit

Examples

values = [1e6, 2*1e6, 4.5*1e7, 0, Nan, inf] ->

[1, 2, 4.5, 0, Nan, inf] [‘M’]

climada.util.yearsets module

climada.util.yearsets.impact_yearset(event_impacts, sampled_years=None, sampling_dict=None, correction_fac=True)

Create an annual_impacts object containing a probabilistic impact for each year

in the sampled_years list (or for a list of sampled_years generated with the length

of given sampled_years)

by sampling events from the existing input event_impacts with a Poisson distribution centered around n_events per year (n_events = sum(event_impacts.frequency)). In contrast to the expected annual impact (eai) annual_impacts contains impact values that differ among years (the correction factor can however be used to scale the annual_impacts

to fit the eai of the events_impacts object that is used to generated it)

Parameters

event_impacts – impact object impact object containing impacts per event

Optional parameters:

sampled_yearsint or list

Either an integer specifying the number of years to be sampled (labelled [0001,…,sampled_years]) or a list of years that shall be covered by the resulting annual_impacts. The default is a 1000 year-long list starting in the year 0001.

sampling_dictdict

The sampling dictionary specifying how to sample the annual_impacts It consists of two arrays:

selected_events: array

indices of sampled events in event_impacts.at_event()

events_per_year: array

number of events per sampled year

The sampling_dict needs to be obtained in a first call, i.e. [annual_impacts, sampling_dict] = climada_yearsets.impact_yearset(…) and can then be provided in subsequent calls(s) to obtain the exact same sampling (also for a different event_impacts object)

correction_facboolean

If True a correction factor is applied to the resulting annual_impacts. They are scaled in such a way that the expected annual impact (eai) of the annual_impacts equals the eai of the events_impacts

Returns

impact object

annual impacts for all sampled_years

sampling_dictdict

the sampling dictionary containing two arrays:

selected_events (array) : sampled events (len: total amount of sampled events) events_per_year (array) : events per sampled year

Can be used to re-create the exact same annual_impacts yearset

Return type

annual_impacts

climada.util.yearsets.create_sampling_dict(n_sampled_years, n_annual_events, n_input_events)

Create a sampling dictionary consisting of the amount of events per sample year and the index of the sampled events

Parameters

• n_sampled_years – int The target number of years the impact yearset shall contain.

• n_annual_events – int Number of events per year in given event_impacts object

• n_input_events – int Number of events contained in given event_impacts object

Returns

dict

The sampling dictionary containing two arrays:

selected_events (array): sampled events (len: total amount of sampled events) events_per_year (array): events per sampled year

n_events_per_yeararray

Number of events per sampled year

Return type

sampling_dict

climada.util.yearsets.sample_events(tot_n_events, n_input_events)

Sample events (length = tot_n_events) uniformely from an array (n_input_events) without replacement (if tot_n_events > n_input_events the input events are repeated

(tot_n_events/n_input_events) times).

Parameters

• tot_n_events – int Number of events to be sampled

• n_input_events – int Number of events contained in given event_impacts object

Returns

array

Uniformaly sampled events (length: tot_n_events)

Return type

selected_events

climada.util.yearsets.compute_annual_impacts(event_impacts, sampling_dict)

Sample annual impacts from the given event_impacts according to the sampling dictionary

Parameters

• event_impacts – impact object impact object containing impacts per event

• sampling_dict – dict The sampling dictionary containing two arrays:

  selected_events (array) : sampled events (len: total amount of sampled events) events_per_year (array) : events per sampled year

Returns

array

Sampled impact per year (length = n_sampled_years)

Return type

impact_per_year

climada.util.yearsets.calculate_correction_fac(impact_per_year, event_impacts)

Calculate a correction factor that can be used to scale the annual_impacts in such a way that the expected annual impact (eai) of the annual_impacts amounts to the eai of the input event_impacts

Parameters

• impact_per_year – array sampled annual_impacts

• event_impacts – impact object impact object containing impacts per event

Returns

int

The correction factor is calculated as event_impacts_eai/annual_impacts_eai

Return type

correction_factor