Merge pull request #45 from coecms/timestep

Timestep

.codeclimate.yml

@@ -0,0 +1,3 @@
+exclude_paths:
+    - docs/_build/**/*
+    - test/**/*

.codecov.yml

@@ -0,0 +1 @@
+comment: off

.github/workflows/xmhw-conda.yml

@@ -0,0 +1,56 @@
+name: xmhw-conda-install-test
+
+#on: [push]
+on: 
+  push:
+    branches:
+      - master
+      - timestep
+  pull_request:
+    branches:
+      - master
+
+
+jobs:
+  build-linux:
+    runs-on: ubuntu-latest
+    strategy:
+      max-parallel: 5
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Python 3.9
+      uses: actions/setup-python@v2
+      with:
+        python-version: 3.9
+    - name: Add conda to system path
+      run: |
+        # $CONDA is an environment variable pointing to the root of the miniconda directory
+        echo $CONDA/bin >> $GITHUB_PATH
+    - name: Install dependencies
+      run: |
+        conda env update --file conda/environment.yml --name base 
+    - name: Lint with flake8
+      run: |
+        conda install flake8
+        # stop the build if there are Python syntax errors or undefined names
+        flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
+        # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
+        flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
+        #    - name: Install package 
+      #      run: |
+              #        conda run python setup.py install
+    - name: Test with pytest
+      run: |
+        conda install pytest coverage codecov
+        conda run python -m pytest
+        conda run coverage run --source xmhw -m py.test
+    - name: Upload to codecov 
+      if: steps.build.outcome == 'success'
+      run: |
+        curl -Os https://uploader.codecov.io/latest/linux/codecov
+        chmod +x codecov
+        ./codecov
+          # codeclimate-test-reporter specifi to python is deprecated and as been replaced by a binary
+        # curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter
+

.gitignore

@@ -0,0 +1,68 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*,cover
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Editor files
+*.swp
+
+# Databases
+*.db
+
+/README.cookiecutter.md
+
+.vagrant
+.pytest_cache

README.rst

@@ -37,8 +37,7 @@ Install
 ---
 Use
 ---
-Some examples of how to use the functions and explanations of how the functions work are shown in the xmhw_demo.ipynb notebook in the docs folder.
-We will keep on adding more information to this notebook.
+Some examples of how to use the functions and explanations of how the functions work are shown in the readthedocs documentation linked above and the `xmhw_demo.ipynb notebook <https://github.com/coecms/xmhw/blob/master/docs/xmhw_demo.ipynb>_` in the docs folder.
 
 --------------------
 Latest version v 0.7

conda/.condarc

@@ -0,0 +1,2 @@
+conda config --add channels <username> 
+conda install mypackage

conda/bld.bat

@@ -0,0 +1,2 @@
+"%PYTHON%" setup.py install
+if errorlevel 1 exit 1

conda/build.sh

@@ -0,0 +1 @@
+$PYTHON setup.py install     # Python command to install the script.

conda/environment.yml

@@ -0,0 +1,6 @@
+dependencies:
+  - netcdf4
+  - numpy
+  - pandas
+  - xarray
+  - dask

conda/meta.yml

@@ -0,0 +1,52 @@
+{% set version = "0.7.0" %}
+package:
+    name: xmhw 
+    version: {{ version }}
+
+about:
+    home: https://github.com/coecms/xmhw
+    license: Apache-2.0
+    license_file: LICENSE-2.0.txt
+    summary: "Xarray based Marine HeatWave detection code"
+    description: |
+      XMHW identifies marine heatwaves from a timseries of 
+      Sea Surface Temperature data and calculates statistics 
+      associated to the detected heatwaves. It is based on the 
+      marineHeatWaves code <https://github.com/ecjoliver/marineHeatWaves/> 
+    doc_url:
+    dev_url: https://github.com/coecms/xmhw 
+
+requirements:
+    host:
+        - python >= 3.7
+        - pip
+    run:
+        - python >= 3.7
+        - pandas
+        - xarray
+        - numpy
+        - dask 
+
+source:
+    url:  https://github.com/coecms/xmhw/archive/refs/tags/{{version}}.tar.gz 
+
+build:
+    number: {{ GIT_DESCRIBE_NUMBER }}
+    script: python setup.py install --single-version-externally-managed --record=record.txt
+
+test:
+    source_files:
+        - setup.cfg
+        - test
+    requires:
+        - pytest
+        - coverage
+        - numpy
+        - xarray
+        - pandas
+        - dask
+    imports:
+        - xmhw
+    commands:
+        - COVERAGE_FILE=${TEST_OUTPUT:-.}/coverage coverage run --source xmhw -m pytest ./test
+

conda/run_test.sh

@@ -0,0 +1,2 @@
+#!/bin/bash
+py.test

conda/run_test_coverage.sh

@@ -0,0 +1,3 @@
+#!/bin/bash
+pip install coverage pytest-cov
+py.test --cov=xmhw --cov-report xml:/tmp/artefacts/tests/pytest/coverage.xml --junit-xml /tmp/artefacts/tests/pytest/results.xml

docs/block_average.rst

@@ -0,0 +1,93 @@
+Block average
+~~~~~~~~~~~~~
+
+The blockAverage function on the original MHW code is used to calculate
+statistics along a block of time. The default is 1 year block. If the
+timeseries used starts or ends in the middle of the year then the
+results for this two years have to be treated carefully. Most of the
+statistics calculated on the block are simple statistics. Given that the
+mhw properties are saved now as an array it is simple to calculate them
+after grouping by year or “bins”of years on the entire dataset. However,
+we added xmhw has a block_average() function to reproduce the same
+results.
+
+.. code:: ipython3
+
+    # To call with standard parameters, all is needed is the output of detect function 
+    # I am also passing the intermediate results datasets as a way to provide the temperature and
+    # climatologies
+    from xmhw.stats import block_average
+    block = block_average(mhw, dstime=intermediate)
+    block
+     
+    Assuming time is time dimension
+    Both ts and climatologies are available, calculating ts and category stats
+
+    xarray.Dataset
+    Dimensions:
+        years: 41  lat: 12  lon: 20
+    Coordinates:
+        years (years) object [1981, 1982) ... 
+        lat (lat) float64 -43.88 -43.62 ...
+        lon (lon) float64 144.1 144.4 ...
+    Data variables:
+        ecount (years, lat, lon) float64 0.0 0.0 ...
+        duration (years, lat, lon) float64 nan nan ...
+        intensity_max (years, lat, lon) float64 nan nan ...
+        intensity_max_max (years, lat, lon) float64 nan nan ...
+        intensity_mean (years, lat, lon) float64 nan nan ...
+        intensity_cumulative (years, lat, lon) float64 nan nan ...
+        total_icum (years, lat, lon) float64 0.0 0.0 ...
+        intensity_mean_relThresh (years, lat, lon) float64 nan nan ...
+        intensity_cumulative_relThresh (years, lat, lon) float64 nan nan ...
+        severity_mean (years, lat, lon) float64 nan nan ...
+        severity_cumulative (years, lat, lon) float64 nan nan ...
+        intensity_mean_abs (years, lat, lon) float64 nan nan ...
+        intensity_cumulative_abs (years, lat, lon) float64 nan nan ...
+        rate_onset (years, lat, lon) float64 nan nan ...
+        rate_decline (years, lat, lon) float64 nan nan ...
+        ts_mean (years, lat, lon) float32 11.57 11.56 ...
+        ts_max (years, lat, lon) float32 14.28 14.32 ...
+        ts_min (years, lat, lon) float32 9.51 9.46 ...
+        moderate_days (years, lat, lon) float64 0.0 0.0 ...
+        strong_days (years, lat, lon) float64 0.0 0.0 ...
+        severe_days (years, lat, lon) float64 0.0 0.0 ...
+        extreme_days (years, lat, lon) float64 0.0 0.0 ...
+        total_days (years, lat, lon) float64 0.0 0.0 ...
+
+Block_average function in detail
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+   def block_average(mhw, dstime=None, period=None, blockLength=1, mtime='time_start',
+                     removeMissing=False, split=False):
+
+       Parameters
+       ----------
+       mhw: xarray Dataset 
+           Includes MHW properties by events
+       dstime: xarray DataArray/Dataset, optional
+            Based on intermediate dataset returned by detect(), includes
+            original ts and climatologies (optional) along 'time' dimension
+            (default is None)
+            If present and is array or dataset with only 1 variable script assumes this
+            is sst and sw_temp is set to True
+            If present and dataset with 'thresh' and 'seas' also sw_cats is set to True
+       period: pandas Series
+           Absolute value of temperature along time index
+       blockLength: int, optional
+           Size of blocks in years (default=1)
+       mtime: str, optional
+           Name of mhw time variable to use to assign events to blocks, 
+           Options are start or peak times (default='time_start')
+       removeMissing: bool, optional
+           If True remove statistics for any blocks that has NaNs in ts.
+           Work in progress
+           (default is False)
+       split: bool, optional
+           Work in progress
+           (default is False)
+
+We are still working on the mhw_rank() function to calculate rank and
+return periods.