0.9.2-beta release (neuralhydrology#2)

- speed improvement in `Tester`, when merging date and time_step index
- renaming of `MultiFreqLSTM` into `MTSLSTM` (multi timescale `LSTM`)
- more documentation
- restructuring of data module into `neuralhydrolog.datasetzoo` and `neuralhydrology.datautils`
- GitHub workflow for sphinx build on PR

.github/workflows/docs-ci.yml

@@ -0,0 +1,25 @@
+name: "docs check"
+on: 
+  pull_request:
+    branches: 
+      - master
+      - public
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - uses: actions/setup-python@v2
+      with:
+        python-version: '3.8'
+    - name: Install pandoc
+      run: |
+        sudo apt-get update -y && sudo apt-get install -y pandoc
+    - name: Install dependencies
+      run: |
+        pip install sphinx sphinx-rtd-theme nbsphinx nbsphinx-link
+    - name: Build Sphinx docs
+      working-directory: docs/
+      run: |
+        make html

docs/source/api/neuralhydrology.data.basedataset.rst → docs/source/api/neuralhydrology.datasetzoo.basedataset.rst

@@ -1,7 +1,7 @@
 BaseDataset
 ===========
 
-.. automodule:: neuralhydrology.data.basedataset
+.. automodule:: neuralhydrology.datasetzoo.basedataset
    :members:
    :undoc-members:
    :show-inheritance:

docs/source/api/neuralhydrology.data.camelsgb.rst → docs/source/api/neuralhydrology.datasetzoo.camelsgb.rst

@@ -1,7 +1,7 @@
 CamelsGB
 ========
 
-.. automodule:: neuralhydrology.data.camelsgb
+.. automodule:: neuralhydrology.datasetzoo.camelsgb
    :members:
    :undoc-members:
    :show-inheritance:

docs/source/api/neuralhydrology.data.camelsus.rst → docs/source/api/neuralhydrology.datasetzoo.camelsus.rst

@@ -1,7 +1,7 @@
 CamelsUS
 ========
 
-.. automodule:: neuralhydrology.data.camelsus
+.. automodule:: neuralhydrology.datasetzoo.camelsus
    :members:
    :undoc-members:
    :show-inheritance:

docs/source/api/neuralhydrology.data.hourlycamelsus.rst → docs/source/api/neuralhydrology.datasetzoo.hourlycamelsus.rst

@@ -1,7 +1,7 @@
 HourlyCamelsUS
 ==============
 
-.. automodule:: neuralhydrology.data.hourlycamelsus
+.. automodule:: neuralhydrology.datasetzoo.hourlycamelsus
    :members:
    :undoc-members:
    :show-inheritance:

docs/source/api/neuralhydrology.datasetzoo.rst

@@ -0,0 +1,15 @@
+nh.datasetzoo
+=============
+
+.. automodule:: neuralhydrology.datasetzoo
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. toctree::
+   :maxdepth: 4
+
+   neuralhydrology.datasetzoo.basedataset
+   neuralhydrology.datasetzoo.camelsus
+   neuralhydrology.datasetzoo.hourlycamelsus
+   neuralhydrology.datasetzoo.camelsgb

docs/source/api/neuralhydrology.data.climateindices.rst → docs/source/api/neuralhydrology.datautils.climateindices.rst

@@ -1,7 +1,7 @@
 climateindices
 ==============
 
-.. automodule:: neuralhydrology.data.climateindices
+.. automodule:: neuralhydrology.datautils.climateindices
    :members:
    :undoc-members:
    :show-inheritance:

docs/source/api/neuralhydrology.data.dischargeinput.rst → docs/source/api/neuralhydrology.datautils.dischargeinput.rst

@@ -1,7 +1,7 @@
 dischargeinput
 ==============
 
-.. automodule:: neuralhydrology.data.dischargeinput
+.. automodule:: neuralhydrology.datautils.dischargeinput
    :members:
    :undoc-members:
    :show-inheritance:

docs/source/api/neuralhydrology.data.pet.rst → docs/source/api/neuralhydrology.datautils.pet.rst

@@ -1,7 +1,7 @@
 pet
 ===
 
-.. automodule:: neuralhydrology.data.pet
+.. automodule:: neuralhydrology.datautils.pet
    :members:
    :undoc-members:
    :show-inheritance:

docs/source/api/neuralhydrology.datautils.rst

@@ -0,0 +1,15 @@
+nh.datautils
+============
+
+.. automodule:: neuralhydrology.datautils
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. toctree::
+   :maxdepth: 4
+
+   neuralhydrology.datautils.climateindices
+   neuralhydrology.datautils.dischargeinput
+   neuralhydrology.datautils.pet
+   neuralhydrology.datautils.utils

docs/source/api/neuralhydrology.data.utils.rst → docs/source/api/neuralhydrology.datautils.utils.rst

@@ -1,7 +1,7 @@
 utils
 =====
 
-.. automodule:: neuralhydrology.data.utils
+.. automodule:: neuralhydrology.datautils.utils
    :members:
    :undoc-members:
    :show-inheritance:

docs/source/api/neuralhydrology.data.caravan.rst → docs/source/api/neuralhydrology.modelzoo.mtslstm.rst

@@ -1,7 +1,7 @@
-Caravan
+MTSLSTM
 =======
 
-.. automodule:: neuralhydrology.data.caravan
+.. automodule:: neuralhydrology.modelzoo.mtslstm
    :members:
    :undoc-members:
    :show-inheritance:

docs/source/api/neuralhydrology.modelzoo.rst

@@ -16,6 +16,6 @@ nh.modelzoo
    neuralhydrology.modelzoo.fc
    neuralhydrology.modelzoo.head
    neuralhydrology.modelzoo.lstm
-   neuralhydrology.modelzoo.multifreqlstm
+   neuralhydrology.modelzoo.mtslstm
    neuralhydrology.modelzoo.odelstm
    neuralhydrology.modelzoo.template

docs/source/api/neuralhydrology.rst

@@ -10,7 +10,8 @@ neuralhydrology API
 .. toctree::
    :maxdepth: 4
 
-   neuralhydrology.data
+   neuralhydrology.datasetzoo
+   neuralhydrology.datautils
    neuralhydrology.evaluation
    neuralhydrology.modelzoo
    neuralhydrology.training

docs/source/usage/models.rst

@@ -39,14 +39,14 @@ activations for all time steps. This class is implemented for exploratory reason
 ``model.copy_weights()`` to copy the weights of a ``CudaLSTM`` model into an ``LSTM`` model. This allows to use the fast
 CUDA implementation for training, and only use this class for inference with more detailed outputs.
 
-MultiFreqLSTM
--------------
-:py:class:`neuralhydrology.modelzoo.multifreqlstm.MultiFreqLSTM` is a newly proposed model by Gauch et al. (pre-print
-published soon). This model allows the training on more than one temporal frequency (e.g. daily and hourly inputs) and
-returns multi-frequency model predictions accordingly. A more detailed tutorial will follow shortly.
+MTS-LSTM
+--------
+:py:class:`neuralhydrology.modelzoo.mtslstm.MTSLSTM` is a newly proposed model by Gauch et al. (pre-print
+published soon). This model allows the training on more than temporal resolution (e.g. daily and hourly inputs) and
+returns multi-timescale model predictions accordingly. A more detailed tutorial will follow shortly.
 
-ODELSTM
--------
+ODE-LSTM
+--------
 :py:class:`neuralhydrology.modelzoo.odelstm.ODELSTM` is a PyTorch implementation of the ODE-LSTM proposed by
 `Lechner and Hasani <https://arxiv.org/abs/2006.04418>`_. This model can be used with unevenly sampled inputs and can
 be queried to return predictions for any arbitrary time step.

examples/01-Introduction/1_basin.yml

@@ -35,7 +35,7 @@ metrics:
 
 # --- Model configuration --------------------------------------------------------------------------
 
-# base model type [lstm, ealstm, cudalstm, embcudalstm, multifreqlstm]
+# base model type [lstm, ealstm, cudalstm, embcudalstm, mtslstm]
 # (has to match the if statement in modelzoo/__init__.py)
 model: cudalstm
 

examples/config.yml.example

@@ -52,7 +52,7 @@ metrics:
 
 # --- Model configuration --------------------------------------------------------------------------
 
-# base model type [lstm, ealstm, cudalstm, embcudalstm, multifreqlstm]
+# base model type [lstm, ealstm, cudalstm, embcudalstm, mtslstm]
 # (has to match the if statement in modelzoo/__init__.py)
 model: cudalstm
 
@@ -79,13 +79,13 @@ embedding_activation: tanh
 # dropout applied to embedding network
 embedding_dropout: 0.0
 
-# ----> MultiFreqLSTM settings <----
+# ----> MTSLSTM settings <----
 
 # Use an individual LSTM per frequencies (True) vs. use a single shared LSTM for all frequencies (False)
-per_frequency_lstm: True
+shared_mtslstm: True
 
 # how to transfer states from lower to higher frequencies. One of [identity, linear, None].
-transfer_multifreq_states:
+transfer_mtslstm_states:
     h: identity
     c: identity
 

neuralhydrology/__about__.py

@@ -1 +1 @@
-__version__ = "0.9.1-beta"
+__version__ = "0.9.2-beta"