m_mhw
The m_mhw toolbox is an matlab - based tool designed to detect and analyse spatial marine heatwaves (MHWs). Previously, approaches to detecting and analysing MHW time series have been applied in python (https://github.com/ecjoliver/marineHeatWaves, written by Eric C. J. Oliver) and R (Schlegel and Smit, 2018).
The m_mhw toolbox is designed 1) to determine spatial MHWs according to the definition provided in Hobday et al. (2016) and marine cold spells (MCSs) introduced in Schlegel et al. (2017); 2) to visualize MHW/MCS event in a particular location during a period; 3) to explore the mean states and trends of MHW metrics, such as what have done in Oliver et al. (2018).
Installation
The installation of this toolbox could be directly achieved by downloading this repositories and add its path in your MATLAB.
Requirements
The MATLAB Statistics and Machine Learning Toolbox. m_map is recommended for running example.
Functions
| Function | Description |
|---|---|
detect() |
The main function, aiming to detect spatial MHW/MCS events following definition given by Hobday et al. (2016). |
detectc() |
Similar to detect but it stores the MHW output in cell format, resulting in faster computation. See an example for the comparison between detect and detectc. |
event_line() |
The function to create a line plot of MHW/MCS in a particular grid during a particular period. |
mean_and_trend() |
The function to calculate spatial mean states and annual trends of MHW/MCS properties. |
composites() |
The function to calculate composites for a particular dataset across a particular index. |
Additionally, this toolbox also provides sea surface temperature off eastern Tasmania [147-155E, 45-37S] during 1982-2015, extracted from NOAA OI SST V2 (Reynolds et al., 2007).
Inputs and outputs
The core function detect need some inputs:
| Variable | Description |
|---|---|
temp |
A 3D matrix containing temperature data. |
time |
A numeric vector indicating the time corresponding to temp in the format of datenum() |
cli_start |
A numeric value indicating the starting date for calculating climatology in the format of datenum() |
cli_end |
A numeric value indicating the ending date for calculating climatology in the format of datenum() |
mhw_start |
A numeric value indicating the starting date for detection of MHW in the format of datenum() |
mhw_end |
A numeric value indicating the ending date for detection of MHW in the format of datenum() |
The core function detect would return four outputs, which are MHW, mclim, m90 and mhw_ts. Their descriptions are summarized in following table.
| Variable | Description |
|---|---|
MHW |
A table containing all detected MHW/MCS events, where every row corresponds to a particular event and every column indicates a metric or property. |
mclim |
A 3D numeric matrix in size of (x,y,366), containing climatologies in each grid for every Julian day. |
m90 |
A 3D numeric matrix in size of (x,y,366), containing thresholds in each grid for every Julian day. |
mhw_ts |
A 3D numeric matrix in size of (x,y,(datenum(MHW_end)-datenum(MHW_start)+1)), containing daily MHW/MCS intensity. 0 in this variable indicates that corresponding day is not in a MHW/MCS event and NaN indicates missing value or lands. |
The major output MHW contains all detected MHW/MCS events, characterized by 9 different properties, including:
| Property | Description |
|---|---|
mhw_onset |
A numeric vector indicating the onset date (YYYYMMDD) of each event. |
mhw_end |
Similar to mhw_onset, but indicating the end date (YYYYMMDD). |
mhw_dur |
A numeric vector indicating the duration (days) of each event. |
int_max |
A numeric vector indicating the maximum intensity of each event in unit of deg. C. |
int_mean |
A numeric vector indicating the mean intensity of each event in unit of deg. C. |
int_var |
A numeric vector indicating the variance of intensity of each event. |
int_cum |
A numeric vector indicating the cumulative intensity of each event in unit of deg. C x days. |
xloc |
A numeric vector indicating the location of each event in the x-dimension of temperature data. |
yloc |
A numeric vector indicating the location of each event in the y-dimension of temperature data. |
For information of other functions, please see help text via MATLAB. For practical tutorial and example, please see following contents.
Example
We provide examples about how to use functions in m_mhw and how to apply them to real-world data.
Current examples include:
An example about how to apply m_mhw to real-world data (Codes)
Analysing seasonality and monthly variability of MHWs (Codes)
EOF analysis on annual MHW days (Codes)
EOF analysis on annual MHW cumulative intensity (Codes)
Comparison for the efficiency biases between detect and detectc (Codes)
Issues
The results from this toolbox would be slightly different from outputs from Python and R modules. This is due to the fact that MATLAB follows different rules to calculate percentile thresholds. The number of detected events from this toolbox would be slightly less than that from Python and R. Please see a comparison. If you would like to get the same outputs as python, please set the optional input 'percentile' as 'python' (default is 'matlab').
Contributing to m_mhw
To contribute to the package please follow the guidelines here.
Please use this link to report any bugs found.
Citation
If you use this toolbox, please cite the paper:
Zhao, Z., & Marin, M. (2019). A MATLAB toolbox to detect and analyze marine heatwaves. Journal of Open Source Software, 4(33), 1124.
References
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., 2017. Nearshore and offshore co-occurrences of marine heatwaves and cold-spells. Progress in Oceanography, 151, pp. 189-205.
Schlegel, R. W. and Smit, A. J, 2018. heatwaveR: A central algorithm for the detection of heatwaves and cold-spells. The Journal of Open Source Software, 3, p.821.
Oliver, E.C., Lago, V., Hobday, A.J., Holbrook, N.J., Ling, S.D. and Mundy, C.N., 2018. Marine heatwaves off eastern Tasmania: Trends, interannual variability, and predictability. Progress in Oceanography, 161, pp.116-130.
Reynolds, Richard W., Thomas M. Smith, Chunying Liu, Dudley B. Chelton, Kenneth S. Casey, Michael G. Schlax, 2007: Daily High-Resolution-Blended Analyses for Sea Surface Temperature. J. Climate, 20, 5473-5496.
Contact
Zijie Zhao
School of Earth Science, The University of Melbourne
Parkville VIC 3010, Melbourne, Australia
E-mail: zijie.zhao@utas.edu.au
Maxime Marin
CSIRO Oceans & Atmosphere, Indian Ocean Marine Research Centre
Crawley 6009, Western Australia, Australia
E-mail: Maxime.Marin@csiro.au