Merge pull request #1 from umr-lops/add_production_description_doc

add a Product Description for  Ifremer Sentinel-1 Level-2 WAVE

.gitignore

@@ -127,3 +127,6 @@ dmypy.json
 
 # Pyre type checker
 .pyre/
+
+.idea
+localconfig.yaml

AUTHORS.rst

@@ -6,6 +6,7 @@ Development Lead
 ----------------
 
 * Antoine Grouazel <[email protected]>
+* Robin Marquart <[email protected]>
 
 Contributors
 ------------

CONTRIBUTING.rst

@@ -15,7 +15,7 @@ Types of Contributions
 Report Bugs
 ~~~~~~~~~~~
 
-Report bugs at https://github.com/agrouaze/sarwaveifrproc/issues.
+Report bugs at https://github.com/umr-lops/sarwaveifrproc/issues.
 
 If you are reporting a bug, please include:
 
@@ -45,7 +45,7 @@ articles, and such.
 Submit Feedback
 ~~~~~~~~~~~~~~~
 
-The best way to send feedback is to file an issue at https://github.com/agrouaze/sarwaveifrproc/issues.
+The best way to send feedback is to file an issue at https://github.com/umr-lops/sarwaveifrproc/issues.
 
 If you are proposing a feature:
 
@@ -103,7 +103,7 @@ Before you submit a pull request, check that it meets these guidelines:
    your new functionality into a function with a docstring, and add the
    feature to the list in README.rst.
 3. The pull request should work for Python 3.5, 3.6, 3.7 and 3.8, and for PyPy. Check
-   https://travis-ci.com/agrouaze/sarwaveifrproc/pull_requests
+   https://travis-ci.com/umr-lops/sarwaveifrproc/pull_requests
    and make sure that the tests pass for all supported Python versions.
 
 Tips

README.rst

@@ -20,7 +20,7 @@ sarwaveifrproc
 
 
 
-SAR sea state Ifremer processor
+SAR Sentinel-1 ESA mission sea state Ifremer processor
 
 
 * Free software: MIT license
@@ -30,7 +30,11 @@ SAR sea state Ifremer processor
 Features
 --------
 
-* TODO
+ * predicts sea state geophysical quantities from Level-1B or Level-1C Ifremer SARWAVE Sentinel-1 (WV,IW,EW) products using empirical function learnt on numerical hindcasts (WAVEWATCH III):
+  - significant wave height (`Hs`)
+  - mean wave period (`t0m1`)
+  - significant wave height of the wind-sea (`pshs0`)
+ * save results in a netCDF file per sub-swath.
 
 Credits
 -------

docs/_static/css/sarwaveifrproc.css

@@ -0,0 +1,9 @@
+@import url("theme.css");
+
+.wy-nav-content {
+	max-width: 1000px !important;
+}
+dl.py.property {
+	display: block !important;
+}
+

docs/atbd.rst

@@ -0,0 +1,26 @@
+.. _atbd:
+
+Algorithm Description
+#####################
+
+This page stands as the Algorithm Technical Baseline Description (A.T.B.D.) for Ifremer Sentinel-1 SAR Level-2 WAV product.
+
+.. image:: ./figures/sar_cross_spectrum.png
+  :alt: cross spectrum
+  :scale: 50 %
+  :name: cross spectrum
+  :align: center
+
+
+.. image:: ./figures/ATBD_coarse_idea.png
+  :alt: from cross spectrum to sea state parameters
+  :scale: 50 %
+  :name: from cross spectrum to sea state parameters
+  :align: center
+
+Data used as input is described in :cite:t:`topsar` and :cite:t:`level1sar`.
+The algorithm is based on previous works: :cite:t:`hasselmann1991nonlinear`, :cite:t:`garello2001wave`
+but also :cite:t:`krogstad1992simple`,  :cite:t:`li2010ocean` :cite:t:`li2019new`
+It is a algorithm that could be compared to: :cite:t:`pleskachevsky2019estimation`, :cite:t:`PleskachevskyEtAlIJRS2019` :cite:t:`pleskachevsky2022multiparametric` applied to GRD SAR images.
+Inputs features are derived following methodology described in :cite:t:`schulz2007empirical`.
+Previous works on WV have been published in stopa2017significant , :cite:t:`QuachEtAlIEEETGRS2021`

docs/bibliography.rst

@@ -0,0 +1,6 @@
+************
+Bibliography
+************
+
+.. bibliography:: refs.bib
+  :style: unsrt

docs/conf.py

