API

Measure Functions

hdp.measure.apply_heat_index(temp: DataArray, rh: DataArray) → DataArray

Calculates heat index from temperature and relative humidity DataArrays leveraging Dask.

Parameters:

  • temp (xarray.DataArray) – Temperature DataArray in degrees Fahrenheit

  • rh (xarray.DataArray) – Relative humidity DataArray in percentage [0-100]

Returns:

Heat index value in degrees Fahrenheit

Return type:

xarray.DataArray

hdp.measure.celsius_to_fahrenheit(temp: float) → float

Converts from temperature value from Celsius to Fahrenheit.

Parameters:

temp (float) – Temperature value in degrees Celsius

Returns:

Temperature value in degrees Fahrenheit

Return type:

float

hdp.measure.convert_temp_units(temp_ds: DataArray) → DataArray

Determines and converts temperature units to degrees Celsius.

Parameters:

temp_ds (xarray.DataArray) – Temperature DataArray with one of the supported units

Returns:

Temperature DataArray in degrees Celsius

Return type:

xarray.DataArray

hdp.measure.fahrenheit_to_celsius(temp: float) → float

Converts from temperature value from Fahrenheit to Celsius.

Parameters:

temp (float) – Temperature value in degrees Fahrenheit

Returns:

Temperature value in degrees Celsius

Return type:

float

hdp.measure.format_standard_measures(temp_datasets: list[DataArray], rh: DataArray = None) → Dataset

Formats heat measure datasets (base inputs for heatwave diagnostics) for use within the HDP.

Parameters:

  • temp_datasets (list[xarray.DataArray]) – List of input temperature DataArrays using supported units

  • rh (xarray.DataArray) – (Optional) Relative humidity DataArray to compute heat index values with for each temperature DataArray.

Returns:

Dataset containing all input variables formatted and initialized for HDP analysis.

Return type:

xarray.Dataset

hdp.measure.kelvin_to_celsius(temp: float) → float

Converts from temperature value from Kelvin to Celsius.

Parameters:

temp (float) – Temperature value in degrees Kelvin

Returns:

Temperature value in degrees Celsius

Return type:

float

Threshold Functions

hdp.threshold.compute_threshold(baseline_data: DataArray, percentiles: ndarray, no_season: bool = False, rolling_window_size: int = 7, fixed_value: float = None) → Dataset

Computes percentile and, optionally, fixed value thresholds for a baseline measurements.

Parameters:

  • baseline_data (xarray.DataArray) – DataArrays with baseline measurements to calculate thresholds from.

  • percentiles (np.ndarray) – List of percentiles to calculate for each baseline.

  • no_season (bool) – (Optional) Instead of taking window samples at each day of year to get a seasonally-varying threshold, calculate a single percentile for the entire year. Defaults to False.

  • rolling_window_size (int) – (Optional) Size of rolling windows to use when calculating the percentiles. Defaults to 7.

  • fixed_value (float) – (Optional) Value to use for fixed threshold (non-seasonally varying). Defaults to None.

Returns:

Aggregated dataset of all thresholds generated.

Return type:

xarray.Dataset

hdp.threshold.compute_threshold_io(baseline_path: str, baseline_var: str, output_path: str, percentiles: ndarray, no_season: bool = False, rolling_window_size: int = 7, fixed_value: float = None, overwrite: bool = False) → None

Computes thresholds from path inputs instead of manually supplied xarray Datasets/DataArrays (automates reading from and writing to disk). Resulting threshold datasets are written directly to disk instead of holding in memory.

Parameters:

  • baseline_path (str) – Path to netCDF or zarr store containing baseline measurements to compute thresholds from.

  • baseline_var (str) – Variable read from the dataset at the specified path.

  • output_path (str :param percentiles: List of percentiles to calculate for each baseline.) – Path to write dataset(s) to, can be a zarr store (faster) or netCDF file (slower).

  • no_season (bool) – (Optional) Instead of taking window samples at each day of year to get a seasonally-varying threshold, calculate a single percentile for the entire year. Defaults to False.

  • rolling_window_size (int) – (Optional) Size of rolling windows to use when calculating the percentiles. Defaults to 7.

  • fixed_value (float) – (Optional) Value to use for fixed threshold (non-seasonally varying). Defaults to None.

  • overwrite (bool) – (Optional) Whether or not to overwrite existing datasets at the output_path. Defaults to False

Returns:

None

Return type:

None

hdp.threshold.compute_thresholds(baseline_dataset: list[DataArray], percentiles: ndarray, no_season: bool = False, rolling_window_size: int = 7, fixed_value: float = None) → Dataset

Wrapper function for generating multiple thresholds with hdp.threshold.compute_threshold. Computes percentile and, optionally, fixed value thresholds for a list of baseline measurements.

Parameters:

  • baseline_data (list[xarray.DataArray]) – List of DataArrays with baseline measurements to calculate thresholds from.

  • percentiles (np.ndarray) – List of percentiles to calculate for each baseline.

  • no_season (bool) – (Optional) Instead of taking window samples at each day of year to get a seasonally-varying threshold, calculate a single percentile for the entire year. Defaults to False.

  • rolling_window_size (int) – Size of rolling windows to use when calculating the percentiles.

  • fixed_value (float) – Value to use for fixed threshold (non-seasonally varying).

Returns:

Aggregated dataset of all thresholds generated.

Return type:

xarray.Dataset

hdp.threshold.datetimes_to_windows(datetimes: ndarray, window_radius: int) → ndarray

Generate rolling window sample of the day of year for each time index in the specified time series. Example below:

Day of year values for datetimes: 1 2 3 4 5 6 Window radius: 1 Result: [6 1 2], [1 2 3], [2 3 4], [3 4 5], [4 5 6], [5 6 1]

Parameters:

  • datetimes (np.ndarray) – Array of datetime objects corresponding to the dataset’s time dimension

  • window_radius (int) – Radius of each window

Returns:

Two dimensional array where each index of the first dimension corresponds to the time dimension and the second dimension stores the indices of each window.

Return type:

np.ndarray

Metric Functions

hdp.metric.build_doy_map(times: ndarray) → ndarray

Maps the time series index (key) to its respective day of the year (value).

Parameters:

measure (np.ndarray) – Array of CFTime objects.

Returns:

Day of year for each timestep.

Return type:

np.ndarray

hdp.metric.compute_heatwave_metrics(measure: ndarray, threshold: ndarray, doy_map: ndarray, min_duration: int, max_break: int, max_subs: int, season_ranges: ndarray) → ndarray

Computes HWN, HWF, HWD, and HWA metrics for a given measure, threshold, and definition. Additional parameters can be used to fine tune the analysis. This is the Numba-compiled function that is parallelized with Dask and formatted into a more user-friendly format by hdp.metrics.compute_individual_metrics

Parameters:

  • measure (np.ndarray) – Heat measure to compare against the threshold.

  • threshold (np.ndarray) – Threshold for extreme heat.

  • doy_map (np.ndarray) – Mapping from index in times array to day of year value.

  • min_duration (int) – Minimum number of days that exceed the threshold to constitute a heatwave.

  • max_break (int) – Maximum number of days below the threshold that can exist in a heatwave.

  • max_subs (int) – Maximum number of subsequent heatwaves.

  • season_ranges (np.ndarray)

Returns:

Array of equal number of dimensions to measure and an additional dimension containing each heatwave metric: HWN, HWF, HWD, HWA

Return type:

np.ndarray

hdp.metric.compute_hemisphere_ranges(measure: DataArray) → DataArray

Computes the heatwave season ranges by time index (not the timestamp, rather the index corresponding to the timestamp) for each grid cell based on whether it is in the Northern Hemisphere (boreal summer, May 1st to October 1st) or Southern Hemisphere (austral summer, November 1st to March 1st).

Parameters:

measure (xarray.DataArray) – DataArray containing ‘lat’ and ‘lon’ variables corresponding to grid.

Returns:

Generates seasonal ranges by hemisphere for an arbitrary ‘lat’-‘lon’ grid.

Return type:

xarray.DataArray

hdp.metric.compute_individual_metrics(measure: DataArray, threshold: DataArray, hw_definitions: list, include_threshold: bool = True, check_variables: bool = True) → Dataset

Computes HWN, HWF, HWD, and HWA heatwave metrics for an individual parameter configuration of measure, threshold, and definition.

