heatwaveR

analysis

MHW

Introducing heatwaveR to a non-marine science audience.

Author

Affiliation

Robert Schlegel

Laboratoire d’Océanographie, Institut de la Mer de Villefranche

Published

November 22, 2023

Modified

November 23, 2023

Introducing heatwaveR

The heatwaveR R package is a translation of the original Python code written by Eric C. J. Oliver. heatwaveR uses the same naming conventions for objects, columns, and arguments as the Python code, and it reports the same metrics.

heatwaveR calculates and displays marine heatwaves (MHWs) according to the definition of Hobday et al. (2016). Additionally, it also accommodates marine cold-spells (MCSs) as first introduced in Schlegel et al. (2017a). MHW categories are also provided as outlined in Hobday et al. (2018).

The packages is currently undergoing active enhancements for spead that would make it suitable for applying to larger datasets on High Performance Computers (HPC). This is alleviating the bottlenecks that slowed down the climatology creation portions of the code as well as generally creating an overall increase in the speed of the calculations, and helping with memory-use efficiency. The development version of the R code, which is not yet available on CRAN, runs about twice as fast as the original python functions when applied to gridded time series of temperatures, for example those obtained from SST products.

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 to deal with the increasingly larger (finer resolution) SST products. To that end, the extension package heatwave3 is being developed. This will help the user to apply the code from heatwaveR directly onto their NetCDF and other 3D gridded data files.

heatwaveR has also adopted mechanisms to better accommodate the inclusion of the definitions of atmospheric heatwaves in addition to MHWs. We have been quite responsive to users’ needs and welcome input regarding additional metrics and applications of our functions to extend application outside of the ‘traditional’ marine heatwave detection. 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 ts2clm() and detect_event() functions.

Install from CRAN

This package may be installed from CRAN by typing the following command into the console:

install.packages("heatwaveR")

Install from GitHub

The development version may be installed from GitHub with:

devtools::install_github("robwschlegel/heatwaveR")

The development package contains the functions ts2clm3() and detect_event3() which are the same as the original functions but with speed improvements (due to data.table internals) leading to up to a doubling of speed. The functions ts2clm() and detect_event() are still available for use.

Vignette

Please refer to the heatwaveR vignette for more information on how to use the package. The vignette is on our GitHub page .

Benefits

The benefits of the heatwaveR package include:

Event detection: It can identify periods of extreme temperature, both high (heatwaves) and low (cold spells), based on flexible user-defined criteria.
Event characterisation: Once events are identified, heatwaveR provides summaries of the heatwaves’ characteristics, such as duration, intensity, and frequency.
Visualisation: The package includes functions for creating informative visualisations of the detected events, helping in the interpretation and communication of results.
Flexibility: heatwaveR is designed to work with a variety of temperature (and other) datasets and allows customisation in the definition of what constitutes a heatwave or cold spell.

Reuse

CC BY-NC-SA 4.0

Citation

BibTeX citation:

@online{j._smit2023,
  author = {J. Smit, Albertus and Schlegel, Robert},
  title = {heatwaveR},
  date = {2023-11-22},
  url = {http://tangledbank.netlify.app/blog/2023-11-23-heatwaver/},
  langid = {en}
}

For attribution, please cite this work as:

J. Smit A, Schlegel R (2023) heatwaveR. http://tangledbank.netlify.app/blog/2023-11-23-heatwaver/.

--- title: "heatwaveR" description: "Introducing heatwaveR to a non-marine science audience." author: - name: Robert Schlegel url: https://github.com/robwschlegel affiliation: Laboratoire d’Océanographie, Institut de la Mer de Villefranche affiliation-url: https://lov.imev-mer.fr/web/ date: "2023-11-22" date-modified: "2023-11-23" draft: false categories: - R - analysis - MHW feed: true bibliography: ../../references.bib csl: ../../marine-biology.csl --- ## Introducing **heatwaveR** The **heatwaveR** R package is a translation of the original Python code written by Eric C. J. Oliver. **heatwaveR** uses the same naming conventions for objects, columns, and arguments as the Python code, and it reports the same metrics. **heatwaveR** calculates and displays marine heatwaves (MHWs) according to the definition of Hobday et al. (2016). Additionally, it also accommodates marine cold-spells (MCSs) as first introduced in Schlegel et al. (2017a). MHW categories are also provided as outlined in Hobday et al. (2018). The packages is currently undergoing active enhancements for spead that would make it suitable for applying to larger datasets on High Performance Computers (HPC). This is alleviating the bottlenecks that slowed down the climatology creation portions of the code as well as generally creating an overall increase in the speed of the calculations, and helping with memory-use efficiency. The development version of the R code, which is not yet available on CRAN, runs about twice as fast as the original python functions when applied to gridded time series of temperatures, for example those obtained from SST products. 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 to deal with the increasingly larger (finer resolution) SST products. To that end, the extension package **heatwave3** is being developed. This will help the user to apply the code from **heatwaveR** directly onto their NetCDF and other 3D gridded data files. **heatwaveR** has also adopted mechanisms to better accommodate the inclusion of the definitions of atmospheric heatwaves in addition to MHWs. We have been quite responsive to users' needs and welcome input regarding additional metrics and applications of our functions to extend application outside of the 'traditional' marine heatwave detection. 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 `ts2clm()` and `detect_event()` functions. ## Install from CRAN This package may be installed from CRAN by typing the following command into the console: `install.packages("heatwaveR")` ## Install from GitHub The development version may be installed from GitHub with: `devtools::install_github("robwschlegel/heatwaveR")` The development package contains the functions `ts2clm3()` and `detect_event3()` which are the same as the original functions but with speed improvements (due to **data.table** internals) leading to up to a doubling of speed. The functions `ts2clm()` and `detect_event()` are still available for use. ## Vignette Please refer to the **heatwaveR** vignette for more information on how to use the package. The vignette is on our [GitHub page](https://robwschlegel.github.io/heatwaveR/index.html) . ## Benefits The benefits of the **heatwaveR** package include: 1. **Event detection**: It can identify periods of extreme temperature, both high (heatwaves) and low (cold spells), based on flexible user-defined criteria. 2. **Event characterisation**: Once events are identified, `heatwaveR` provides summaries of the heatwaves' characteristics, such as duration, intensity, and frequency. 3. **Visualisation**: The package includes functions for creating informative visualisations of the detected events, helping in the interpretation and communication of results. 4. **Flexibility**: `heatwaveR` is designed to work with a variety of temperature (and other) datasets and allows customisation in the definition of what constitutes a heatwave or cold spell.