@@ -31,7 +31,9 @@
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode',
+'sphinxcontrib.bibtex'
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -64,7 +66,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -95,7 +97,7 @@
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
-
+# html_style = 'css/sarwaveifrproc.css'
 
 # -- Options for HTMLHelp output ---------------------------------------
 
@@ -157,6 +159,7 @@
      'One line description of project.',
      'Miscellaneous'),
 ]
-
+bibtex_bibfiles = ["./refs.bib"]
+bibtex_reference_style = 'author_year'
 
 

docs/index.rst

@@ -1,5 +1,11 @@
 Welcome to sarwaveifrproc's documentation!
-======================================
+==========================================
+
+.. image:: ./figures/cover.png
+  :alt: cover
+  :scale: 100 %
+  :name: cover
+  :align: center
 
 .. toctree::
    :maxdepth: 2
@@ -8,6 +14,9 @@ Welcome to sarwaveifrproc's documentation!
    readme
    installation
    usage
+   product_description
+   atbd
+   bibliography
    modules
    contributing
    authors

docs/installation.rst

@@ -1,19 +1,23 @@
 .. highlight:: shell
 
-============
+############
 Installation
-============
+############
 
 
 Stable release
 --------------
 
-To install sarwaveifrproc, run this command in your terminal:
+To install **sarwaveifrproc**, run this command in your terminal:
 
 .. code-block:: console
 
     $ pip install sarwaveifrproc
 
+.. code-block:: console
+
+    $ micromamba install -c conda-forge sarwaveifrproc
+
 This is the preferred method to install sarwaveifrproc, as it will always install the most recent stable release.
 
 If you don't have `pip`_ installed, this `Python installation guide`_ can guide
@@ -32,13 +36,13 @@ You can either clone the public repository:
 
 .. code-block:: console
 
-    $ git clone git://github.com/agrouaze/sarwaveifrproc
+    $ git clone git://github.com/umr-lops/sarwaveifrproc
 
 Or download the `tarball`_:
 
 .. code-block:: console
 
-    $ curl -OJL https://github.com/agrouaze/sarwaveifrproc/tarball/master
+    $ curl -OJL https://github.com/umr-lops/sarwaveifrproc/tarball/master
 
 Once you have a copy of the source, you can install it with:
 
@@ -47,5 +51,10 @@ Once you have a copy of the source, you can install it with:
     $ python setup.py install
 
 
-.. _Github repo: https://github.com/agrouaze/sarwaveifrproc
-.. _tarball: https://github.com/agrouaze/sarwaveifrproc/tarball/master
+.. _Github repo: https://github.com/umr-lops/sarwaveifrproc
+.. _tarball: https://github.com/umr-lops/sarwaveifrproc/tarball/master
+
+
+.. raw:: latex
+
+    \newpage

docs/modules.rst

@@ -0,0 +1,19 @@
+########
+Modules
+########
+
+..
+    to document functions, add them to __all__ in ../sarwaveifrproc/__init__.py
+
+.. automodule:: sarwaveifrproc
+    :members:
+
+
+.. automodule:: sarwaveifrproc.utils
+    :members:
+
+.. automodule:: sarwaveifrproc.l2_wave
+     :members:
+
+.. automodule:: sarwaveifrproc.main
+     :members:

docs/product_description.rst

