mirzaees · mirzaees · Jun 29, 2023 · Jun 29, 2023 · Jun 29, 2023 · Jun 29, 2023
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -36,7 +36,7 @@ repos:
                '--combine-as']
 
   - repo: https://github.com/asottile/pyupgrade
-    rev: "v3.7.0"
+    rev: "v3.10.1"
     hooks:
       - id: pyupgrade
         name: modernize python

diff --git a/Dockerfile b/Dockerfile
@@ -10,7 +10,7 @@ LABEL org.opencontainers.image.source="https://github.com/insarlab/MintPy"
 LABEL org.opencontainers.image.documentation="https://mintpy.readthedocs.io/en/latest/"
 LABEL org.opencontainers.image.licenses="GPL-3.0-or-later"
 
-# Dynamic lables to define at build time via `docker build --label`
+# Dynamic labels to define at build time via `docker build --label`
 # LABEL org.opencontainers.image.created=""
 # LABEL org.opencontainers.image.version=""
 # LABEL org.opencontainers.image.revision=""

diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
@@ -36,7 +36,7 @@ is a great starting point if you are new to version control.
    - `origin`, which refers to your personal fork
 
 + Setting up [`pre-commit`](https://pre-commit.com/) within `MintPy` directory:
-   - Run `pre-commit install` to set up the git hook scripts, so that `pre-commit` will run automatically on `git commit`. If the `No .pre-commit-config.yaml file was found` error occurrs, update your local MintPy to the latest upstream version to have this config file.
+   - Run `pre-commit install` to set up the git hook scripts, so that `pre-commit` will run automatically on `git commit`. If the `No .pre-commit-config.yaml file was found` error occurs, update your local MintPy to the latest upstream version to have this config file.
 
 
 #### 2. Develop your contribution: ####
@@ -56,7 +56,7 @@ is a great starting point if you are new to version control.
    git checkout -b seasonal_fitting
    ```
 
-+ Work on your idea, run tests and commit locally (`git add` and `git commit`) and/or to your fork on GitHub as you progress (`git push` in command line or [GitHub Desktop](https://desktop.github.com/) with graphical user interface). Use a clear commit message describing the motivation of a change, the nature of a bug for bug fixes or some details on what an enchancement does.
++ Work on your idea, run tests and commit locally (`git add` and `git commit`) and/or to your fork on GitHub as you progress (`git push` in command line or [GitHub Desktop](https://desktop.github.com/) with graphical user interface). Use a clear commit message describing the motivation of a change, the nature of a bug for bug fixes or some details on what an enhancement does.
 
 + Run the [overall test](./CONTRIBUTING.md#testing) locally.
 

diff --git a/docs/FAQs.md b/docs/FAQs.md
@@ -6,7 +6,7 @@ For line-of-sight (LOS) phase in the unit of radians, i.e. 'unwrapPhase' dataset
 
 For LOS displacement (velocity) in the unit of meters (m/yr), i.e. 'timeseries' dataset in `timeseries.h5` file, positive value represents motion toward the satellite (uplift for pure vertical motion).
 
-### 2. How to prepare the input for MintPy if I am using currently un-supported InSAR softwares?
+### 2. How to prepare the input for MintPy if I am using currently un-supported InSAR software?
 
 The input of MintPy routine workflow (`smallbaselineApp.py`) is a stack of unwrapped interferograms. For "stack", we mean all the interferograms (unwrapped phase and spatial coherence) and geometries (DEM, incidence angle, etc.) have the same spatial extent and same spatial resolution, either in geo-coordinates or radar (range-doppler) coordinates. The input has 2 components: data and attributes.
 
@@ -39,7 +39,7 @@ For dataset in geo-coordinates [recommended]:
 
 For dataset in radar-coordinates, the extra lookup table file(s) is required (_e.g._ lat/lon.rdr for `ISCE-2`, sim_\*.UTM_TO_RDC for `Gamma`, geo_\*.trans for `ROI_PAC`).
 
-All the files above should be in the same spatial extent and same spatial resolution (except for the lookup table in geo-coordinates from Gamma/ROI_PAC). If they are not (e.g. different row/column number, different spatial extent in terms of SNWE, different spatial resolution, etc.), the easiest way is to geocode them with the same ouput spatial extent and same output spatial resolution.
+All the files above should be in the same spatial extent and same spatial resolution (except for the lookup table in geo-coordinates from Gamma/ROI_PAC). If they are not (e.g. different row/column number, different spatial extent in terms of SNWE, different spatial resolution, etc.), the easiest way is to geocode them with the same output spatial extent and same output spatial resolution.
 
 MintPy read data files via `mintpy.utils.readfile.read()`. It supports the following two types of file formats:
 

diff --git a/docs/api/attributes.md b/docs/api/attributes.md
@@ -41,6 +41,7 @@ The following attributes vary for each interferogram:
 +  FILE_PATH = absolute file path
 +  PROCESSOR = processing software, i.e. isce, aria, snap, gamma, roipac etc.
 +  DATA_TYPE = data type, i.e. float32, int16, etc., for isce product read using GDAL
++  BYTE_ORDER = order of bytes, or endianness, for binary files, i.e. big-endian or little-endian. Most InSAR processors use little-endian, except for Gamma, which sometimes use big-endian.
 +  BANDS = number of bands, for binary file I/O.
 +  INTERLEAVE = band interleave type, i.e. BSQ, BIL, BIP for binary file I/O.
 +  NO_DATA_VALUE = No data value, value that should be ignored.
@@ -50,7 +51,7 @@ The following attributes vary for each interferogram:
 +  SUBSET_XMIN/XMAX/YMIN/YMAX = start/end column/row number of subset in the original coverage
 +  MODIFICATION_TIME = dataset modification time, exists in ifgramStack.h5 file for 3D dataset, used for "--update" option of unwrap error corrections.
 +  NCORRLOOKS = number of independent looks, as explained in [SNAPHU](https://web.stanford.edu/group/radar/softwareandlinks/sw/snaphu/snaphu.conf.full)
-+  UTM_ZONE = UTM zone, e.g. 60S, for geocoded file with UTM projection only.
++  UTM_ZONE = UTM zone, comprises a zone number and a hemisphere, e.g. 11N, 60S, for geocoded file with UTM projection only.
 +  EPSG = EPSG code for coordinate systems, for geocoded files only.
 
 ### Reference ###

diff --git a/docs/api/data_structure.md b/docs/api/data_structure.md
@@ -2,53 +2,69 @@
 
 MintPy uses [HDF5](https://www.hdfgroup.org) file internally. It loads files generated by various InSAR processors into HDF5 format (via `load_data.py` or `prep_*.py`). HDF5 files can exported into other format via `save_*.py`, i.e. [QGIS](../QGIS.md), [HDF-EOS5](../hdfeos5.md), GMT, ROI_PAC and [Google Earth KMZ](../google_earth.md).
 
+### File name convention
+
+Using the underscore `_` as the delimiter in the file name, the first part describes the file type, while the rest parts describe the additional operations. For example:
+
++  `timeseries.h5` is the raw time series
++  `timeseries_ERA5.h5` is the time series after the ERA5 correction;
++  `velocity.h5` is the velocity from the final displacement time series
++  `velocityERA5.h5` is the velocity from ERA5 tropospheric delay (from `inputs/ERA5.h5` file), not the displacement velocity after ERA5 correction.
++  `timeseriesResidual.h5` is the residual phase time series
++  `timeseriesResidual_ramp.h5` is the residual phase time series after deramping
+
+### HDF5 data structure
+
 All HDF5 files generated by MintPy have **datasets and attributes in the root level**. Files may have one or multiple datasets. Datasets in most files have the same shape (size), except for the pre-defined structure types below (presented in the most complete form):
 
-### timeseries
+#### timeseries
 
-```
+```cfg
 /                Root level
 Attributes       Dictionary for metadata
-/timeseries      3D array of float32 in size of (n, l, w) in meter for cumulative displacement.
 /date            1D array of string  in size of (n,     ) in YYYYMMDD format.
+/timeseries      3D array of float32 in size of (n, l, w) in meter for cumulative displacement.
 /bperp           1D array of float32 in size of (n,     ) in meter for perpendicular baseline.
 ```
 
 where `n` is the number of acquisitions, `l` for length, `w` for width.
 
-### velocity
-
-```
-/                         Root level
-Attributes                Dictionary of metadata
-/velocity                 2D array of float32 in size of (l, w) in m/year         for polynomial function with the order of 1
-/velocityStd              2D array of float32 in size of (l, w) in m/year         for polynomial function with the order of 1
-/acceleration             2D array of float32 in size of (l, w) in m^2/year       for polynomial function with the order of 2
-/accelerationStd          2D array of float32 in size of (l, w) in m^2/year       for polynomial function with the order of 2
-/poly{order}              2D array of float32 in size of (l, w) in m^{order}/year for polynomial function with the order >= 3
-/poly{order}Std           2D array of float32 in size of (l, w) in m^{order}/year for polynomial function with the order >= 3
+#### velocity
+
+```cfg
+/                          Root level
+Attributes                 Dictionary of metadata
+/velocity                  2D array of float32 in size of (l, w) in m/year         for polynomial function with the order of 1
+/velocityStd               2D array of float32 in size of (l, w) in m/year         for polynomial function with the order of 1
+/acceleration              2D array of float32 in size of (l, w) in m^2/year       for polynomial function with the order of 2
+/accelerationStd           2D array of float32 in size of (l, w) in m^2/year       for polynomial function with the order of 2
+/poly{order}               2D array of float32 in size of (l, w) in m^{order}/year for polynomial function with the order >= 3
+/poly{order}Std            2D array of float32 in size of (l, w) in m^{order}/year for polynomial function with the order >= 3
+...
+/annualAmplitude           2D array of float32 in size of (l, w) in meter  for periodic function with period of 1     year
+/annualPhase               2D array of float32 in size of (l, w) in radian for periodic function with period of 1     year
+/semiAnnualAmplitude       2D array of float32 in size of (l, w) in meter  for periodic function with period of 1/2   year
+/semiAnnualPhase           2D array of float32 in size of (l, w) in radian for periodic function with period of 1/2   year
+/periodY{per}Amplitude     2D array of float32 in size of (l, w) in meter  for periodic function with period of {per} year
+/periodY{per}Phase         2D array of float32 in size of (l, w) in radian for periodic function with period of {per} year
 ...
-/annualAmplitude          2D array of float32 in size of (l, w) in meter  for periodic function with period of 1     year
-/annualPhase              2D array of float32 in size of (l, w) in radian for periodic function with period of 1     year
-/semiAnnualAmplitude      2D array of float32 in size of (l, w) in meter  for periodic function with period of 1/2   year
-/semiAnnualPhase          2D array of float32 in size of (l, w) in radian for periodic function with period of 1/2   year
-/periodY{per}Amplitude    2D array of float32 in size of (l, w) in meter  for periodic function with period of {per} year
-/periodY{per}Phase        2D array of float32 in size of (l, w) in radian for periodic function with period of {per} year
+/step{YYYYMMDD}            2D array of float32 in size of (l, w) in meter for step function
+/step{YYYYMMDD}Std         2D array of float32 in size of (l, w) in meter for step function
 ...
-/step{YYYYMMDD}           2D array of float32 in size of (l, w) in meter for step function
-/step{YYYYMMDD}Std        2D array of float32 in size of (l, w) in meter for step function
+/velocityPost{YYYYMMDD}    2D array of float32 in size of (l, w) in m/year for a polyline function starting at {YYYYMMDD}
+/velocityPost{YYYYMMDD}Std 2D array of float32 in size of (l, w) in m/year for a polyline function starting at {YYYYMMDD}
 ...
-/exp{YYYYMMDD}Tau{tau}    2D array of float32 in size of (l, w) in meter for exponential function starting at {YYYYMMDD} with characteristic time of {tau} days
-/exp{YYYYMMDD}Tau{tau}Std 2D array of float32 in size of (l, w) in meter for exponential function starting at {YYYYMMDD} with characteristic time of {tau} days
+/exp{YYYYMMDD}Tau{tau}     2D array of float32 in size of (l, w) in meter for an exponential function starting at {YYYYMMDD} with characteristic time of {tau} days
+/exp{YYYYMMDD}Tau{tau}Std  2D array of float32 in size of (l, w) in meter for an exponential function starting at {YYYYMMDD} with characteristic time of {tau} days
 ...
-/log{YYYYMMDD}Tau{tau}    2D array of float32 in size of (l, w) in meter for logarithmic function starting at {YYYYMMDD} with characteristic time of {tau} days
-/log{YYYYMMDD}Tau{tau}Std 2D array of float32 in size of (l, w) in meter for logarithmic function starting at {YYYYMMDD} with characteristic time of {tau} days
+/log{YYYYMMDD}Tau{tau}     2D array of float32 in size of (l, w) in meter for a logarithmic function starting at {YYYYMMDD} with characteristic time of {tau} days
+/log{YYYYMMDD}Tau{tau}Std  2D array of float32 in size of (l, w) in meter for a logarithmic function starting at {YYYYMMDD} with characteristic time of {tau} days
 ...
 ```
 
-### geometry
+#### geometry
 
-```
+```cfg
 /                        Root level
 Attributes               Dictionary for metadata. 'X/Y_FIRST/STEP' attribute for geocoded.
 /height                  2D array of float32 in size of (l, w   ) in meter. Height with respect to the ellipsoid (as provided by ISCE-2/topsStack) or geoid.
@@ -64,9 +80,9 @@ Attributes               Dictionary for metadata. 'X/Y_FIRST/STEP' attribute for
 ...
 ```
 
-### ifgramStack
+#### ifgramStack
 
-```
+```cfg
 /                  Root level group name
 Attributes         Dictionary for metadata
 /date              2D array of string  in size of (m, 2   ) in YYYYMMDD format for reference and secondary date
@@ -89,7 +105,7 @@ where `m` is the number of (interferometric / offset) pairs.
 
 One could run `info.py` on ANY HDF5 file to display its file structure, e.g.:
 
-```
+```bash
 yunjunz:~/data/test/FernandinaSenDT128/mintpy>$ info.py timeseries.h5
 ******************** Basic File Info ************************
 file name: /Users/yunjunz/data/test/FernandinaSenDT128/mintpy/timeseries.h5
@@ -100,7 +116,7 @@ coordinates : RADAR
 Start Date: 20141213
 End   Date: 20180619
 Number of acquisitions    : 98
-Std. of acquisition times : 0.99 yeras
+Std. of acquisition times : 0.99 years
 ----------------------
 List of dates:
 ['20141213', '20141225', '20150307', '20150319', '20150331', '20150412', '20150424', '20150506', '20150518', '20150530', '20150611', '20150623', '20150717', '20150729', '20150822', '20150903', '20150915', '20150927', '20151009', '20151021', '20151102', '20151114', '20151126', '20151208', '20151220', '20160101', '20160113', '20160125', '20160206', '20160218', '20160301', '20160406', '20160418', '20160430', '20160512', '20160524', '20160605', '20160629', '20160711', '20160723', '20160804', '20160816', '20160828', '20160909', '20160921', '20161003', '20161015', '20161027', '20161108', '20161120', '20161202', '20161214', '20161226', '20170107', '20170119', '20170131', '20170212', '20170224', '20170308', '20170320', '20170401', '20170413', '20170425', '20170507', '20170519', '20170531', '20170612', '20170624', '20170706', '20170718', '20170730', '20170811', '20170823', '20170904', '20170916', '20170928', '20171010', '20171022', '20171103', '20171115', '20171127', '20171209', '20171221', '20180102', '20180114', '20180126', '20180207', '20180219', '20180303', '20180315', '20180327', '20180408', '20180420', '20180502', '20180514', '20180526', '20180607', '20180619']

diff --git a/docs/api/doc_generation.md b/docs/api/doc_generation.md
@@ -1,6 +1,6 @@
 We use [Doxygen](http://www.doxygen.nl/) to generate the API documentation automatically.
 
-+ Install Doxygen following [link](http://www.doxygen.nl/download.html) if you have not already doen so.
++ Install Doxygen following [link](http://www.doxygen.nl/download.html) if you have not already done so.
 
 + Run doxygen command with `MintPy/docs/Doxyfile` to generate the API documentation in html and latex format (to `$MINTPY_HOME/docs/api_docs` by default).
 

diff --git a/docs/dask.md b/docs/dask.md
@@ -106,7 +106,7 @@ smallbaselineApp.py smallbaselineApp.cfg
 
 #### 2.3 Configuration parameters in `~/.config/dask/mintpy.yaml` ####
 
-We provide a brief description below for the most commonly used configurations of dask-jobqueue for MintPy. Users are recommended to check [Dask-Jobqueue](https://jobqueue.dask.org/en/latest/configuration-setup.html) for more detailed and comprehensive documentaion.
+We provide a brief description below for the most commonly used configurations of dask-jobqueue for MintPy. Users are recommended to check [Dask-Jobqueue](https://jobqueue.dask.org/en/latest/configuration-setup.html) for more detailed and comprehensive documentation.
 
 + **name:** Name of the worker job as it will appear to the job scheduler. Any values are perfectly fine.
 

diff --git a/docs/dir_structure.md b/docs/dir_structure.md
@@ -388,6 +388,10 @@ mintpy.load.waterMaskFile    = $DATA_DIR/SanFranSenDT42/mask/watermask.msk
 
 Here is an example workflow: [smallbaselineApp_hyp3](https://nbviewer.jupyter.org/github/insarlab/MintPy-tutorial/blob/main/smallbaselineApp_hyp3.ipynb).
 
+HyP3 produces two types of InSAR products: 1) scene-wide products using Gamma and 2) burst-wide products using ISCE2.
+
++ INSAR_GAMMA directory structure:
+
 ```
 $DATA_DIR/RidgecrestSenDT71
 ├── hyp3
@@ -410,6 +414,30 @@ $DATA_DIR/RidgecrestSenDT71
     └── RidgecrestSenDT71.txt
 ```
 
++ INSAR_ISCE2_BURST directory structure:
+
+```
+$DATA_DIR/MtEdgecumbeSenAT174
+├── hyp3
+│   ├── S1_372326_IW3_20141017_20141110_VV_INT80_7044
+│   │   ├── S1_372326_IW3_20141017_20141110_VV_INT80_7044_dem_clipped.tif
+│   │   ├── S1_372326_IW3_20141017_20141110_VV_INT80_7044_corr_clipped.tif
+│   │   ├── S1_372326_IW3_20141017_20141110_VV_INT80_7044_lv_theta_clipped.tif
+│   │   ├── S1_372326_IW3_20141017_20141110_VV_INT80_7044_lv_phi_clipped.tif
+│   │   ├── S1_372326_IW3_20141017_20141110_VV_INT80_7044_unw_phase_clipped.tif
+│   │   ├── S1_372326_IW3_20141017_20141110_VV_INT80_7044_water_mask_clipped.tif
+│   │   ├── S1_372326_IW3_20141017_20141110_VV_INT80_7044.txt
+│   │   └── ...
+│   ├── S1_372326_IW3_20141110_20141204_VV_INT80_1894
+│   │   ├── S1_372326_IW3_20141110_20141204_VV_INT80_1894_corr_clipped.tif
+│   │   ├── S1_372326_IW3_20141110_20141204_VV_INT80_1894_unw_phase_clipped.tif
+│   │   ├── S1_372326_IW3_20141110_20141204_VV_INT80_1894.txt
+│   │   └── ...
+│   └── ...
+└── mintpy
+    └── MtEdgecumbeSenAT174.txt
+```
+
 The corresponding template options for `load_data`:
 
 ```cfg

diff --git a/docs/docker.md b/docs/docker.md
@@ -45,7 +45,7 @@ docker run -it -v </path/to/data/dir>:/home/mambauser/data ghcr.io/insarlab/mint
 docker run -it -v </path/to/data/dir>:/home/mambauser/data ghcr.io/insarlab/mintpy:latest smallbaselineApp.py /home/mambauser/data/FernandinaSenDT128/mintpy/FernandinaSenDT128.txt
 ```
 
-Or run the following to launch the Jupyter Lab server, then copy and paste the printed `http://localhost:8888/lab?token=` url in a brower.
+Or run the following to launch the Jupyter Lab server, then copy and paste the printed `http://localhost:8888/lab?token=` url in a browser.
 
 ```shell
 # to launch a Jupyter Notebook frontend, replace "lab" with "notebook" in the command below

diff --git a/docs/google_earth.md b/docs/google_earth.md
@@ -26,7 +26,7 @@ save_kmz_timeseries.py embeds a [dygraphs](http://dygraphs.com) javascript for i
 
 The script also use the [regions KML feature](https://developers.google.com/kml/documentation/regions) to support very large datasets without sacrificing resolution. It divides the data matrix into regionalized boxes, nests them using network links so that Google Earth could load them in a "smart" way.
 
-**Alert: for very large datasets, the default settings are not generic due to the various computer memories, data sizes and different prefered details. The user is highly recommended to read the following to understand how the regions feature works and adjust parameters accordingly.**
+**Alert: for very large datasets, the default settings are not generic due to the various computer memories, data sizes and different preferred details. The user is highly recommended to read the following to understand how the regions feature works and adjust parameters accordingly.**
 
 1. Level of Detail (LOD)