climada.util package

climada.util.api_client module

class climada.util.api_client.Download(*args, **kwargs)

Bases: peewee.Model

Database entry keeping track of downloaded files from the CLIMADA data API

url = <CharField: Download.url>

path = <CharField: Download.path>

startdownload = <DateTimeField: Download.startdownload>

enddownload = <DateTimeField: Download.enddownload>

exception Failed

Bases: Exception

The download failed for some reason.

DoesNotExist

alias of climada.util.api_client.DownloadDoesNotExist

id = <AutoField: Download.id>

class climada.util.api_client.FileInfo(uuid: str, url: str, file_name: str, file_format: str, file_size: int, check_sum: str)

Bases: object

file data from CLIMADA data API.

uuid: str

url: str

file_name: str

file_format: str

file_size: int

check_sum: str

__init__(uuid: str, url: str, file_name: str, file_format: str, file_size: int, check_sum: str) → None

class climada.util.api_client.DataTypeInfo(data_type: str, data_type_group: str, status: str, description: str, properties: list)

Bases: object

data type meta data from CLIMADA data API.

data_type: str

data_type_group: str

status: str

description: str

properties: list

__init__(data_type: str, data_type_group: str, status: str, description: str, properties: list) → None

class climada.util.api_client.DataTypeShortInfo(data_type: str, data_type_group: str)

Bases: object

data type name and group from CLIMADA data API.

data_type: str

data_type_group: str

__init__(data_type: str, data_type_group: str) → None

class climada.util.api_client.DatasetInfo(uuid: str, data_type: climada.util.api_client.DataTypeShortInfo, name: str, version: str, status: str, properties: dict, files: list, doi: str, description: str, license: str, activation_date: str, expiration_date: str)

Bases: object

dataset data from CLIMADA data API.

uuid: str

data_type: climada.util.api_client.DataTypeShortInfo

name: str

version: str

status: str

properties: dict

files: list

doi: str

description: str

license: str

activation_date: str

expiration_date: str

static from_json(jsono)

creates a DatasetInfo object from the json object returned by the CLIMADA data api server.

Parameters

jsono (dict)

Return type

DatasetInfo

__init__(uuid: str, data_type: climada.util.api_client.DataTypeShortInfo, name: str, version: str, status: str, properties: dict, files: list, doi: str, description: str, license: str, activation_date: str, expiration_date: str) → None

climada.util.api_client.checksize(local_path, fileinfo)

Checks sanity of downloaded file simply by comparing actual and registered size.

Parameters

• local_path (Path) – the downloaded file

• filinfo (FileInfo) – file information from CLIMADA data API

Raises

Download.Failed – if the file is not what it’s supposed to be

climada.util.api_client.checkhash(local_path, fileinfo)

Checks sanity of downloaded file by comparing actual and registered check sum.

Parameters

• local_path (Path) – the downloaded file

• filinfo (FileInfo) – file information from CLIMADA data API

Raises

Download.Failed – if the file is not what it’s supposed to be

class climada.util.api_client.Client

Bases: object

Python wrapper around REST calls to the CLIMADA data API server.

MAX_WAITING_PERIOD = 6

UNLIMITED = 100000

exception AmbiguousResult

Bases: Exception

Custom Exception for Non-Unique Query Result

exception NoResult

Bases: Exception

Custom Exception for No Query Result

__init__()

Constructor of Client.

Data API host and chunk_size (for download) are configurable values. Default values are ‘climada.ethz.ch’ and 8096 respectively.

list_dataset_infos(data_type=None, name=None, version=None, properties=None, status='active')

Find all datasets matching the given parameters.

Parameters

• data_type (str, optional) – data_type of the dataset, e.g., ‘litpop’ or ‘draught’

• name (str, optional) – the name of the dataset

• version (str, optional) – the version of the dataset

• properties (dict, optional) – search parameters for dataset properties, by default None any property has a string for key and can be a string or a list of strings for value

• status (str, optional) – valid values are ‘preliminary’, ‘active’, ‘expired’, ‘test_dataset’ and None by default ‘active’

Return type

list of DatasetInfo

get_dataset_info(data_type=None, name=None, version=None, properties=None, status='active')

