Merge pull request #42 from sfinkens/doc-satpy-usage

Update documentation

doc/source/api.rst

@@ -9,10 +9,6 @@ This is done by reading the first three bytes of the data set. If they contain t
 
 GAC POD reader
 --------------
-
-.. automodule:: pygac.gac_pod
- :members:
- :undoc-members:
 
 As the format of GAC POD header is changed twice (once in 1992 and again in 1994), there are currently three readers integrated in the *pygac* to read POD header.
 
@@ -45,6 +41,9 @@ It is evident that year, month values are jumping and have non-sense values.
 
 Whenever possible, *pygac* uses RPY corrections along with other orbital parameters to compute accurate satellite location (e.g. instead of assuming constant altitude). However, RPY corrections are not available for all NOAA satellites. In case of the majority of the POD family satellites, these corrections are set to zero.
 
+.. automodule:: pygac.gac_pod
+ :members:
+ :undoc-members:
 
 GAC KLM reader
 --------------
@@ -54,34 +53,29 @@ GAC KLM reader
  :undoc-members:
 
 
-Computation of geolocation
---------------
+GAC Reader
+----------
 
-.. automodule:: pygac.gac_klm
+.. automodule:: pygac.gac_reader
  :members:
  :undoc-members:
 
 
+Computation of geolocation
+--------------------------
+
 Each GAC row has total 409 pixels. But lat-lon values are provided for every eigth pixel starting from pixel 5 and ending at pixel 405. Using Numpy, Scipy and Pyresample packages, inter- and extrapolation is carried out to obtain geolocation for each pixel along the scanline.
 
 If the GAC data belongs to POD family, then clock drift errors are used to adjust existing Lat-Lon information. Here, *pygac* makes use of PyOrbital package, which is a part of PyTroll suite of Python interface developed to process meteorological satellite data (further information here: http://www.pytroll.org/ and https:/mraspaud/pyorbital). *pygac* interpolates the clock offset and adjusts the nominal scan times to the actual scan times. Since the geolocation was computed using the nominal scan times, *pygac* interpolates the latitudes and longitudes to the actual scan times using spherical linear interpolation, aka slerp. However, in the case of a clock drift error greater than the scan rate of the dataset, the latitude and longitude for each pixel of the scan lines that cannot have an interpolated geolocation (typically at the start or end of the dataset) are recomputed. This is done using pyorbital, which in turn uses TLEs to compute the position of the satellite at each scan time and the instrument geometry compute the longitude and latitude of each pixel of the dataset. Since this operation can be quite costly, the interpolation is prefered whenever possible.
 
 Computation of angles
---------------
-
-.. automodule:: pygac.gac_reader
- :members:
- :undoc-members:
+---------------------
 
 The azimuth angles are calculated using get_alt_az and get_observer_look from pyorbital. In pyorbital documentation there is a link describing how calculations are done http://celestrak.com/columns/v02n02/. The azimuth described in the link is measured as clockwise from North instead of counter-clockwise from South. Counter clockwise from south would be the standard for a right-handed orthogonal coordinate system. Pygac was updated to use the same definition for angles as pyorbital (2019, September, version > 1.1.0). Previous versions used azimuth +/-180 degrees, which correspond to degrees clockwise from south. All angles are converted to degrees. All azimuth angles are converted to range ]-180, 180] (2019 October version > 1.1.0). Note that ]-180, 180] is an open interval.
 
 
 GAC calibration/inter-calibration
---------------
-
-.. automodule:: pygac.gac_klm
- :members:
- :undoc-members:
+---------------------------------
 
 *pygac* currently supports calibration of all GAC data from AVHRRs onboard
  NOAA-7 and onwards, including Metop satellites.
@@ -103,10 +97,6 @@ In some cases it was found that, apart from the reset values, even the readings
 GAC I/O module
 --------------
 
-.. automodule:: pygac.gac_pod
- :members:
- :undoc-members:
-
 The I/O module generates three HDF5 files, one containing reflectances, brightness temperatures, and lat/lon information. The other output file contains solar and satellite zenith and azimuth angles. And the third file contains quality flags.
 
 The output file name format is:
@@ -147,13 +137,13 @@ In some orbits, the latitude and longitude information contains corrupt values f
 
 For extremely warm and cold temperatures, the channel 3b is saturating producing irrelevant brightness temperatures. Such saturation is often not flagged in quality information. *pygac* currently uses a simple if_else construct to constrain valid range of Bts (170.0K<BT<350.0K). Such condition is also applied to split-window channels.
 
-
-Supplement A: Structure of an output file containing reflectances and brightness temperatures
---------------
-
-.. automodule:: pygac.gac_klm
+.. automodule:: pygac.gac_io
  :members:
  :undoc-members:
+
+
+Supplement A: Structure of an output file containing reflectances and brightness temperatures
+---------------------------------------------------------------------------------------------
 
 Input: L1b file: ``NSS.GHRR.NN.D06279.S1800.E1955.B0711012.GC``
 
@@ -402,11 +392,7 @@ Output::
 
 
 Supplement B: Structure of an output file containing Sun and satellite positions
---------------
-
-.. automodule:: pygac.gac_klm
- :members:
- :undoc-members:
+--------------------------------------------------------------------------------
 
 Input: L1b file: ``NSS.GHRR.NN.D06279.S1800.E1955.B0711012.GC``
 
@@ -597,11 +583,8 @@ Output::
 
 
 Supplement C: Structure of an output file containing quality flags
---------------
+------------------------------------------------------------------
 
-.. automodule:: pygac.gac_klm
- :members:
- :undoc-members:
 
 The file that contains quality flags has following information.
 

doc/source/usage.rst

@@ -1,6 +1,9 @@
 Usage
 -----
 
+Standalone
+~~~~~~~~~~
+
 Copy the template file ``etc/pygac.cfg.template`` to ``pygac.cfg`` and place
 it in a directory as you please. Set the environment variable PYGAC_CONFIG_FILE
 pointing to the file. E.g.::
@@ -26,3 +29,7 @@ portion of the GAC orbit that user wants to process. The first scanline number
 starts at 0. If zeroes are specified at both locations, then the entire orbit
 will be processed.
 
+In Satpy
+~~~~~~~~
+It is also possible to use pygac as a library in Satpy, see this `example notebook
+<https:/pytroll/pytroll-examples/blob/master/satpy/avhrr_l1b_gaclac.ipynb>`_.

pygac/gac_reader.py

@@ -478,14 +478,20 @@ def get_angles(self):
  and different ranges.
 
  Returns:
- sat_azi: satellite azimuth angle
- degree clockwise from north in range ]-180, 180],
- sat_zentih: satellite zenith angles in degrees in range [0,90],
- sun_azi: sun azimuth angle
- degree clockwise from north in range ]-180, 180],
- sun_zentih: sun zenith angles in degrees in range [0,90],
- rel_azi: absolute azimuth angle difference in degrees between sun
- and sensor in range [0, 180]
+ Tuple containing:
+
+ sat_azi: Satellite azimuth angle (in degrees clockwise from
+ north, range ]-180, 180]).
+
+ sat_zenith: Satellite zenith angle (in degrees, range [0,90]).
+
+ sun_azi: Sun azimuth angle (in degrees clockwise from north,
+ range ]-180, 180]).
+
+ sun_zenith: Sun zenith angle (in degrees, range [0,90]).
+
+ rel_azi: Absolute azimuth angle difference between sun and
+ sensor (in degrees, range [0, 180]).
 
  """
  self.get_times()
@@ -577,14 +583,16 @@ def correct_scan_line_numbers(self):
  """Remove scanlines with corrupted scanline numbers
 
  This includes:
- - Scanline numbers outside the valide range
- - Scanline numbers deviating more than a certain threshold from the
- ideal case (1,2,3,...N)
+
+ - Scanline numbers outside the valide range
+ - Scanline numbers deviating more than a certain threshold from the
+ ideal case (1,2,3,...N)
 
  Example files having corrupt scanline numbers:
- - NSS.GHRR.NJ.D96144.S2000.E2148.B0720102.GC
- - NSS.GHRR.NJ.D96064.S0043.E0236.B0606162.WI
- - NSS.GHRR.NJ.D99286.S1818.E2001.B2466869.WI
+
+ - NSS.GHRR.NJ.D96144.S2000.E2148.B0720102.GC
+ - NSS.GHRR.NJ.D96064.S0043.E0236.B0606162.WI
+ - NSS.GHRR.NJ.D99286.S1818.E2001.B2466869.WI
 
  Returns:
  Intermediate and final results (for plotting purpose)