Merge pull request #162 from DassHydro/enh-read-input-data

ENH: Update the reading of geo-referenced input data

doc/source/release/1.0.0-notes.rst

@@ -145,7 +145,7 @@ Below is the table of equivalence between the two versions:
     * - ``gr-a``
       - No equivalence
     * - ``gr-b``
-      - ``zero`` - ``gr4`` - ``lr``
+      - No equivalence
     * - ``gr-c``
       - No equivalence
     * - ``gr-d``
@@ -161,6 +161,25 @@ file is clipped by taking as its maximum extension the number of cells required
 rectangular catchment one cell wide. In this way, it is possible to create a mesh of a French catchment using
 worldwide flow direction.
 
+Reading of atmospheric and physiograhic data
+********************************************
+
+The reading of geo-referenced data (i.e. precipitation, snow, descriptor, etc) has been improved to manage:
+
+- ``Resolution missmatch``
+    Nearest-Neighbour resample algorithm is used to match the resolution of the data and the resolution of the
+    mesh.
+
+- ``Overlap missmatch``
+    The reading window is correctly shifted to overlap the data and the mesh on the nearest overlapping cell.
+
+- ``Out Of Bound``
+    In the previous version, when the mesh extent was larger than the data extent a not a very informative
+    error was returned. It is now possible to read data whose extent partially include the mesh extent. The
+    corresponding out of bound extent will be filled in with no data.
+
+A warning is returned if one of the 3 cases below is encountered when reading the data.
+
 Mean atmospheric data
 *********************
 
@@ -334,7 +353,10 @@ The precipitation partitioning can be selected using the ``prcp_partitioning`` s
 New hydrological modules
 ************************
 
-3 new hydrological modules have been introduced:
+4 new hydrological modules have been introduced:
+
+- ``gr4``
+    This hydrological module is derived from the GR4 model :cite:p:`perrin2003improvement`.
 
 - ``gr5``
     This hydrological module is derived from the GR5 model :cite:p:`LeMoine_2008`.

doc/source/user_guide/others/input_data_convention.rst

@@ -5,15 +5,39 @@ Input Data Convention
 =====================
 
 The aim of this section is to describe the conventions that apply to all input data used in `smash`
-(i.e. precipitation, observed discharge, descriptor, etc)
+(i.e. observed discharge, precipitation, descriptor, etc)
+
+Observed discharge
+------------------
+
+The observed discharge for one catchment is read from a ``.csv`` file with the following structure: 
+
+.. csv-table:: V3524010.csv
+    :align: center
+    :header: "200601010000"
+    :width: 50
+
+    -99.000
+    -99.000
+    ...
+    1.180
+    1.185
+
+It is a single-column ``.csv`` file containing the observed discharge values in m\ :sup:`3` \/s (negative values in the series will be interpreted 
+as no-data) and whose header is the first time step of the chronicle. The name of the file, for any catchment, must contains the code of the 
+gauge which is filled in the ``mesh`` (see the `smash.factory.generate_mesh` method).
+
+.. note::
+    The time step of the header does not have to match the first simulation time step. `smash` manages to read the corresponding lines 
+    from the ``setup`` variables, ``start_time``, ``end_time`` and ``dt``.
+
 
 Precipitation
 -------------
 
 The precipitation files must be stored for each time step of the simulation in ``tif`` format. For one time step, `smash` will recursively 
 search in the ``prcp_directory``, a file with the following name structure: ``*%Y%m%d%H%M*.tif`` (``*`` means that we can match any character).
-An example of file name in tif format for the date 2014-09-15 00:00: ``prcp_201409150000.tif``. The spatial resolution and the projection 
-between the precipitation files and the flow direction file must be **identical**.
+An example of file name in tif format for the date 2014-09-15 00:00: ``prcp_201409150000.tif``.
 
 .. note::
     ``%Y%m%d%H%M`` is a unique key, the ``prcp_directory`` (and all subdirectories) can not contains files with similar dates.
@@ -23,8 +47,7 @@ Potential evapotranspiration
 
 The potential evapotranspiration files must be stored for each each time step of the simulation in ``tif`` format. For one time step, `smash` 
 will recursively search in the ``pet_directory``, a file with the following name structure: ``*%Y%m%d%H%M*.tif`` (``*`` means that we can match any character).
