Azimuth FM rate mismatch mitigation (#80)

* Replacing the loaders in Burst* class into class methods, with further implementation for thermal and EAP correction

* fix on determining beta_naught; addressing PEP8 issues

* Bug fix and feature addition to BurstEAP; restructuring LUT exportation

* Readibility improvement; removing unnecessary imports

* Format change on `burst_id`; keeping the absolute orbit number inside `Sentinel1BurstSlc`

* updates on test_bursts.py

* keeping the basename of the CADS and NADS for populating RTC metadata

* Update src/s1reader/s1_annotation.py

Readability improvement on equation

Co-authored-by: Liang Yu <liangjyu@gmail.com>

* Update src/s1reader/s1_annotation.py

Removing commented out code

Co-authored-by: Liang Yu <liangjyu@gmail.com>

* Update src/s1reader/s1_annotation.py

Reverting the docstring to be split into two lines for PEP8 compliance

Co-authored-by: Liang Yu <liangjyu@gmail.com>

* Update src/s1reader/s1_annotation.py

Improving docstring of the code copied from isce2

Co-authored-by: Liang Yu <liangjyu@gmail.com>

* Update src/s1reader/s1_burst_slc.py

Removing the commented out codes

Co-authored-by: Liang Yu <liangjyu@gmail.com>

* Update src/s1reader/s1_burst_slc.py

improvement on code brevity

Co-authored-by: Liang Yu <liangjyu@gmail.com>

* Update src/s1reader/s1_burst_slc.py

renaming variable for better clarity

Co-authored-by: Liang Yu <liangjyu@gmail.com>

* Update src/s1reader/s1_burst_slc.py

renaming variable name for clarity

Co-authored-by: Liang Yu <liangjyu@gmail.com>

* Update src/s1reader/s1_burst_slc.py

variable name revised for clarity

Co-authored-by: Liang Yu <liangjyu@gmail.com>

* Update src/s1reader/s1_burst_slc.py

variable renamed for clarity

Co-authored-by: Liang Yu <liangjyu@gmail.com>

* Update src/s1reader/s1_burst_slc.py

improvement on docstring

Co-authored-by: Liang Yu <liangjyu@gmail.com>

* Update src/s1reader/s1_burst_slc.py

Readability improvement of equation

Co-authored-by: Liang Yu <liangjyu@gmail.com>

* addressing comments bt @LiangJYu

* docstring fix; variables renamed for clarity

* implemented s1_annotation.AucCal.load_from_zip_file()

* readability improvement

* s1_annotation.py - code cleanup; excention handling for AUX_CAL; PEP8 compliance

* docstring for `s1_burst_slc.eap_compensation_lut()`

* class import scheme changed

* PEP8 compliance

* initial structure of modification

* less mod compared to the branch fork

* extended coeffs for FM rate and Doppler centroid to be used for azimuth FM mismatch rate mitigation

* Working version of azimuth FM rate mismatch mitigation

* Update src/s1reader/s1_orbit.py

Co-authored-by: Gustavo H. X. Shiroma <52007211+gshiroma@users.noreply.github.com>

* Update src/s1reader/s1_orbit.py

Co-authored-by: Gustavo H. X. Shiroma <52007211+gshiroma@users.noreply.github.com>

* Update src/s1reader/s1_orbit.py

Co-authored-by: Gustavo H. X. Shiroma <52007211+gshiroma@users.noreply.github.com>

* Update src/s1reader/s1_orbit.py

Co-authored-by: Gustavo H. X. Shiroma <52007211+gshiroma@users.noreply.github.com>

* Update src/s1reader/s1_orbit.py

Co-authored-by: Gustavo H. X. Shiroma <52007211+gshiroma@users.noreply.github.com>

* Update src/s1reader/s1_orbit.py

Co-authored-by: Gustavo H. X. Shiroma <52007211+gshiroma@users.noreply.github.com>

* addressing comments from @gshiroma

* trailing white spaces are removed

* docstring updated

* Code cleanup and docstrings

* code cleanup

* trailing white space removed

* docsrting added; variable renaming for less verbosity;

* code cleanup and simplification

* variable name simplification

* clde cleanup

* Output as isce3.core.LUT2d

* threshold and num_iter for rdr2geo

* Addressing codacy issue

* Trailing whitespace removed

* codacy issue

* docstring clarification on `BurstExtendedCoeffs`

* whitespace removed

* Update src/s1reader/s1_orbit.py

Co-authored-by: vbrancat <virginia.brancato@jpl.nasa.gov>

* Update src/s1reader/s1_orbit.py

Co-authored-by: vbrancat <virginia.brancato@jpl.nasa.gov>

* Update src/s1reader/s1_annotation.py

Co-authored-by: Liang Yu <liangjyu@gmail.com>

* comment added for clarity

* Update src/s1reader/s1_annotation.py

Co-authored-by: Liang Yu <liangjyu@gmail.com>

* Update src/s1reader/s1_annotation.py

Co-authored-by: Liang Yu <liangjyu@gmail.com>

* Update src/s1reader/s1_annotation.py

Co-authored-by: Liang Yu <liangjyu@gmail.com>

* Update src/s1reader/s1_burst_slc.py

Co-authored-by: Liang Yu <liangjyu@gmail.com>

* Update src/s1reader/s1_burst_slc.py

Co-authored-by: Liang Yu <liangjyu@gmail.com>

* Update src/s1reader/s1_burst_slc.py

Co-authored-by: Liang Yu <liangjyu@gmail.com>

* mod on the suggested commit to reuse the topo output filenames

* fix on variable

* Update src/s1reader/s1_burst_slc.py

Co-authored-by: Liang Yu <liangjyu@gmail.com>

* Update src/s1reader/s1_annotation.py

Co-authored-by: Liang Yu <liangjyu@gmail.com>

* Update src/s1reader/s1_burst_slc.py

Co-authored-by: Liang Yu <liangjyu@gmail.com>

* Update src/s1reader/s1_burst_slc.py

Co-authored-by: vbrancat <virginia.brancato@jpl.nasa.gov>

* Update src/s1reader/s1_burst_slc.py

Co-authored-by: vbrancat <virginia.brancato@jpl.nasa.gov>

* typo fix

* Update src/s1reader/s1_burst_slc.py

Co-authored-by: vbrancat <virginia.brancato@jpl.nasa.gov>

* Re-using the parsed polynomials; mitigation results as ISCE3 LUT2d

* revision on import format

* TODO removed

* Option to turn on / off the functionalities for az fm rate mismatch mitigation

* removing alias for `Rdr2Geo`

* whitespace removed after resolving conflict

* addressing codacy issue

* Update src/s1reader/s1_burst_slc.py

Co-authored-by: Liang Yu <liangjyu@gmail.com>

* Update src/s1reader/s1_annotation.py

Co-authored-by: Liang Yu <liangjyu@gmail.com>

* Update src/s1reader/s1_annotation.py

Co-authored-by: Liang Yu <liangjyu@gmail.com>

* Update src/s1reader/s1_burst_slc.py

Co-authored-by: Liang Yu <liangjyu@gmail.com>

* Update src/s1reader/s1_burst_slc.py

Co-authored-by: Liang Yu <liangjyu@gmail.com>

* Update src/s1reader/s1_burst_slc.py

Co-authored-by: Liang Yu <liangjyu@gmail.com>

* Update src/s1reader/s1_burst_slc.py

Co-authored-by: Liang Yu <liangjyu@gmail.com>

* Update src/s1reader/s1_burst_slc.py

Co-authored-by: Liang Yu <liangjyu@gmail.com>

* Update src/s1reader/s1_reader.py

Co-authored-by: Liang Yu <liangjyu@gmail.com>

* variable name changed

* bug fixed; variable name updated

* addressing codacy issues

* codacy issue

* variable name changed

* pulling out functions that does not need to be methods

* whitespace removed

* updates after linting

* Docstring for `_burst_from_safe_dir` revised

* Docstring for `_burst_from_zip` revised

* Docstring for `load_bursts` revised

* Docstring for `burst_from_xml` revised

* Update src/s1reader/s1_burst_slc.py

Co-authored-by: Liang Yu <liangjyu@gmail.com>

* Docstring for `az_fm_rate_mismatch_mitigation` revised

* Use temporary directory when `path_scratch` was not provided; take in az/rg steps as options to define radargrid

* codacy issue

* docstring updated; variable name changed

* unnecessary members removed; docstring revised

* temporary filename format changed

* Update src/s1reader/s1_annotation.py

Co-authored-by: Scott Staniewicz <scott.stanie@gmail.com>

* Update src/s1reader/s1_annotation.py

Co-authored-by: Scott Staniewicz <scott.stanie@gmail.com>

* Update src/s1reader/s1_annotation.py

Co-authored-by: Scott Staniewicz <scott.stanie@gmail.com>

* Update src/s1reader/s1_annotation.py

Co-authored-by: Scott Staniewicz <scott.stanie@gmail.com>

* Update src/s1reader/s1_burst_slc.py

Co-authored-by: Scott Staniewicz <scott.stanie@gmail.com>

* Update src/s1reader/s1_burst_slc.py

Co-authored-by: Scott Staniewicz <scott.stanie@gmail.com>

* Update src/s1reader/s1_burst_slc.py

Co-authored-by: Scott Staniewicz <scott.stanie@gmail.com>

* unit_degree -> in_degree

* Update src/s1reader/s1_burst_slc.py

Co-authored-by: Scott Staniewicz <scott.stanie@gmail.com>

* Update src/s1reader/s1_burst_slc.py

Co-authored-by: Scott Staniewicz <scott.stanie@gmail.com>

* Update src/s1reader/s1_burst_slc.py

Co-authored-by: Scott Staniewicz <scott.stanie@gmail.com>

* Apply suggestions from code review

Co-authored-by: Scott Staniewicz <scott.stanie@gmail.com>

* variable name format revised

* `mitigate_az_fmrate_mismatch` removed

* PEP8 issues

Co-authored-by: Seongsu Jeong <seongsu.jeong@jpl.nasa.gov>
Co-authored-by: Liang Yu <liangjyu@gmail.com>
Co-authored-by: Gustavo H. X. Shiroma <52007211+gshiroma@users.noreply.github.com>
Co-authored-by: vbrancat <virginia.brancato@jpl.nasa.gov>
Co-authored-by: Scott Staniewicz <scott.stanie@gmail.com>

src/s1reader/s1_annotation.py

@@ -15,6 +15,8 @@
 from scipy.interpolate import InterpolatedUnivariateSpline, interp1d
 from packaging import version
 
+from isce3.core import speed_of_light
+
 # Minimum IPF version from which the S1 product's Noise Annotation
 # Data Set (NADS) includes azimuth noise vector annotation
 min_ipf_version_az_noise_vector = version.parse('2.90')
@@ -333,6 +335,7 @@ class ProductAnnotation(AnnotationBase):
 
     slant_range_time: float
 
+
     @classmethod
     def from_et(cls, et_in: ET):
         '''
@@ -897,3 +900,120 @@ def _anx2height(cls, delta_anx):
             h_t += h_i * np.sin((i+1) * worb * delta_anx + phi[i])
 
         return h_t
+
+
+@dataclass
+class BurstExtendedCoeffs:
+    '''
+    Segments of FM rate / Doppler centroid polynomial coefficients.
+    For (linear) interpolation of FM rate / Doppler Centroid along azimuth.
+    To be used for calculating azimuth FM rate mismatch mitigation
+    '''
+
+    # FM rate
+    fm_rate_aztime_vec: np.ndarray
+    fm_rate_coeff_arr: np.ndarray
+    fm_rate_tau0_vec:np.ndarray
+
+    # Doppler centroid
+    dc_aztime_vec: np.ndarray
+    dc_coeff_arr: np.ndarray
+    dc_tau0_vec: np.ndarray
+
+    @classmethod
+    def from_polynomial_lists(cls,
+                              az_fm_rate_list: list,
+                              doppler_centroid_list: list,
+                              sensing_start: datetime.datetime,
+                              sensing_end: datetime.datetime):
+        '''
+        Extract coefficients from the list of the polynomial lists that fall within
+        the provided sensing start / end times of a burst.
+
+        Parameters:
+        -----------
+        az_fm_rate_list: list[isce3.core.Poly1d]
+            List of azimuth FM rate polynomials
+        doppler_centroid_list: list[isce3.core.Poly1d]
+            List of doppler centroid polynomials
+        sensing_start: datetime.datetime
+            Azimuth start time of the burst
+        sensing_end: datetime.datetime
+            Azimuth end time of the burst
+        '''
+
+        # Extract polynomial info for azimuth FM rate
+        (fm_rate_aztime_burst_vec,
+         fm_rate_coeff_burst_arr,
+         fm_rate_tau0_burst_vec) = cls.extract_polynomial_sequence(az_fm_rate_list,
+                                                                   sensing_start,
+                                                                   sensing_end)
+
+        (dc_aztime_burst_vec,
+         dc_coeff_burst_arr,
+         dc_tau0_burst_vec) = cls.extract_polynomial_sequence(doppler_centroid_list,
+                                                              sensing_start,
+                                                              sensing_end)
+
+        return cls(fm_rate_aztime_burst_vec, fm_rate_coeff_burst_arr, fm_rate_tau0_burst_vec,
+                   dc_aztime_burst_vec, dc_coeff_burst_arr, dc_tau0_burst_vec)
+
+
+    @classmethod
+    def extract_polynomial_sequence(cls, polynomial_list: list,
+                                    datetime_start: datetime.datetime,
+                                    datetime_end: datetime.datetime):
+        '''
+        Scan `vec_azimuth_time` end find indices of the vector
+        that covers the period defined with
+        `datetime_start` and `datetime_end`
+
+        Parameters:
+        -----------
+        polynomial_list: list
+            list of (azimuth_time, isce3.core.Poly1d)
+        datetime_start: datetime.datetime
+            Start time of the period
+        datetime_end: datetime.datetime
+            end time of the period
+
+        Returns:
+        --------
+        tuple
+            Tuple of (vec_aztime_sequence,
+                      arr_coeff_sequence,
+                      vec_tau0_sequence)
+            as a sequence of polynomial info that covers the period
+            defined in the parameters.
+            vec_aztime_sequence: azimuth time of each sample in the sequence
+            arr_coeff_sequence: N by 3 npy array whose row is coefficients of
+                                each sample in the sequence
+            vec_tau0_sequence: Range start time of each sample in the sequence
+        '''
+
+        # NOTE: dt is defined as: [azimuth time] - [start/end time]
+        # find index of poly time closest to start time that is less than start time
+        dt_wrt_start = np.array([(poly[0] - datetime_start).total_seconds() for poly in polynomial_list])
+        dt_wrt_start = np.ma.masked_array(dt_wrt_start, mask=dt_wrt_start > 0)
+        index_start = np.argmax(dt_wrt_start)
+
+        # find index of poly time  closest to end time that is greater than end time
+        dt_wrt_end = np.array([(poly[0] - datetime_end).total_seconds() for poly in polynomial_list])
+        dt_wrt_end = np.ma.masked_array(dt_wrt_end, mask=dt_wrt_end < 0)
+        index_end = np.argmin(dt_wrt_end)
+
+        # Done extracting the IDs. Extract the polynomial sequence
+        vec_aztime_sequence = []
+        arr_coeff_sequence = []
+        vec_tau0_sequence = []
+
+        # Scale factor to convert range (in meters) to seconds (tau)
+        range_to_tau = 2.0 / speed_of_light
+        for poly in polynomial_list[index_start:index_end+1]:
+            vec_aztime_sequence.append(poly[0])
+            arr_coeff_sequence.append(poly[1].coeffs)
+            vec_tau0_sequence.append(poly[1].mean * range_to_tau)
+
+        return (np.array(vec_aztime_sequence),
+                np.array(arr_coeff_sequence),
+                np.array(vec_tau0_sequence))