zijiezhaommhw/m_mhw1.0

A MATLAB toolbox to detect and analyze marine heatwaves (MHWs).

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)

MHW Category Analysis (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: [email protected]

Maxime Marin

CSIRO Oceans & Atmosphere, Indian Ocean Marine Research Centre

Crawley 6009, Western Australia, Australia

E-mail: [email protected]

m_mhw1.0's Issues

issue in the mean_and_trend function

I have found two issues in the new code
1_ In the mean_and_trend function, the 1982 should be changed to data_here as not all people used the data from 1982.
2- the output of MHW days is not the same as in the old version.
Thanks

m_map required for testing

For JOSS review

The separate package m_map is required to run the example scripts but no information is provided on how to obtain and install this. Consequently I cannot fully test the functional claims of the software.

m_map is also not listed as a requirement in the documentation. If you consider the example scripts to be not part of the software under review then that could perhaps be justified; m_map is not needed to actually execute the main functions. But as the example scripts are the only straightforward way to test the functionality, I'm not sure that that applies in this case.

MATLAB warning flags

For JOSS review

The MATLAB code for the functions themselves contains many warning messages indicating inefficient or unnecessary constructs. I strongly suggest the authors work through and eliminate these, to improve code legibility, and in some cases, its performance.

Matrix dimensions must agree in <= statement

Seems like calculating the climatologies is too advanced for the Matlab 2015a

_Error using <=
Matrix dimensions must agree.

Error in detect (line 179)
m90(:,:,i) = quantile(temp_clim(:,:,any(ind_fake'>=(ind_fake(fake_doy == i)-vWindowHalfWidth) & ind_fake' <=
(ind_fake(fake_doy ==i)+vWindowHalfWidth),2)),vThreshold,3);_

On a Matlab 2020a this error did not appear.

Results inconsistencies with other implementations

For JOSS review

The noted differences in results between the different implementations (MATLAB, Python, R) are worrisome. It's said that this is caused by differences in how the different languages evaluate percentile thresholds, but surely the code could be adapted to enforce consistent calculations? If not, can you demonstrate that this is the only difference between the implementations, and thus prove that no other discrepancies are hiding behind it?

Function inputs documentation

For JOSS review

Documentation on the functions’ API in the readme includes a description of their outputs but nothing on inputs. Inputs are described in code comments within the functions themselves, but it would be helpful to have this info in the readme too.

Non-OSI license

For JOSS review

The license file simply states a name and a year, and does not appear to refer to any from the OSI approved list as required by JOSS.

Update to detect (Adding date_peak and no use of toolbox)

The use of quantile()

The use of quantile() function in MATLAB raises some errors. Under modifications.

a ‘compound heatwave

Hello
Can this program calculate compound heat waves?
Thank

Problems with an_example.m

Undefined function 'datetime' for input arguments of type 'double'.

Error in detect (line 164)
fake_doy = day(datetime(date_false),'dayofyear');

event_line.m seems to only work correctly when data time series starts at the start of the year

The event_line function was incorrectly plotting my MHW events when the time series started in Feb. However when I removed the first year of data so that my time series started on Jan 1st it correctly identified the events. This seems to be a (possibly accidental) deliberate decision and one which should be mentioned in the documentation as I did not see mention of it in there.

Possible solution (??) has now been suggested (#17).

Error in evaluating .mat files

I'm trying to focus on MHW in the coastal areas of Greenland. Loaded the "sst" data and saved them as .mat files in the appropriate folder. I get an error:

Error using eval
Undefined function or variable 'sst_2006'.

Here's my code:
`

sst_full=NaN(280,112,datenum(2018,12,31)-datenum(2006,1,1)+1);
for i=2006:2016;
file_here=['sst_' num2str(i)];
load(file_here);
eval(['data_here=sst_' num2str(i) ';'])
sst_full(:,:,(datenum(i,1,1):datenum(i,12,31))-datenum(2006,1,1)+1)=data_here;
end`

Would be grateful to receive some help in this. OR is there another easier code of combining the files?

No DOIs in paper

For JOSS review

There are no DOIs for citations in the paper or its .bib file; these are required by JOSS.

an_example

Hello! I'm trying to run an_example.m on matlab 2014b
And there is an error:
Error using >=
Matrix dimensions must agree.

Error in detect (line 176)
data_thre=num2cell(temp_clim(:,:,any(ind_fake'>=(ind_fake(fake_doy == i)-vWindowHalfWidth) & ind_fake' <= (ind_fake(fake_doy
==i)+vWindowHalfWidth),2)),3);

Error in an_example (line 28)
[MHW,mclim,m90,mhw_ts]=detect(sst_full,datenum(1982,1,1):datenum(2016,12,31),datenum(1982,1,1),datenum(2005,12,31),datenum(1993,1,1),datenum(2016,12,31));;
%take about 30 seconds.

What it can be?