Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/ZijieZhaoMMHW/m_mhw1.0

A MATLAB toolbox to detect and analyze marine heatwaves (MHWs).
https://github.com/ZijieZhaoMMHW/m_mhw1.0

climate-science data-analysis heatwaves marine-heatwaves matlab

Last synced: 3 months ago
JSON representation

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

Awesome Lists containing this project

README 

        
m_mhw

==================================================================

[![DOI](http://joss.theoj.org/papers/10.21105/joss.01124/status.svg)](https://doi.org/10.21105/joss.01124)



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](https://www.eoas.ubc.ca/~rich/map.html) 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](https://github.com/ZijieZhaoMMHW/m_mhw1.0/tree/master/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](https://github.com/ZijieZhaoMMHW/m_mhw1.0/blob/master/examples/an_example.md) [(Codes)](https://github.com/ZijieZhaoMMHW/m_mhw1.0/blob/master/examples/an_example.m)



[Analysing seasonality and monthly variability of MHWs](https://github.com/ZijieZhaoMMHW/m_mhw1.0/blob/master/examples/seasonality.md) [(Codes)](https://github.com/ZijieZhaoMMHW/m_mhw1.0/blob/master/examples/seasonality.m)



[EOF analysis on annual MHW days](https://github.com/ZijieZhaoMMHW/m_mhw1.0/blob/master/examples/mhweof.md) [(Codes)](https://github.com/ZijieZhaoMMHW/m_mhw1.0/blob/master/examples/mhweof.m)



[MHW Category Analysis](https://github.com/ZijieZhaoMMHW/m_mhw1.0/blob/master/examples/category_analysis.md) [(Codes)](https://github.com/ZijieZhaoMMHW/m_mhw1.0/blob/master/examples/category_analysis.m)



[EOF analysis on annual MHW cumulative intensity](https://github.com/ZijieZhaoMMHW/m_mhw1.0/blob/master/examples/mhweof_int.md) [(Codes)](https://github.com/ZijieZhaoMMHW/m_mhw1.0/blob/master/examples/mhweof_int.m)



[Comparison for the efficiency biases between `detect` and `detectc`](https://github.com/ZijieZhaoMMHW/m_mhw1.0/blob/master/examples/mhw_efficiency.md) [(Codes)](https://github.com/ZijieZhaoMMHW/m_mhw1.0/blob/master/examples/mhw_efficiency.m)



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](https://github.com/ZijieZhaoMMHW/m_mhw1.0/blob/master/testing/compare_M_R.md). 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](https://github.com/ZijieZhaoMMHW/m_mhw1.0/blob/master/docs/Contributing_to_mmhw.md).



Please use this [link](https://github.com/ZijieZhaoMMHW/m_mhw1.0/issues) 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:  



Maxime Marin



CSIRO Oceans & Atmosphere, Indian Ocean Marine Research Centre



Crawley 6009, Western Australia, Australia



E-mail: