Refactor code for Sun zenith angle corrections and change to effective_solar_pathlength_corrected instead of sunz_corrected for built-in RGB recipes

doc/source/composites.rst

@@ -371,9 +371,9 @@ can be applied in the following way::
         compositor: !!python/name:satpy.composites.core.GenericCompositor
         prerequisites:
         - name: VIS006
-          modifiers: [sunz_corrected]
+          modifiers: [effective_solar_pathlength_corrected]
         - name: VIS008
-          modifiers: [sunz_corrected]
+          modifiers: [effective_solar_pathlength_corrected]
         - IR_108
         standard_name: overview
 
@@ -384,7 +384,9 @@ Here we see two changes:
 2. a list of modifiers attached to the dictionary defining the channel
 
 The modifier above is a built-in that normalizes the Solar zenith
-angle to Sun being directly at the zenith.
+angle to Sun being directly at the zenith following the Li and Shibata
+(2006, :doi:`10.1175/JAS3682.1`) parameterization that reduces over-correction at high Solar
+zenith angles.
 
 More examples can be found in Satpy source code directory
 `satpy/etc/composites <https://github.com/pytroll/satpy/tree/main/satpy/etc/composites>`_.

doc/source/dev_guide/custom_reader.rst

@@ -218,7 +218,8 @@ Parameters you can define for example are:
    when it is returned by the file handler. Only a few of these have been
    standardized across Satpy, but are based on the names of the modifiers
    configured in the "composites" YAML files. Examples include
-   ``sunz_corrected`` or ``rayleigh_corrected``. See the
+   ``sunz_corrected``, ``effective_solar_pathlength_corrected``
+   or ``rayleigh_corrected``. See the
    `metadata wiki <https://github.com/pytroll/satpy/wiki/Metadata-names>`_
    for more information.
  - file\_type: Name of file type (see above).

doc/source/modifiers.rst

@@ -34,11 +34,16 @@ on those modifiers can be found in the linked API documentation.
       - Description
     * - ``sunz_corrected``
       - :class:`~satpy.modifiers.geometry.SunZenithCorrector`
-      - Modifies solar channels for the solar zenith angle to provide
-        smoother images.
+      - Normalizes solar channels for the solar zenith angle using ``1/cos(sza)``
+        to compute the true reflectance. This leads to zero reflectance for
+        solar zenith angles of 90 degrees and above.
     * - ``effective_solar_pathlength_corrected``
       - :class:`~satpy.modifiers.geometry.EffectiveSolarPathLengthCorrector`
-      - Modifies solar channels for atmospheric path length of solar radiation.
+      - Normalizes solar channels for the solar zenith angle to compute the reflectance,
+        but parameterized following Li and Shibata (2006, :doi:`10.1175/JAS3682.1`) to avoid
+        over-correction at high solar zenith angles for better looking (RGB) imagery, also
+        extending beyond 90 degrees solar zenith angle. This should not be used for
+        quantitative or scientific applications.
     * - ``nir_reflectance``
       - :class:`~satpy.modifiers.spectral.NIRReflectance`
       - Calculates reflective part of channels at the edge of solar and

satpy/composites/spectral.py

@@ -41,11 +41,11 @@ class SpectralBlender(GenericCompositor):
         fractions: [0.63, 0.29, 0.08]
         prerequisites:
           - name: B02
-            modifiers: [sunz_corrected, rayleigh_corrected]
+            modifiers: [effective_solar_pathlength_corrected, rayleigh_corrected]
           - name: B03
-            modifiers: [sunz_corrected, rayleigh_corrected]
+            modifiers: [effective_solar_pathlength_corrected, rayleigh_corrected]
           - name: B04
-            modifiers: [sunz_corrected, rayleigh_corrected]
+            modifiers: [effective_solar_pathlength_corrected, rayleigh_corrected]
         standard_name: toa_bidirectional_reflectance
 
     Other examples can be found in the``ahi.yaml`` composite file in the satpy distribution.
@@ -93,9 +93,9 @@ class HybridGreen(SpectralBlender):
         fraction: 0.15
         prerequisites:
           - name: B02