Find the one dataset that matches the given parameters.

Parameters

• data_type (str, optional) – data_type of the dataset, e.g., ‘litpop’ or ‘draught’

• name (str, optional) – the name of the dataset

• version (str, optional) – the version of the dataset

• properties (dict, optional) – search parameters for dataset properties, by default None any property has a string for key and can be a string or a list of strings for value

• status (str, optional) – valid values are ‘preliminary’, ‘active’, ‘expired’, ‘test_dataset’, None by default ‘active’

Return type

DatasetInfo

Raises

• AmbiguousResult – when there is more than one dataset matching the search parameters

• NoResult – when there is no dataset matching the search parameters

get_dataset_info_by_uuid(uuid)

Returns the data from ‘https://climada.ethz.ch/data-api/v1/dataset/{uuid}’ as DatasetInfo object.

Parameters

uuid (str) – the universal unique identifier of the dataset

Return type

DatasetInfo

Raises

NoResult – if the uuid is not valid

list_data_type_infos(data_type_group=None)

Returns all data types from the climada data API belonging to a given data type group.

Parameters

data_type_group (str, optional) – name of the data type group, by default None

Return type

list of DataTypeInfo

get_data_type_info(data_type)

Returns the metadata of the data type with the given name from the climada data API.

Parameters

data_type (str) – data type name

Return type

DataTypeInfo

Raises

NoResult – if there is no such data type registered

download_dataset(dataset, target_dir=PosixPath('/home/docs/climada/data'), organize_path=True)

Download all files from a given dataset to a given directory.

Parameters

• dataset (DatasetInfo) – the dataset

• target_dir (Path, optional) – target directory for download, by default climada.util.constants.SYSTEM_DIR

• organize_path (bool, optional) – if set to True the files will end up in subdirectories of target_dir: [target_dir]/[data_type_group]/[data_type]/[name]/[version] by default True

Returns

• download_dir (Path) – the path to the directory containing the downloaded files, will be created if organize_path is True

• downloaded_files (list of Path) – the downloaded files themselves

Raises

Exception – when one of the files cannot be downloaded

static purge_cache(local_path)

Removes entry from the sqlite database that keeps track of files downloaded by cached_download. This may be necessary in case a previous attempt has failed in an uncontroled way (power outage or the like).

Parameters

• local_path (Path) – target destination

• fileinfo (FileInfo) – file object as retrieved from the data api

get_hazard(hazard_type, name=None, version=None, properties=None, status='active', dump_dir=PosixPath('/home/docs/climada/data'))

Queries the data api for hazard datasets of the given type, downloads associated hdf5 files and turns them into a climada.hazard.Hazard object.

Parameters

• hazard_type (str) – Type of climada hazard.

• name (str, optional) – the name of the dataset

• version (str, optional) – the version of the dataset

• properties (dict, optional) – search parameters for dataset properties, by default None any property has a string for key and can be a string or a list of strings for value

• status (str, optional) – valid values are ‘preliminary’, ‘active’, ‘expired’, ‘test_dataset’, None by default ‘active’

• dump_dir (str, optional) – Directory where the files should be downoladed. Default: SYSTEM_DIR If the directory is the SYSTEM_DIR (as configured in climada.conf, i.g. ~/climada/data), the eventual target directory is organized into dump_dir > hazard_type > dataset name > version

Returns

The combined hazard object

Return type

climada.hazard.Hazard

to_hazard(dataset, dump_dir=PosixPath('/home/docs/climada/data'))

Downloads hdf5 files belonging to the given datasets reads them into Hazards and concatenates them into a single climada.Hazard object.

Parameters

• dataset (DatasetInfo) – Dataset to download and read into climada.Hazard object.

• dump_dir (str, optional) – Directory where the files should be downoladed. Default: SYSTEM_DIR (as configured in climada.conf, i.g. ~/climada/data). If the directory is the SYSTEM_DIR, the eventual target directory is organized into dump_dir > hazard_type > dataset name > version

Returns

The combined hazard object

Return type

climada.hazard.Hazard

get_exposures(exposures_type, name=None, version=None, properties=None, status='active', dump_dir=PosixPath('/home/docs/climada/data'))

