API
Measure Functions
- hdp.measure.apply_heat_index(temp: DataArray, rh: DataArray) DataArray[source]
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:
- hdp.measure.celsius_to_fahrenheit(temp: DataArray) DataArray[source]
Converts from temperature value from Celsius to Fahrenheit.
- Parameters:
temp (xarray.DataArray) – Temperature DataArray in degrees Celsius
- Returns:
Temperature DataArray in degrees Fahrenheit
- Return type:
- hdp.measure.convert_temp_units(temp_ds: DataArray) DataArray[source]
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:
- hdp.measure.fahrenheit_to_celsius(temp: DataArray) DataArray[source]
Converts from temperature value from Fahrenheit to Celsius.
- Parameters:
temp (xarray.DataArray) – Temperature DataArray in degrees Fahrenheit
- Returns:
Temperature DataArray in degrees Celsius
- Return type:
- hdp.measure.format_standard_measures(temp_datasets: list[DataArray], rh: DataArray = None) Dataset[source]
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:
- hdp.measure.kelvin_to_celsius(temp: DataArray) DataArray[source]
Converts from temperature value from Kelvin to Celsius.
- Parameters:
temp (xarray.DataArray) – Temperature DataArray in degrees Kelvin
- Returns:
Temperature DataArray in degrees Celsius
- Return type:
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[source]
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:
- 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[source]
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[source]
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_dataset (xarray.Dataset) – Dataset containing baseline measurements to calculate thresholds from, where each data variable is used to compute a threshold.
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:
- hdp.threshold.datetimes_to_windows(datetimes: ndarray, window_radius: int) ndarray[source]
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[source]
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[source]
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[source]
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:
- hdp.metric.compute_individual_metrics(measure: DataArray, threshold: DataArray, hw_definitions: list, include_threshold: bool = True, check_variables: bool = True) Dataset[source]
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:
- 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, overwrite: bool = False) None[source]
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.
overwrite (bool) – (Optional) Whether or not to overwrite an existing dataset at the output_path. Defaults to False.
- Returns:
None
- Return type:
None
- hdp.metric.get_range_indices(times: ndarray, start: tuple, end: tuple) ndarray[source]
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:
- 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[source]
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[source]
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[source]
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[source]
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[source]
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[source]
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)[source]
Get the color for a specific value from a colorbar.
- hdp.graphics.figure.plot_metric_decadal_maps(metric_da)[source]
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)[source]
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)[source]
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)[source]
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
Utility Functions
- hdp.utils.generate_test_control_dataarray(start_date='1700-01-01', end_date='1749-12-31', grid_shape=(2, 3), add_noise=False, seed=0)[source]
Generates a synthetic control temperature DataArray with a seasonal cycle for testing.
Produces a no-leap-calendar daily time series with a sinusoidal temperature pattern and an optional latitudinal gradient. Used as the baseline (control) input in unit tests.
- Parameters:
start_date (str) – Start date of the time series in YYYY-MM-DD format. Defaults to “1700-01-01”.
end_date (str) – End date of the time series in YYYY-MM-DD format. Defaults to “1749-12-31”.
grid_shape (tuple) – Tuple of (lat, lon) grid dimensions. Defaults to (2, 3).
add_noise (bool) – If True, adds random noise to create variance across definitions and percentiles. Defaults to False.
seed (int) – Random seed for reproducibility when add_noise is True. Defaults to 0.
- Returns:
Synthetic control temperature DataArray in degrees Celsius.
- Return type:
- hdp.utils.generate_test_rh_dataarray(start_date='2000-01-01', end_date='2049-12-31', grid_shape=(2, 3))[source]
Generates a synthetic relative humidity DataArray for testing.
Derived from
generate_test_control_dataarray()and scaled to a relative humidity range with units of g/g.- Parameters:
- Returns:
Synthetic relative humidity DataArray with units “g/g”.
- Return type:
- hdp.utils.generate_test_warming_dataarray(start_date='2000-01-01', end_date='2049-12-31', grid_shape=(2, 3), warming_period=100, add_noise=False)[source]
Generates a synthetic warming temperature DataArray for testing.
Wraps
generate_test_control_dataarray()and adds a linear warming trend over the specified warming period (in years).- Parameters:
start_date (str) – Start date of the time series in YYYY-MM-DD format. Defaults to “2000-01-01”.
end_date (str) – End date of the time series in YYYY-MM-DD format. Defaults to “2049-12-31”.
grid_shape (tuple) – Tuple of (lat, lon) grid dimensions. Defaults to (2, 3).
warming_period (int) – Number of years over which 1 degree of warming is applied. Defaults to 100.
add_noise (bool) – If True, adds random noise to create variance. Defaults to False.
- Returns:
Synthetic warming temperature DataArray in degrees Celsius.
- Return type: