SatCloP · slarosa · Feb 24, 2024 · Nov 27, 2023 · Dec 6, 2023 · Dec 6, 2023
diff --git a/CITATION.cff b/CITATION.cff
@@ -1,4 +1,4 @@
-title: "PyRTlib: A python package for non-scattering line-by-line microwave Radiative Transfer simulations."
+title: "PyRTlib: a python package for non-scattering line-by-line microwave Radiative Transfer simulations."
 abstract: 
   "PyRTlib is an attractive educational software to simulate observations from ground-based, 
   airborne, and satellite microwave sensors. It provides a flexible and user-friendly tool to broadly 
@@ -26,14 +26,14 @@ authors:
 - family-names: "Romano"
   given-names: "Filomena"
   orcid: "https://orcid.org/0000-0002-0544-073X"
-version: 1.0.3
+version: 1.0.4
 license: GPL-3.0
 keywords:
   - atmospheric-modelling
   - microwave
   - radiative-transfer-models
   - python
 doi: 10.5281/zenodo.8219145
-date-released: 2023-10-05
+date-released: 2023-12-06
 repository-code: "https://github.com/SatCloP/pyrtlib"
 url: "https://satclop.github.io/pyrtlib/"
diff --git a/README.md b/README.md
@@ -95,8 +95,10 @@ Execute model by computing upwelling radiances:
 ```
 
 ## Cite as
-Please cite us: 
 
 Larosa, S., Cimini, D., Gallucci, D., Nilo, S. T., and Romano, F.: PyRTlib: an educational Python-based library for non-scattering atmospheric microwave Radiative Transfer computations, Geosci. Model Dev. Discuss. (preprint), https://doi.org/10.5194/gmd-2023-171, in review, 2023.
 
-Larosa, S., Cimini, D., Gallucci, D., Nilo, S. T., & Romano, F. (2023). PyRTlib: A python package for non-scattering line-by-line microwave Radiative Transfer simulations. (Computer software). https://doi.org/10.5281/zenodo.8219145
+Larosa, S., Cimini, D., Gallucci, D., Nilo, S. T., & Romano, F. (2023). PyRTlib: a python package for non-scattering line-by-line microwave Radiative Transfer simulations. (Computer software). https://doi.org/10.5281/zenodo.8219145
+
+## Contributors
+<a href="https://github.com/SatCloP/pyrtlib/graphs/contributors"><img align="" src="https://contrib.rocks/image?repo=SatCloP/pyrtlib"></a>
diff --git a/docs/build-docs.sh b/docs/build-docs.sh
@@ -5,9 +5,9 @@ set -x
 ###################
 
 sudo apt-get update
-sudo apt-get -y install git rsync python3-sphinx python3-git python3-pip python3-virtualenv python3-setuptools pandoc zlib1g-dev
-python3 -m pip install --upgrade rinohtype pygments
-pip3 install pydata-sphinx-theme==0.13.3 sphinx-toggleprompt nbconvert==5.6.1 nbsphinx sphinx-gallery sphinx-copybutton ipython_genutils sphinx-toggleprompt sphinx-panels pandas scipy scikit-learn netcdf4 matplotlib
+sudo apt-get -y install git rsync python3-git python3-pip python3-virtualenv python3-setuptools pandoc zlib1g-dev # python3-sphinx
+python3 -m pip install --upgrade pygments #rinohtype[PDF] #sphinxcontrib-bibtex
+pip3 install sphinx==5.3.0 pydata-sphinx-theme sphinx-toggleprompt nbconvert==5.6.1 nbsphinx sphinx-gallery sphinx-copybutton ipython_genutils sphinx-toggleprompt sphinx_design pandas scipy scikit-learn netcdf4 matplotlib jupyter_client ipykernel
 
 #####################
 # DECLARE VARIABLES #

diff --git a/docs/script_examples/plot_brightness_temperature_wO3.py b/docs/script_examples/plot_brightness_temperature_wO3.py
@@ -1,5 +1,5 @@
 """
-Performing Brightness Temperature calculation from ground with Ozone
+Performing Downwelling Brightness Temperature calculation with Ozone
 ====================================================================
 """
 

diff --git a/docs/script_examples/plot_bt_era5.py b/docs/script_examples/plot_bt_era5.py
@@ -1,6 +1,6 @@
 """
-Performing BT calculation from satellite using ERA5 Reanalysis Observations
-===========================================================================
+Performing Upwelling Brightness Temperature calculation using ERA5 Reanalysis Observations.
+===========================================================================================
 """
 
 # %%

diff --git a/docs/script_examples/plot_bt_era5_cloudy_profile.py b/docs/script_examples/plot_bt_era5_cloudy_profile.py
@@ -1,6 +1,6 @@
 """
-Performing BT calculation from satellite using ERA5 Reanalysis Observations in cloudy condition.
-================================================================================================
+Performing Upwelling Brightness Temperature calculation using ERA5 Reanalysis Observations in cloudy condition.
+===============================================================================================================
 """
 
 # %%

diff --git a/docs/script_examples/plot_bt_igra2.py b/docs/script_examples/plot_bt_igra2.py
@@ -1,6 +1,6 @@
 """
-Performing BT calculation from satellite using IGRA2 Upper Air Observations (with Extrapolation)
-================================================================================================
+Performing Upwelling Brightness Temperature calculation using IGRA2 Upper Air Observations (with Extrapolation).
+================================================================================================================
 """
 
 # %%

diff --git a/docs/script_examples/plot_bt_wyoming.py b/docs/script_examples/plot_bt_wyoming.py
@@ -1,6 +1,6 @@
 """
-Performing BT calculation from satellite using Wyoming Upper Air Observations
-=============================================================================
+Performing Upwelling Brightness Temperature calculation using Wyoming Upper Air Observations.
+=============================================================================================
 """
 
 # %%

diff --git a/docs/script_examples/plot_log_dependance_tb.py b/docs/script_examples/plot_log_dependance_tb.py
@@ -0,0 +1,89 @@
+"""
+Logarithmic dependence of monochromatic radiance at 22.235 and 183 GHz
+======================================================================
+"""
+
+# %%
+# This example shows the logarithmic dependence of monochromatic radiance at 22.235 GHz and 183 GHz
+# on the water vapor content in the atmosphere. The brigthness temperature are calculated using the
+# :py:class:`pyrtlib.tb_spectrum.TbCloudRTE` method for the zenith view angle and
+# the following water vapor content: 1/8, 1/4, 1/2, 1, 2, 4, 8 times the water vapor
+# content of the reference atmosphere. The reference atmosphere is the Tropical atmosphere
+
+# Reference: Huang & Bani, 2014. 
+
+import numpy as np
+
+import matplotlib.pyplot as plt
+import matplotlib as mpl
+mpl.rcParams["axes.spines.right"] = True
+mpl.rcParams["axes.spines.top"] = True
+plt.rcParams.update({'font.size': 30})
+
+
+from pyrtlib.climatology import AtmosphericProfiles as atmp
+from pyrtlib.tb_spectrum import TbCloudRTE
+from pyrtlib.absorption_model import O2AbsModel
+from pyrtlib.utils import ppmv2gkg, mr2rh
+
+z, p, _, t, md = atmp.gl_atm(atmp.TROPICAL)
+
+tb_23 = []
+tb_183 = []
+tau_23 = []
+tau_183 = []
+m = [1/8, 1/4, 1/2, 1, 2, 4, 8]
+
+for i in range(0, 7):
+    gkg = ppmv2gkg(md[:, atmp.H2O], atmp.H2O) * m[i]
+    rh = mr2rh(p, t, gkg)[0] / 100
+
+    # frq = np.arange(20, 201, 1)
+    frq = np.array([22.235, 183])
+    rte = TbCloudRTE(z, p, t, rh, frq)
+    rte.init_absmdl('R22SD')
+    O2AbsModel.model = 'R22'
+    df = rte.execute()
+    df['tau'] = df.tauwet + df.taudry
+    tb_23.append(df.tbtotal[0])
+    tb_183.append(df.tbtotal[1])
+    tau_23.append(df.tau[0])
+    tau_183.append(df.tau[1])
+
+tb_023 = np.array(tb_23) - tb_23[3]
+tb_0183 = np.array(tb_183) - tb_183[3]
+
+fig, axes = plt.subplots(2, 2, figsize=(24, 14), sharex=True)
+axes[0, 1].tick_params(axis='both', direction='in', length=10, width=.5)
+axes[0, 1].plot(np.log2(m), tb_0183, linestyle='--', linewidth=3, color='black')
+axes[0, 1].plot(np.log2(m), tb_0183, marker='+', linestyle='None', color='r', ms=20, markeredgewidth=5)
+axes[0, 1].set_title(f"{frq[1]} GHz")
+axes[0, 1].grid(True, 'both')
+axes[0, 1].annotate("c)", xy=(0.02, 0.05), xycoords='axes fraction', fontsize=40)
+
+axes[0, 0].set_ylabel('$\Delta T_b$ [K]')
+axes[0, 0].tick_params(axis='both', direction='in', length=10, width=.5)
+axes[0, 0].plot(np.log2(m), tb_023, linestyle='--', linewidth=3, color='black')
+axes[0, 0].plot(np.log2(m), tb_023, marker='+', linestyle='None', color='r', ms=20, markeredgewidth=5)
+axes[0, 0].set_title(f"{frq[0]} GHz")
+axes[0, 0].grid(True, 'both')
+axes[0, 0].annotate("a)", xy=(0.02, 0.05), xycoords='axes fraction', fontsize=40)
+
+axes[1, 1].set_xlabel('$log_2(SF_{q_{H_2O}}))$')
+axes[1, 1].tick_params(axis='both', direction='in', length=10, width=.5)
+axes[1, 1].plot(np.log2(m), tau_183, linestyle='--', linewidth=3, color='black')
+axes[1, 1].plot(np.log2(m), tau_183, marker='+', linestyle='None', color='blue', ms=20, markeredgewidth=5)
+axes[1, 1].grid(True, 'both')
+axes[1, 1].annotate("d)", xy=(0.02, 0.88), xycoords='axes fraction', fontsize=40)
+
+axes[1, 0].set_xlabel('$log_2(SF_{q_{H_2O}})$')
+axes[1, 0].set_ylabel('$\\tau$ [Np]')
+axes[1, 0].tick_params(axis='both', direction='in', length=10, width=.5)
+axes[1, 0].plot(np.log2(m), tau_23, linestyle='--', linewidth=3, color='black')
+axes[1, 0].plot(np.log2(m), tau_23, marker='+', linestyle='None', color='blue', ms=20, markeredgewidth=5)
+axes[1, 0].grid(True, 'both')
+axes[1, 0].annotate("b)", xy=(0.02, 0.88), xycoords='axes fraction', fontsize=40)
+
+plt.tight_layout()
+
+plt.show()
diff --git a/docs/script_examples/plot_model_cloudy.py b/docs/script_examples/plot_model_cloudy.py
@@ -1,6 +1,6 @@
 """
-Performing Brightness Temperature calculation in cloudy condition
-=================================================================
+Performing Downwelling Brightness Temperature calculation in cloudy condition.
+==============================================================================
 """
 
 # %%

diff --git a/docs/source/_static/pyrtlib.css b/docs/source/_static/pyrtlib.css
@@ -16,10 +16,15 @@ table {
     text-align: center !important;
 }
 
-.bd-header .navbar-header-items__start {
+/* .bd-header .navbar-header-items__start {
     flex-shrink: 0;
     gap: .5rem;
     margin-right: 200px;
+} */
+
+.sd-card-img, .sd-card-img-top {
+    height: 100px;
+    margin-top: 5px;
 }
 
 @media(max-width: 960px) {

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -61,7 +61,8 @@
     'nbsphinx',
     'sphinx_gallery.gen_gallery',
     'sphinx.ext.coverage',
-    'sphinx_panels',
+    # 'sphinx_panels',
+    "sphinx_design",
     # 'sphinx.ext.graphviz',
     # 'rst2pdf.pdfbuilder',
     # 'autoapi.extension'
@@ -70,6 +71,7 @@
     # 'myst_nb'
 ]
 
+nbsphinx_allow_errors = True
 toggleprompt_offset_right = 35
 
 # Configuration of sphinx.ext.coverage

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -16,44 +16,55 @@ PyRTlib also allows to quantify absorption model uncertainty due to uncertainty
 The approach is applied to a widely used microwave absorption model [Rosenkranz-2017]_, on which PyRTlib is based, and radiative transfer calculations at any frequencies range, 
 which are commonly exploited for atmospheric sounding by microwave radiometer (MWR).  
 
-.. panels::
-   :card: + intro-card text-center
-
-   ---
-   :img-top: _static/shuttle.svg
-
-   Getting started
-
-   +++
-
-   .. link-button:: installation
-      :type: ref
-      :text: Go To Reference
-      :classes: btn-block btn-outline-primary 
-
-   ---
-   :img-top: _static/api.svg
-
-   API references
-
-   +++
-
-   .. link-button:: api
-      :type: ref
-      :text: Go To Reference
-      :classes: btn-block btn-outline-primary 
-
-   ---
-   :img-top: _static/code.svg
-
-   Gallery example
-
-   +++
-
-   .. link-button:: examples/index
-      :type: ref
-      :text: Go To Reference
-      :classes: btn-outline-primary btn-block
+.. grid:: 2 2 2 2
+    :gutter: 4
+    :padding: 0 0 2 2
+    :class-container: sd-text-center
+
+    .. grid-item-card:: Getting started
+        :img-top: _static/shuttle.svg
+        :class-card: intro-card
+        :shadow: md
+
+        +++
+
+        .. button-link:: installation.html
+            :ref-type: ref
+            :click-parent:
+            :color: primary
+            :expand:
+
+            To the getting started guides
+
+    .. grid-item-card:: API reference
+        :img-top: _static/api.svg
+        :class-card: intro-card
+        :shadow: md
+
+        +++
+
+        .. button-link:: api.html
+            :ref-type: ref
+            :click-parent:
+            :color: primary
+            :expand:
+
+            To the API references
+
+    .. grid-item-card:: Gallery examples
+        :img-top: _static/code.svg
+        :class-card: intro-card
+        :shadow: md
+
+        +++
+
+        .. button-link:: examples/index.html
+            :ref-type: ref
+            :click-parent:
+            :color: primary
+            :expand:
+
+            To the Gallery examples
 
 .. pyrtlib is a python tool that provides a set of calsses and methods for simulating ........
 

diff --git a/docs/source/installation.rst b/docs/source/installation.rst
@@ -145,8 +145,28 @@ From within pyrtlib folder run the following docker command to build the docker
    $ docker build --pull --rm -f "Dockerfile" -t pyrtlib:latest "." 
    $ docker run --rm -it  pyrtlib:latest
 
-To test run the exaple script from within the docker image
+To test run the example script from within the docker image
 
 .. code-block:: console
 
-   $ root@993587e5fea9:/home/dev/pyrtlib# python3 hello_spectrum.py
+   $ root@993587e5fea9:/home/dev/pyrtlib# python3 hello_spectrum.py
+
+My first run with PyRTlib (Colab Notebook)
+==========================================
+
+To run the example script in a Google Colab Notebook, you can use the following code:
+
+.. code-block:: console
+
+   !pip install pyrtlib
+   !python3 hello_spectrum.py
+
+.. note::
+
+    The example script is available at `this link <https://colab.research.google.com/github/SatCloP/pyrtlib/blob/main/docs/source/notebook/first_run.ipynb>`_.
+
+.. code-block:: console
+
+   !wget https://raw.githubusercontent.com/SatCloP/pyrtlib/main/pyrtlib/hello_spectrum.py
+   !python3 hello_spectrum.py
+