Queries the data api for exposures datasets of the given type, downloads associated hdf5 files and turns them into a climada.entity.exposures.Exposures object.

Parameters

• exposures_type (str) – Type of climada exposures.

• name (str, optional) – the name of the dataset

• version (str, optional) – the version of the dataset

• properties (dict, optional) – search parameters for dataset properties, by default None any property has a string for key and can be a string or a list of strings for value

• status (str, optional) – valid values are ‘preliminary’, ‘active’, ‘expired’, ‘test_dataset’, None by default ‘active’

• dump_dir (str, optional) – Directory where the files should be downoladed. Default: SYSTEM_DIR If the directory is the SYSTEM_DIR, the eventual target directory is organized into dump_dir > hazard_type > dataset name > version

Returns

The combined exposures object

Return type

climada.entity.exposures.Exposures

to_exposures(dataset, dump_dir=PosixPath('/home/docs/climada/data'))

Downloads hdf5 files belonging to the given datasets reads them into Exposures and concatenates them into a single climada.Exposures object.

Parameters

• dataset (DatasetInfo) – Dataset to download and read into climada.Exposures objects.

• dump_dir (str, optional) – Directory where the files should be downoladed. Default: SYSTEM_DIR (as configured in climada.conf, i.g. ~/climada/data). If the directory is the SYSTEM_DIR, the eventual target directory is organized into dump_dir > exposures_type > dataset name > version

Returns

The combined exposures object

Return type

climada.entity.exposures.Exposures

get_litpop_default(country=None, dump_dir=PosixPath('/home/docs/climada/data'))

Get a LitPop instance on a 150arcsec grid with the default parameters: exponents = (1,1) and fin_mode = ‘pc’.

Parameters

• country (str or list, optional) – List of country name or iso3 codes for which to create the LitPop object. If None is given, a global LitPop instance is created. Defaut is None

• dump_dir (str) – directory where the files should be downoladed. Default: SYSTEM_DIR

Returns

default litpop Exposures object

Return type

climada.entity.exposures.Exposures

static get_property_values(dataset_infos, known_property_values=None, exclude_properties=None)

Returns a dictionnary of possible values for properties of a data type, optionally given known property values.

Parameters

• dataset_infos (list of DataSetInfo) – as returned by list_dataset_infos

• known_properties_value (dict, optional) – dict {‘property’:’value1, ‘property2’:’value2’}, to provide only a subset of property values that can be combined with the given properties.

• exclude_properties (list of str, optional) – properties in this list will be excluded from the resulting dictionary, e.g., because they are strictly metadata and don’t provide any information essential to the dataset. Default: ‘creation_date’, ‘climada_version’

Returns

of possibles property values

Return type

dict

static into_datasets_df(dataset_infos)

Convenience function providing a DataFrame of datasets with properties.

Parameters

dataset_infos (list of DatasetInfo) – as returned by list_dataset_infos

Returns

of datasets with properties as found in query by arguments

Return type

pandas.DataFrame

static into_files_df(dataset_infos)

Convenience function providing a DataFrame of files aligned with the input datasets.

Parameters

datasets (list of DatasetInfo) – as returned by list_dataset_infos

Returns

of the files’ informations including dataset informations

Return type

pandas.DataFrame

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 –

Return type

Filled array

climada.util.config module

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.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.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.constants.TEST_UNC_OUTPUT_IMPACT = 'test_unc_output_impact'

Demo uncertainty impact output

climada.util.constants.TEST_UNC_OUTPUT_COSTBEN = 'test_unc_output_costben'

Demo uncertainty costben output

climada.util.coordinates module

climada.util.coordinates.NE_EPSG = 4326

Natural Earth CRS EPSG

climada.util.coordinates.NE_CRS = 'epsg:4326'

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.NEAREST_NEIGHBOR_THRESHOLD = 100

Distance threshold in km for coordinate assignment. Nearest neighbors with greater distances are not considered.

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 ISO 3166 alpha-3 codes 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.assign_grid_points(x, y, grid_width, grid_height, grid_transform)

To each coordinate in x and y, assign the closest centroid in the given raster grid