-            modifiers: [sunz_corrected, rayleigh_corrected]
+            modifiers: [effective_solar_pathlength_corrected, rayleigh_corrected]
           - name: B04
-            modifiers: [sunz_corrected, rayleigh_corrected]
+            modifiers: [effective_solar_pathlength_corrected, rayleigh_corrected]
         standard_name: toa_bidirectional_reflectance
 
     Other examples can be found in the ``ahi.yaml`` and ``ami.yaml`` composite
@@ -126,11 +126,11 @@ class NDVIHybridGreen(SpectralBlender):
         strength: 1.0
         prerequisites:
           - name: vis_05
-            modifiers: [sunz_corrected, rayleigh_corrected]
+            modifiers: [effective_solar_pathlength_corrected, rayleigh_corrected]
           - name: vis_06
-            modifiers: [sunz_corrected, rayleigh_corrected]
+            modifiers: [effective_solar_pathlength_corrected, rayleigh_corrected]
           - name: vis_08
-            modifiers: [sunz_corrected ]
+            modifiers: [effective_solar_pathlength_corrected ]
         standard_name: toa_bidirectional_reflectance
 
     In this example, pixels with NDVI=0.0 will be a weighted average with 15% contribution from the

satpy/etc/composites/abi.yaml

@@ -32,11 +32,11 @@ composites:
     prerequisites:
       # should we be using the most corrected or least corrected inputs?
       - name: C01
-        modifiers: [sunz_corrected, rayleigh_corrected_crefl]
+        modifiers: [effective_solar_pathlength_corrected, rayleigh_corrected_crefl]
       - name: C02
-        modifiers: [sunz_corrected, rayleigh_corrected_crefl]
+        modifiers: [effective_solar_pathlength_corrected, rayleigh_corrected_crefl]
       - name: C03
-        modifiers: [sunz_corrected]
+        modifiers: [effective_solar_pathlength_corrected]
     standard_name: toa_bidirectional_reflectance
 
   green_raw:
@@ -46,11 +46,11 @@ composites:
     prerequisites:
       # should we be using the most corrected or least corrected inputs?
       - name: C01
-        modifiers: [sunz_corrected]
+        modifiers: [effective_solar_pathlength_corrected]
       - name: C02
-        modifiers: [sunz_corrected]
+        modifiers: [effective_solar_pathlength_corrected]
       - name: C03
-        modifiers: [sunz_corrected]
+        modifiers: [effective_solar_pathlength_corrected]
     standard_name: toa_bidirectional_reflectance
 
   green:
@@ -60,11 +60,11 @@ composites:
     prerequisites:
       # should we be using the most corrected or least corrected inputs?
       - name: C01
-        modifiers: [sunz_corrected, rayleigh_corrected]
+        modifiers: [effective_solar_pathlength_corrected, rayleigh_corrected]
       - name: C02
-        modifiers: [sunz_corrected, rayleigh_corrected]
+        modifiers: [effective_solar_pathlength_corrected, rayleigh_corrected]
       - name: C03
-        modifiers: [sunz_corrected]
+        modifiers: [effective_solar_pathlength_corrected]
     standard_name: toa_bidirectional_reflectance
 
   green_nocorr:
@@ -82,30 +82,30 @@ composites:
     compositor: !!python/name:satpy.composites.resolution.SelfSharpenedRGB
     prerequisites:
       - name: C02
-        modifiers: [sunz_corrected, rayleigh_corrected_crefl]
+        modifiers: [effective_solar_pathlength_corrected, rayleigh_corrected_crefl]
       - name: green_crefl
       - name: C01
-        modifiers: [sunz_corrected, rayleigh_corrected_crefl]
+        modifiers: [effective_solar_pathlength_corrected, rayleigh_corrected_crefl]
     standard_name: true_color
 
   true_color_raw:
     compositor: !!python/name:satpy.composites.resolution.SelfSharpenedRGB
     prerequisites:
       - name: C02
-        modifiers: [sunz_corrected]
+        modifiers: [effective_solar_pathlength_corrected]
       - name: green_raw
       - name: C01
