A MATLAB toolbox to detect and analyze marine heatwaves
A MATLAB toolbox to detect and analyze marine heatwaves - Published in JOSS (2019)
Science Score: 93.0%
This score indicates how likely this project is to be science-related based on various indicators:
-
○CITATION.cff file
-
✓codemeta.json file
Found codemeta.json file -
✓.zenodo.json file
Found .zenodo.json file -
✓DOI references
Found 4 DOI reference(s) in README and JOSS metadata -
✓Academic publication links
Links to: joss.theoj.org -
○Committers with academic emails
-
○Institutional organization owner
-
✓JOSS paper metadata
Published in Journal of Open Source Software
Keywords
Scientific Fields
Repository
A MATLAB toolbox to detect and analyze marine heatwaves (MHWs).
Basic Info
Statistics
- Stars: 54
- Watchers: 6
- Forks: 21
- Open Issues: 16
- Releases: 0
Topics
Metadata Files
README.md
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
Owner
- Name: Zijie Zhao
- Login: ZijieZhaoMMHW
- Kind: user
- Location: Melbourne
- Company: The University of Melbourne
- Repositories: 2
- Profile: https://github.com/ZijieZhaoMMHW
A boring researcher who does not know so many things. email: zijiezhaomj@gmail.com
JOSS Publication
A MATLAB toolbox to detect and analyze marine heatwaves
Authors
School of Earth Sciences, The University of Melbourne, Melbourne, Victoria, Australia, Institute for Marine and Antarctic Studies, University of Tasmania, Hobart, Tasmania, Australia, Australian Research Council Centre of Excellence for Climate System Science, Hobart, Tasmania, Australia, College of Oceanic and Atmospheric Sciences, Ocean University of China, Qingdao, China
Institute for Marine and Antarctic Studies, University of Tasmania, Hobart, Tasmania, Australia, Australian Research Council Centre of Excellence for Climate System Science, Hobart, Tasmania, Australia, CSIRO Oceans & Atmosphere, Indian Ocean Marine Research Centre, Crawley 6009, Western Australia, Australia
Editor
Kristen Thyng
Tags
MATLAB heatwaves extremes oceanGitHub Events
Total
- Issues event: 3
- Watch event: 14
- Issue comment event: 11
- Push event: 3
- Fork event: 4
Last Year
- Issues event: 3
- Watch event: 14
- Issue comment event: 11
- Push event: 3
- Fork event: 4
Issues and Pull Requests
Last synced: 6 months ago
All Time
- Total issues: 20
- Total pull requests: 5
- Average time to close issues: 22 days
- Average time to close pull requests: N/A
- Total issue authors: 14
- Total pull request authors: 3
- Average comments per issue: 1.8
- Average comments per pull request: 0.2
- Merged pull requests: 0
- Bot issues: 0
- Bot pull requests: 0
Past Year
- Issues: 4
- Pull requests: 0
- Average time to close issues: N/A
- Average time to close pull requests: N/A
- Issue authors: 4
- Pull request authors: 0
- Average comments per issue: 2.0
- Average comments per pull request: 0
- Merged pull requests: 0
- Bot issues: 0
- Bot pull requests: 0
Top Authors
Issue Authors
- mvdh7 (6)
- Marina-red (2)
- Smabmn (1)
- 7eatriz (1)
- met-sree (1)
- sxuswy (1)
- ZijieZhaoMMHW (1)
- cindyisok (1)
- Hangyu1008 (1)
- maximemarin (1)
- MazenBayoumy (1)
- iljamal (1)
- mlchandler (1)
- keegancarvalho28 (1)
Pull Request Authors
- maximemarin (3)
- codacy-badger (1)
- mlchandler (1)