Make sure that your grid specification is relative to the same coordinate reference system as the x and y coordinates. In case of lon/lat coordinates, make sure that the longitudinal values are within the same longitudinal range (such as [-180, 180]).

If your grid is given by bounds instead of a transform, the functions rasterio.transform.from_bounds and pts_to_raster_meta might be helpful.

Parameters

• x, y (np.array) – x- and y-coordinates of points to assign coordinates to.

• grid_width (int) – Width (number of columns) of the grid.

• grid_height (int) – Height (number of rows) of the grid.

• grid_transform (affine.Affine) – Affine transformation defining the grid raster.

Returns

assigned_idx – Index into the flattened grid. Note that the value -1 is used to indicate that no matching coordinate has been found, even though -1 is a valid index in NumPy!

Return type

np.array of size equal to the size of x and y

climada.util.coordinates.assign_coordinates(coords, coords_to_assign, distance='euclidean', threshold=100, **kwargs)

To each coordinate in coords, assign a matching coordinate in coords_to_assign

If there is no exact match for some entry, an attempt is made to assign the geographically nearest neighbor. If the distance to the nearest neighbor exceeds threshold, the index -1 is assigned.

Currently, the nearest neighbor matching works with lat/lon coordinates only. However, you can disable nearest neighbor matching by setting threshold to 0, in which case only exactly matching coordinates are assigned to each other.

Make sure that all coordinates are according to the same coordinate reference system. In case of lat/lon coordinates, the “haversine” distance is able to correctly compute the distance across the antimeridian. However, when exact matches are enforced with threshold=0, lat/lon coordinates need to be given in the same longitudinal range (such as (-180, 180)).

Parameters

• coords (np.array with two columns) – Each row is a geographical coordinate pair. The result’s size will match this array’s number of rows.

• coords_to_assign (np.array with two columns) – Each row is a geographical coordinate pair. The result will be an index into the rows of this array. Make sure that these coordinates use the same coordinate reference system as coords.

• distance (str, optional) – Distance to use for non-exact matching. Possible values are “euclidean”, “haversine” and “approx”. Default: “euclidean”

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

• kwargs (dict, optional) – Keyword arguments to be passed on to nearest-neighbor finding functions in case of non-exact matching with the specified distance.

Returns

assigned_idx – Index into coords_to_assign. Note that the value -1 is used to indicate that no matching coordinate has been found, even though -1 is a valid index in NumPy!

Return type

np.array of size equal to the number of rows in coords

Notes

By default, the ‘euclidean’ distance metric is used to find the nearest neighbors in case of non-exact matching. This method is fast for (quasi-)gridded data, but introduces innacuracy since distances in lat/lon coordinates are not equal to distances in meters on the Earth surface, in particular for higher latitude and distances larger than 100km. If more accuracy is needed, please use the ‘haversine’ distance metric. This however is slower for (quasi-)gridded data.

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_to_iso(countries, representation='alpha3', fillvalue=None)

Determine ISO 3166 representation of countries

Example

>>> country_to_iso(840)
'USA'
>>> country_to_iso("United States", representation="alpha2")
'US'
>>> country_to_iso(["United States of America", "SU"], "numeric")
[840, 810]

Some geopolitical areas that are not covered by ISO 3166 are added in the “user-assigned” range of ISO 3166-compliant values:

>>> country_to_iso(["XK", "Dhekelia"], "numeric")  # XK for Kosovo
[983, 907]

Parameters

• countries (one of str, int, list of str, list of int) – Country identifiers: name, official name, alpha-2, alpha-3 or numeric ISO codes. Numeric representations may be specified as str or int.

• representation (str (one of “alpha3”, “alpha2”, “numeric”, “name”), optional) – All countries are converted to this representation according to ISO 3166. Default: “alpha3”.

• fillvalue (str or int or None, optional) – The value to assign if a country is not recognized by the given identifier. By default, a LookupError is raised. Default: None

Returns

iso_list – ISO 3166 representation of countries. Will only return a list if the input is a list. Numeric representations are returned as integers.

Return type

one of str, int, list of str, list of int

climada.util.coordinates.country_iso_alpha2numeric(iso_alpha)

