climada.hazard package

Contents

climada.hazard package#

climada.hazard.base module#

class climada.hazard.base.Hazard(haz_type: str = '', pool: ProcessPool | None = None, units: str = '', centroids: Centroids | None = None, event_id: ndarray | None = None, frequency: ndarray | None = None, frequency_unit: str = '1/year', event_name: List[str] | None = None, date: ndarray | None = None, orig: ndarray | None = None, intensity: csr_matrix | None = None, fraction: csr_matrix | None = None)[source]#

Bases: HazardIO, HazardPlot

Contains events of some hazard type defined at centroids. Loads from files with format defined in FILE_EXT.

Attention

This class uses instances of scipy.sparse.csr_matrix to store intensity and fraction. This data types comes with its particular pitfalls. Depending on how the objects are instantiated and modified, a matrix might end up in a “non-canonical” state. In this state, its .data attribute does not necessarily represent the values apparent in the final matrix. In particular, a “non-canonical” matrix may store “duplicates”, i.e. multiple values that map to the same matrix position. This is supported, and the default behavior is to sum up these values. To avoid any inconsistencies, call check_matrices() before accessing the data attribute of either matrix. This will explicitly sum all values at the same matrix position and eliminate explicit zeros.

haz_type#

two-letters hazard-type string, e.g., “TC” (tropical cyclone), “RF” (river flood) or “WF” (wild fire). Note: The acronym is used as reference to the hazard when centroids of multiple hazards are assigned to an Exposures object.

Type:

str

units#

units of the intensity

Type:

str

centroids#

centroids of the events

Type:

Centroids

event_id#

id (>0) of each event

Type:

np.array

event_name#

name of each event (default: event_id)

Type:

list(str)

date#

integer date corresponding to the proleptic Gregorian ordinal, where January 1 of year 1 has ordinal 1 (ordinal format of datetime library)

Type:

np.array

orig#

flags indicating historical events (True) or probabilistic (False)

Type:

np.array

frequency#

frequency of each event

Type:

np.array

frequency_unit#

unit of the frequency (default: “1/year”)

Type:

str

intensity#

intensity of the events at centroids

Type:

sparse.csr_matrix

fraction#

fraction of affected exposures for each event at each centroid. If empty (all 0), it is ignored in the impact computations (i.e., is equivalent to fraction is 1 everywhere).

Type:

sparse.csr_matrix

intensity_thres = 10#

Intensity threshold per hazard used to filter lower intensities. To be set for every hazard type

vars_oblig = {'centroids', 'event_id', 'fraction', 'frequency', 'intensity', 'units'}#

scalar, str, list, 1dim np.array of size num_events, scipy.sparse matrix of shape num_events x num_centroids, Centroids.

Type:

Name of the variables needed to compute the impact. Types

vars_def = {'date', 'event_name', 'frequency_unit', 'orig'}#

Name of the variables used in impact calculation whose value is descriptive and can therefore be set with default values. Types: scalar, string, list, 1dim np.array of size num_events.

vars_opt = {}#

Name of the variables that aren’t need to compute the impact. Types: scalar, string, list, 1dim np.array of size num_events.

__init__(haz_type: str = '', pool: ProcessPool | None = None, units: str = '', centroids: Centroids | None = None, event_id: ndarray | None = None, frequency: ndarray | None = None, frequency_unit: str = '1/year', event_name: List[str] | None = None, date: ndarray | None = None, orig: ndarray | None = None, intensity: csr_matrix | None = None, fraction: csr_matrix | None = None)[source]#

Initialize values.

Parameters:
  • haz_type (str, optional) – acronym of the hazard type (e.g. ‘TC’).

  • pool (pathos.pool, optional) – Pool that will be used for parallel computation when applicable. Default: None

  • units (str, optional) – units of the intensity. Defaults to empty string.

  • centroids (Centroids, optional) – centroids of the events. Defaults to empty Centroids object.

  • event_id (np.array, optional) – id (>0) of each event. Defaults to empty array.

  • event_name (list(str), optional) – name of each event (default: event_id). Defaults to empty list.

  • date (np.array, optional) – integer date corresponding to the proleptic Gregorian ordinal, where January 1 of year 1 has ordinal 1 (ordinal format of datetime library). Defaults to empty array.

  • orig (np.array, optional) – flags indicating historical events (True) or probabilistic (False). Defaults to empty array.

  • frequency (np.array, optional) – frequency of each event. Defaults to empty array.

  • frequency_unit (str, optional) – unit of the frequency (default: “1/year”).

  • intensity (sparse.csr_matrix, optional) – intensity of the events at centroids. Defaults to empty matrix.

  • fraction (sparse.csr_matrix, optional) – fraction of affected exposures for each event at each centroid. Defaults to empty matrix.

Examples

Initialize using keyword arguments:

>>> haz = Hazard('TC', intensity=sparse.csr_matrix(np.zeros((2, 2))))

Take hazard values from file:

>>> haz = Hazard.from_hdf5(HAZ_DEMO_H5)
check_matrices()[source]#

Ensure that matrices are consistently shaped and stored

It is good practice to call this method before accessing the data attribute of either intensity or fraction.

Raises:

ValueError – If matrices are ill-formed or ill-shaped in relation to each other

classmethod get_default(attribute)[source]#

Get the Hazard type default for a given attribute.

Parameters:

attribute (str) – attribute name

Return type:

Any

check()[source]#

Check dimension of attributes.

Raises:

ValueError

reproject_vector(dst_crs)[source]#

Change current point data to a a given projection

Parameters:

dst_crs (crs) – reproject to given crs

select(event_names=None, event_id=None, date=None, orig=None, reg_id=None, extent=None, reset_frequency=False)[source]#

Select events matching provided criteria

The frequency of events may need to be recomputed (see reset_frequency)!

Parameters:
  • event_names (list of str, optional) – Names of events.

  • event_id (list of int, optional) – Id of events. Default is None.

  • date (array-like of length 2 containing str or int, optional) – (initial date, final date) in string ISO format (‘2011-01-02’) or datetime ordinal integer.

  • orig (bool, optional) – Select only historical (True) or only synthetic (False) events.

  • reg_id (int, optional) – Region identifier of the centroids’ region_id attibute.

  • extent (tuple(float, float, float, float), optional) – Extent of centroids as (min_lon, max_lon, min_lat, max_lat). The default is None.

  • reset_frequency (bool, optional) – Change frequency of events proportional to difference between first and last year (old and new). Default: False.

Returns:

haz – If no event matching the specified criteria is found, None is returned.

Return type:

Hazard or None

select_tight(buffer=0.8999280057595392, val='intensity')[source]#

Reduce hazard to those centroids spanning a minimal box which contains all non-zero intensity or fraction points.

Parameters:
  • buffer (float, optional) – Buffer of box in the units of the centroids. The default is approximately equal to the default threshold from the assign_centroids method (works if centroids in lat/lon)

  • val (string, optional) – Select tight by non-zero ‘intensity’ or ‘fraction’. The default is ‘intensity’.

Returns:

Copy of the Hazard with centroids reduced to minimal box. All other hazard properties are carried over without changes.

Return type:

Hazard

See also

self.select

Method to select centroids by lat/lon extent

util.coordinates.match_coordinates

algorithm to match centroids.

local_exceedance_intensity(return_periods=(25, 50, 100, 250), method='interpolate', min_intensity=None, log_frequency=True, log_intensity=True)[source]#

Compute local exceedance intensity for given return periods. The default method is fitting the ordered intensitites per centroid to the corresponding cummulated frequency with by linear interpolation on log-log scale.

Parameters:
  • return_periods (array_like) – User-specified return periods for which the exceedance intensity should be calculated locally (at each centroid). Defaults to (25, 50, 100, 250).

  • method (str) – Method to interpolate to new return periods. Currently available are “interpolate”, “extrapolate”, “extrapolate_constant” and “stepfunction”. If set to “interpolate”, return periods outside the range of the Hazard object’s observed local return periods will be assigned NaN. If set to “extrapolate_constant” or “stepfunction”, return periods larger than the Hazard object’s observed local return periods will be assigned the largest local intensity, and return periods smaller than the Hazard object’s observed local return periods will be assigned 0. If set to “extrapolate”, local exceedance intensities will be extrapolated (and interpolated). Defauls to “interpolate”.

  • min_intensity (float, optional) – Minimum threshold to filter the hazard intensity. If set to None, self.intensity_thres will be used. Defaults to None.

  • log_frequency (bool, optional) – This parameter is only used if method is set to “interpolate”. If set to True, (cummulative) frequency values are converted to log scale before inter- and extrapolation. Defaults to True.

  • log_intensity (bool, optional) – This parameter is only used if method is set to “interpolate”. If set to True, intensity values are converted to log scale before inter- and extrapolation. Defaults to True.

Returns:

  • gdf (gpd.GeoDataFrame) – GeoDataFrame containing exeedance intensities for given return periods. Each column corresponds to a return period, each row corresponds to a centroid. Values in the gdf correspond to the exceedance intensity for the given centroid and return period

  • label (str) – GeoDataFrame label, for reporting and plotting

  • column_label (function) – Column-label-generating function, for reporting and plotting

local_exceedance_inten(return_period=(25, 50, 100, 250))[source]#

This function is deprecated, use Hazard.local_exceedance_intensity instead.

