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.

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_mat(HAZ_DEMO_MAT, 'demo')
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_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

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.

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.isimip_data module#

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

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(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.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: 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.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’

  • 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

climada.hazard.trop_cyclone module#

class climada.hazard.trop_cyclone.TropCyclone(category: ndarray | None = None, basin: List | None = None, windfields: List[csr_matrix] | None = None, **kwargs)[source]#

Bases: 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.ndarray of ints

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 of str

windfields#

For each event, the full velocity vectors at each centroid and track position in a sparse matrix of shape (npositions, ncentroids * 2) that can be reshaped to a full ndarray of shape (npositions, ncentroids, 2).

Type:

list of csr_matrix

intensity_thres = 17.5#

intensity threshold for storage in m/s

vars_opt = {'category'}#

Name of the variables that are not needed to compute the impact.

__init__(category: ndarray | None = None, basin: List | None = None, windfields: List[csr_matrix] | None = None, **kwargs)[source]#

Initialize values.

Parameters:
  • category (np.ndarray of int, optional) –

    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

  • basin (list of str, optional) –

    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

  • windfields (list of csr_matrix, optional) – For each event, the full velocity vectors at each centroid and track position in a sparse matrix of shape (npositions, ncentroids * 2) that can be reshaped to a full ndarray of shape (npositions, ncentroids, 2).

  • **kwargs (Hazard properties, optional) – All other keyword arguments are passed to the Hazard constructor.

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

This function is deprecated, use TropCyclone.from_tracks instead.

classmethod from_tracks(tracks: TCTracks, centroids: Centroids, pool: ProcessPool | None = None, model: str = 'H08', model_kwargs: dict | None = None, ignore_distance_to_coast: bool = False, store_windfields: bool = False, metric: str = 'equirect', intensity_thres: float = 17.5, max_latitude: float = 61, max_dist_inland_km: float = 1000, max_dist_eye_km: float = 300, max_memory_gb: float = 8)[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 (climada.hazard.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

  • model (str, optional) – Parametric wind field model to use. Default: “H08”.

    • "H1980" (the prominent Holland 1980 model) from the paper:

      Holland, G.J. (1980): An Analytic Model of the Wind and Pressure Profiles in Hurricanes. Monthly Weather Review 108(8): 1212–1218. https://doi.org/10.1175/1520-0493(1980)108<1212:AAMOTW>2.0.CO;2

    • "H08" (Holland 1980 with b-value from Holland 2008) from the paper:

      Holland, G. (2008). A revised hurricane pressure-wind model. Monthly Weather Review, 136(9), 3432–3445. https://doi.org/10.1175/2008MWR2395.1

    • "H10" (Holland et al. 2010) from the paper:

      Holland et al. (2010): A Revised Model for Radial Profiles of Hurricane Winds. Monthly Weather Review 138(12): 4393–4401. https://doi.org/10.1175/2010MWR3317.1

    • "ER11" (Emanuel and Rotunno 2011) from the paper:

      Emanuel, K., Rotunno, R. (2011): Self-Stratification of Tropical Cyclone Outflow. Part I: Implications for Storm Structure. Journal of the Atmospheric Sciences 68(10): 2236–2249. https://dx.doi.org/10.1175/JAS-D-10-05024.1

  • model_kwargs (dict, optional) – If given, forward these kwargs to the selected wind model. None of the parameters is currently supported by the ER11 model. Default: None. The Holland models support the following parameters, in alphabetical order:

    gradient_to_surface_windsfloat, optional

    The gradient-to-surface wind reduction factor to use. In H1980, the wind profile is computed on the gradient level, and wind speeds are converted to the surface level using this factor. In H08 and H10, the wind profile is computed on the surface level, but the clipping interval of the B-value depends on this factor. Default: 0.9

    rho_air_constfloat or None, optional

    The constant value for air density (in kg/m³) to assume in the formulas from Holland 1980. By default, the constant value suggested in Holland 1980 is used. If set to None, the air density is computed from pressure following equation (9) in Holland et al. 2010. Default: 1.15

    vmax_from_cenboolean, optional

    Only used in H10. If True, replace the recorded value of vmax along the track by an estimate from pressure, following equation (8) in Holland et al. 2010. Default: True

    vmax_in_bracketsbool, optional

    Only used in H10. Specifies which of the two formulas in equation (6) of Holland et al. 2010 to use. If False, the formula with vmax outside of the brackets is used. Note that, a side-effect of the formula with vmax inside of the brackets is that the wind speed maximum is attained a bit farther away from the center than according to the recorded radius of maximum winds (RMW). Default: False

  • ignore_distance_to_coast (boolean, optional) – If True, centroids far from coast are not ignored. If False, the centroids’ distances to the coast are calculated with the Centroids.get_dist_coast() method (unless there is “dist_coast” column in the centroids’ GeoDataFrame) and centroids far from coast are 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

  • max_latitude (float, optional) – No wind speed calculation is done for centroids with latitude larger than this parameter. Default: 61

  • max_dist_inland_km (float, optional) – No wind speed calculation is done for centroids with a distance (in km) to the coast larger than this parameter. Default: 1000

  • max_dist_eye_km (float, optional) – No wind speed calculation is done for centroids with a distance (in km) to the TC center (“eye”) larger than this parameter. Default: 300

  • max_memory_gb (float, optional) – To avoid memory issues, the computation is done for chunks of the track sequentially. The chunk size is determined depending on the available memory (in GB). Note that this limit applies to each thread separately if a pool is used. Default: 8

Raises:

ValueError

Return type:

TropCyclone

apply_climate_scenario_knu(ref_year: int = 2050, rcp_scenario: int = 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: str, tracks: ~climada.hazard.tc_tracks.TCTracks, centroids: ~climada.hazard.centroids.centr.Centroids, file_name: str | None = None, writer: <module 'matplotlib.animation' from '/home/docs/checkouts/readthedocs.org/user_builds/climada-python/conda/latest/lib/python3.9/site-packages/matplotlib/animation.py'> = <matplotlib.animation.PillowWriter object>, figsize: ~typing.Tuple[float, float] = (9, 13), adapt_fontsize: bool = 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.ndarray)

Raises:

ValueError

frequency_from_tracks(tracks: List)[source]#

Set hazard frequency from tracks data.

Parameters:

tracks (list of xarray.Dataset)

classmethod from_single_track(track: Dataset, centroids: Centroids, idx_centr_filter: ndarray, model: str = 'H08', model_kwargs: dict | None = None, store_windfields: bool = False, metric: str = 'equirect', intensity_thres: float = 17.5, max_dist_eye_km: float = 300, max_memory_gb: float = 8)[source]#

Generate windfield hazard from a single track dataset

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

  • centroids (Centroids) – Centroids instance.

  • idx_centr_filter (np.ndarray) – Indices of centroids to restrict to (e.g. sufficiently 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), “H10” (Holland et al. 2010), or “ER11” (Emanuel and Rotunno 2011). Default: “H08”.

  • model_kwargs (dict, optional) – If given, forward these kwargs to the selected model. Default: None

  • 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

  • max_dist_eye_km (float, optional) – No wind speed calculation is done for centroids with a distance (in km) to the TC center (“eye”) larger than this parameter. Default: 300

  • max_memory_gb (float, optional) – To avoid memory issues, the computation is done for chunks of the track sequentially. The chunk size is determined depending on the available memory (in GB). Default: 8

Raises:

ValueError, KeyError

Returns:

haz

Return type:

TropCyclone