Deprecated: Use country_to_iso with representation=”numeric” instead

climada.util.coordinates.country_natid2iso(natids, representation='alpha3')

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

Parameters

• natids (int or list of int) – NatIDs of countries (or single ID) as used in ISIMIP’s version of the GPWv3 national identifier grid.

• representation (str, one of “alpha3”, “alpha2” or “numeric”) – All countries are converted to this representation according to ISO 3166. Default: “alpha3”.

Returns

iso_list – ISO 3166 representation of countries. Will only return a list if the input is a list. Numeric representations are returned as integers.

Return type

one of str, int, list of str, list of int

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 Natural Earth 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 or str) – string or list with strings, either ISO code or names of countries, e.g.: [‘ZWE’, ‘GBR’, ‘VNM’, ‘UZB’, ‘Kenya’, ‘051’] For example, for Armenia, the following inputs work:

‘Armenia’, ‘ARM’, ‘AM’, ‘051’, 51

Returns

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

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

climada.util.coordinates.get_admin1_geometries(countries)

return geometries, names and codes of admin 1 regions in given countries in a GeoDataFrame. If no admin 1 regions are defined, all regions in countries are returned.

Parameters

countries (list or str or int) – string or list containing strings, either ISO3 code or ISO2 code or names names of countries, e.g.: [‘ZWE’, ‘GBR’, ‘VNM’, ‘UZB’, ‘Kenya’, ‘051’] For example, for Armenia, the following inputs work:

‘Armenia’, ‘ARM’, ‘AM’, ‘051’, 51

Returns

gdf –

geopandas.GeoDataFrame instance with columns:

”admin1_name”str

name of admin 1 region

”iso_3166_2”str

iso code of admin 1 region

”geometry”Polygon or MultiPolygon

shape of admin 1 region as shapely geometry object

”iso_3n”str

numerical iso 3 code of country (admin 0)

”iso_3a”str

alphabetical iso 3 code of country (admin 0)

Return type

GeoDataFrame

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='nearest')

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 (int or str, optional) – Resampling method to use, encoded as an integer value (see rasterio.enums.Resampling). String values like “nearest” or “bilinear” are resolved to attributes of rasterio.enums.Resampling. Default: “nearest”

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, resampling='nearest', global_origin=None, pad_cells=1.0)

Read raster file within given bounds at given resolution

By default, not only the grid cells of the destination raster whose cell centers fall within the specified bounds are selected, but one additional row/column of grid cells is added as a padding in each direction (pad_cells=1). This makes sure that the extent of the selected cell centers encloses the specified bounds.

The axis orientations (e.g. north to south, west to east) of the input data set are preserved.

Parameters

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

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

• res (float or pair of floats, optional) – Resolution of output. Note that the orientation (sign) of these is overwritten by the input data set’s axis orientations (e.g. north to south, west to east). Default: Resolution of input raster file.

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

• resampling (int or str, optional) – Resampling method to use, encoded as an integer value (see rasterio.enums.Resampling). String values like “nearest” or “bilinear” are resolved to attributes of rasterio.enums.Resampling. Default: “nearest”

• global_origin (pair of floats, optional) – If given, align the output raster to a global reference raster with this origin. By default, the data set’s origin (according to it’s transform) is used.

• pad_cells (float, optional) – The number of cells to add as a padding (in terms of the destination grid that is inferred from res and/or global_origin if those parameters are given). This defaults to 1 to make sure that applying methods like bilinear interpolation to the output of this function is well-defined everywhere within the specified bounds. Default: 1.0

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, crs='EPSG:4326', 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

• crs (object (anything accepted by pyproj.CRS.from_user_input), optional) – If given, overwrites the CRS information given in points_df. If no CRS is explicitly given and there is no CRS information in points_df, the CRS is assumed to be EPSG:4326 (lat/lon). Default: None

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

Returns

• data (np.array) – 3d array containing the raster values. The first dimension has the same size as val_names and represents the raster bands.

• meta (dict) – Dictionary with ‘crs’, ‘height’, ‘width’ and ‘transform’ attributes.

climada.util.coordinates.subraster_from_bounds(transform, bounds)

Compute a subraster definition from a given reference transform and bounds.