Deprecated since version The: use of Hazard.local_exceedance_inten is deprecated. Use Hazard.local_exceedance_intensity instead. Some errors in the previous calculation in Hazard.local_exceedance_inten have been corrected. To reproduce data with the previous calculation, use CLIMADA v5.0.0 or less.

sanitize_event_ids()[source]#

Make sure that event ids are unique

local_return_period(threshold_intensities=(10.0, 20.0), method='interpolate', min_intensity=None, log_frequency=True, log_intensity=True)[source]#

Compute local return periods for given hazard intensities. The default method is fitting the ordered intensitites per centroid to the corresponding cummulated frequency with by linear interpolation on log-log scale.

Parameters:
  • threshold_intensities (array_like) – User-specified hazard intensities for which the return period should be calculated locally (at each centroid). Defaults to (10, 20)

  • method (str) – Method to interpolate to new threshold intensities. Currently available are “interpolate”, “extrapolate”, “extrapolate_constant” and “stepfunction”. If set to “interpolate”, threshold intensities outside the range of the Hazard object’s local intensities will be assigned NaN. If set to “extrapolate_constant” or “stepfunction”, threshold intensities larger than the Hazard object’s local intensities will be assigned NaN, and threshold intensities smaller than the Hazard object’s local intensities will be assigned the smallest observed local return period. If set to “extrapolate”, local return periods will be extrapolated (and interpolated). Defaults to “interpolate”.

  • min_intensity (float, optional) – Minimum threshold to filter the hazard intensity. If set to None, self.intensity_thres will be used. Defaults to None.

  • log_frequency (bool, optional) – This parameter is only used if method is set to “interpolate”. If set to True, (cummulative) frequency values are converted to log scale before inter- and extrapolation. Defaults to True.

  • log_intensity (bool, optional) – This parameter is only used if method is set to “interpolate”. If set to True, intensity values are converted to log scale before inter- and extrapolation. Defaults to True.

Returns:

  • gdf (gpd.GeoDataFrame) – GeoDataFrame containing return periods for given threshold intensities. Each column corresponds to a threshold_intensity value, each row corresponds to a centroid. Values in the gdf correspond to the return period for the given centroid and threshold_intensity value

  • label (str) – GeoDataFrame label, for reporting and plotting

  • column_label (function) – Column-label-generating function, for reporting and plotting

get_event_id(event_name)[source]#

Get an event id from its name. Several events might have the same name.

Parameters:

event_name (str) – Event name

Returns:

list_id

Return type:

np.array(int)

get_event_name(event_id)[source]#

Get the name of an event id.

Parameters:

event_id (int) – id of the event

Return type:

str

Raises:

ValueError

get_event_date(event=None)[source]#

Return list of date strings for given event or for all events, if no event provided.

Parameters:

event (str or int, optional) – event name or id.

Returns:

l_dates

Return type:

list(str)

calc_year_set()[source]#

From the dates of the original events, get number yearly events.

Returns:

orig_yearset – key are years, values array with event_ids of that year

Return type:

dict

remove_duplicates()[source]#

Remove duplicate events (events with same name and date).

set_frequency(yearrange=None)[source]#

Set hazard frequency from yearrange or intensity matrix.

Parameters:

yearrange (tuple or list, optional) – year range to be used to compute frequency per event. If yearrange is not given (None), the year range is derived from self.date

property size#

Return number of events.

append(*others)[source]#

Append the events and centroids to this hazard object.

All of the given hazards must be of the same type and use the same units as self. The centroids of all hazards must have the same CRS.

The following kinds of object attributes are processed:

  • All centroids are combined together using Centroids.union.

  • Lists, 1-dimensional arrays (NumPy) and sparse CSR matrices (SciPy) are concatenated. Sparse matrices are concatenated along the first (vertical) axis.

For any other type of attribute: A ValueError is raised if an attribute of that name is not defined in all of the non-empty hazards at least. However, there is no check that the attribute value is identical among the given hazard objects. The initial attribute value of self will not be modified.

Note: Each of the hazard’s centroids attributes might be modified in place in the sense that missing properties are added, but existing ones are not overwritten. In case of raster centroids, conversion to point centroids is applied so that raster information (meta) is lost. For more information, see Centroids.union.

Parameters:

others (one or more climada.hazard.Hazard objects) – Hazard instances to append to self

Raises:

TypeError, ValueError

See also

Hazard.concat

concatenate 2 or more hazards

Centroids.union

combine centroids

classmethod concat(haz_list)[source]#

Concatenate events of several hazards of same type.

This function creates a new hazard of the same class as the first hazard in the given list and then applies the append method. Please refer to the docs of Hazard.append for caveats and limitations of the concatenation procedure.

For centroids, lists, arrays and sparse matrices, the remarks in Hazard.append apply. All other attributes are copied from the first object in haz_list.

Note that Hazard.concat can be used to concatenate hazards of a subclass. The result’s type will be the subclass. However, calling concat([]) (with an empty list) is equivalent to instantiation without init parameters. So, Hazard.concat([]) is equivalent to Hazard(). If HazardB is a subclass of Hazard, then HazardB.concat([]) is equivalent to HazardB() (unless HazardB overrides the concat method).

Parameters:

haz_list (list of climada.hazard.Hazard objects) – Hazard instances of the same hazard type (subclass).

Returns:

haz_concat – This will be of the same type (subclass) as all the hazards in haz_list.

Return type:

instance of climada.hazard.Hazard

See also

Hazard.append

append hazards to a hazard in place

Centroids.union

combine centroids

change_centroids(centroids, threshold=100)[source]#

Assign (new) centroids to hazard.

Centoids of the hazard not in centroids are mapped onto the nearest point. Fails if a point is further than threshold from the closest centroid.

The centroids must have the same CRS as self.centroids.

Parameters:
  • haz (Hazard) – Hazard instance

  • centroids (Centroids) – Centroids instance on which to map the hazard.

  • threshold (int or float) – Threshold (in km) for mapping haz.centroids not in centroids. Argument is passed to climada.util.coordinates.match_coordinates. Default: 100 (km)

Returns:

haz_new_cent – Hazard projected onto centroids

Return type:

Hazard

Raises:

ValueError

See also

util.coordinates.match_coordinates

algorithm to match centroids.

property centr_exp_col#

Name of the centroids columns for this hazard in an exposures

Returns:

centroids string indicator with hazard type defining column in an exposures gdf. E.g. “centr_TC”

Return type:

String

get_mdr(cent_idx, impf)[source]#

Return Mean Damage Ratio (mdr) for chosen centroids (cent_idx) for given impact function.

Parameters:
  • cent_idx (array-like) – array of indices of chosen centroids from hazard

  • impf (ImpactFunc) – impact function to compute mdr

Returns:

sparse matrix (n_events x len(cent_idx)) with mdr values

Return type:

sparse.csr_matrix

See also

get_paa

get the paa ffor the given centroids

get_paa(cent_idx, impf)[source]#

Return Percentage of Affected Assets (paa) for chosen centroids (cent_idx) for given impact function.

Note that value as intensity = 0 are ignored. This is different from get_mdr.

Parameters:
  • cent_idx (array-like) – array of indices of chosen centroids from hazard

  • impf (ImpactFunc) – impact function to compute mdr

Returns:

sparse matrix (n_events x len(cent_idx)) with paa values

Return type:

sparse.csr_matrix

See also

get_mdr

get the mean-damage ratio for the given centroids

climada.hazard.io module#

climada.hazard.io.DEF_VAR_EXCEL = {'col_centroids': {'col_name': {'cen_id': 'centroid_id', 'latitude': 'lat', 'longitude': 'lon'}, 'sheet_name': 'centroids'}, 'col_name': {'cen_id': 'centroid_id/event_id', 'even_dt': 'event_date', 'even_id': 'event_id', 'even_name': 'event_name', 'freq': 'frequency', 'orig': 'orig_event_flag'}, 'sheet_name': {'freq': 'hazard_frequency', 'inten': 'hazard_intensity'}}#

Excel variable names

climada.hazard.io.DEF_VAR_MAT = {'field_name': 'hazard', 'var_cent': {'field_names': ['centroids', 'hazard'], 'var_name': {'cen_id': 'centroid_ID', 'lat': 'lat', 'lon': 'lon'}}, 'var_name': {'comment': 'comment', 'datenum': 'datenum', 'ev_name': 'name', 'even_id': 'event_ID', 'frac': 'fraction', 'freq': 'frequency', 'inten': 'intensity', 'orig': 'orig_event_flag', 'per_id': 'peril_ID', 'unit': 'units'}}#

MATLAB variable names

climada.hazard.io.DEF_COORDS = {'event': 'time', 'latitude': 'latitude', 'longitude': 'longitude'}#

Default coordinates when reading Hazard data from an xarray Dataset

climada.hazard.io.DEF_DATA_VARS = ['fraction', 'frequency', 'event_id', 'event_name', 'date']#

Default keys for optional Hazard attributes when reading from an xarray Dataset

class climada.hazard.io.HazardIO[source]#

Bases: object

Contains all read/write methods of the Hazard class

set_raster(*args, **kwargs)[source]#

This function is deprecated, use Hazard.from_raster.

classmethod from_raster(files_intensity, files_fraction=None, attrs=None, band=None, haz_type=None, pool=None, src_crs=None, window=None, geometry=None, dst_crs=None, transform=None, width=None, height=None, resampling=Resampling.nearest)[source]#

Create Hazard with intensity and fraction values from raster files