-An example of file name in tif format for the date 2014-09-15 00:00: ``pet_201409150000.tif``. The spatial resolution and the projection 
-between the potential evapotranspiration files and the flow direction file must be **identical**.
+An example of file name in tif format for the date 2014-09-15 00:00: ``pet_201409150000.tif``.
 
 .. note::
     ``%Y%m%d%H%M`` is a unique key, the ``pet_directory`` (and all subdirectories) can not contains files with similar dates.
@@ -43,8 +66,7 @@ Snow
 
 The snow files must be stored for each time step of the simulation in ``tif`` format. For one time step, `smash` will recursively 
 search in the ``snow_directory``, a file with the following name structure: ``*%Y%m%d%H%M*.tif`` (``*`` means that we can match any character).
-An example of file name in tif format for the date 2014-09-15 00:00: ``snow_201409150000.tif``. The spatial resolution and the projection 
-between the snow files and the flow direction file must be **identical**.
+An example of file name in tif format for the date 2014-09-15 00:00: ``snow_201409150000.tif``.
 
 .. note::
     ``%Y%m%d%H%M`` is a unique key, the ``snow_directory`` (and all subdirectories) can not contains files with similar dates.
@@ -54,48 +76,40 @@ Temperature
 
 The temperature files must be stored for each time step of the simulation in ``tif`` format. For one time step, `smash` will recursively 
 search in the ``temp_directory``, a file with the following name structure: ``*%Y%m%d%H%M*.tif`` (``*`` means that we can match any character).
-An example of file name in tif format for the date 2014-09-15 00:00: ``temp_201409150000.tif``. The spatial resolution and the projection 
-between the temperature files and the flow direction file must be **identical**.
+An example of file name in tif format for the date 2014-09-15 00:00: ``temp_201409150000.tif``.
 
 .. note::
     ``%Y%m%d%H%M`` is a unique key, the ``temp_directory`` (and all subdirectories) can not contains files with similar dates.
 
-Observed discharge
-------------------
-
-The observed discharge for one catchment is read from a ``.csv`` file with the following structure: 
-
-.. csv-table:: V3524010.csv
-    :align: center
-    :header: "200601010000"
-    :width: 50
-
-    -99.000
-    -99.000
-    ...
-    1.180
-    1.185
-
-It is a single-column ``.csv`` file containing the observed discharge values in m\ :sup:`3` \/s (negative values in the series will be interpreted 
-as no-data) and whose header is the first time step of the chronicle. The name of the file, for any catchment, must contains the code of the 
-gauge which is filled in the ``mesh`` (see the `smash.factory.generate_mesh` method).
-
-.. note::
-    The time step of the header does not have to match the first simulation time step. `smash` manages to read the corresponding lines 
-    from the ``setup`` variables, ``start_time``, ``end_time`` and ``dt``.
-
 Descriptor
 ----------
 
 The catchment descriptors files must be stored in ``tif`` format. For each descriptor name filled in the setup argument ``descriptor_name``,
 `smash` will recursively search in the ``descriptor_directory``, a file with the following name structure: ``descriptor_name.tif``.
-An example of file name in tif format for the slope descriptor: ``slope.tif``. The spatial resolution and the projection 
-between the decriptor files and the flow direction file must be **identical**.
+An example of file name in tif format for the slope descriptor: ``slope.tif``.
 
 .. note::
-
     ``descriptor_name`` is a unique key, the ``descriptor_directory`` (and all subdirectories) can not contains files with similar decriptor name.
 
+.. warning::
+    There are 4 possible warnings when reading geo-referenced data (i.e. precipitation, descriptor, etc):
+
+    - ``Missing Warning``
+        A file (or more) is missing. It will be interpreted as no data.
+
+    - ``Resolution Warning``
+        A file (or more) has a spatial resolution different from the mesh resolution (i.e. the flow direction resolution).
+        It will be resampled using a Nearest Neighbour algorithm.
+
+    - ``Overlap Warning``
+        A file (or more) has an origin that does not overlap with the mesh origin (i.e. the flow direction origin).
+        The reading window is shifted towards the nearest overlapping cell.
+
+    - ``Out Of Bound Warning``
+        A file (or more) has an extent that does not include, partially or totally, the mesh extent.
+        It will be interpreted as no data where the mesh extent is out of bound.
+
+
 Directory structure
 -------------------