The axis orientations (sign of resolution step sizes) in transform are not required to be north to south and west to east. The given orientation is preserved in the result.

Parameters

• transform (rasterio.Affine) – Affine transformation defining the reference grid.

• bounds (tuple of floats (xmin, ymin, xmax, ymax)) – Bounds of the subraster in units and CRS of the reference grid.

Returns

• dst_transform (rasterio.Affine) – Subraster affine transformation. The axis orientations of the input transform (e.g. north to south, west to east) are preserved.

• dst_shape (tuple of ints (height, width)) – Number of pixels of subraster in vertical and horizontal direction.

climada.util.coordinates.align_raster_data(source, src_crs, src_transform, dst_crs=None, dst_resolution=None, dst_bounds=None, global_origin=(- 180, 90), resampling='nearest', conserve=None, **kwargs)

Reproject 2D np.ndarray to be aligned to a reference grid.

This function ensures that reprojected data with the same dst_resolution and global_origins are aligned to the same global grid, i.e., no offset between destination grid points for different source grids that are projected to the same target resolution.

Note that the origin is required to be in the upper left corner. The result is always oriented left to right (west to east) and top to bottom (north to south).

Parameters

• source (np.ndarray) – The source is a 2D ndarray containing the values to be reprojected.

• src_crs (CRS or dict) – Source coordinate reference system, in rasterio dict format.

• src_transform (rasterio.Affine) – Source affine transformation.

• dst_crs (CRS, optional) – Target coordinate reference system, in rasterio dict format. Default: src_crs

• dst_resolution (tuple (x_resolution, y_resolution) or float, optional) – Target resolution (positive pixel sizes) in units of the target CRS. Default: (abs(src_transform[0]), abs(src_transform[4]))

• dst_bounds (tuple of floats (xmin, ymin, xmax, ymax), optional) – Bounds of the target raster in units of the target CRS. By default, the source’s bounds are reprojected to the target CRS.

• global_origin (tuple (west, north) of floats, optional) – Coordinates of the reference grid’s upper left corner. Default: (-180, 90). Make sure to change global_origin for non-geographical CRS!

• resampling (int or str, optional) – Resampling method to use, encoded as an integer value (see rasterio.enums.Resampling). String values like “nearest” or “bilinear” are resolved to attributes of rasterio.enums.Resampling. Default: “nearest”

• conserve (str, optional) – If provided, conserve the source array’s ‘mean’ or ‘sum’ in the transformed data or normalize the values of the transformed data ndarray (‘norm’). WARNING: Please note that this procedure will not apply any weighting of values according to the geographical cell sizes, which will introduce serious biases for lat/lon grids in case of areas spanning large latitudinal ranges. Default: None (no conservation)

• kwargs (dict, optional) – Additional arguments passed to rasterio.warp.reproject.

Raises

ValueError –

Returns

• destination (np.ndarray with same dtype as source) – The transformed 2D ndarray.

• dst_transform (rasterio.Affine) – Destination affine transformation.

climada.util.coordinates.mask_raster_with_geometry(raster, transform, shapes, nodata=None, **kwargs)

Change values in raster that are outside of given shapes to nodata.

This function is a wrapper for rasterio.mask.mask to allow for in-memory processing. This is done by first writing data to memfile and then reading from it before the function call to rasterio.mask.mask(). The MemoryFile will be discarded after exiting the with statement.

Parameters

• raster (numpy.ndarray) – raster to be masked with dim: [H, W].

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

• shapes (GeoJSON-like dict or an object that implements the Python geo) – interface protocol (such as a Shapely Polygon) Passed to rasterio.mask.mask

• nodata (int or float, optional) – Passed to rasterio.mask.mask: Data points outside shapes are set to nodata.

• kwargs (optional) – Passed to rasterio.mask.mask.

Returns

masked – raster with dim: [H, W] and points outside shapes set to nodata

Return type

numpy.ndarray or numpy.ma.MaskedArray

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

Set given geometry to given dataframe using dask if scheduler.

Parameters

• df_val (GeoDataFrame) – contains latitude and longitude columns

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