If raster files are masked, the masked values are set to 0.

Files can be partially read using either window or geometry. Additionally, the data is reprojected when custom dst_crs and/or transform, width and height are specified.

Parameters:
  • files_intensity (list(str)) – file names containing intensity

  • files_fraction (list(str)) – file names containing fraction

  • attrs (dict, optional) – name of Hazard attributes and their values

  • band (list(int), optional) – bands to read (starting at 1), default [1]

  • haz_type (str, optional) – acronym of the hazard type (e.g. ‘TC’). Default: None, which will use the class default (’’ for vanilla Hazard objects, and hard coded in some subclasses)

  • pool (pathos.pool, optional) – Pool that will be used for parallel computation when applicable. Default: None

  • src_crs (crs, optional) – source CRS. Provide it if error without it.

  • window (rasterio.windows.Windows, optional) – window where data is extracted

  • geometry (list of shapely.geometry, optional) – consider pixels only within these shapes

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

  • transform (rasterio.Affine) – affine transformation to apply

  • wdith (float, optional) – number of lons for transform

  • height (float, optional) – number of lats for transform

  • resampling (rasterio.warp.Resampling, optional) – resampling function used for reprojection to dst_crs

Return type:

Hazard

classmethod from_xarray_raster_file(filepath: Path | str, *args, **kwargs)[source]#

Read raster-like data from a file that can be loaded with xarray

This wraps from_xarray_raster() by first opening the target file as xarray dataset and then passing it to that classmethod. Use this wrapper as a simple alternative to opening the file yourself. The signature is exactly the same, except for the first argument, which is replaced by a file path here.

Additional (keyword) arguments are passed to from_xarray_raster().

Parameters:

filepath (Path or str) – Path of the file to read with xarray. May be any file type supported by xarray. See https://docs.xarray.dev/en/stable/user-guide/io.html

Returns:

hazard – A hazard object created from the input data

Return type:

climada.Hazard

Examples

>>> hazard = Hazard.from_xarray_raster_file("path/to/file.nc", "", "")

Notes

If you have specific requirements for opening a data file, prefer opening it yourself and using from_xarray_raster(), following this pattern:

>>> open_kwargs = dict(engine="h5netcdf", chunks=dict(x=-1, y="auto"))
>>> with xarray.open_dataset("path/to/file.nc", **open_kwargs) as dset:
...     hazard = Hazard.from_xarray_raster(dset, "", "")
classmethod from_xarray_raster(data: Dataset, hazard_type: str, intensity_unit: str, *, intensity: str = 'intensity', coordinate_vars: Dict[str, str] | None = None, data_vars: Dict[str, str] | None = None, crs: str = 'EPSG:4326', rechunk: bool = False)[source]#

Read raster-like data from an xarray Dataset

This method reads data that can be interpreted using three coordinates: event, latitude, and longitude. The names of the coordinates to be read from the dataset can be specified via the coordinate_vars parameter. The data and the coordinates themselves may be organized in arbitrary dimensions (e.g. two dimensions ‘year’ and ‘altitude’ for the coordinate ‘event’). See Notes and Examples if you want to load single-event data that does not contain an event dimension.

The only required data is the intensity. For all other data, this method can supply sensible default values. By default, this method will try to find these “optional” data in the Dataset and read it, or use the default values otherwise. Users may specify the variables in the Dataset to be read for certain Hazard object entries, or may indicate that the default values should be used although the Dataset contains appropriate data. This behavior is controlled via the data_vars parameter.

If this method succeeds, it will always return a “consistent” Hazard object, meaning that the object can be used in all CLIMADA operations without throwing an error due to missing data or faulty data types.

Use from_xarray_raster_file() to open a file on disk and load the resulting dataset with this method in one step.

Parameters:
  • data (xarray.Dataset) – The dataset to read from.

  • hazard_type (str) – The type identifier of the hazard. Will be stored directly in the hazard object.

  • intensity_unit (str) – The physical units of the intensity.

  • intensity (str, optional) – Identifier of the xarray.DataArray containing the hazard intensity data.

  • coordinate_vars (dict(str, str), optional) – Mapping from default coordinate names to coordinate names used in the data to read. The default is dict(event="time", longitude="longitude", latitude="latitude"), as most of the commonly used hazard data happens to have a “time” attribute but no “event” attribute.

  • data_vars (dict(str, str), optional) – Mapping from default variable names to variable names used in the data to read. The default names are fraction, hazard_type, frequency, event_name, event_id, and date. If these values are not set, the method tries to load data from the default names. If this fails, the method uses default values for each entry. If the values are set to empty strings (""), no data is loaded and the default values are used exclusively. See examples for details.

    Default values are:

    • date: The event coordinate interpreted as date or ordinal, or ones if that fails (which will issue a warning).

    • fraction: None, which results in a value of 1.0 everywhere, see Hazard.__init__() for details.

    • hazard_type: Empty string

    • frequency: 1.0 for every event

    • event_name: String representation of the event date or empty strings if that fails (which will issue a warning).

    • event_id: Consecutive integers starting at 1 and increasing with time

  • crs (str, optional) – Identifier for the coordinate reference system of the coordinates. Defaults to EPSG:4326 (WGS 84), defined by climada.util.constants.DEF_CRS. See https://pyproj4.github.io/pyproj/dev/api/crs/crs.html#pyproj.crs.CRS.from_user_input for further information on how to specify the coordinate system.

  • rechunk (bool, optional) – Rechunk the dataset before flattening. This might have serious performance implications. Rechunking in general is expensive, but it might be less expensive than stacking a poorly-chunked array. One event being stored in one chunk would be the optimal configuration. If rechunk=True, this will be forced by rechunking the data. Ideally, you would select the chunks in that manner when opening the dataset before passing it to this function. Defaults to False.

Returns:

hazard – A hazard object created from the input data

Return type:

climada.Hazard

See also

from_xarray_raster_file()

Use this method if you want CLIMADA to open and read a file on disk for you.