Heatwave definitions are described by tuples of three integers in the following order: 1. Minimum number of days exceeding the threshold to define the start of a heatwave 2. Maximum number of days following the start of a heatwave that do not exceed the threshold and are followed by days that do exceed the threshold. In other words, the maximum “break” that a heatwave can have between the initial hot days and some number of hot days afterwards. 3. Maximum number of breaks in a heatwave (can also be thought of as the maximum number of secondary events after the initial hot days).

Parameters:

  • measure (xarray.DataArray) – Formatted HDP measure DataArray

  • threshold (xarray.DataArray) – Formatted HDP threshold compatable with the given measure

  • hw_definitions (list[tuple]) – Heatwave definitions to calculate metrics for. See the function description for how to generate definitions.

  • include_threshold (bool) – (Optional) Whether or not to include the threshold DataArray in the aggregated output dataset. Default is True.

  • check_variables (bool) – (Optional) Whether or not to check if measure is compatable with the threshold. Default is True.

Returns:

Aggregate dataset containing all of the heatwave metrics and optional datasets.

Return type:

xarray.Dataset

hdp.metric.compute_metrics_io(output_path: str, measure_path: str, measure_var: str, threshold_path: str, hw_definitions: list, include_threshold: bool = False, override_threshold_var: str = None) → None

Computes heatwave metrics from path inputs instead of manually supplied xarray Datasets/DataArrays (automates reading from and writing to disk). Resulting metrics are written directly to disk instead of holding in memory.

Parameters:

  • output_path (str) – Path to write dataset(s) to, can be a zarr store (faster) or netCDF file (slower).

  • measure_path (str) – Path to heat measure dataset formatted by the HDP.

  • measure_var (str) – Name of measure variable to use from specified dataset.

  • threshold_path (str) – Path to threshold dataset formatted by the HDP.

  • hw_definitions (list) – Definitions to compute heatwave metrics over.

  • include_threshold (bool) – (Optional) Whether or not to include the threshold dataset in the resulting output. Default is False.

  • override_threshold_var (str) – (Optional) Override threshold variable to use when computing metrics. If left unspecified, the format “threshold_{measure_var}” will be used.

Returns:

None

Return type:

None

hdp.metric.get_range_indices(times: ndarray, start: tuple, end: tuple) → ndarray

Calculates the range of time indices to define each heatwave season for a given time series. This function is agnostic to the calendar type, but will not yield accurate results if the month and day exceed the calendar’s definition. The ranges of indices are then used to slice the time series into the heatwave seasons, this is faster than iterating through CFTime objects.

Parameters:

  • times (np.ndarray) – Array of CFTime objects corresponding to the time series to define the seasons over.

  • start (tuple) – Tuple of starting month integer and day integer to compare times array against.

  • end (tuple) – Tuple of ending month integer and day integer to compare times array against.

Returns:

Range of indices in times array for each season.

Return type:

np.ndarray

hdp.metric.heatwave_average(hw_ts: ndarray, season_ranges: ndarray) → ndarray

Measures the average length of all heatwaves in each season of a given heatwave index time series. Heatwave metric, commonly abbreviated as HWA.

Parameters:

  • hw_ts (np.ndarray) – Integer timeseries of indexed heatwave days.

  • season_ranges (np.ndarray) – Range of array indices, corresponding to heatwave season, in indexed heatwave day timeseries to count.

Returns:

Average heatwave length per heatwave season.

Return type:

np.ndarray

hdp.metric.heatwave_duration(hw_ts: ndarray, season_ranges: ndarray) → ndarray

Measures the length of the longest heatwave in each season of a given heatwave index time series. Heatwave metric, commonly abbreviated as HWD.

Parameters:

  • hw_ts (np.ndarray) – Integer timeseries of indexed heatwave days.

  • season_ranges (np.ndarray) – Range of array indices, corresponding to heatwave season, in indexed heatwave day timeseries to count.

Returns:

Length of longest heatwave per heatwave season.

Return type:

np.ndarray

hdp.metric.heatwave_frequency(hw_ts: ndarray, season_ranges: ndarray) → ndarray

Measures the number of heatwave days in each season of a given heatwave index time series. Heatwave metric, commonly abbreviated as HWF.

Parameters:

  • hw_ts (np.ndarray) – Integer timeseries of indexed heatwave days.

  • season_ranges (np.ndarray) – Range of array indices, corresponding to heatwave season, in indexed heatwave day timeseries to count.

Returns:

Number of heatwave days per heatwave season.

Return type:

np.ndarray

hdp.metric.heatwave_number(hw_ts: ndarray, season_ranges: ndarray) → ndarray

Measures the number of heatwaves (by event, not days) in each season of a given heatwave index time series. Heatwave metric, commonly abbreviated as HWN.

Parameters:

  • hw_ts (np.ndarray) – Integer timeseries of indexed heatwave days.

  • season_ranges (np.ndarray) – Range of array indices, corresponding to heatwave season, in indexed heatwave day timeseries to count.

Returns:

Number of heatwaves per heatwave season

Return type:

np.ndarray

hdp.metric.index_heatwaves(hot_days_ts: ndarray, min_duration: int, max_break: int, max_subs: int) → ndarray

Identifies the heatwaves in the timeseries using the specified heatwave definition

Parameters:

  • hot_days_ts (np.ndarray) – Integer array of ones and zeros where ones indicates a hot day

  • min_duration (int) – The minimum number of hot days to constitute a heatwave event, including after breaks

  • max_break (int) – The maximum number of days between hot days within one heatwave event

  • max_subs (int) – the maximum number of subsequent events allowed to be apart of the initial consecutive hot days

Returns:

Timeseries where nonzero integers indicate heatwave indices for each timestep

Return type:

np.ndarray

hdp.metric.indicate_hot_days(measure: ndarray, threshold: ndarray, doy_map: ndarray) → ndarray

Determines whether each time step in a heat measure exceeds the threshold.

Parameters:

  • measure (np.ndarray) – Heat measure to compare against the threshold.

  • threshold (np.ndarray) – Threshold for extreme heat.

  • doy_map (np.ndarray) – Mapping from index in times array to day of year value.

Returns:

Boolean array of days in measure that exceed the threshold.

Return type:

np.ndarray

Plotting/Graphics Functions

hdp.graphics.figure.get_color_for_value(cbar, value)

Get the color for a specific value from a colorbar.

hdp.graphics.figure.plot_metric_decadal_maps(metric_da)

Multi-figure (4 panels per figure) plotting of decadal means for a particular metric. If an ensemble, set of percentiles, or set of definitions is supplied, the average will be used. Abbreviations include ensemble (ens), percentile (perc), and definition (def).

Parameters:

metric_da (xarray.DataArray) – DataArray of the metric (with the metric name) to plot.

Returns:

Matplotlib Figure of the plot with the figure title containing a list of metrics displayed.

Return type:

np.ndarray

hdp.graphics.figure.plot_metric_parameter_comparison(metric_da)

4-panel plot of metric visualizing various comparisons of percentiles against the definitions. If ensemble is supplied, the average is taken.

Parameters:

metric_da (xarray.DataArray) – DataArray of the metric (with the metric name) to plot.

Returns:

Matplotlib Figure of the plot with the figure title containing a list of metrics displayed.

Return type:

np.ndarray

hdp.graphics.figure.plot_metric_timeseries(metric_da)

4-panel plot of time-evolution of metric, spatial-ensemble mean. The top two panels are means taken across thresholds and definitions while the bottom two panels show standard deviations. Abbreviations include ensemble (ens), percentile (perc), definition (def), and standard deviation (std).

Parameters:

metric_da (xarray.DataArray) – DataArray of the metric (with the metric name) to plot.

Returns:

Matplotlib Figure of the plot with the figure title containing a list of metrics displayed.

Return type:

np.ndarray

hdp.graphics.figure.plot_multi_measure_metric_comparisons(hw_ds)

4-panel plot of time-evolution of heatwave metrics accross multiple measures. Spatially-weighted by latitide, mean taken spatially and over both percentiles and all definitions. If ensemble is used, the range of member values is shaded behind the mean line. Abbreviations include percentile (perc) and definition (def).

Parameters:

metric_da (xarray.Dataset) – Dataset of the metrics (with the metric names) to plot.

Returns:

Matplotlib Figure of the plot with the figure title containing a list of metrics displayed.

Return type:

np.ndarray

class hdp.graphics.winkel_tripel.WinkelTripel(central_longitude=0.0, central_latitude=0.0, globe=None)

Winkel-Tripel projection implementation for Cartopy