• crs (object (anything readable by pyproj4.CRS.from_user_input), optional) – Coordinate Reference System, if omitted or None: df_val.geometry.crs

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 (iterable of int) – ISO numeric-3 code(s) of country/countries

Returns

output_faocode – FAO country code(s) of country/countries

Return type

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

Return type

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’

Return type

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

Return type

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

Return type

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

Return type

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

file_names – a list of filenames that link to all just downloaded or available files from the forecast run, defined by the input parameters

Return type

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

file_name – absolute path and filename of the downloaded and decompressed netcdf file

Return type

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) – expected number of list elements

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

• val_name (str) – name of the variable values

Return type

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.

Return type

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.

Return type

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

Return type

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

Return type

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

Return type

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

Return type

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.

Return type

sparse csr matrix

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=<Derived Projected CRS: +proj=eqc +ellps=WGS84 +a=6378137.0 +lon_0=0.0 +to ...> Name: unknown Axis Info [cartesian]: - E[east]: Easting (unknown) - N[north]: Northing (unknown) - h[up]: Ellipsoidal height (metre) Area of Use: - undefined Coordinate Operation: - name: unknown - method: Equidistant Cylindrical Datum: unknown - Ellipsoid: WGS 84 - Prime Meridian: Greenwich, shapes=True, axes=None, figsize=(9, 13), adapt_fontsize=True, **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()

• shapes (bool, optional) – Overlay Earth’s countries coastlines to matplotlib.pyplot axis. The default is True

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

• figsize (tuple, optional) – figure size for plt.subplots, by default (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.

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

Return type

cartopy.mpl.geoaxes.GeoAxesSubplot

Raises

ValueError: – Input array size missmatch

climada.util.plot.geo_im_from_array(array_sub, coord, var_name, title, proj=None, smooth=True, axes=None, figsize=(9, 13), adapt_fontsize=True, **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)

• 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 – arbitrary keyword arguments for pcolormesh matplotlib function

Return type

cartopy.mpl.geoaxes.GeoAxesSubplot

Raises

ValueError –

climada.util.plot.make_map(num_sub=1, figsize=(9, 13), proj=<Derived Projected CRS: +proj=eqc +ellps=WGS84 +a=6378137.0 +lon_0=0.0 +to ...> Name: unknown Axis Info [cartesian]: - E[east]: Easting (unknown) - N[north]: Northing (unknown) - h[up]: Ellipsoidal height (metre) Area of Use: - undefined Coordinate Operation: - name: unknown - method: Equidistant Cylindrical Datum: unknown - Ellipsoid: WGS 84 - Prime Meridian: Greenwich, adapt_fontsize=True)

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.

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

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=<Derived Projected CRS: +proj=eqc +ellps=WGS84 +a=6378137.0 +lon_0=0.0 +to ...> Name: unknown Axis Info [cartesian]: - E[east]: Easting (unknown) - N[north]: Northing (unknown) - h[up]: Ellipsoidal height (metre) Area of Use: - undefined Coordinate Operation: - name: unknown - method: Equidistant Cylindrical Datum: unknown - Ellipsoid: WGS 84 - Prime Meridian: Greenwich, fontsize=None)

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.

• fontsize (int, optional) – Size of the fonts. If set to None, the default matplotlib settings are used.

climada.util.plot.add_cntry_names(axis, extent, proj=<Derived Projected CRS: +proj=eqc +ellps=WGS84 +a=6378137.0 +lon_0=0.0 +to ...> Name: unknown Axis Info [cartesian]: - E[east]: Easting (unknown) - N[north]: Northing (unknown) - h[up]: Ellipsoidal height (metre) Area of Use: - undefined Coordinate Operation: - name: unknown - method: Equidistant Cylindrical Datum: unknown - Ellipsoid: WGS 84 - Prime Meridian: Greenwich, fontsize=None)

Add country 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.

  fontsizeint, optional

  Size of the fonts. If set to None, the default matplotlib settings are used.

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) – file name

Return type

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

with 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.convert_monetary_value(values, abbrev, n_sig_dig=None)

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(imp, sampled_years, lam=None, correction_fac=True, seed=None)