-        modifiers: [sunz_corrected]
+        modifiers: [effective_solar_pathlength_corrected]
     standard_name: true_color
 
   true_color:
     compositor: !!python/name:satpy.composites.resolution.SelfSharpenedRGB
     prerequisites:
       - name: C02
-        modifiers: [sunz_corrected, rayleigh_corrected]
+        modifiers: [effective_solar_pathlength_corrected, rayleigh_corrected]
       - name: green
       - name: C01
-        modifiers: [sunz_corrected, rayleigh_corrected]
+        modifiers: [effective_solar_pathlength_corrected, rayleigh_corrected]
     standard_name: true_color
 
   true_color_nocorr:
@@ -120,11 +120,11 @@ composites:
     compositor: !!python/name:satpy.composites.resolution.SelfSharpenedRGB
     prerequisites:
       - name: C05
-        modifiers: [sunz_corrected]
+        modifiers: [effective_solar_pathlength_corrected]
       - name: C03
-        modifiers: [sunz_corrected]
+        modifiers: [effective_solar_pathlength_corrected]
       - name: C02
-        modifiers: [sunz_corrected]
+        modifiers: [effective_solar_pathlength_corrected]
     high_resolution_band: blue
     standard_name: natural_color
 
@@ -149,9 +149,9 @@ composites:
     compositor: !!python/name:satpy.composites.core.GenericCompositor
     prerequisites:
       - name: C02
-        modifiers: [sunz_corrected]
+        modifiers: [effective_solar_pathlength_corrected]
       - name: C03
-        modifiers: [sunz_corrected]
+        modifiers: [effective_solar_pathlength_corrected]
       - C14
     standard_name: overview
 
@@ -190,11 +190,11 @@ composites:
     prerequisites:
       # should we be using the most corrected or least corrected inputs?
       - name: C01
-        modifiers: [sunz_corrected, rayleigh_corrected]
+        modifiers: [effective_solar_pathlength_corrected, rayleigh_corrected]
       - name: C02
-        modifiers: [sunz_corrected, rayleigh_corrected]
+        modifiers: [effective_solar_pathlength_corrected, rayleigh_corrected]
       - name: C03
-        modifiers: [sunz_corrected]
+        modifiers: [effective_solar_pathlength_corrected]
     standard_name: toa_bidirectional_reflectance
 
   cimss_green_sunz:
@@ -203,11 +203,11 @@ composites:
     prerequisites:
       # should we be using the most corrected or least corrected inputs?
       - name: C01
-        modifiers: [sunz_corrected]
+        modifiers: [effective_solar_pathlength_corrected]
       - name: C02
-        modifiers: [sunz_corrected]
+        modifiers: [effective_solar_pathlength_corrected]
       - name: C03
-        modifiers: [sunz_corrected]
+        modifiers: [effective_solar_pathlength_corrected]
     standard_name: toa_bidirectional_reflectance
 
   cimss_green:
@@ -232,10 +232,10 @@ composites:
       Research Article: https://agupubs.onlinelibrary.wiley.com/doi/10.1029/2018EA000379
     prerequisites:
       - name: C02
-        modifiers: [sunz_corrected, rayleigh_corrected]
+        modifiers: [effective_solar_pathlength_corrected, rayleigh_corrected]
       - name: cimss_green_sunz_rayleigh
       - name: C01
-        modifiers: [sunz_corrected, rayleigh_corrected]
+        modifiers: [effective_solar_pathlength_corrected, rayleigh_corrected]
     standard_name: cimss_true_color
 
   cimss_true_color_sunz:
@@ -250,10 +250,10 @@ composites:
       Research Article: https://agupubs.onlinelibrary.wiley.com/doi/10.1029/2018EA000379
     prerequisites:
       - name: C02
-        modifiers: [sunz_corrected]
+        modifiers: [effective_solar_pathlength_corrected]
       - name: cimss_green_sunz
       - name: C01
-        modifiers: [sunz_corrected]
+        modifiers: [effective_solar_pathlength_corrected]
     standard_name: cimss_true_color
 
   cimss_true_color:
@@ -439,9 +439,9 @@ composites:
     prerequisites:
       - name: C13
       - name: C02