Notes

  • Single-valued coordinates given by coordinate_vars, that are not proper dimensions of the data, are promoted to dimensions automatically. If one of the three coordinates does not exist, use Dataset.expand_dims (see https://docs.xarray.dev/en/stable/generated/xarray.Dataset.expand_dims.html and Examples) before loading the Dataset as Hazard.

  • Single-valued data for variables frequency. event_name, and event_date will be broadcast to every event.

  • The event coordinate may take arbitrary values. In case these values cannot be interpreted as dates or date ordinals, the default values for Hazard.date and Hazard.event_name are used, see the data_vars` parameter documentation above.

  • To avoid confusion in the call signature, several parameters are keyword-only arguments.

  • The attributes Hazard.haz_type and Hazard.unit currently cannot be read from the Dataset. Use the method parameters to set these attributes.

  • This method does not read coordinate system metadata. Use the crs parameter to set a custom coordinate system identifier.

Examples

The use of this method is straightforward if the Dataset contains the data with expected names.

>>> dset = xr.Dataset(
...     dict(
...         intensity=(
...             ["time", "latitude", "longitude"],
...             [[[0, 1, 2], [3, 4, 5]]],
...         )
...     ),
...     dict(
...         time=[datetime.datetime(2000, 1, 1)],
...         latitude=[0, 1],
...         longitude=[0, 1, 2],
...     ),
... )
>>> hazard = Hazard.from_xarray_raster(dset, "", "")

For non-default coordinate names, use the coordinate_vars argument.

>>> dset = xr.Dataset(
...     dict(
...         intensity=(
...             ["day", "lat", "longitude"],
...             [[[0, 1, 2], [3, 4, 5]]],
...         )
...     ),
...     dict(
...         day=[datetime.datetime(2000, 1, 1)],
...         lat=[0, 1],
...         longitude=[0, 1, 2],
...     ),
... )
>>> hazard = Hazard.from_xarray_raster(
...     dset, "", "", coordinate_vars=dict(event="day", latitude="lat")
... )

Coordinates can be different from the actual dataset dimensions. The following loads the data with coordinates longitude and latitude (default names):

>>> dset = xr.Dataset(
...     dict(intensity=(["time", "y", "x"], [[[0, 1, 2], [3, 4, 5]]])),
...     dict(
...         time=[datetime.datetime(2000, 1, 1)],
...         y=[0, 1],
...         x=[0, 1, 2],
...         longitude=(["y", "x"], [[0.0, 0.1, 0.2], [0.0, 0.1, 0.2]]),
...         latitude=(["y", "x"], [[0.0, 0.0, 0.0], [0.1, 0.1, 0.1]]),
...     ),
... )
>>> hazard = Hazard.from_xarray_raster(dset, "", "")

Optional data is read from the dataset if the default keys are found. Users can specify custom variables in the data, or that the default keys should be ignored, with the data_vars argument.

>>> dset = xr.Dataset(
...     dict(
...         intensity=(
...             ["time", "latitude", "longitude"],
...             [[[0, 1, 2], [3, 4, 5]]],
...         ),
...         fraction=(
...             ["time", "latitude", "longitude"],
...             [[[0.0, 0.1, 0.2], [0.3, 0.4, 0.5]]],
...         ),
...         freq=(["time"], [0.4]),
...         event_id=(["time"], [4]),
...     ),
...     dict(
...         time=[datetime.datetime(2000, 1, 1)],
...         latitude=[0, 1],
...         longitude=[0, 1, 2],
...     ),
... )
>>> hazard = Hazard.from_xarray_raster(
...     dset,
...     "",
...     "",
...     data_vars=dict(
...         # Load frequency from 'freq' array
...         frequency="freq",
...         # Ignore 'event_id' array and use default instead
...         event_id="",
...         # 'fraction' array is loaded because it has the default name
...     ),
... )
>>> np.array_equal(hazard.frequency, [0.4]) and np.array_equal(
...     hazard.event_id, [1]
... )
True

If your read single-event data your dataset probably will not have a time dimension. As long as a time coordinate exists, however, this method will automatically promote it to a dataset dimension and load the data:

>>> dset = xr.Dataset(
...     dict(
...         intensity=(
...             ["latitude", "longitude"],
...             [[0, 1, 2], [3, 4, 5]],
...         )
...     ),
...     dict(
...         time=[datetime.datetime(2000, 1, 1)],
...         latitude=[0, 1],
...         longitude=[0, 1, 2],
...     ),
... )
>>> hazard = Hazard.from_xarray_raster(dset, "", "")  # Same as first example

If one coordinate is missing altogehter, you must add it or expand the dimensions before loading the dataset:

>>> dset = xr.Dataset(
...     dict(
...         intensity=(
...             ["latitude", "longitude"],
...             [[0, 1, 2], [3, 4, 5]],
...         )
...     ),
...     dict(
...         latitude=[0, 1],
...         longitude=[0, 1, 2],
...     ),
... )
>>> dset = dset.expand_dims(time=[numpy.datetime64("2000-01-01")])
>>> hazard = Hazard.from_xarray_raster(dset, "", "")
read_excel(*args, **kwargs)[source]#

This function is deprecated, use Hazard.from_excel.

classmethod from_excel(file_name, var_names=None, haz_type=None)[source]#

Read climada hazard generated with the MATLAB code in Excel format.

Parameters:
  • file_name (str) – absolute file name

  • var_names (dict, default) (name of the variables in the file,) – default: DEF_VAR_EXCEL constant

  • haz_type (str, optional) – acronym of the hazard type (e.g. ‘TC’). Default: None, which will use the class default (’’ for vanilla Hazard objects, and hard coded in some subclasses)

Returns:

haz – Hazard object from the provided Excel file

Return type:

climada.hazard.Hazard

Raises:

KeyError

write_raster(file_name, variable='intensity', output_resolution=None)[source]#

Write intensity or fraction as GeoTIFF file. Each band is an event. Output raster is always a regular grid (same resolution for lat/lon).

Note that if output_resolution is not None, the data is rasterized to that resolution. This is an expensive operation. For hazards that are already a raster, output_resolution=None saves on this raster which is efficient.

If you want to save both fraction and intensity, create two separate files. These can then be read together with the from_raster method.

Parameters:
  • file_name (str) – file name to write in tif format

  • variable (str) – if ‘intensity’, write intensity, if ‘fraction’ write fraction. Default is ‘intensity’

  • output_resolution (int) – If not None, the data is rasterized to this resolution. Default is None (resolution is estimated from the data).

See also

from_raster

method to read intensity and fraction raster files.

write_hdf5(file_name, todense=False)[source]#

Write hazard in hdf5 format.

Parameters:
  • file_name (str) – file name to write, with h5 format

  • todense (bool) – if True write the sparse matrices as hdf5.dataset by converting them to dense format first. This increases readability of the file for other programs. default: False

read_hdf5(*args, **kwargs)[source]#

This function is deprecated, use Hazard.from_hdf5.

classmethod from_hdf5(file_name)[source]#

Read hazard in hdf5 format.

Parameters:

file_name (str) – file name to read, with h5 format

Returns:

haz – Hazard object from the provided MATLAB file

Return type:

climada.hazard.Hazard

climada.hazard.isimip_data module#

climada.hazard.plot module#

class climada.hazard.plot.HazardPlot[source]#

Bases: object

Contains all plotting methods of the Hazard class

plot_rp_intensity(return_periods=(25, 50, 100, 250), smooth=True, axis=None, figsize=(9, 13), adapt_fontsize=True, **kwargs)[source]#

This function is deprecated, use Impact.local_exceedance_impact and util.plot.plot_from_gdf instead.

Compute and plot hazard exceedance intensity maps for different return periods. Calls local_exceedance_inten.

Parameters:
  • return_periods (tuple(int), optional) – return periods to consider

  • smooth (bool, optional) – smooth plot to plot.RESOLUTIONxplot.RESOLUTION

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

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

  • kwargs (optional) – arguments for pcolormesh matplotlib function used in event plots

Returns:

axis, inten_stats – intenstats is return_periods.size x num_centroids

Return type:

matplotlib.axes._subplots.AxesSubplot, np.ndarray

Deprecated since version The: use of Hazard.plot_rp_intensity is deprecated.Use Hazard.local_exceedance_intensity and util.plot.plot_from_gdf instead.

plot_intensity(event=None, centr=None, smooth=True, axis=None, adapt_fontsize=True, **kwargs)[source]#

Plot intensity values for a selected event or centroid.

Parameters:
  • event (int or str, optional) – If event > 0, plot intensities of event with id = event. If event = 0, plot maximum intensity in each centroid. If event < 0, plot abs(event)-largest event. If event is string, plot events with that name.

  • centr (int or tuple, optional) – If centr > 0, plot intensity of all events at centroid with id = centr. If centr = 0, plot maximum intensity of each event. If centr < 0, plot abs(centr)-largest centroid where higher intensities are reached. If tuple with (lat, lon) plot intensity of nearest centroid.

  • smooth (bool, optional) – Rescale data to RESOLUTIONxRESOLUTION pixels (see constant in module climada.util.plot)

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

  • kwargs (optional) – arguments for pcolormesh matplotlib function used in event plots or for plot function used in centroids plots

Return type:

matplotlib.axes._subplots.AxesSubplot

Raises:

ValueError

plot_fraction(event=None, centr=None, smooth=True, axis=None, **kwargs)[source]#

Plot fraction values for a selected event or centroid.

Parameters:
  • event (int or str, optional) – If event > 0, plot fraction of event with id = event. If event = 0, plot maximum fraction in each centroid. If event < 0, plot abs(event)-largest event. If event is string, plot events with that name.

  • centr (int or tuple, optional) – If centr > 0, plot fraction of all events at centroid with id = centr. If centr = 0, plot maximum fraction of each event. If centr < 0, plot abs(centr)-largest centroid where highest fractions are reached. If tuple with (lat, lon) plot fraction of nearest centroid.

  • smooth (bool, optional) – Rescale data to RESOLUTIONxRESOLUTION pixels (see constant in module climada.util.plot)

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

  • kwargs (optional) – arguments for pcolormesh matplotlib function used in event plots or for plot function used in centroids plots

Return type:

matplotlib.axes._subplots.AxesSubplot

Raises:

ValueError

climada.hazard.storm_europe module#

class climada.hazard.storm_europe.StormEurope(units: str = 'm/s', ssi: ndarray | None = None, ssi_wisc: ndarray | None = None, ssi_full_area: ndarray | None = None, **kwargs)[source]#

Bases: Hazard

A hazard set containing european winter storm events. Historic storm events can be downloaded at http://wisc.climate.copernicus.eu/ and read with from_footprints. Weather forecasts can be automatically downloaded from https://opendata.dwd.de/ and read with from_icon_grib(). Weather forecast from the COSMO-Consortium http://www.cosmo-model.org/ can be read with from_cosmoe_file().

ssi_wisc#

Storm Severity Index (SSI) as recorded in the footprint files; apparently not reproducible from the footprint values only.

Type:

np.array, float

ssi#

SSI as set by set_ssi; uses the Dawkins definition by default.

Type:

np.array, float

intensity_thres = 14.7#

Intensity threshold for storage in m/s; same as used by WISC SSI calculations.

vars_opt = {'ssi', 'ssi_full_area', 'ssi_wisc'}#

Name of the variables that aren’t need to compute the impact.

__init__(units: str = 'm/s', ssi: ndarray | None = None, ssi_wisc: ndarray | None = None, ssi_full_area: ndarray | None = None, **kwargs)[source]#

Initialize a StormEurope object

Parameters:
  • units (str) – The units of the Hazard intensity. Defaults to ‘m/s’

  • ssi (numpy.ndarray) – The Storm Severity Index (SSI). 1d vector, same length as number of storms. Defaults to an empty array.

  • ssi_wisc (numpy.ndarray) – The Storm Severity Index (SSI) as reconded in the footprint files. 1d vector, same length as number of storms. Defaults to an empty array.

  • ssi_full_area (numpy.ndarray) – 1d vector, same length as number of storms. Used to conserve the the index that is derived from the area and windspeed of the full geographic extent of a storm system. Needed for cropping the StormEurope object into a smaller region`. Defaults to an empty array.

read_footprints(*args, **kwargs)[source]#

This function is deprecated, use StormEurope.from_footprints instead.

classmethod from_footprints(path, ref_raster=None, centroids=None, files_omit='fp_era20c_1990012515_701_0.nc', combine_threshold=None, intensity_thres=None)[source]#

Create new StormEurope object from WISC footprints.

Assumes that all footprints have the same coordinates as the first file listed/first file in dir.

Parameters:
  • path (str, list(str)) – A location in the filesystem. Either a path to a single netCDF WISC footprint, or a folder containing only footprints, or a globbing pattern to one or more footprints.

  • ref_raster (str, optional) – Reference netCDF file from which to construct a new barebones Centroids instance. Defaults to the first file in path.

  • centroids (Centroids, optional) – A Centroids struct, overriding ref_raster

  • files_omit (str, list(str), optional) – List of files to omit; defaults to one duplicate storm present in the WISC set as of 2018-09-10.

  • combine_threshold (int, optional) – threshold for combining events in number of days. if the difference of the dates (self.date) of two events is smaller or equal to this threshold, the two events are combined into one. Default is None, Advised for WISC is 2

  • intensity_thres (float, optional) – Intensity threshold for storage in m/s. Default: class attribute StormEurope.intensity_thres (same as used by WISC SSI calculations)

Returns:

haz – StormEurope object with data from WISC footprints.

Return type:

StormEurope

read_cosmoe_file(*args, **kwargs)[source]#

This function is deprecated, use StormEurope.from_cosmoe_file instead.

classmethod from_cosmoe_file(fp_file, run_datetime, event_date=None, model_name='COSMO-2E', description=None, intensity_thres=None)[source]#

Create a new StormEurope object with gust footprint from weather forecast.

The funciton is designed for the COSMO ensemble model used by the COSMO Consortium http://www.cosmo-model.org/ and postprocessed to an netcdf file using fieldextra. One event is one full day in UTC. Works for MeteoSwiss model output of COSMO-1E (11 members, resolution 1.1 km, forecast period 33-45 hours) COSMO-2E (21 members, resolution 2.2 km, forecast period 5 days)

The frequency of each event is informed by their probability in the ensemble forecast and is equal to 1/11 or 1/21 for COSMO-1E or COSMO-2E, respectively.

Parameters:
  • fp_file (str) – string directing to one netcdf file

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

  • event_date (datetime, optional) – one day within the forecast period, only this day (00H-24H) will be included in the hazard

  • model_name (str,optional) – provide the name of the COSMO model, for the description (e.g., ‘COSMO-1E’, ‘COSMO-2E’)

  • description (str, optional) – description of the events, defaults to a combination of model_name and run_datetime

  • intensity_thres (float, optional) – Intensity threshold for storage in m/s. Default: class attribute StormEurope.intensity_thres (same as used by WISC SSI calculations)

Returns:

haz – StormEurope object with data from COSMO ensemble file.

Return type:

StormEurope

read_icon_grib(*args, **kwargs)[source]#

This function is deprecated, use StormEurope.from_icon_grib instead.

classmethod from_icon_grib(run_datetime, event_date=None, model_name='icon-eu-eps', description=None, grib_dir=None, delete_raw_data=True, intensity_thres=None)[source]#

Create new StormEurope object from DWD icon weather forecast footprints.

New files are available for 24 hours on https://opendata.dwd.de, old files can be processed if they are already stored in grib_dir. One event is one full day in UTC. Current setup works for runs starting at 00H and 12H. Otherwise the aggregation is inaccurate, because of the given file structure with 1-hour, 3-hour and 6-hour maxima provided.

The frequency for one event is 1/(number of ensemble members)

Parameters:
  • run_datetime (datetime) – The starting timepoint of the forecast run of the icon model

  • event_date (datetime, optional) – one day within the forecast period, only this day (00H-24H) will be included in the hazard

  • model_name (str,optional) – select the name of the icon model to be downloaded. Must match the url on https://opendata.dwd.de (see download_icon_grib for further info)

  • description (str, optional) – description of the events, defaults to a combination of model_name and run_datetime

  • grib_dir (str, optional) – path to folder, where grib files are or should be stored

  • delete_raw_data (bool,optional) – select if downloaded raw data in .grib.bz2 file format should be stored on the computer or removed

  • intensity_thres (float, optional) – Intensity threshold for storage in m/s. Default: class attribute StormEurope.intensity_thres (same as used by WISC SSI calculations)

Returns:

haz – StormEurope object with data from DWD icon weather forecast footprints.

Return type:

StormEurope

calc_ssi(method='dawkins', intensity=None, on_land=True, threshold=None, sel_cen=None)[source]#

Calculate the SSI, method must either be ‘dawkins’ or ‘wisc_gust’.

‘dawkins’, after Dawkins et al. (2016), doi:10.5194/nhess-16-1999-2016, matches the MATLAB version. ssi = sum_i(area_cell_i * intensity_cell_i^3)

‘wisc_gust’, according to the WISC Tier 1 definition found at https://wisc.climate.copernicus.eu/wisc/#/help/products#tier1_section ssi = sum(area_on_land) * mean(intensity)^3

In both definitions, only raster cells that are above the threshold are used in the computation. Note that this method does not reproduce self.ssi_wisc, presumably because the footprint only contains the maximum wind gusts instead of the sustained wind speeds over the 72 hour window. The deviation may also be due to differing definitions of what lies on land (i.e. Syria, Russia, Northern Africa and Greenland are exempt).

Parameters:
  • method (str) – Either ‘dawkins’ or ‘wisc_gust’

  • intensity (scipy.sparse.csr) – Intensity matrix; defaults to self.intensity

  • on_land (bool) – Only calculate the SSI for areas on land, ignoring the intensities at sea. Defaults to true, whereas the MATLAB version did not.

  • threshold (float, optional) – Intensity threshold used in index definition. Cannot be lower than the read-in value.

  • sel_cen (np.array, bool) – A boolean vector selecting centroids. Takes precendence over on_land.

set_ssi(**kwargs)[source]#

Wrapper around calc_ssi for setting the self.ssi attribute.

Parameters:

kwargs – passed on to calc_ssi

plot_ssi(full_area=False)[source]#
Plot the distribution of SSIs versus their cumulative exceedance

frequencies, highlighting historical storms in red.

Returns:

  • fig (matplotlib.figure.Figure)

  • ax (matplotlib.axes._subplots.AxesSubplot)

generate_prob_storms(reg_id=528, spatial_shift=4, ssi_args=None, **kwargs)[source]#

Generates a new hazard set with one original and 29 probabilistic storms per historic storm. This represents a partial implementation of the Monte-Carlo method described in section 2.2 of Schwierz et al. (2010), doi:10.1007/s10584-009-9712-1. It omits the rotation of the storm footprints, as well as the pseudo- random alterations to the intensity.

In a first step, the original intensity and five additional intensities are saved to an array. In a second step, those 6 possible intensity levels are shifted by n raster pixels into each direction (N/S/E/W).

Caveats:
  • Memory safety is an issue; trial with the entire dataset resulted in 60GB of swap memory being used…

  • Can only use numeric region_id for country selection

  • Drops event names as provided by WISC

Parameters:
  • region_id (int, list of ints, or None) – iso_n3 code of the countries we want the generated hazard set to be returned for.

  • spatial_shift (int) – amount of raster pixels to shift by

  • ssi_args (dict) – A dictionary of arguments passed to calc_ssi

  • kwargs – keyword arguments passed on to self._hist2prob()

Returns:

new_haz – A new hazard set for the given country. Centroid attributes are preserved. self.orig attribute is set to True for original storms (event_id ending in 00). Also contains a ssi_prob attribute,

Return type:

StormEurope

climada.hazard.tc_clim_change module#

climada.hazard.tc_clim_change.get_knutson_scaling_factor(variable: str = 'cat05', percentile: str = '50', basin: str = 'NA', baseline: tuple = (1982, 2022), yearly_steps: int = 5)[source]#

This code combines data in Knutson et al. (2020) and global mean surface temperature (GMST) data (historical and CMIP5 simulated) to produce TC projections for 4 RCPs and any historical baseline. The code uses GMST data implements to interpolate and extrapolate the Knutson data relative to the specified baseline time period for various RCPs with a log-linear model. The methodology was developed and explained in Jewson et al., (2021).

Related publications: - Knutson et al., (2020): Tropical cyclones and climate

change assessment. Part II: Projected response to anthropogenic warming. Bull. Amer. Meteor. Soc., 101 (3), E303–E322, https://doi.org/10.1175/BAMS-D-18-0194.1.

Parameters:
  • variable (int) – variable of interest, possible choices are ‘cat05’ (frequencies of all tropical cyclones), ‘cat45’ (frequencies of category 4 and 5 tropical cyclones) and ‘intensity’ (mean intensity of all tropical cyclones)

  • percentile (str) – percentiles of Knutson et al. 2020 estimates, representing the model uncertainty in future changes in TC activity. These estimates come from a review of state-of-the-art literature and models. For the ‘cat05’ variable (i.e. frequency of all tropical cyclones) the 5th, 25th, 50th, 75th and 95th percentiles are provided. For ‘cat45’ and ‘intensity’, the provided percentiles are the 10th, 25th, 50th, 75th and 90th. Please refer to the mentioned publications for more details. possible percentiles:

    ‘5/10’ either the 5th or 10th percentile depending on variable (see text above) ‘25’ for the 25th percentile ‘50’ for the 50th percentile ‘75’ for the 75th percentile ‘90/95’ either the 90th or 95th percentile depending on variable (see text above)

    Default: ‘50’

  • basin (str) –

    region of interest, possible choices are:

    ‘NA’, ‘WP’, ‘EP’, ‘NI’, ‘SI’, ‘SP’

  • baseline (tuple of int) – the starting and ending years that define the historical baseline. The historical baseline period must fall within the GSMT data period, i.e., 1880-2100. Default is 1982-2022.

  • yearly_steps (int) – yearly resolution at which projections are provided. Default is 5 years.

Returns:

future_change_variable – data frame with future projections of the selected variables at different times (indexes) and for RCPs 2.6, 4.5, 6.0 and 8.5 (columns).

Return type:

pd.DataFrame

climada.hazard.tc_clim_change.get_gmst_info()[source]#

Get Global Mean Surface Temperature (GMST) data from 1880 to 2100 for RCPs 2.6, 4.5, 6.0 and 8.5. Data are provided in:

Jewson (2021): Conversion of the Knutson et al. (2020) Tropical Cyclone Climate Change Projections to Risk Model Baselines, https://doi.org/10.1175/JAMC-D-21-0102.1

and in supporting documentation and code.

Returns:

gmst_info – dictionary with four keys, which are: - rcps: list of strings referring to RCPs 2.6, 4.5, 6.0 and 8.5 - gmst_start_year: integer with the GMST data starting year, 1880 - gmst_end_year: integer with the GMST data ending year, 2100 - gmst_data: array with GMST data across RCPs (first dim) and years (second dim)

Return type:

dict

climada.hazard.tc_clim_change.get_knutson_data()[source]#

Retrieve projections data in Knutson et al., (2020):

Tropical cyclones and climate change assessment. Part II: Projected

response to anthropogenic warming. Bull. Amer. Meteor. Soc., 101 (3), E303–E322, https://doi.org/10.1175/BAMS-D-18-0194.1.

for 4 variables (i.e., cat05 frequency, cat45 frequency, intensity, precipitation rate), 6 regions, i.e., N. Atl (NA), NW Pac. (WP), NE Pac (EP)., N. Ind (NI), S. Ind. (SI), SW Pac. (SP), and 5 percentiles, i.e., 5% or 10%, 25%, 50%, 75%, 95% or 90%.

The data are available at:

S Jewson, T Knutson, S Camargo, J Chan, K Emanuel, C Ho, J Kossin, M Mohapatra, M Satoh, M Sugi, K Walsh, & L Wu. (2021). Knutson et al 2020 Tropical Cyclone Projections Data (v0.2) [Data set]. Zenodo. https://doi.org/10.5281/zenodo.4757343

Returns:

knutson_data – array contaning data used by Knutson et al. (2020) to project changes in cat05 frequency, cat45 frequency, intensity and precipitation rate (first array’s dimension), for the N. Atl (NA), NW Pac. (WP), NE Pac (EP)., N. Ind (NI), S. Ind. (SI), SW Pac. (SP) regions (second array’s dimension) for the 5%/10%, 25%, 50%, 75%, 95%/90% percentiles (thirs array’s dimension).

Return type:

np.array of dimension (4x6x5)

climada.hazard.tc_tracks module#

climada.hazard.tc_tracks.CAT_NAMES = {-1: 'Tropical Depression', 0: 'Tropical Storm', 1: 'Hurricane Cat. 1', 2: 'Hurricane Cat. 2', 3: 'Hurricane Cat. 3', 4: 'Hurricane Cat. 4', 5: 'Hurricane Cat. 5'}#

Saffir-Simpson category names.

climada.hazard.tc_tracks.SAFFIR_SIM_CAT = [34, 64, 83, 96, 113, 137, 1000]#

Saffir-Simpson Hurricane Wind Scale in kn based on NOAA

class climada.hazard.tc_tracks.TCTracks(data: List[Dataset] | None = None, pool: ProcessPool | None = None)[source]#

Bases: object

Contains tropical cyclone tracks.

data#
List of tropical cyclone tracks. Each track contains following attributes:
  • time (coords)

  • lat (coords)

  • lon (coords)

  • time_step (in hours)

  • radius_max_wind (in nautical miles)

  • radius_oci (in nautical miles)

  • max_sustained_wind (in knots)

  • central_pressure (in hPa/mbar)

  • environmental_pressure (in hPa/mbar)

  • basin (for each track position)

  • max_sustained_wind_unit (attrs)

  • central_pressure_unit (attrs)

  • name (attrs)

  • sid (attrs)

  • orig_event_flag (attrs)

  • data_provider (attrs)

  • id_no (attrs)

  • category (attrs)

Computed during processing:
  • on_land (bool for each track position)

  • dist_since_lf (in km)

Additional data variables such as “nature” (specifiying, for each track position, whether a system is a disturbance, tropical storm, post-transition extratropical storm etc.) might be included, depending on the data source and on use cases.

Type:

list(xarray.Dataset)

__init__(data: List[Dataset] | None = None, pool: ProcessPool | None = None)[source]#

Create new (empty) TCTracks instance.

Parameters:
  • data (list of xarray.Dataset, optional) – List of tropical cyclone tracks, each stored as single xarray Dataset. See the Attributes for a full description of the required Dataset variables and attributes. Defaults to an empty list.

  • pool (pathos.pools, optional) – Pool that will be used for parallel computation when applicable. Default: None

append(tracks)[source]#

Append tracks to current.

Parameters:

tracks (xarray.Dataset or list(xarray.Dataset)) – tracks to append.

get_track(track_name=None)[source]#

Get track with provided name.

Returns the first matching track based on the assumption that no other track with the same name or sid exists in the set.

Parameters:

track_name (str, optional) – Name or sid (ibtracsID for IBTrACS) of track. If None (default), return all tracks.

Returns:

result – Usually, a single track is returned. If no track with the specified name is found, an empty list [] is returned. If called with track_name=None, the list of all tracks is returned.

Return type:

xarray.Dataset or list of xarray.Dataset

subset(filterdict)[source]#

Subset tracks based on track attributes.

Select all tracks matching exactly the given attribute values.

Parameters:

filterdict (dict or OrderedDict) – Keys are attribute names, values are the corresponding attribute values to match. In case of an ordered dict, the filters are applied in the given order.

Returns:

tc_tracks – A new instance of TCTracks containing only the matching tracks.

Return type:

TCTracks

tracks_in_exp(exposure, buffer=1.0)[source]#

Select only the tracks that are in the vicinity (buffer) of an exposure.

Each exposure point/geometry is extended to a disc of radius buffer. Each track is converted to a line and extended by a radius buffer.

Parameters:
  • exposure (Exposure) – Exposure used to select tracks.

  • buffer (float, optional) – Size of buffer around exposure geometries (in the units of exposure.crs), see geopandas.distance. Default: 1.0

Returns:

filtered_tracks – TCTracks object with tracks from tc_tracks intersecting the exposure whitin a buffer distance.

Return type:

TCTracks

read_ibtracs_netcdf(*args, **kwargs)[source]#

This function is deprecated, use TCTracks.from_ibtracs_netcdf instead.

classmethod from_ibtracs_netcdf(provider=None, rescale_windspeeds=True, storm_id=None, year_range=None, basin=None, genesis_basin=None, interpolate_missing=True, estimate_missing=False, correct_pres=False, discard_single_points=True, additional_variables=None, file_name='IBTrACS.ALL.v04r00.nc')[source]#

Create new TCTracks object from IBTrACS databse.

When using data from IBTrACS, make sure to be familiar with the scope and limitations of IBTrACS, e.g. by reading the official documentation (https://www.ncei.noaa.gov/sites/default/files/2021-07/IBTrACS_version4_Technical_Details.pdf). Reading the CLIMADA documentation can’t replace a thorough understanding of the underlying data. This function only provides a (hopefully useful) interface for the data input, but cannot provide any guidance or make recommendations about if and how to use IBTrACS data for your particular project.

Resulting tracks are required to have both pressure and wind speed information at all time steps. Therefore, all track positions where one of wind speed or pressure are missing are discarded unless one of interpolate_missing or estimate_missing are active.

Some corrections are automatically applied, such as: environmental_pressure is enforced to be larger than central_pressure.

Note that the tracks returned by this function might contain irregular time steps since that is often the case for the original IBTrACS records: many agencies add an additional time step at landfall. Apply the equal_timestep function afterwards to enforce regular time steps.

Parameters:
  • provider (str or list of str, optional) – Either specify an agency, such as “usa”, “newdelhi”, “bom”, “cma”, “tokyo”, or the special values “official” and “official_3h”:

    • “official” means using the (usually 6-hourly) officially reported values of the officially responsible agencies.

    • “official_3h” means to include (inofficial) 3-hourly data of the officially responsible agencies (whenever available).

    If you want to restrict to the officially reported values by the officially responsible agencies (provider=”official”) without any modifications to the original official data, make sure to also set estimate_missing=False and interpolate_missing=False. Otherwise, gaps in the official reporting will be filled using interpolation and/or statistical estimation procedures (see below). If a list is given, the following logic is applied: For each storm, the variables that are not reported by the first agency for this storm are taken from the next agency in the list that did report this variable for this storm. For different storms, the same variable might be taken from different agencies. Default: ['official_3h', 'usa', 'tokyo', 'newdelhi', 'reunion', 'bom', 'nadi', 'wellington', 'cma', 'hko', 'ds824', 'td9636', 'td9635', 'neumann', 'mlc']

  • rescale_windspeeds (bool, optional) – If True, all wind speeds are linearly rescaled to 1-minute sustained winds. Note however that the IBTrACS documentation (Section 5.2, https://www.ncei.noaa.gov/sites/default/files/2021-07/IBTrACS_version4_Technical_Details.pdf) includes a warning about this kind of conversion: “While a multiplicative factor can the numerical differences, there are procedural and observational differences between agencies that can change through time, which confounds the simple multiplicative factor.” Default: True

  • storm_id (str or list of str, optional) – IBTrACS ID of the storm, e.g. 1988234N13299, [1988234N13299, 1989260N11316].

  • year_range (tuple (min_year, max_year), optional) – Year range to filter track selection. Default: None.

  • basin (str, optional) – If given, select storms that have at least one position in the specified basin. This allows analysis of a given basin, but also means that basin-specific track sets should not be combined across basins since some storms will be in more than one set. If you would like to select storms by their (unique) genesis basin instead, use the parameter genesis_basin. For possible values (basin abbreviations), see the parameter genesis_basin. If None, this filter is not applied. Default: None.

  • genesis_basin (str, optional) – The basin where a TC is formed is not defined in IBTrACS. However, this filter option allows to restrict to storms whose first valid eye position is in the specified basin, which simulates the genesis location. Note that the resulting genesis basin of a particular track may depend on the selected provider and on estimate_missing because only the first valid eye position is considered. Possible values are ‘NA’ (North Atlantic), ‘SA’ (South Atlantic), ‘EP’ (Eastern North Pacific, which includes the Central Pacific region), ‘WP’ (Western North Pacific), ‘SP’ (South Pacific), ‘SI’ (South Indian), ‘NI’ (North Indian). If None, this filter is not applied. Default: None.

  • interpolate_missing (bool, optional) – If True, interpolate temporal reporting gaps within a variable (such as pressure, wind speed, or radius) linearly if possible. Temporal interpolation is with respect to the time steps defined in IBTrACS for a particular storm. No new time steps are added that are not originally defined in IBTrACS. For each time step with a missing value, this procedure is only able to fill in that value if there are other time steps before and after this time step for which values have been reported. This procedure will be applied before the statistical estimations referred to by estimate_missing. It is applied to all variables (eye position, wind speed, environmental and central pressure, storm radius and radius of maximum winds). Default: True

  • estimate_missing (bool, optional) – For each fixed time step, estimate missing pressure, wind speed and radius using other variables that are available at that time step. The relationships between the variables are purely statistical. In comparison to interpolate_missing, this procedure is able to estimate values for variables that haven’t been reported by any agency at any time step, as long as other variables are available. A typical example are storms before 1950, for which there are often no reported values for pressure, but for wind speed. In this case, a rough statistical pressure-wind relationship is applied to estimate the missing pressure values from the available wind-speed values. Make sure to set rescale_windspeeds=True when using this option because the statistical relationships are calibrated using rescaled wind speeds. Default: False

  • correct_pres (bool, optional) – For backwards compatibility, alias for estimate_missing. This is deprecated, use estimate_missing instead!

  • discard_single_points (bool, optional) – Whether to discard tracks that consists of a single point. Recommended for full compatiblity with other functions such as equal_timesteps. Default: True.

  • file_name (str, optional) – Name of NetCDF file to be dowloaded or located at climada/data/system. Default: ‘IBTrACS.ALL.v04r00.nc’

  • additional_variables (list of str, optional) – If specified, additional IBTrACS data variables are extracted, such as “nature” or “storm_speed”. Only variables that are not agency-specific are supported. Default: None.

Returns:

tracks – TCTracks with data from IBTrACS

Return type:

TCTracks

read_processed_ibtracs_csv(*args, **kwargs)[source]#

This function is deprecated, use TCTracks.from_processed_ibtracs_csv instead.

classmethod from_processed_ibtracs_csv(file_names)[source]#

Create TCTracks object from processed ibtracs CSV file(s).

Parameters:

file_names (str or list of str) – Absolute file name(s) or folder name containing the files to read.

Returns:

tracks – TCTracks with data from the processed ibtracs CSV file.

Return type:

TCTracks

read_simulations_emanuel(*args, **kwargs)[source]#

This function is deprecated, use TCTracks.from_simulations_emanuel instead.

classmethod from_simulations_emanuel(file_names, hemisphere=None, subset=None)[source]#

Create new TCTracks object from Kerry Emanuel’s tracks.

Parameters:
  • file_names (str or list of str) – Absolute file name(s) or folder name containing the files to read.

  • hemisphere (str or None, optional) – For global data sets, restrict to northern (‘N’) or southern (‘S’) hemisphere. Default: None (no restriction)

  • subset (list of int, optional) – If given, only include the tracks with the given indices. Since the simulation files can be huge, this feature is useful for running tests on smaller subsets or on random subsamples. Default: None

Returns:

tracks – TCTracks with data from Kerry Emanuel’s simulations.

Return type:

TCTracks

read_one_gettelman(nc_data, i_track)[source]#

This function is deprecated, use TCTracks.from_gettelman instead.

classmethod from_gettelman(path)[source]#

Create new TCTracks object from Andrew Gettelman’s tracks.

Parameters:

path (str or Path) – Path to one of Andrew Gettelman’s NetCDF files.

Returns:

tracks – TCTracks with data from Andrew Gettelman’s simulations.

Return type:

TCTracks

read_simulations_chaz(*args, **kwargs)[source]#

This function is deprecated, use TCTracks.from_simulations_chaz instead.

classmethod from_simulations_chaz(file_names, year_range=None, ensemble_nums=None)[source]#

Create new TCTracks object from CHAZ simulations

Lee, C.-Y., Tippett, M.K., Sobel, A.H., Camargo, S.J. (2018): An Environmentally Forced Tropical Cyclone Hazard Model. J Adv Model Earth Sy 10(1): 223–241.

Parameters:
  • file_names (str or list of str) – Absolute file name(s) or folder name containing the files to read.

  • year_range (tuple (min_year, max_year), optional) – Filter by year, if given.

  • ensemble_nums (list, optional) – Filter by ensembleNum, if given.

Returns:

tracks – TCTracks with data from the CHAZ simulations.

Return type:

TCTracks

read_simulations_storm(*args, **kwargs)[source]#

This function is deprecated, use TCTracks.from_simulations_storm instead.

classmethod from_simulations_storm(path, years=None)[source]#

Create new TCTracks object from STORM simulations

Bloemendaal et al. (2020): Generation of a global synthetic tropical cyclone hazard dataset using STORM. Scientific Data 7(1): 40.

Track data available for download from

Wind speeds are converted to 1-minute sustained winds through division by 0.88 (this value is taken from Bloemendaal et al. (2020), cited above).

Parameters:
  • path (str) – Full path to a txt-file as contained in the data.zip archive from the official source linked above.

  • years (list of int, optional) – If given, only read the specified “years” from the txt-File. Note that a “year” refers to one ensemble of tracks in the data set that represents one sample year.

Returns:

tracks – TCTracks with data from the STORM simulations.

Return type:

TCTracks

Notes

All tracks are set in the year 1980. The id of the year (starting from 0) is saved in the attribute ‘id_no’. To obtain the year of each track use

>>> years = [int(tr.attrs['id_no'] / 1000) for tr in tc_tracks.data]
>>> # or, alternatively,
>>> years = [int(tr.attrs['sid'].split("-")[-2]) for tr in tc_tracks.data]

If a windfield is generated from these tracks using the method TropCylcone.from_tracks(), the following should be considered:

  1. The frequencies will be set to 1 for each storm. Thus, in order to compute annual values, the frequencies of the TropCylone should be changed to 1/number of years.

  2. The storm year and the storm id are stored in the TropCyclone.event_name attribute.

equal_timestep(time_step_h=1, land_params=False, pool=None)[source]#

Resample all tracks at the specified temporal resolution

The resulting track data will be given at evenly distributed time steps, relative to midnight (00:00). For example, if time_step_h is 1 and the original track data starts at 06:30, the interpolated track will not have a time step at 06:30 because only multiples of 01:00 (relative to midnight) are included. In this case, the interpolated track will start at 07:00.

Depending on the original resolution of the track data, this method may up- or downsample track time steps.

Note that tracks that already have the specified resolution remain unchanged.

Parameters:
  • time_step_h (float or int, optional) – Temporal resolution in hours (positive, may be non-integer-valued). Default: 1.

  • land_params (bool, optional) – If True, recompute on_land and dist_since_lf at each node. Default: False.

  • pool (pathos.pool, optional) – Pool that will be used for parallel computation when applicable. If not given, the pool attribute of self will be used. Default: None

calc_random_walk(**kwargs)[source]#

Deprecated. Use TCTracks.calc_perturbed_trajectories instead.

calc_perturbed_trajectories(**kwargs)[source]#

See function in climada.hazard.tc_tracks_synth.

property size#

Get longitude from coord array.

get_bounds(deg_buffer=0.1)[source]#

Get bounds as (lon_min, lat_min, lon_max, lat_max) tuple.

Parameters:

deg_buffer (float) – A buffer to add around the bounding box

Returns:

bounds

Return type:

tuple (lon_min, lat_min, lon_max, lat_max)

property bounds#

Exact bounds of trackset as tuple, no buffer.

get_extent(deg_buffer=0.1)[source]#

Get extent as (lon_min, lon_max, lat_min, lat_max) tuple.

Parameters:

deg_buffer (float) – A buffer to add around the bounding box

Returns:

extent

Return type:

tuple (lon_min, lon_max, lat_min, lat_max)

property extent#

Exact extent of trackset as tuple, no buffer.

generate_centroids(res_deg, buffer_deg)[source]#

Generate gridded centroids within padded bounds of tracks

Parameters:
  • res_deg (float) – Resolution in degrees.

  • buffer_deg (float) – Buffer around tracks in degrees.

Returns:

centroids – Centroids instance.

Return type:

Centroids

plot(axis=None, figsize=(9, 13), legend=True, adapt_fontsize=True, **kwargs)[source]#

Track over earth. Historical events are blue, probabilistic black.

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

  • figsize ((float, float), optional) – figure size for plt.subplots The default is (9, 13)

  • legend (bool, optional) – whether to display a legend of Tropical Cyclone categories. Default: True.

  • kwargs (optional) – arguments for LineCollection matplotlib, e.g. alpha=0.5

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

axis

Return type:

matplotlib.axes._subplots.AxesSubplot

write_netcdf(folder_name)[source]#

Write a netcdf file per track with track.sid name in given folder.

Parameters:

folder_name (str) – Folder name where to write files.

read_netcdf(*args, **kwargs)[source]#

This function is deprecated, use TCTracks.from_netcdf instead.

classmethod from_netcdf(folder_name)[source]#

Create new TCTracks object from NetCDF files contained in a given folder

Warning

Do not use this classmethod for reading IBTrACS NetCDF files! If you need to manually download IBTrACS NetCDF files, place them in the ~/climada/data/system folder and use the TCTracks.from_ibtracks_netcdf classmethod.

Parameters:

folder_name (str) – Folder name from where to read files.

Returns:

tracks – TCTracks with data from the given directory of NetCDF files.

Return type:

TCTracks

write_hdf5(file_name, complevel=5)[source]#

Write TC tracks in NetCDF4-compliant HDF5 format.

Parameters:
  • file_name (str or Path) – Path to a new HDF5 file. If it exists already, the file is overwritten.

  • complevel (int) – Specifies a compression level (0-9) for the zlib compression of the data. A value of 0 or None disables compression. Default: 5

classmethod from_hdf5(file_name)[source]#

Create new TCTracks object from a NetCDF4-compliant HDF5 file

Parameters:

file_name (str or Path) – Path to a file that has been generated with TCTracks.write_hdf.

Returns:

tracks – TCTracks with data from the given HDF5 file.

Return type:

TCTracks

to_geodataframe(as_points=False, split_lines_antimeridian=True)[source]#

Transform this TCTracks instance into a GeoDataFrame.

Parameters:
  • as_points (bool, optional) – If False (default), one feature (row) per track with a LineString or MultiLineString as geometry (or Point geometry for tracks of length one) and all track attributes (sid, name, orig_event_flag, etc) as dataframe columns. If True, one feature (row) per track time step, with variable values per time step (radius_max_wind, max_sustained_wind, etc) as columns in addition to attributes.

  • split_lines_antimeridian (bool, optional) – If True, tracks that cross the antimeridian are split into multiple Lines as a MultiLineString, with each Line on either side of the meridian. This ensures all Lines are within (-180, +180) degrees longitude. Note that lines might be split at more locations than strictly necessary, due to the underlying splitting algorithm (Toblerity/Shapely#572).

Returns:

gdf

Return type:

GeoDataFrame

climada.hazard.tc_tracks.set_category(max_sus_wind, wind_unit='kn', saffir_scale=None)[source]#

Add storm category according to Saffir-Simpson hurricane scale.

Parameters:
  • max_sus_wind (np.array) – Maximum sustained wind speed records for a single track.

  • wind_unit (str, optional) – Units of wind speed. Default: ‘kn’.

  • saffir_scale (list, optional) – Saffir-Simpson scale in same units as wind (default scale valid for knots).

Returns:

category

Intensity of given track according to the Saffir-Simpson hurricane scale:
  • -1 : tropical depression

  • 0 : tropical storm

  • 1 : Hurricane category 1

  • 2 : Hurricane category 2

  • 3 : Hurricane category 3

  • 4 : Hurricane category 4

  • 5 : Hurricane category 5

Return type:

int

climada.hazard.tc_tracks_synth module#

climada.hazard.tc_tracks_synth.LANDFALL_DECAY_V = {-1: 0.00012859077693295416, 0: 0.0017226346292718126, 1: 0.002309772914350468, 2: 0.0025968221565522698, 3: 0.002626252944053856, 4: 0.002550639312763181, 5: 0.003788695795963695}#

Global landfall decay parameters for wind speed by TC category.

Keys are TC categories with -1=’TD’, 0=’TS’, 1=’Cat 1’, …, 5=’Cat 5’.

It is v_rel as derived from:

>>> tracks = TCTracks.from_ibtracs_netcdf(year_range=(1980,2019), estimate_missing=True)
>>> extent = tracks.get_extent()
>>> land_geom = climada.util.coordinates.get_land_geometry(
...     extent=extent, resolution=10
... )
>>> v_rel, p_rel = _calc_land_decay(tracks.data, land_geom, pool=tracks.pool)
climada.hazard.tc_tracks_synth.LANDFALL_DECAY_P = {-1: (1.0088807492745373, 0.002117478217863062), 0: (1.0192813768091684, 0.003068578025845065), 1: (1.0362982218631644, 0.003620816186262243), 2: (1.0468630800617038, 0.004067381088015585), 3: (1.0639055205005432, 0.003708174876364079), 4: (1.0828373148889825, 0.003997492773076179), 5: (1.1088615145002092, 0.005224331234796362)}#

Global landfall decay parameters for pressure by TC category.

Keys are TC categories with -1=’TD’, 0=’TS’, 1=’Cat 1’, …, 5=’Cat 5’.

It is p_rel as derived from:

>>> tracks = TCTracks.from_ibtracs_netcdf(year_range=(1980,2019), estimate_missing=True)
>>> extent = tracks.get_extent()
>>> land_geom = climada.util.coordinates.get_land_geometry(
...     extent=extent, resolution=10
... )
>>> v_rel, p_rel = _calc_land_decay(tracks.data, land_geom, pool=tracks.pool)
climada.hazard.tc_tracks_synth.calc_perturbed_trajectories(tracks, nb_synth_tracks=9, max_shift_ini=0.75, max_dspeed_rel=0.3, max_ddirection=0.008726646259971648, autocorr_dspeed=0.85, autocorr_ddirection=0.5, seed=54, decay=True, use_global_decay_params=True, pool=None)[source]#

Generate synthetic tracks based on directed random walk. An ensemble of nb_synth_tracks synthetic tracks is computed for every track contained in self.

The methodology perturbs the tracks locations, and if decay is True it additionally includes decay of wind speed and central pressure drop after landfall. No other track parameter is perturbed. The track starting point location is perturbed by random uniform values of magnitude up to max_shift_ini in both longitude and latitude. Then, each segment between two consecutive points is perturbed in direction and distance (i.e., translational speed). These perturbations can be correlated in time, i.e., the perturbation in direction applied to segment i is correlated with the perturbation in direction applied to segment i-1 (and similarly for the perturbation in translational speed). Perturbations in track direction and temporal auto-correlations in perturbations are on an hourly basis, and the perturbations in translational speed is relative. Hence, the parameter values are relatively insensitive to the temporal resolution of the tracks. Note however that all tracks should be at the same temporal resolution, which can be achieved using equal_timestep(). max_dspeed_rel and autocorr_dspeed control the spread along the track (‘what distance does the track run for’), while max_ddirection and autocorr_ddirection control the spread perpendicular to the track movement (‘how does the track diverge in direction’). max_dspeed_rel and max_ddirection control the amplitude of perturbations at each track timestep but perturbations may tend to compensate each other over time, leading to a similar location at the end of the track, while autocorr_dspeed and autocorr_ddirection control how these perturbations persist in time and hence the amplitude of the perturbations towards the end of the track.

Note that the default parameter values have been only roughly calibrated so that the frequency of tracks in each 5x5degree box remains approximately constant. This is not an in-depth calibration and should be treated as such. The object is mutated in-place.

Parameters:
  • tracks (climada.hazard.TCTracks) – Tracks data.

  • nb_synth_tracks (int, optional) – Number of ensemble members per track. Default: 9.

  • max_shift_ini (float, optional) – Amplitude of max random starting point shift in decimal degree (up to +/-max_shift_ini for longitude and latitude). Default: 0.75.

  • max_dspeed_rel (float, optional) – Amplitude of translation speed perturbation in relative terms (e.g., 0.2 for +/-20%). Default: 0.3.

  • max_ddirection (float, optional) – Amplitude of track direction (bearing angle) perturbation per hour, in radians. Default: pi/360.

  • autocorr_dspeed (float, optional) – Temporal autocorrelation in translation speed perturbation at a lag of 1 hour. Default: 0.85.

  • autocorr_ddirection (float, optional) – Temporal autocorrelation of translational direction perturbation at a lag of 1 hour. Default: 0.5.

  • seed (int, optional) – Random number generator seed for replicability of random walk. Put negative value if you don’t want to use it. Default: configuration file.

  • decay (bool, optional) – Whether to apply landfall decay in probabilistic tracks. Default: True.

  • use_global_decay_params (bool, optional) – Whether to use precomputed global parameter values for landfall decay obtained from IBTrACS (1980-2019). If False, parameters are fitted using historical tracks in input parameter ‘tracks’, in which case the landfall decay applied depends on the tracks passed as an input and may not be robust if few historical tracks make landfall in this object. Default: True.

  • pool (pathos.pool, optional) – Pool that will be used for parallel computation when applicable. If not given, the pool attribute of tracks will be used. Default: None