Create a yearset of impacts (yimp) containing a probabilistic impact for each year in the sampled_years list by sampling events from the impact received as input with a Poisson distribution centered around lam per year (lam = sum(imp.frequency)). In contrast to the expected annual impact (eai) yimp contains impact values that differ among years. When correction factor is true, the yimp are scaled such that the average over all years is equal to the eai.

Parameters

• imp (climada.engine.Impact()) – impact object containing impacts per event

• sampled_years (list) – A list of years that shall be covered by the resulting yimp.

• seed (Any, optional) – seed for the default bit generator default: None

Optional parameters

lam: int

The applied Poisson distribution is centered around lam events per year. If no lambda value is given, the default lam = sum(imp.frequency) is used.

correction_facboolean

If True a correction factor is applied to the resulting yimp. It is scaled in such a way that the expected annual impact (eai) of the yimp equals the eai of the input impact

Returns

• yimp (climada.engine.Impact()) – yearset of impacts containing annual impacts for all sampled_years

• sampling_vect (2D array) – The sampling vector specifies how to sample the yimp, it consists of one sub-array per sampled_year, which contains the event_ids of the events used to calculate the annual impacts. Can be used to re-create the exact same yimp.

climada.util.yearsets.impact_yearset_from_sampling_vect(imp, sampled_years, sampling_vect, correction_fac=True)

Create a yearset of impacts (yimp) containing a probabilistic impact for each year in the sampled_years list by sampling events from the impact received as input following the sampling vector provided. In contrast to the expected annual impact (eai) yimp contains impact values that differ among years. When correction factor is true, the yimp are scaled such that the average over all years is equal to the eai.

Parameters

• imp (climada.engine.Impact()) – impact object containing impacts per event

• sampled_years (list) – A list of years that shall be covered by the resulting yimp.

• sampling_vect (2D array) – The sampling vector specifies how to sample the yimp, it consists of one sub-array per sampled_year, which contains the event_ids of the events used to calculate the annual impacts. It needs to be obtained in a first call, i.e. [yimp, sampling_vect] = climada_yearsets.impact_yearset(…) and can then be provided in this function to obtain the exact same sampling (also for a different imp object)

Optional parameter

correction_facboolean

If True a correction factor is applied to the resulting yimp. It is scaled in such a way that the expected annual impact (eai) of the yimp equals the eai of the input impact

Returns

yimp – yearset of impacts containing annual impacts for all sampled_years

Return type

climada.engine.Impact()

climada.util.yearsets.sample_from_poisson(n_sampled_years, lam, seed=None)

Sample the number of events for n_sampled_years

Parameters

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

• lam (int) – the applied Poisson distribution is centered around lambda events per year

• seed (int, optional) – seed for numpy.random, will be set if not None default: None

Returns

events_per_year – Number of events per sampled year

Return type

array

climada.util.yearsets.sample_events(events_per_year, freqs_orig, seed=None)

Sample events uniformely from an array (indices_orig) without replacement (if sum(events_per_year) > n_input_events the input events are repeated (tot_n_events/n_input_events) times, by ensuring that the same events doens’t occur more than once per sampled year).

Parameters

• events_per_year (array) – Number of events per sampled year

• freqs_orig (array) – Frequency of each input event

• seed (Any, optional) – seed for the default bit generator. Default: None

Returns

sampling_vect – The sampling vector specifies how to sample the yimp, it consists of one sub-array per sampled_year, which contains the event_ids of the events used to calculate the annual impacts.

Return type

2D array

climada.util.yearsets.compute_imp_per_year(imp, sampling_vect)

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

Parameters

• imp (climada.engine.Impact()) – impact object containing impacts per event

• sampling_vect (2D array) – The sampling vector specifies how to sample the yimp, it consists of one sub-array per sampled_year, which contains the event_ids of the events used to calculate the annual impacts.

Returns

imp_per_year – Sampled impact per year (length = sampled_years)

Return type

array

climada.util.yearsets.calculate_correction_fac(imp_per_year, imp)

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

Parameters

• imp_per_year (array) – sampled yimp

• imp (climada.engine.Impact()) – impact object containing impacts per event

Returns

correction_factor – The correction factor is calculated as imp_eai/yimp_eai

Return type

int