@@ -0,0 +1,148 @@
+.. _productdescription:
+
+Ifremer SARWAVE Level-2 WAV Product Description
+###############################################
+
+This page serves as the Product Description document for the **Sentinel-1 SARWAVE Level-2 WAV** product developed by Ifremer.
+It outlines the filename structure, product organization, format, and content of the Level-2 SARWAVE product.
+
+Product Philosophy
+------------------
+
+The organization of the SARWAVE product follows the ESA Level-1 SLC and SARWAVE Level-1B approach but contains geophysical parameter as the main information.
+Each Level-1 SLC product corresponds to one Level-2 product, and each subswath is processed independently.
+Within each subswath, geophysical information is retrieved on two different grids to optimize the information extracted from the Level-1 SLC product.
+
+The geophysical parameters are thus retrieved on these two grids with the same resolution and sampling.
+The main difference with respect to Level-1 SLC or Level-1B products is that at Level-2 stage, the concept of polarization channel does not exist anymore - indeed the two polarization channels can be combined together to produce a given geophysical quantity.
+
+The variables are always the same from a product to another independently of the land flag value.
+The number of files (ie subswath) per SAFE is always the same from a product to another independently of the land flag value.
+The geophysical variables on land are filled with NaN (fill-values) while "radar" variables are always defined with meaningful values.
+A slice completely on land would be produced even if it contains only fill-values.
+
+
+Product naming conventions
+--------------------------
+
+SAFE naming convention
+~~~~~~~~~~~~~~~~~~~~~~
+
+Each product is stored in a .SAFE directory. The SAFE convention is inherited from Sentinel-1 mission and in particular from the Level-1 SLC. The SLC (single look complex) acronym has been replaced by WAV (for waves as the main goal of the product is to provide sea state parameters).
+
+Each .SAFE directory contains only netCDF files.
+
+There is one SAFE file per slice and one .nc file per sub-swath.
+
+There are 3 netCDF files for IW and 5 for EW. For WV there are as many netCDF files are measurement in the Level-1 SLC product.
+
+The netCDF naming convention is also very close to the ESA convention for the naming of the measurement files including in the Level-1 SLC .SAFE directories.
+
+An example of L2 WAV filename is
+
+.. code-block::
+
+    S1A_IW_WAV__2SDV_20231103T063230_20231103T063257_051049_0627C3_C45D_E00.SAFE
+
+, where :math:`E00` define a product version, it means: a processor version + options of processing
+
+measurement naming convention
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+An example of L2 WAV measurement filename is
+
+.. code-block::
+
+    l2-s1a-iw1-wav-dv-20231103t063230-20231103t063255-051049-0627c3-e00.nc
+
+where :math:`l2` gives the processing level, :math:`wav` describe the product family; :math:`dv` the polarization configuration for the acquisition (independently of how the channels are used in the file itself).
+:math:`e00` is a product version, it means: a processor version + options of processing. The same are the one given at the end of the SAFE name.
+
+
+
+Product organisation
+--------------------
+
+For a specific slice and subswath, the two grids (defined during the processing of Level-1 SLC products into Level-1B products) on which are retrieved the Level-2 geophysical parameters are:
+
+
+     - **intraburst** grid is defined by a set of tiles within each burst. Several looks are then extracted, and associated cross-spectra are computed from these looks. The maximum tile size is approximately 17 by 17 km, depending on the processing parameters.
+     - **interburst** grid is defined by a set of tiles that match the overlapping area between two adjacent bursts. The signals from these two bursts are then used as two different looks to compute cross-spectra. The maximum tile size is about 2 km (azimuth) by 17 km (range), depending on the processing parameters.
+
+Figure \ref{fig:level2_variables_grids} illustrates the two grids for a set of 10 consecutive Level-2 products.
+Geopĥysical parameters are estimated independently for all tiles on the two grids
+
+
+.. image:: ./figures/level2_variables_grids.png
+  :alt: level2_variables_grids
+  :scale: 70 %
+  :name: level2_variables_grids
+  :align: center
+
+Information related to these two grids are stored into two different groups : \textbf{intraburst} and \textbf{interburst} groups. Each group is defined by a specific set of attributes and variables.
+
+intraburst group
+~~~~~~~~~~~~~~~~
+
+.. image:: ./figures/coordinates_intra.png
+  :alt: coords
+  :scale: 100 %
+  :name: coords
+  :align: center
+
+Attributes
+==========
+
+.. image:: ./figures/attrs_intra.png
+  :alt: aintra
+  :scale: 100 %
+  :name: aintra
+  :align: center
+
+Variables
+=========
+
+.. image:: ./figures/variables_intra.png
+  :alt: vintra
+  :scale: 100 %
+  :name: vintra
+  :align: center
+
+intraburst group
+~~~~~~~~~~~~~~~~
+
+.. image:: ./figures/coordinates.png
+  :alt: coordsinter
+  :scale: 100 %
+  :name: coordsinter
+  :align: center
+
+Attributes
+==========
+
+.. image:: ./figures/attrs_intra.png
+  :alt: ainter
+  :scale: 100 %
+  :name: ainter
+  :align: center
+
+Variables
+=========
+
+.. image:: ./figures/variables_inter.png
+  :alt: vinter
+  :scale: 100 %
+  :name: vinter
+  :align: center
+
+Product access
+--------------
+
+Currently the Level-2 SARWAVE Sentinel-1 product is disseminated from this URL:
+
+https://cerweb.ifremer.fr/datarmor/sarwave/diffusion/sar/iw/slc/l2/
+
+Acknowledgment
+--------------
+
+The Sentinel-1 Level-2 SARWAVE Product has been developed by Ifremer. This work is co-funded by ESA through the SARWAVE project (https://www.sarwave.org/).
+The processor development benefits from support and contributions from Sentinel-1 Mission Performance Cluster team (https://sar-mpc.eu/about/activities-and-team/).