climada.hazard package

climada.hazard.base module

class climada.hazard.base.Hazard(haz_type='', pool=None)[source]

Bases: object

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

tag

information about the source

Type

TagHazard

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 in years

Type

np.array

intensity

intensity of the events at centroids

Type

sparse.csr_matrix

fraction

fraction of affected exposures for each event at each centroid

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', 'tag', 'units'}

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

Type

Name of the variables needed to compute the impact. Types

vars_def = {'date', 'event_name', '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='', pool=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

Examples

Fill hazard values by hand:

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

Take hazard values from file:

>>> haz = Hazard.from_mat(HAZ_DEMO_MAT, 'demo')
clear()[source]

Reinitialize attributes (except the process Pool).

check()[source]

Check dimension of attributes.

Raises

ValueError

classmethod from_raster(files_intensity, files_fraction=None, attrs=None, band=None, haz_type=None, pool=None, src_crs=None, window=False, geometry=False, dst_crs=False, 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 (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, 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

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

This function is deprecated, use Hazard.from_raster.

set_vector(*args, **kwargs)[source]

This function is deprecated, use Hazard.from_vector.

classmethod from_vector(files_intensity, files_fraction=None, attrs=None, inten_name=None, frac_name=None, dst_crs=None, haz_type=None)[source]

Read vector files format supported by fiona. Each intensity name is considered an event.

Parameters
  • files_intensity (list(str)) – file names containing intensity, default: [‘intensity’]

  • files_fraction ((list(str))) – file names containing fraction, default: [‘fraction’]

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

  • inten_name (list(str), optional) – name of variables containing the intensities of each event

  • frac_name (list(str), optional) – name of variables containing the fractions of each event

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

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

Returns

haz – Hazard from vector file

Return type

climada.hazard.Hazard

reproject_raster(dst_crs=False, transform=None, width=None, height=None, resampl_inten=Resampling.nearest, resampl_fract=Resampling.nearest)[source]

Change current raster data to other CRS and/or transformation

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

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

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

reproject_vector(dst_crs, scheduler=None)[source]

Change current point data to a a given projection

Parameters
  • dst_crs (crs) – reproject to given crs

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

raster_to_vector()[source]

Change current raster to points (center of the pixels)

vector_to_raster(scheduler=None)[source]

Change current point data to a raster with same resolution

Parameters

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

read_mat(*args, **kwargs)[source]

This function is deprecated, use Hazard.from_mat.

classmethod from_mat(file_name, description='', var_names=None)[source]

Read climada hazard generate with the MATLAB code in .mat format.

Parameters
  • file_name (str) – absolute file name

  • description (str, optional) – description of the data

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

Returns

haz – Hazard object from the provided MATLAB file

Return type

climada.hazard.Hazard

Raises

KeyError

read_excel(*args, **kwargs)[source]

This function is deprecated, use Hazard.from_excel.

classmethod from_excel(file_name, description='', 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

  • description (str, optional) – description of the data

  • 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

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

algorithm to match centroids.

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

Compute exceedance intensity map for given return periods.

Parameters

return_periods (np.array) – return periods to consider

Returns

inten_stats

Return type

np.array

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

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

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

sanitize_event_ids()[source]

Make sure that event ids are unique

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.

write_raster(file_name, intensity=True)[source]

Write intensity or fraction as GeoTIFF file. Each band is an event

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

  • intensity (bool) – if True, write intensity, otherwise write fraction

write_hdf5(file_name, todense=False)[source]

Write hazard in hdf5 format.

Parameters

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

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

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.

  • All tag attributes are appended to self.tag.

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, tags, 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.assign_coordinates. Default: 100 (km)

Returns

haz_new_cent – Hazard projected onto centroids

Return type

Hazard

Raises

ValueError

See also

util.coordinates.assign_coordinates

algorithm to match centroids.

climada.hazard.isimip_data module

climada.hazard.storm_europe module

class climada.hazard.storm_europe.StormEurope[source]

Bases: climada.hazard.base.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__()[source]

Calls the Hazard init dunder. Sets unit to ‘m/s’.

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

This function is deprecated, use StormEurope.from_footprints instead.

classmethod from_footprints(path, description=None, 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.

  • description (str, optional) – description of the events, defaults to ‘WISC historical hazard set’

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

self.ssi_dawkins

SSI per event

Type

np.array

set_ssi(**kwargs)[source]

Wrapper around calc_ssi for setting the self.ssi attribute.

Parameters

kwargs – passed on to calc_ssi

ssi

SSI per event

Type

np.array

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

class climada.hazard.tag.Tag(haz_type='', file_name='', description='')[source]

Bases: object

Contain information used to tag a Hazard.

file_name

name of the source file(s)

Type

str or list(str)

haz_type

acronym defining the hazard type (e.g. ‘TC’)

Type

str

description

description(s) of the data

Type

str or list(str)

__init__(haz_type='', file_name='', description='')[source]

Initialize values.

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

  • file_name (str or list(str), optional) – file name(s) to read

  • description (str or list(str), optional) – description of the data

append(tag)[source]

Append input Tag instance information to current Tag.

join_file_names()[source]

Get a string with the joined file names.

join_descriptions()[source]

Get a string with the joined descriptions.

climada.hazard.tc_clim_change module

climada.hazard.tc_clim_change.TOT_RADIATIVE_FORCE = PosixPath('/home/docs/climada/data/rcp_db.xls')

//www.iiasa.ac.at/web-apps/tnt/RcpDb. generated: 2018-07-04 10:47:59.

Type

© RCP Database (Version 2.0.5) http

climada.hazard.tc_clim_change.get_knutson_criterion()[source]

Fill changes in TCs according to Knutson et al. 2015 Global projections of intense tropical cyclone activity for the late twenty-first century from dynamical downscaling of CMIP5/RCP4.5 scenarios.

Returns

criterion – list of the criterion dictionary for frequency and intensity change per basin, per category taken from the Table 3 in Knutson et al. 2015. with items ‘basin’ (str), ‘category’ (list(int)), ‘year’ (int), ‘change’ (float), ‘variable’ (‘intensity’ or ‘frequency’)

Return type

list(dict)

climada.hazard.tc_clim_change.calc_scale_knutson(ref_year=2050, rcp_scenario=45)[source]

Comparison 2081-2100 (i.e., late twenty-first century) and 2001-20 (i.e., present day). Late twenty-first century effects on intensity and frequency per Saffir-Simpson-category and ocean basin is scaled to target year and target RCP proportional to total radiative forcing of the respective RCP and year.

Parameters
  • ref_year (int, optional) – year between 2000 ad 2100. Default: 2050

  • rcp_scenario (int, optional) – 26 for RCP 2.6, 45 for RCP 4.5. The default is 45 60 for RCP 6.0 and 85 for RCP 8.5.

Returns

factor – factor to scale Knutson parameters to the give RCP and year

Return type

float

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(pool=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)

Type

list(xarray.Dataset)

__init__(pool=None)[source]

Create new (empty) TCTracks instance.

Parameters

pool (pathos.pool, 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, 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.ncdc.noaa.gov/ibtracs/pdf/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. 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.ncdc.noaa.gov/ibtracs/pdf/IBTrACS_version4_Technical_Details.pdf) includes a warning about this kind of conversion: “While a multiplicative factor can describe 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’

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

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

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

Generate interpolated track values to time steps of time_step_h.

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

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 (https://github.com/Toblerity/Shapely/issues/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

climada.hazard.trop_cyclone module

class climada.hazard.trop_cyclone.TropCyclone(pool=None)[source]

Bases: climada.hazard.base.Hazard

Contains tropical cyclone events.

category

for every event, the TC category using the Saffir-Simpson scale:

-1 tropical depression

0 tropical storm 1 Hurrican category 1 2 Hurrican category 2 3 Hurrican category 3 4 Hurrican category 4 5 Hurrican category 5

Type

np.array(int)

basin

basin where every event starts ‘NA’ North Atlantic ‘EP’ Eastern North Pacific ‘WP’ Western North Pacific ‘NI’ North Indian ‘SI’ South Indian ‘SP’ Southern Pacific ‘SA’ South Atlantic

Type

list(str)

intensity_thres = 17.5

intensity threshold for storage in m/s

vars_opt = {'category'}

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

__init__(pool=None)[source]

Initialize values.

Parameters

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

set_from_tracks(*args, **kwargs)[source]

This function is deprecated, use TropCyclone.from_tracks instead.

classmethod from_tracks(tracks, centroids=None, pool=None, description='', model='H08', ignore_distance_to_coast=False, store_windfields=False, metric='equirect', intensity_thres=17.5)[source]

Create new TropCyclone instance that contains windfields from the specified tracks.

This function sets the intensity attribute to contain, for each centroid, the maximum wind speed (1-minute sustained winds at 10 meters above ground) experienced over the whole period of each TC event in m/s. The wind speed is set to 0 if it doesn’t exceed the threshold intensity_thres.

The category attribute is set to the value of the category-attribute of each of the given track data sets.

The basin attribute is set to the genesis basin for each event, which is the first value of the basin-variable in each of the given track data sets.

Optionally, the time dependent, vectorial winds can be stored using the store_windfields function parameter (see below).

Parameters
  • tracks (TCTracks) – Tracks of storm events.

  • centroids (Centroids, optional) – Centroids where to model TC. Default: global centroids at 360 arc-seconds resolution.

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

  • description (str, optional) – Description of the event set. Default: “”.

  • model (str, optional) – Parametric wind field model to use: one of “H1980” (the prominent Holland 1980 model), “H08” (Holland 1980 with b-value from Holland 2008), or “H10” (Holland et al. 2010). Default: “H08”.

  • ignore_distance_to_coast (boolean, optional) – If True, centroids far from coast are not ignored. Default: False.

  • store_windfields (boolean, optional) – If True, the Hazard object gets a list windfields of sparse matrices. For each track, the full velocity vectors at each centroid and track position are stored in a sparse matrix of shape (npositions, ncentroids * 2) that can be reshaped to a full ndarray of shape (npositions, ncentroids, 2). Default: False.

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

    large distances and high latitudes.

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

    Default: “equirect”.

  • intensity_thres (float, optional) – Wind speeds (in m/s) below this threshold are stored as 0. Default: 17.5

Raises

ValueError

Return type

TropCyclone

apply_climate_scenario_knu(ref_year=2050, rcp_scenario=45)[source]

From current TC hazard instance, return new hazard set with future events for a given RCP scenario and year based on the parametrized values derived from Table 3 in Knutson et al 2015. https://doi.org/10.1175/JCLI-D-15-0129.1 . The scaling for different years and RCP scenarios is obtained by linear interpolation.

Note: The parametrized values are derived from the overall changes in statistical ensemble of tracks. Hence, this method should only be applied to sufficiently large tropical cyclone event sets that approximate the reference years 1981 - 2008 used in Knutson et. al.

The frequency and intensity changes are applied independently from one another. The mean intensity factors can thus slightly deviate from the Knutson value (deviation was found to be less than 1% for default IBTrACS event sets 1980-2020 for each basin).

Parameters
  • ref_year (int) – year between 2000 ad 2100. Default: 2050

  • rcp_scenario (int) – 26 for RCP 2.6, 45 for RCP 4.5, 60 for RCP 6.0 and 85 for RCP 8.5. The default is 45.

Returns

haz_cc – Tropical cyclone with frequencies and intensity scaled according to the Knutson criterion for the given year and RCP. Returns a new instance of climada.hazard.TropCyclone, self is not modified.

Return type

climada.hazard.TropCyclone

set_climate_scenario_knu(*args, **kwargs)[source]

This function is deprecated, use TropCyclone.apply_climate_scenario_knu instead.

classmethod video_intensity(track_name, tracks, centroids, file_name=None, writer=<matplotlib.animation.PillowWriter object>, figsize=(9, 13), adapt_fontsize=True, **kwargs)[source]

Generate video of TC wind fields node by node and returns its corresponding TropCyclone instances and track pieces.

Parameters
  • track_name (str) – name of the track contained in tracks to record

  • tracks (climada.hazard.TCTracks) – tropical cyclone tracks

  • centroids (climada.hazard.Centroids) – centroids where wind fields are mapped

  • file_name (str, optional) – file name to save video (including full path and file extension)

  • writer (matplotlib.animation., optional*) – video writer. Default is pillow with bitrate=500

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

  • adapt_fontsize (bool, optional) – If set to true, the size of the fonts will be adapted to the size of the figure. Otherwise the default matplotlib font size is used. Default is True.

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

Returns

tc_list, tc_coord

Return type

list(TropCyclone), list(np.array)

Raises

ValueError

frequency_from_tracks(tracks)[source]

Set hazard frequency from tracks data.

Parameters

tracks (list of xarray.Dataset)

classmethod from_single_track(track, centroids, coastal_idx, model='H08', store_windfields=False, metric='equirect', intensity_thres=17.5)[source]

Generate windfield hazard from a single track dataset

Parameters
  • track (xr.Dataset) – Single tropical cyclone track.

  • centroids (Centroids) – Centroids instance.

  • coastal_idx (np.array) – Indices of centroids close to coast.

  • model (str, optional) – Parametric wind field model, one of “H1980” (the prominent Holland 1980 model), “H08” (Holland 1980 with b-value from Holland 2008), or “H10” (Holland et al. 2010). Default: “H08”.

  • store_windfields (boolean, optional) – If True, store windfields. Default: False.

  • metric (str, optional) – Specify an approximation method to use for earth distances: “equirect” (faster) or “geosphere” (more accurate). See dist_approx function in climada.util.coordinates. Default: “equirect”.

  • intensity_thres (float, optional) – Wind speeds (in m/s) below this threshold are stored as 0. Default: 17.5

Raises

ValueError, KeyError

Returns

haz

Return type

TropCyclone