-        modifiers: [sunz_corrected, rayleigh_corrected]
+        modifiers: [effective_solar_pathlength_corrected, rayleigh_corrected]
       - name: C05
-        modifiers: [sunz_corrected]
+        modifiers: [effective_solar_pathlength_corrected]
     standard_name: cloud_phase_distinction
 
   day_cloud_type_distinction:
@@ -600,9 +600,9 @@ composites:
     compositor: !!python/name:satpy.composites.core.GenericCompositor
     prerequisites:
       - name: C03
-        modifiers: [sunz_corrected]
+        modifiers: [effective_solar_pathlength_corrected]
       - name: C05
-        modifiers: [sunz_corrected]
+        modifiers: [effective_solar_pathlength_corrected]
       - compositor: !!python/name:satpy.composites.arithmetic.DifferenceCompositor
         prerequisites:
           - name: C07
@@ -680,9 +680,9 @@ composites:
     prerequisites:
       - name: C06
       - name: C03
-        modifiers: [sunz_corrected]
+        modifiers: [effective_solar_pathlength_corrected]
       - name: C02
-        modifiers: [sunz_corrected]
+        modifiers: [effective_solar_pathlength_corrected]
     standard_name: land_cloud_fire
 
   land_cloud:
@@ -694,9 +694,9 @@ composites:
     prerequisites:
       - name: C05
       - name: C03
-        modifiers: [sunz_corrected]
+        modifiers: [effective_solar_pathlength_corrected]
       - name: C02
-        modifiers: [sunz_corrected]
+        modifiers: [effective_solar_pathlength_corrected]
     standard_name: land_cloud
 
   snow:
@@ -709,9 +709,9 @@ composites:
     compositor: !!python/name:satpy.composites.core.GenericCompositor
     prerequisites:
       - name: C03
-        modifiers: [sunz_corrected]
+        modifiers: [effective_solar_pathlength_corrected]
       - name: C05
-        modifiers: [sunz_corrected]
+        modifiers: [effective_solar_pathlength_corrected]
       - name: C07
         modifiers: [nir_reflectance]
     standard_name: snow
@@ -726,7 +726,7 @@ composites:
     compositor: !!python/name:satpy.composites.core.GenericCompositor
     prerequisites:
       - name: C03
-        modifiers: [sunz_corrected]
+        modifiers: [effective_solar_pathlength_corrected]
       - name: C07
         modifiers: [nir_reflectance]
       - name: C14
@@ -754,11 +754,11 @@ composites:
     compositor: !!python/name:satpy.composites.core.GenericCompositor
     prerequisites:
       - name: C05
-        modifiers: [sunz_corrected]
+        modifiers: [effective_solar_pathlength_corrected]
       - name: C06
-        modifiers: [sunz_corrected]
+        modifiers: [effective_solar_pathlength_corrected]
       - name: C02
-        modifiers: [sunz_corrected, rayleigh_corrected]
+        modifiers: [effective_solar_pathlength_corrected, rayleigh_corrected]
     standard_name: cloud_phase
 
   cloud_phase_raw:
@@ -796,9 +796,9 @@ composites:
     compositor: !!python/name:satpy.composites.resolution.SelfSharpenedRGB
     prerequisites:
       - name: C03
-        modifiers: [sunz_corrected]
+        modifiers: [effective_solar_pathlength_corrected]
       - name: C02
-        modifiers: [sunz_corrected, rayleigh_corrected]
+        modifiers: [effective_solar_pathlength_corrected, rayleigh_corrected]
       - name: green
     standard_name: true_color
 
@@ -824,10 +824,10 @@ composites:
     compositor: !!python/name:satpy.composites.resolution.SelfSharpenedRGB
     prerequisites:
       - name: C02
-        modifiers: [sunz_corrected, rayleigh_corrected]
+        modifiers: [effective_solar_pathlength_corrected, rayleigh_corrected]
       - name: green
       - name: C01
-        modifiers: [sunz_corrected, rayleigh_corrected]
+        modifiers: [effective_solar_pathlength_corrected, rayleigh_corrected]
     standard_name: true_color_reproduction_color_stretch
 
   true_color_reproduction_uncorr: