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.config.setup_conf_user()

Setup climada configuration

climada.util.config.setup_environ()

Parse binary environment and correct if necessary

climada.util.constants module

climada.util.constants.SOURCE_DIR = '/home/docs/checkouts/readthedocs.org/user_builds/climada-python/checkouts/v1.4.2/climada'

climada directory

climada.util.constants.DATA_DIR = '/home/docs/checkouts/readthedocs.org/user_builds/climada-python/checkouts/v1.4.2/data'

Folder containing the data

climada.util.constants.SYSTEM_DIR = '/home/docs/checkouts/readthedocs.org/user_builds/climada-python/checkouts/v1.4.2/data/system'

Folder containing the data used internally

climada.util.constants.GLB_CENTROIDS_NC = '/home/docs/checkouts/readthedocs.org/user_builds/climada-python/checkouts/v1.4.2/data/system/NatID_grid_0150as.nc'

Global centroids nc.

climada.util.constants.GLB_CENTROIDS_MAT = '/home/docs/checkouts/readthedocs.org/user_builds/climada-python/checkouts/v1.4.2/data/system/GLB_NatID_grid_0360as_adv_2.mat'

Global centroids.

climada.util.constants.ENT_TEMPLATE_XLS = '/home/docs/checkouts/readthedocs.org/user_builds/climada-python/checkouts/v1.4.2/data/system/entity_template.xlsx'

Entity template in xls format.

climada.util.constants.NAT_REG_ID = '/home/docs/checkouts/readthedocs.org/user_builds/climada-python/checkouts/v1.4.2/data/system/NatRegIDs.csv'

Look-up table ISO3 codes

climada.util.constants.HAZ_DEMO_FLDDPH = '/home/docs/checkouts/readthedocs.org/user_builds/climada-python/checkouts/v1.4.2/data/demo/flddph_WaterGAP2_miroc5_historical_flopros_gev_picontrol_2000_0.1.nc'

NetCDF4 Flood depth from isimip simulations

climada.util.constants.HAZ_DEMO_FLDFRC = '/home/docs/checkouts/readthedocs.org/user_builds/climada-python/checkouts/v1.4.2/data/demo/fldfrc_WaterGAP2_miroc5_historical_flopros_gev_picontrol_2000_0.1.nc'

NetCDF4 Flood fraction from isimip simulations

climada.util.constants.HAZ_DEMO_MAT = '/home/docs/checkouts/readthedocs.org/user_builds/climada-python/checkouts/v1.4.2/data/demo/atl_prob.mat'

hurricanes from 1851 to 2011 over Florida with 100 centroids.

Type

Hazard demo from climada in MATLAB

climada.util.constants.HAZ_DEMO_H5 = '/home/docs/checkouts/readthedocs.org/user_builds/climada-python/checkouts/v1.4.2/data/demo/tc_fl_1975_2011.h5'

ibtracs from 1975 to 2011 over Florida with 2500 centroids.

Type

Hazard demo in h5 format

climada.util.constants.DEMO_GDP2ASSET = '/home/docs/checkouts/readthedocs.org/user_builds/climada-python/checkouts/v1.4.2/data/demo/gdp2asset_CHE_exposure.nc'

Exposure demo file for GDP2Asset

climada.util.constants.WS_DEMO_NC = ['/home/docs/checkouts/readthedocs.org/user_builds/climada-python/checkouts/v1.4.2/data/demo/fp_lothar_crop-test.nc', '/home/docs/checkouts/readthedocs.org/user_builds/climada-python/checkouts/v1.4.2/data/demo/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.EXP_DEMO_H5 = '/home/docs/checkouts/readthedocs.org/user_builds/climada-python/checkouts/v1.4.2/data/demo/exp_demo_today.h5'

Exposures over Florida

climada.util.constants.TC_ANDREW_FL = '/home/docs/checkouts/readthedocs.org/user_builds/climada-python/checkouts/v1.4.2/data/demo/ibtracs_global_intp-None_1992230N11325.csv'

Tropical cyclone Andrew in Florida

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.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 = '/home/docs/checkouts/readthedocs.org/user_builds/climada-python/checkouts/v1.4.2/data/system/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.grid_is_regular(coord)

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

Parameters

coord (np.array)

Returns

bool (is regular), int (height), int (width)

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

Get Polygones of coast intersecting given bounds

Parameter:

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

GeoDataFrame

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

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

Parameter:

lon (float): longitude point in EPSG 4326 lat (float): latitude of point (lat, lon) in EPSG 4326

Returns

int

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

Comput distance to coast from input points in meters.

Parameters

• coord_lat (GeoDataFrame or np.array or float) –

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

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

  • float with a longitude value in epsg:4326

Returns

np.array

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

Get union of all the countries or the provided ones 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

shapely.geometry.multipolygon.MultiPolygon

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

Check if point is on land (True) or water (False) of provided coordinates. All globe considered if no input countries.

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) – profiles of land.

Returns

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

str

Raises

ValueError –

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

Returns a gpd GeoSeries of natural earth multipolygons of the specified countries, resp. the countries that lie within the specified 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, optional) – (min_lon, max_lon, min_lat, max_lat) 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

GeoDataFrame

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

Provide numeric country iso code for every point.

Parameters

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

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

Returns

np.array(int)

climada.util.coordinates.get_resolution(lat, lon, min_resol=1e-08)

Compute resolution of points in lat and lon

Parameters

• lat (np.array) – latitude of points

• lon (np.array) – longitude of points

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

Returns

float

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

” Transform vector data coordinates to raster. Returns number of rows, columns and affine transformation

Parameters

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

• res (float) – resolution of output raster

Returns

int, int, affine.Affine

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

Compare two crs

Parameters

• crs_one (dict or string or wkt) – user crs

• crs_two (dict or string or wkt) – user crs

Returns

bool

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

Read raster of bands and set 0 values to the masked ones. Each band is an event. Select region using window or geometry. Reproject input by proving dst_crs and/or (transform, width, height). Returns matrix in 2d: band x coordinates in 1d (evtl. reshape to band x height x width)

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

dict (meta), np.array (band x coordinates_in_1d)

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

Read vector file format supported by fiona. Each field_name name is considered an event.

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

np.array (lat), np.array (lon), geometry (GeiSeries), np.array (value)

climada.util.coordinates.write_raster(file_name, data_matrix, meta)

Write raster in GeoTiff format

Parameters

• fle_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 (transform needs to contain upper left corner!)

climada.util.coordinates.points_to_raster(points_df, val_names=['value'], res=None, raster_res=None, scheduler=None)

Compute raster matrix and transformation from value column

Parameters

• points_df (GeoDataFrame) – contains columns latitude, longitude and in val_names

• 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

np.array, affine.Affine

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

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.DIST_DEF = ['approx', 'haversine']

Distances

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

Interpolation methods

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

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

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

• proj (ccrs) – coordinate reference system used in coordinates

• kwargs (optional) – arguments for hexbin matplotlib function

Returns

cartopy.mpl.geoaxes.GeoAxesSubplot

Raises

ValueError –

climada.util.plot.geo_im_from_array(array_sub, geo_coord, var_name, title, proj=<cartopy.crs.PlateCarree object>, smooth=True, axes=None, **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.

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

• proj (ccrs) – coordinate reference system used in coordinates

• smooth (bool, optional) – smooth plot to RESOLUTIONxRESOLUTION. Default: True.

• kwargs (optional) – arguments for pcolormesh matplotlib function.

Returns

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, PlateCarree default.

Returns

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, PlateCarree default.

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, PlateCarree default.

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

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, PlateCarree default.

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