mehdizadehm · mehdizadehm · Nov 14, 2020 · Jul 21, 2020 · Aug 21, 2020 · Aug 11, 2020
diff --git a/.gitignore b/.gitignore
@@ -2,14 +2,15 @@
 *.pyc
 *.idea/*
 *ipynb_checkpoints*
+*.egg*
 build/
+dist/
 docs/api_docs/
-docs/examples/dev/*
 docs/resources/*logo*
 docs/resources/*.ai
 docs/resources/*.pdf
+docs/deps.svg
 isce.log
-mintpy/dev/*
 mintpy/modis*
+mintpy/objects/solid/solid_f.*.so*
 site/
-test/unwrap_error_bridging/
diff --git a/MANIFEST.in b/MANIFEST.in
@@ -0,0 +1,6 @@
+# Include the README
+include docs/README.md
+
+# Include the license file
+include LICENSE
+
diff --git a/docs/FAQs.md b/docs/FAQs.md
@@ -0,0 +1,13 @@
+## Frequently Asked Questions
+
+#### 1. What's the sign convention of the line-of-sight data?
+
+For line-of-sight (LOS) phase in the unit of radians, i.e. 'unwrapPhase' dataset in `ifgramStack.h5` file, positive value represents motion away from the satellite. We assume the "date1_date2" format for the interferogram with "date1" being the earlier acquisition.
+
+For LOS displacement in the unit of meters, 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 InSAR software rather than ISCE stack processors and ARIA-tools?
+
+
+
+
diff --git a/docs/README.md b/docs/README.md
@@ -1,14 +1,14 @@
-[![Language](https://img.shields.io/badge/python-3.5%2B-blue.svg)](https://www.python.org/)
+[![Language](https://img.shields.io/badge/python-3.6%2B-blue.svg)](https://www.python.org/)
 [![Docs Status](https://readthedocs.org/projects/mintpy/badge/?version=latest)](https://mintpy.readthedocs.io/?badge=latest)
 [![CircleCI](https://img.shields.io/circleci/build/github/insarlab/MintPy.svg?color=green&logo=circleci)](https://circleci.com/gh/insarlab/MintPy)
-[![Latest version](https://img.shields.io/badge/latest%20version-v1.2.3-yellowgreen.svg)](https://github.com/insarlab/MintPy/releases)
+[![Version](https://img.shields.io/badge/version-v1.2.3-yellowgreen.svg)](https://github.com/insarlab/MintPy/releases)
 [![License](https://img.shields.io/badge/license-GPLv3-yellow.svg)](https://github.com/insarlab/MintPy/blob/main/LICENSE)
 [![Forum](https://img.shields.io/badge/forum-Google%20Group-orange.svg)](https://groups.google.com/forum/#!forum/mintpy)
 [![Citation](https://img.shields.io/badge/doi-10.1016%2Fj.cageo.2019.104331-blue)](https://doi.org/10.1016/j.cageo.2019.104331)
 
 ## MintPy ##
 
-The Miami INsar Time-series software in PYthon (MintPy) is an open-source package for Interferometric Synthetic Aperture Radar time series analysis. It reads the stack of interferograms (coregistered and unwrapped) in [ISCE](https://github.com/isce-framework/isce2), [ARIA](https://github.com/aria-tools/ARIA-tools), [FRInGE](https://github.com/isce-framework/fringe), [SNAP](http://step.esa.int/), [GAMMA](https://www.gamma-rs.ch/no_cache/software.html) or ROI_PAC format, and produces three dimensional (2D in space and 1D in time) ground surface displacement in line-of-sight direction. It includes a routine time series analysis (`smallbaselineApp.py`) and some independent toolbox.
+The Miami INsar Time-series software in PYthon (MintPy as /mɪnt paɪ/) is an open-source package for Interferometric Synthetic Aperture Radar (InSAR) time series analysis. It reads the stack of interferograms (coregistered and unwrapped) in [ISCE](https://github.com/isce-framework/isce2), [ARIA](https://github.com/aria-tools/ARIA-tools), [FRInGE](https://github.com/isce-framework/fringe), [SNAP](http://step.esa.int/), [GAMMA](https://www.gamma-rs.ch/no_cache/software.html) or ROI_PAC format, and produces three dimensional (2D in space and 1D in time) ground surface displacement in line-of-sight direction. It includes a routine time series analysis (`smallbaselineApp.py`) and some independent toolbox.
 
 This package was called PySAR before version 1.1.1. For version 1.1.2 and onward, we use MintPy instead. 
 
@@ -45,7 +45,7 @@ Configuration parameters for each step are initiated with default values in a cu
 wget https://zenodo.org/record/3952953/files/FernandinaSenDT128.tar.xz
 tar -xvJf FernandinaSenDT128.tar.xz
 cd FernandinaSenDT128/mintpy
-smallbaselineApp.py ${MINTPY_HOME}/docs/examples/input_files/FernandinaSenDT128.txt
+smallbaselineApp.py ${MINTPY_HOME}/mintpy/data/input_files/FernandinaSenDT128.txt
 ```
 
 <p align="left">
@@ -67,7 +67,7 @@ save_kmz_timeseries.py     #generate Goodle Earth KMZ file in points for time-se
 
 #### 2.2 Customized processing recipe ####
 
-MintPy is a toolbox with individual utility scripts. Simply run the script with `-h / --help` to see its usage, you could build your own customized processing recipe! [Here](../sh/compare_velocity_with_diff_tropo.sh) is an example to compare the velocities estimated from displacement time-series with different tropospheric delay corrections.
+MintPy is a toolbox with individual utility scripts. Simply run the script with `-h / --help` to see its usage, you could build your own customized processing recipe! [Here](../mintpy/sh/compare_velocity_with_diff_tropo.sh) is an example to compare the velocities estimated from displacement time-series with different tropospheric delay corrections.
 
 #### 2.3 Build on top of `mintpy` module ####
 
@@ -84,7 +84,7 @@ Algorithms implemented in the software are described in details at [Yunjun et al
 
 + [Quick start with example datasets](./demo_dataset.md)
 + [Example data directory](./dir_structure.md)
-+ [Example template files for InSAR processors](./examples/input_files/README.md)
++ [Example template files for InSAR processors](./../mintpy/data/input_files/README.md)
 + [Tutorials in Jupyter Notebook](https://github.com/insarlab/MintPy-tutorial)
 
 ### 4. Contact us ###

diff --git a/docs/api/attributes.md b/docs/api/attributes.md
@@ -1,8 +1,8 @@
-MintPy mainly uses attribute names from [ROI_PAC](http://www.geo.cornell.edu/eas/PeoplePlaces/Faculty/matt/pub/winsar/InSAR_textbook_for_web_2014.pdf), with some additional attributes generated by MintPy itself.
+MintPy mainly uses attribute names from [ROI_PAC](http://www.geo.cornell.edu/eas/PeoplePlaces/Faculty/matt/pub/winsar/InSAR_textbook_for_web_2014.pdf), with some additional self-generated attributes.
 
 ### Required attributes ###
 
-If using ROI_PAC as InSAR processor, both **baseline parameter RSC** file (i.e. *100416-100901_baseline.rsc*) and **basic metadata file** (i.e. *filt_100416-100901-sim_HDR_4rlks_c10.unw.rsc*) will be imported into MintPy. The following attributes for each interferogram are required in order to run MintPy:
+If using ROI_PAC as the InSAR processor, both **baseline parameter RSC** file (i.e. *100416-100901_baseline.rsc*) and **basic metadata file** (i.e. *filt_100416-100901-sim_HDR_4rlks_c10.unw.rsc*) will be imported into MintPy. The following attributes for each interferogram are required in order to run MintPy:
 
 +  FILE_LENGTH = number of rows.  
 +  WIDTH = number of columns.  
@@ -15,30 +15,33 @@ If using ROI_PAC as InSAR processor, both **baseline parameter RSC** file (i.e.
 +  CENTER_LINE_UTC = Time at middle of interferogram in seconds, used in tropo correction using PyAPS.   
 +  HEIGHT = Height of satellite in meters, used in dem_error, incidence_angle, convert2mat.   
 +  STARTING_RANGE = Distance from satellite to first ground pixel in meters, used in incidence_angle calculation   
-+  DATE12 = (date1)-(date2), reference - secondary date of interferogram in 6 digit number.   
 +  PLATFORM = satellite/sensor name, used in Local Oscillator Drift correction for Envisat.   
 +  ORBIT_DIRECTION = ascending, or descending.   
++  ALOOKS/RLOOKS = multilook number in azimuth/range direction, used in weighted network inversion.
+
+The following attributes vary for each interferogram:
+
++  DATE12 = (date1)-(date2), reference - secondary date of interferogram in 6 digit number.   
 +  P_BASELINE_TOP_HDR = Perpendicular baseline at top (first line) of interferogram in meters.   
 +  P_BASELINE_BOTTOM_HDR = Perpendicular baseline at bottom (last line) of interferogram in meters.   
-+  ALOOKS/RLOOKS = multilook number in azimuth/range direction, used in weighted network inversion.
-
+
 ### Optional attributes ###
 
 +  ANTENNA_SIDE = -1 for right looking radar, used in save_unavco
 +  AZIMUTH_PIXEL_SIZE = Azimuth pixel size at orbital altitude (multiply by Re/(Re+h) for ground size (m), where Re is the local earth radius), used in baseline_error/trop and multilook.   
 +  HEADING = Spacecraft heading at peg point (degree), used in asc_desc, los2enu   
 +  PRF = Pulse repetition frequency (Hz), used in save_unavco   
 
-### Attributes generated by MintPy automatically ###
+### Self-generated attributes ###
 
 +  FILE_TYPE = file type.
     - for HDF5 files, it's the root level dataset name, such as `velocity, timeseries, ifgramStack, temporalCoherence, mask, HDFEOS, dem, coherence, etc.`;`
     - for binary files, it's the file extension name, such as `.unw, .cor, .int, .amp, .mli, .dem, .hgt, .unw.conncomp, .UTM_TO_RDC, .trans, etc.`, except for ISCE geometry files, which is the file base name such as `hgt, lat, lon, los, shadowMask, incLocal`.  
 +  FILE_PATH = absolute file path   
 +  LENGTH = row number, equivalent to FILE_LENGTH
-+  PROCESSOR = processing software, i.e. isce, roipac, gamma
++  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
-+  UNIT = data unit, i.e. m, m/yr, radian, and 1 for file without unit, such as coherence
++  UNIT = data unit, i.e. m, m/yr, radian, and 1 for file without unit, such as coherence [[source]](https://github.com/insarlab/MintPy/blob/main/mintpy/objects/stack.py#L75)
 +  REF_DATE = reference date
 +  REF_X/Y/LAT/LON = column/row/latitude/longitude of reference point
 +  SUBSET_XMIN/XMAX/YMIN/YMAX = start/end column/row number of subset in the original coverage
@@ -47,4 +50,4 @@ If using ROI_PAC as InSAR processor, both **baseline parameter RSC** file (i.e.
 
 ### Reference ###
 
-+ Pritchard et al., (2014), Open-source software for geodetic imaging: ROI_PAC for InSAR and pixel tracking, pp 44-48. [PDF](http://www.geo.cornell.edu/eas/PeoplePlaces/Faculty/matt/pub/winsar/InSAR_textbook_for_web_2014.pdf)
++ Pritchard et al., (2014), Open-source software for geodetic imaging: ROI_PAC for InSAR and pixel tracking, pp 44-48. [PDF](http://www.geo.cornell.edu/eas/PeoplePlaces/Faculty/matt/pub/winsar/InSAR_textbook_for_web_2014.pdf)
diff --git a/docs/resources/colormaps/README.md → docs/api/colormaps.md b/docs/resources/colormaps/README.md → docs/api/colormaps.md
@@ -4,7 +4,7 @@ MintPy support the following colormaps:
 
 + [Matplotlib colormaps](https://matplotlib.org/3.1.0/tutorials/colors/colormaps.html)
 + Custom colormaps: `cmy` and `dismph`
-+ Custom colormaps in **.cpt** (color palette tables) format. To add your own colormap, drop the corresponding .cpt file in `$MINTPY/docs/resources/colormaps`.
++ Custom colormaps in **.cpt** (color palette tables) format. To add your own colormap, drop the corresponding .cpt file in `$MINTPY/mintpy/data/colormaps`.
 
 We recommend to use cyclic colormap `cmy` for wrapped phase/displacement measurement.
 
@@ -63,5 +63,5 @@ The following colormaps is included by default:
 + More at [Scientific Color-Maps](http://www.fabiocrameri.ch/colourmaps.php) ([Crameri, 2018](https://doi.org/10.5194/gmd-11-2541-2018))
 
 <p align="left">
-  <img width="600" src="http://www.fabiocrameri.ch/resources/ScientificColourMaps_FabioCrameriCompact.png">
+  <img src="http://www.fabiocrameri.ch/resources/ScientificColourMaps_FabioCrameri.png">
 </p>
diff --git a/docs/api/module_hierarchy.md b/docs/api/module_hierarchy.md
@@ -51,7 +51,7 @@ Hierarchy of sub-modules within MintPy. Level N modules depends on level N-1, N-
     /utils
         plot          (objects/{stack, coord, colors}, utils/{ptime, utils0, utils1, readfile, network})
         utils         (objects/{stack, coord},         utils/{ptime, utils0, utils1, readfile})
-        isce_utils    (utils/{readfile, writefile, utils1})
+        isce_utils    (utils/{ptime, readfile, writefile, utils1})
 ------------------ level 6 --------------------
     /objects
         insar_vs_gps  (objects/{stack, giant}, utils/{readfile, gps, plot, utils})

diff --git a/docs/conda.txt b/docs/conda.txt
@@ -12,6 +12,7 @@ matplotlib
 netcdf4
 numpy
 openmp
+pip
 pygrib
 pyhdf
 pykdtree

diff --git a/docs/dask.md b/docs/dask.md
@@ -55,7 +55,7 @@ A typical run time without local cluster is 30 secs and with 8 workers 11.4 secs
 
 To show the run time improvement, we test three datasets (South Isabela, Fernandina, and Kilauea) with different number of cores and same amount of allocated memory (4 GB) on a compute node in the [Stampede2 cluster's skx-normal queue](https://portal.tacc.utexas.edu/user-guides/stampede2#overview-skxcomputenodes). Results are as below:
 
-![Dask LocalCluster Performance](https://github.com/insarlab/MintPy-tutorial/blob/main/docs/dask_local_cluster_performance.png)
+![Dask LocalCluster Performance](https://yunjunzhang.files.wordpress.com/2020/08/dask_local_cluster_performance.png)
 
 #### 1.5 Known problems ####
 

diff --git a/docs/demo_dataset.md b/docs/demo_dataset.md
@@ -10,7 +10,7 @@ Size: ~750 MB
 wget https://zenodo.org/record/3952953/files/FernandinaSenDT128.tar.xz
 tar -xvJf FernandinaSenDT128.tar.xz
 cd FernandinaSenDT128/mintpy
-smallbaselineApp.py ${MINTPY_HOME}/docs/examples/input_files/FernandinaSenDT128.txt     
+smallbaselineApp.py ${MINTPY_HOME}/mintpy/data/input_files/FernandinaSenDT128.txt     
 ```
 
 <p align="left">
@@ -21,6 +21,27 @@ Relevant literature:
 
 + Yunjun, Z., H. Fattahi, and F. Amelung (2019), Small baseline InSAR time series analysis: Unwrapping error correction and noise reduction, _Computers & Geosciences, 133,_ 104331, doi:10.1016/j.cageo.2019.104331.
 
+#### Sentinel-1 on San Francisco Bay with ARIA ####
+
+Area: San Francisco Bay, California, USA     
+Data: Sentinel-1 A/B descending track 42 during May 2015 - March 2020 (114 acquisitoins; [Zenodo](https://zenodo.org/record/4265413))    
+Size: ~2.7 GB
+
+```bash
+wget https://zenodo.org/record/4265413/files/SanFranSenDT42.tar.xz
+tar -xvJf SanFranSenDT42.tar.xz
+cd SanFranSenDT42/mintpy
+smallbaselineApp.py ${MINTPY_HOME}/mintpy/data/input_files/SanFranSenDT42.txt     
+```
+
+<p align="left">
+  <img width="650" src="https://yunjunzhang.files.wordpress.com/2020/11/sanfransendt42_transect.jpg">
+</p>
+
+Relevant literature:
+
++ Chaussard, E., R. Bürgmann, H. Fattahi, R. M. Nadeau, T. Taira, C. W. Johnson, and I. Johanson (2015), Potential for larger earthquakes in the East San Francisco Bay Area due to the direct connection between the Hayward and Calaveras Faults, Geophysical Research Letters, 42(8), 2734-2741, doi:10.1002/2015GL063575.
+
 #### Envisat of the 2008 Wells earthquake with Gamma ####
 
 Area: Wells, Nevada, USA       
@@ -31,7 +52,7 @@ Size: ~280 MB
 wget https://zenodo.org/record/3952950/files/WellsEnvD2T399.tar.xz
 tar -xvJf WellsEnvD2T399.tar.xz
 cd WellsEnvD2T399/mintpy
-smallbaselineApp.py ${MINTPY_HOME}/docs/examples/input_files/WellsEnvD2T399.txt
+smallbaselineApp.py ${MINTPY_HOME}/mintpy/data/input_files/WellsEnvD2T399.txt
 ```
 
 <p align="left">
@@ -42,6 +63,19 @@ Relevant literature:
 
 + Nealy, J. L., H. M. Benz, G. P. Hayes, E. A. Bergman, and W. D. Barnhart (2017), The 2008 Wells, Nevada, Earthquake Sequence: Source Constraints Using Calibrated Multiple‐Event Relocation and InSARThe 2008 Wells, Nevada, Earthquake Sequence: Source Constraints Using Calibrated Multiple‐Event Relocation, _Bulletin of the Seismological Society of America_, 107(3), 1107-1117, doi:10.1785/0120160298.
 
+#### Sentinel-1 on Western Cape, South Africa with SNAP ####
+
+Area: West coast of Western Cape province, South Africa        
+Data: Sentinel-1 ascending track 29 during March - June 2019 (10 acquisitions; [Zenodo](https://zenodo.org/record/4127335))       
+Size: ~560 MB
+
+```bash
+wget https://zenodo.org/record/4127335/files/WCapeSenAT29.tar.xz
+tar -xvJf WCapeSenAT29.tar.xz
+cd WCapeSenAT29
+smallbaselineApp.py ${MINTPY_HOME}/mintpy/data/input_files/WCapeSenAT29.txt
+```
+
 #### ALOS-1 on Kuju with ROI_PAC ####
 
 Area: Kuju volcano at Kyushu island, SW Japan     
@@ -52,7 +86,7 @@ Size: ~240 MB
 wget https://zenodo.org/record/3952917/files/KujuAlosAT422F650.tar.xz
 tar -xvJf KujuAlosAT422F650.tar.xz
 cd KujuAlosAT422F650/mintpy
-smallbaselineApp.py ${MINTPY_HOME}/docs/examples/input_files/KujuAlosAT422F650.txt     
+smallbaselineApp.py ${MINTPY_HOME}/mintpy/data/input_files/KujuAlosAT422F650.txt     
 ```
 
 <p align="left">
-Original file line number
+Diff line change
@@ Expand Up / @@ -12,6 +12,7 @@ matplotlib @@
     netcdf4
     numpy
     openmp
+    pip
     pygrib
     pyhdf
     pykdtree
@@ Expand Down @@