EL Null-Range Product for Pointing (#966)

* Introduce an executable "gen_el_null_range_product.py" under "nisar/workflows"

* Introduce module "el_null_range_from_raw_ant.py" under "nisar/workflows"

* Add python unit tests and two multi-channel datasets for testing

* Add a method to "Raw.py" to extract caltone coefs and update its test suite

* Add new features for performing caltone and null quality

* Update "__init__.py" in workflow

* Add options for external orbit and attitude files

* Add two L0B files (w/ and w/o calibration) with product
  shape "channel-by-rangeline-by-rangebins"

* Add a 4-beam antenna file.

* Add two XML files, one for orbit and one for attitude related
  to the same L0B products

* Update "REE" section of tests/data/README file

* Add "Quality Factor" to the last column of CSV null-range product.

* Make "tx" arg optional in method "isDithered" of class "Raw"

* Run autopep8

* Remove two large L0B files, one antenna file, and two XML files of REE 
  sim 4-channel  extended scene of the first pass due to their sizes.

* Comment out two lines in the respective CMake file for two python test
  suites "el_null_range_from_raw_ant" and "gen_el_null_range_product".

Author: rad-eng-59

python/packages/CMakeLists.txt

@@ -27,6 +27,7 @@ endforeach()
 set (list_of_exe
      nisar/workflows/crossmul.py
      nisar/workflows/focus.py
+     nisar/workflows/gen_el_null_range_product.py
      nisar/workflows/gen_doppler_range_product.py
      nisar/workflows/geo2rdr.py
      nisar/workflows/geocode_insar.py

python/packages/nisar/products/readers/Raw/Raw.py

@@ -230,7 +230,7 @@ def getNominalPRF(self, frequency='A', tx='H'):
         _, az_time = self.getPulseTimes(frequency, tx)
         return (az_time.size - 1) / (az_time[-1] - az_time[0])
 
-    def isDithered(self, frequency='A', tx='H'):
+    def isDithered(self, frequency='A', tx=None):
         """Whether or not PRF is dithering.
 
         That is more than one PRF value within entire azimuth duration.
@@ -240,16 +240,19 @@ def isDithered(self, frequency='A', tx='H'):
         frequency : {'A', 'B'}, optional
             Sub-band.  Typically main science band is 'A'.
 
-        tx : {'H', 'V', 'L', 'R'}
+        tx : {'H', 'V', 'L', 'R'}, optional
             Transmit polarization.  Abbreviations correspond to horizontal
             (linear), vertical (linear), left circular, right circular
+            Default is the first pol under `frequency`.
 
         Returns
         -------
         bool
             True if multiple PRF values and False if PRF is fixed.    
 
         """
+        if tx is None:
+            tx = self.polarizations[frequency][0][0]
         _, az_time = self.getPulseTimes(frequency, tx)
         tm_diff = np.diff(az_time)
         return not np.isclose(tm_diff.min(), tm_diff.max())
@@ -391,6 +394,33 @@ def getChirpCorrelator(self, frequency: str = 'A', tx: str = None):
         with h5py.File(self.filename, 'r', libver='latest', swmr=True) as f:
             return f[path]["chirpCorrelator"][()]
 
+    def getCaltone(self, frequency='A', polarization=None):
+        """Get complex caltone coefficients for all channels and range lines.
+
+        Caltone coefficients are complex values obtained from pulsed CW
+        (continuous wave) signal of each RX channel.
+
+        Parameters
+        ----------
+        frequency : {'A', 'B'}
+            Sub-band.  Typically main science band is 'A'.
+        polarization : {'HH', 'HV', 'VH', 'VV', 'RH','RV', 'LH', 'LV'}, optional
+            Transmit-Receive polarization. If not specified, the first
+            polarization in the `frequency` band will be used.
+
+        Returns
+        -------
+        np.ndarray(np.ndarray(complex))
+            2-D complex float of caltone (CW) coefficients,
+            size = [rangelines x channels].
+            
+        """
+        if polarization is None:
+            polarization = self.polarizations[frequency][0]
+        path_txrx = self._rawGroup(frequency, polarization)
+        with h5py.File(self.filename, 'r', libver='latest', swmr=True) as fid:
+            return fid[path_txrx]["caltone"][()]        
+
     # XXX C++ and Base.py assume SLC.  Grid less well defined for Raw case
     # since PRF isn't necessarily constant.  Return pulse times with grid?
     def getRadarGrid(self, frequency='A', tx='H', prf=None):

python/packages/nisar/workflows/__init__.py

@@ -1 +1,4 @@
+from .el_null_range_from_raw_ant import (el_null_range_from_raw_ant,
+                                         form_overlap_antenna_pairs,
+                                         AntElPair)
 from .doppler_lut_from_raw import doppler_lut_from_raw