The different methods of defining and detecting extreme events, known as heatwaves or cold-spells in both air and water temperature data are encompassed within this package. These detection algorithms may be used on non-temperature data as well however, this is not catered for explicitly here as no use of this technique in the literature currently exists.
heatwaveR package is a project-wide update to the
RmarineHeatWaves package, which is itself a translation of the original Python code written by Eric C. J. Oliver. The
heatwaveR package also uses the same naming conventions for objects, columns, and arguments as the Python code.
heatwaveR R package contains the original functions from the
RmarineHeatWaves package that calculate and display marine heatwaves (MHWs) according to the definition of Hobday et al. (2016) as well as calculating and visualising marine cold-spells (MCSs) as first introduced in Schlegel et al. (2017a). It also contains the functionality to calculate the categories of MHWs as outlined in Hobday et al. (2018).
This package does what
RmarineHeatWaves does, but faster. The entire package has been deconstructed and modularised, and slow portions of the code are being implemented in C++. C++ has already replaced some of the bottlenecks that slowed down the climatology creation portions of the code, and we will slowly but surely improve the efficiency and speed in other portions of the code too. Currently the R code runs about as fast as the original python functions, at least in as far as applying it to single time series of temperatures. Readers familiar with both languages will know about the ongoing debate around the relative speed of the two languages. In our experience, R can be as fast as python, provided that attention is paid to finding ways to reduce the computational inefficiencies that stem from i) the liberal use of complex and inefficient non-atomic data structures, such as data frames; ii) the reliance on non-vectorised calculations such as loops; and iii) lazy (but convenient) coding that comes from drawing too heavily on the
tidyverse suite of packages. We will continue to ensure that
heatwaveR becomes more-and-more efficient so that it can be applied to large gridded data products with ease.
This new package was developed and released in order to better accommodate the inclusion of the definitions of atmospheric heatwaves in addition to MHWs. Additionally,
heatwaveR also provides the first implementation of a definition for a ‘compound heatwave’. There are currently multiple different definitions for this type of event and each of which has arguments provided for it within the
This package may be installed from CRAN by typing the following command into the console:
Or the development version may be installed from GitHub with:
||Constructs seasonal and threshold climatologies as per the definition of Hobday et al. (2016).|
||The main function which detects the events as per the definition of Hobday et al. (2016).|
||Calculates annual means for event metrics.|
||Applies event categories to the output of
||A function similar to
||Creates a line plot of heatwaves or cold-spells.|
||Creates a timeline of selected event metrics.|
||Creates flame polygons of heatwaves or cold-spells.|
||Creates a lolliplot timeline of selected event metric.|
The package also provides data of observed SST records for three historical MHWs: the 2011 Western Australia event, the 2012 Northwest Atlantic event and the 2003 Mediterranean event.
The function will return a list of two tibbles (see the ‘tidyverse’),
event, which are the climatology and MHW (or MCS) events, respectively. The climatology contains the full time series of daily temperatures, as well as the the seasonal climatology, the threshold and various aspects of the events that were detected. The software was designed for detecting extreme thermal events, and the units specified below reflect that intended purpose. However, the various other kinds of extreme events may be detected according to the ‘marine heatwave’ specifications, and if that is the case, the appropriate units need to be determined by the user.
||Julian day (day-of-year). For non-leap years it runs 1…59 and 61…366, while leap years run 1…366. This column will be named differently if another name was specified to the
||The date of the temperature measurement. This column will be named differently if another name was specified to the
||If the software was used for the purpose for which it was designed, seawater temperature [deg. C] on the specified date will be returned. This column will of course be named differently if another kind of measurement was specified to the
||Climatological seasonal cycle [deg. C].|
||Seasonally varying threshold (e.g., 90th percentile) [deg. C].|
||Seasonally varying variance (standard deviation) [deg. C].|
||Boolean indicating if
||Boolean indicating whether periods of consecutive
||Boolean indicating if all criteria that define a MHW or MCS are met.|
||A sequential number indicating the ID and order of occurrence of the MHWs or MCSs.|
The events are summarised using a range of event metrics:
||A sequential number indicating the ID and order of the events.|
||Start index of event.|
||Peak index of event.|
||Index of event peak.|
||Duration of event [days].|
||Start date of event [date].|
||Date of event peak [date].|
||End date of event [date].|
||Mean intensity [deg. C].|
||Maximum (peak) intensity [deg. C].|
||Intensity variability (standard deviation) [deg. C].|
||Cumulative intensity [deg. C x days].|
||Onset rate of event [deg. C / day].|
||Decline rate of event [deg. C / day].|
intensity_cumulative_relThresh are as above except relative to the threshold (e.g., 90th percentile) rather than the seasonal climatology.
intensity_cumulative_abs are as above except as absolute magnitudes rather than relative to the seasonal climatology or threshold.
rate_decline will return
NA when the event begins/ends on the first/last day of the time series. This may be particularly evident when the function is applied to large gridded data sets. Although the other metrics do not contain any errors and provide sensible values, please take this into account in the interpretation of the output.
For detailed explanations and walkthroughs on the use of the
heatwaveR package please click on the articles tab above, or follow the links below:
detect_event()function applied to the gridded data, and then fit a GLM and plot the results.
To contribute to the package please follow the guidelines here.
Please use this link to report any bugs found.
Hobday, A.J. et al. (2016). A hierarchical approach to defining marine heatwaves, Progress in Oceanography, 141, pp. 227-238.
Schlegel, R. W., Oliver, E. C. J., Wernberg, T. W., Smit, A. J. (2017a). Nearshore and offshore co-occurrences of marine heatwaves and cold-spells. Progress in Oceanography, 151, pp. 189-205.
Schlegel, R. W., Oliver, E. C., Perkins-Kirkpatrick, S., Kruger, A., Smit, A. J. (2017b). Predominant atmospheric and oceanic patterns during coastal marine heatwaves. Frontiers in Marine Science, 4, 323.
Hobday, A. J., Oliver, E. C. J., Sen Gupta, A., Benthuysen, J. A., Burrows, M. T., Donat, M. G., Holbrook, N. J., Moore, P. J., Thomsen, M. S., Wernberg, T., Smale, D. A. (2018). Categorizing and naming marine heatwaves. Oceanography 31(2).
The Python code was written by Eric C. J. Oliver.
Contributors to the Marine Heatwaves definition and its numerical implementation include Alistair J. Hobday, Lisa V. Alexander, Sarah E. Perkins, Dan A. Smale, Sandra C. Straub, Jessica Benthuysen, Michael T. Burrows, Markus G. Donat, Ming Feng, Neil J. Holbrook, Pippa J. Moore, Hillary A. Scannell, Alex Sen Gupta, and Thomas Wernberg.
The translation from Python to R was done by A. J. Smit and the graphing functions were contributed to by Robert. W. Schlegel.
Robert W. Schlegel Department for Biodiversity & Conservation Biology, University of the Western Cape Private Bag X17, Bellville 7535, South Africa E-mail: [email protected]
exceedance()will no longer produce a
var = TRUEmay be given to produce this column
FALSEto match the new default for
event_line()to no longer require the user to provide
detect_events.R()for returning the proto events rather than a table for the event metrics
exceedance()so that it is the same as
event_line()that caused it to graph events outside of the
ts2clm()to match the Python default settings
clim_calc()reinstated to allow for calculation of clims with missing data
varcalculations reinstated for documentation issues
ts2clm()no longer calls
smooth_percentile()no longer provides option to create variance climatology (the need to no longer create var seemed to not be fully implemented in 0.3.4)
ts2clm()no longer calculates variance column by default
make_whole()has been deprecated in favour of
proto_event()to return no events than to stop message with an error.
detect_event()without any required changes
category()required a bit of cajoling to also output a blank dataframe
make_whole_fast()to provide a cleaner internal output
ts2clm()that prevented calculation of clims with large contiguous missing periods of data (e.g. ice coverage).
category()that allows one to have the function also output the day-to-day (long) category values, rather than just the summary (wide) output.
clim_calc_cppnot being able to calculate clims from baselines not beginning and ending on the Julian year by making
clim_spreadplug the gaps beforehand with row-wise means.
make_whole_fastwhich did not create a whole, complete time series (i.e. missing dates were still present); the missing dates caused
proto_eventnow handles all event calculations 'in house'
detect_eventto now be given a theoretically limitless number of thresholds
lolli_plotbeing asked to highlight more events than are present
detect_eventto better match Python version
clim_calc_ccp()for faster climatology calculations; speed of climatology calculation comes down from 50.6 ms in R to 3.4 ms in C++ on my MacBook Pro (15-inch, 2017) 2.9 GHz Intel Core i7 16 GB RAM computer
smooth_percentile()by using RcppRoll
clim_spread()now returns a matrix, not a data frame. This makes the loop in
clim_calc()much faster. In testing with the sst_WA data, it leads to a 3.7 fold speed improvement (520 ms down to 140 ms).
make_whole()(60 ms down to 40 ms)
detect()in favour of the new pipeline
exceedance()to utilise the internal functions
detect_event()pipeline returns the same results as the old
detect_event()now passing checks
detect()function was unpacked and simplified. Internal code is now in new functions, most of which will not be seen by the user. They are
ts2clm()used instead of
exceedance()function testthat checks updated to account for change in variable naming
detect()has now been broken into
category()function returns the category results for events
heatwaveRhex logo added to site
event_line()not plotting MCSs correctly
detect()as requested by Maxime Marin (), The University of Tasmania (IMAS) – CSIRO (O&A), and which is present in the python version of the package
event_line()to acknowledge column names other than
lolli_plot()to use underlying
NEWS.mdfile to track changes to the package.
RmarineHeatWavespackage to this repo