Merge pull request #369 from simonpf/qrnn_update

Extensions of QRNN code.

doc/typhon.retrieval.bmci.rst

@@ -0,0 +1,11 @@
+Bayesian Monte Carlo Integration (BMCI)
+=======================================
+
+.. automodule:: typhon.retrieval.bmci
+
+.. currentmodule:: typhon.retrieval.bmci
+
+.. autosummary::
+   :toctree: generated
+
+   BMCI

doc/typhon.retrieval.mcmc.rst

@@ -0,0 +1,11 @@
+Markov-Chain Monte Carlo (MCMC)
+===============================
+
+.. automodule:: typhon.retrieval.mcmc
+
+.. currentmodule:: typhon.retrieval.mcmc
+
+.. autosummary::
+   :toctree: generated
+
+   MCMC

doc/typhon.retrieval.oem.rst

@@ -0,0 +1,15 @@
+Optimal estimation method (OEM)
+===============================
+
+.. automodule:: typhon.retrieval.oem
+
+.. currentmodule:: typhon.retrieval.oem
+
+.. autosummary::
+   :toctree: generated
+
+   error_covariance_matrix
+   averaging_kernel_matrix
+   retrieval_gain_matrix
+   smoothing_error
+   retrieval_noise

doc/typhon.retrieval.qrnn.rst

@@ -0,0 +1,73 @@
+Quantile regression neural networks (QRNNs)
+===========================================
+
+An implementation of quantile regression neural networks (QRNNs) developed
+specifically for remote sensing applications providing a flexible
+interface for simple training and evaluation of QRNNs.
+
+Overview
+--------
+
+The QRNN implementation consists of two-layers:
+
+  - A high-level interface provided by the :py:class:`~typhon.retrieval.qrnn.QRNN`
+    class
+  - Backend-specific implementations of different neural network architectures
+    to be used as models by the high-level implementation
+
+
+The QRNN class
+--------------
+
+The :py:class:`~typhon.retrieval.qrnn.QRNN` class provides the high-level
+interface for QRNNs. This is all that is required to train a plain,
+fully-connected QRNN. The class itself implments generic functionality related
+to the evaluation of QRNNs and the post processing of results such as computing
+the PSD or the posterior mean. For the rest it acts as a wrapper around its
+model attribute, which encapsules all network- and DL-framework-specific code.
+
+Backends
+--------
+
+Currently both `keras <https://keras.io/>`_ and `pytorch <https://pytorch.org/>`_
+are supported as backends for neural networks. The QRNN implementation will
+automatically use the one that is available on your system. If both are available
+you can choose a specific backend using the :py:meth:`~typhon.retrieval.qrnn.set_backend` function.
+
+Neural network models
+---------------------
+
+The :py:class:`typhon.retrieva.qrnn.QRNN` has designed to work with any generic
+regression neural network model. This aim of this was to make the implementation
+sufficiently flexible to allow special network architectures or customization of
+the training process.
+
+This gives the user the flexibility to design custom NN models in pytorch
+or Keras and use them with the ``QRNN`` class. Some predefined architectures
+are defined in the :py:mod:`typhon.retrieval.qrnn.models` submodule.
+
+API documentation
+-----------------
+
+.. automodule:: typhon.retrieval.qrnn.qrnn
+.. currentmodule:: typhon.retrieval.qrnn.qrnn
+.. autosummary::
+   :toctree: generated
+
+   QRNN
+
+.. automodule:: typhon.retrieval.qrnn.models.pytorch
+.. currentmodule:: typhon.retrieval.qrnn.models.pytorch
+.. autosummary::
+   :toctree: generated
+
+   FullyConnected
+   UNet
+
+.. automodule:: typhon.retrieval.qrnn.models.keras
+.. currentmodule:: typhon.retrieval.qrnn.models.keras
+.. autosummary::
+   :toctree: generated
+
+   FullyConnected
+

doc/typhon.retrieval.rst

@@ -1,87 +1,29 @@
-retrieval
-=========
+The retrieval submodule contains implementations of different retrieval methods
+as well as functions for the assessment of their performance.
 
-.. automodule:: typhon.retrieval
-.. currentmodule:: typhon.retrieval
+Retrieval methods
+=================
 
-.. autosummary::
-   :toctree: generated
+.. toctree::
+   :maxdepth: 1
 
-retrieval.bmci
-==============
+   typhon.retrieval.bmci
+   typhon.retrieval.mcmc
+   typhon.retrieval.qrnn
+   typhon.retrieval.oem
 
-.. automodule:: typhon.retrieval.bmci
-
-.. currentmodule:: typhon.retrieval.bmci
-
-.. autosummary::
-   :toctree: generated
-
-   BMCI
-
-retrieval.mcmc
-==============
-
-.. automodule:: typhon.retrieval.mcmc
-
-.. currentmodule:: typhon.retrieval.mcmc
-
-.. autosummary::
-   :toctree: generated
-
-   MCMC
-
-retrieval.oem
-=============
-
-.. automodule:: typhon.retrieval.oem
-
-.. currentmodule:: typhon.retrieval.oem
-
-.. autosummary::
-   :toctree: generated
-
-   error_covariance_matrix
-   averaging_kernel_matrix
-   retrieval_gain_matrix
-   smoothing_error
-   retrieval_noise
-
-retrieval.qrnn
-==============
-
-.. automodule:: typhon.retrieval.qrnn
-
-.. currentmodule:: typhon.retrieval.qrnn
-
-.. autosummary::
-   :toctree: generated
-
-   QRNN
-
-retrieval.scores
-================
-
-.. automodule:: typhon.retrieval.scores
+Retrieval products
+==================
 
-.. currentmodule:: typhon.retrieval.scores
+.. toctree::
+   :maxdepth: 1
 
-.. autosummary::
-   :toctree: generated
+   typhon.retrieval.spareice
 
-    mape
-    bias
-    quantile_score
-    mean_quantile_score
 
-retrieval.spareice
+Utility functions
 ==================
+.. toctree::
+   :maxdepth: 1
 
-.. automodule:: typhon.retrieval.spareice
-
-.. currentmodule:: typhon.retrieval.spareice
-
-.. autosummary::
-   :toctree: generated
-
-   SPAREICE
+   typhon.retrieval.scores

doc/typhon.retrieval.scores.rst

@@ -0,0 +1,14 @@
+Retrieval scores
+================
+
+.. automodule:: typhon.retrieval.scores
+
+.. currentmodule:: typhon.retrieval.scores
+
+.. autosummary::
+   :toctree: generated
+
+    mape
+    bias
+    quantile_score
+    mean_quantile_score

doc/typhon.retrieval.spareice.rst

@@ -0,0 +1,11 @@
+SpareIce
+========
+
+.. automodule:: typhon.retrieval.spareice
+
+.. currentmodule:: typhon.retrieval.spareice
+
+.. autosummary::
+   :toctree: generated
+
+   SPAREICE

typhon/retrieval/qrnn/__init__.py

@@ -1,7 +1,7 @@
 r"""
-An implementation of quantile regression neural networks based on the
-`Keras <https://github.com/keras-team/keras>` deep learning package.
-The implementation has been developed specifically for remote sensing
-applications and provides a high level interface allowing for simple
-training and evaluation of the QRNNs."""
-from typhon.retrieval.qrnn.qrnn import QRNN
+Quantile regression neural networks (QRNNs)
+
+The module provides a flexible implementation of QRNNs for remote sensing
+retrievals.
+"""
+from typhon.retrieval.qrnn.qrnn import QRNN, set_backend, get_backend