+ prep_snap: hardwire attributes X/Y_UNIT = 'degrees'
+ tropo_pyaps3: add default value of degrees for Y_UNIT attribute
+ save_kmz: fix typo in the examplage usagge
+ docs/api/colormaps: update to the latest link of matplotlib colormaps

* generate_mask: mask velocity based on velocityStd

Generate mask based on formula |velocity| > cutoff * velocitStd
- adds --vstd and --vstd-num options
- adds mask generation functionality in create_threshold_mask()

+ utils.readfile.read_gdal_vrt(): support reading metadata from file without SRS info by setting defalt X/Y_UNIT in degrees
+ defaults.smallbaselineApp.cfg: add comments on SNAPHU as the only unwrapper that provides connected components info.
+ dask: use explicit cluster name instead of non-local to avoid confusion in the smallbaselineApp.cfg and dask.md files.
+ view: printout multilook-num even if not calculated from auto_*(); plot water/shadowMask in gray by default

Testing shows that numpy/scipy with OMP_NUM_THREADS > 1 does not help much on the computing time but uses significantly more CPU. The true fast way is "Dask with multiple workers + OMP_NUM_THREADS = 1". Thus, I am setting all the relevant NUM_THREADS env variables to 1, in ifgram_inversion.py and dem_error.py, before running the big matrix inversion and roll back to the original values afterwards.

+ objects/cluster:
   - add set_num_threads() to save original num of threads info and set all relevant env var to the given value
   - add roll_back_num_threads() to roll back to the original setting

+ ifgram_inversion/dem_error: call the above two functions in the begining and the end of the process, to ignore the *_NUM_THREADS setting during the numpy/scipy matrix computation.

For non-exist env variables, set to "1" and remove them afterward. This makes sure that even if one does not set any NUM_THREADS related env variables, the NUM_THREADS limit would still work.

+ resample:
   - auto split for non-h5 file
   - constrain lat/lon dataset in float32, to save memory usage

+ writefile:
   - write(): keep magnitude info for .unw/.int file if fed
   - add write_complex_float32() to properly write complex float32 matrix

+ geocode: add --lat/lon-file option to grab isce lat/lon.rdr file path

+ multilook/subset: write GDAL VRT & ISCE XML file if the input file is generated by ISCE-2 directly
+ utils.readfile: add NUMPY2GDAL_DATATYPE global var
+ [WIP] utils.writefile: add write_gdal_vrt() given the mintpy metadata dict. [work in progress]. !DO NOT USE IT!

+ view.prep_slice(): bugfix for the missing argv, which affects plot_coherence_matrix.py
+ prep_aria: update ariaTSsetup.py example usage in the help msg

Co-authored-by: Zhang Yunjun <yunjunzgeo@gmail.com>

+ add `prep_cosicorr.py` to prepare metadata of COSI-Corr offset products for MintPy, with example usages
+ `load_data.py`: add `cosicorr` as a processor and call prep_cosicorr.py
+ `utils.readfile.py`: read GeoTIFF file produced by `cosicorr` via GDAL
+ `ifgram_inversion.py`:  disable unit conversion from pixel to meter for cosicorr, since it is in meters natively

…ing (#629)

use np.random.Generator.choice() as recommended by numpy (https://numpy.org/doc/stable/reference/random/index.html#random-quick-start)

+ utils.readfile.read_attribute(): fix a bug of grabbing the UNIT for HDF5 dataset, if `datasetName` is specified with date info as suffix. This only affects the unit display in the colorbar for plotting.
+ utils.utils1.get_residual_std/rms(): use np.float32 to replace np.float to avoid numpy deprecation warning
+ view: print WARNING msg regardless of --verbose setting
+ tsview: more friendly figsize_img API for the interactive tsview.ipynb in MintPy-tutorial repo
+ plot_network: fix --nodisplay bug while calling from jupyter notebook
+ install: use bash *.sh to replace chmod +x cmd in docs/installation.md and .circleci/config.yml files

+ add.py:
   - check num of files == 2 for TS file only
   - support two TS file with different reference point, different reference date, different date list; to be consistent with diff.py.
+ diff.py: `_check_reference()` -> `check_reference()` with more comments
+ view: expand --math to multi-subplots
+ save_gdal: use float32 as default to save disk
+ sbApp: plot geo_avgSpatialCoh.h5 file
+ utils.readfile: more relaxed wildcard filename for offset file from ampcor
+ utils.ptime.get_date_range(): add 'dstep' option for coarser list to speedup matrix operation laterward

instead of from FILE_PATH, as it's a more reliable and flexible source.

Currently, the file attributes are modified in the `asc_desc_files2horz_vert` function to take account of the fact that we're looking at the overlap between two tracks. However, the `write_to_one_file` as currently written overwrites the input `atr` variable when looping over the list of attributes for the input files. The least to the attributes of the newly created file being incorrect.

+ Properly pass the azimuth variable: The azimuth variable is supplied as part of the command line input, however, it's not actually passed to the `get_design_matrix` function where it is needed, meaning the command line variable does nothing and the azimuth angle defaults to 90 degrees. I've added code to pass it through to the design matrix function, so now the azimuth angle can be modified via the command line.

+ use `los_az_angle` for the direction of LOS vector throughout the script, and to replace `head_angle` to be consistent with the rest of mintpy

+ ALERT: use `azimuth` in anti-clockwise for consistency. The version before is using a clock-wise direction.

Co-authored-by: Zhang Yunjun <yunjunzgeo@gmail.com>

This PR addresses the error of missing API config for PyAPS. If the user did not input their API credentials in `model.cfg` in the pyaps3 directory it raised a vague ZeroDivisionError: float division by zero error. This revision adds `check_pyaps_account_config()`, which will now raise a ValueError with a more appropriate error message telling users that the API config is missing.

Note that:
+ the function includes checking for ERA5/ERAI/NARR/MERRA for completeness, although tropo_pyaps3.py only accepts ERA5 for now.
+ the function checks both default(demo/invalid) options values as well as empty values, but it can not really check the validity of the user account.

…st) (#640)

+ prep_hyp3:
   - ensure negative HEADING value
   - grab CENTER_LINE_UTC from UTCtime directly
   - put P_BASELINE_* to the ifgram specific metadata
   - add STARTING_RANGE from "Slant range near"
   - add RANGE/AZIMUTH_PIXEL_SIZE from hardwired Sentinel-1 info
   - adjust to the new incidence angle file name 'lv_theta'

+ stackDict:
   - convert Gamma inc angle to isce/mintpy inc angle convention while loading the data for hyp3
   - consider the above conversion while calc slantRangeDistance from incidence angle for hyp3

+ docs/dir_struct*/hyp3: add inc angle and water mask path
   - remove warning for inc angle as the latest HyP3 is producing the correct one now
   - add geometry file path in the template for incidence angle and water mask
  - use Ridgecrest SenT71 dataset for the example in the directory structure

* readfile.read(): add data_type to customized output data type
* tropo_pyaps3.py.check_pyaps_account_config(): typo fix

This PR modifies readfile/writefile to read and write complex binary files (from isce-2) directly in complex data type by default.

For plotting in view.py, which requires real data type, I add readfile.get_slice_list(no_complex) option to translate complex into mag/phase for plotting. This option is turn off by default for generic I/O.

+ readfile:
   - read_binary_file(): for "slc", set cpx_band to "complex" unless mag/phase is clearly specified.
   - get_slice_list(): 1) ignore meaningless geo/rdr file extension; 2) add "no_complex" arg to switch between complex (for I/O) and mag/phase (for plotting)

+ writefile:
   - write(): for .slc/.int, write complex directly
   - write_isce_xml(): add "image_type" arg to initiate different ISCE-2 image objects for better compatiability
   - write_isce_file(): support file_type == 'isce_slc'
   - comment out obsolete write_complex64() as write_complex_float32() is equivalent but simpler and faster.

+ subset/multilook: update usage of writefile.write_isce_xml()

+ view: update usage of readfile.get_slice_list()

Other minor changes:
+ subset.py: add --sub-x/y/lat/lon and --subset-x/y/lat/lon to be consistent with subset option names in other scripts.
+ view.py: add --nmli / --num-multilook for --multilook-num
+ simulation.simulation.py: typo fix and add missing wvl arg while calling timeseries2ifgram()
+ objects.sensor: typo fix for doppler_bandwidth

+ save_gdal.py: Fix bug when dealing with UTM projections, such as provided by hyp3, by adding additional arguments for EPSG code.
+ readfile.read_gdal_vrt(): add "EPSG" to file attributes
+ utils0.py: add new function `utm_zone2epsg_code()`

+ smallbaselineApp.py: limit the number of parallel processes for plotting based on the max memory from the template file, to avoid exceeding the memory. Circle CI kills processes because of this. Note that matplotlib reserved much larger memory than it actually uses.

For users who want to use a lot of parallel processes for plotting, please increase your `mintpy.compute.maxMemory` setting.

+ view.py: add --memory option. Note this is NOT used in the smallbaselineApp.py

+ plot.auto_multilook_num():
   - more detailed multilook num list, for a more detailed memory manegement.
   - add max_memory arg to adjust according. Details are in the code comments.

+ add quotes to the version control for conda/mamba install in command line in docs/installation.md and .circleci/config.yml files
+ circleci: use pip from conda to avoid warning msg
+ docs/api/attributes.md: add EPSG

+ simplify the triplet matrix building by using `itertools.combinations(date_list, 3)`, instead of the previous `for` loop search and check
+ create inverse mapping objects to speed up the indexing. Testing shows more than 10X speedup for large matrix.

+ add documentation on installing in windows

+ fix a few bugs that prevent running through the example

+ add an independent link to installation on read the docs.

Co-authored-by: Joseph H Kennedy <me@jhkennedy.org>

+ ptime.get_date_range(): add dunit and out_fmt
   - add `dunit` arg with default value as before
   - add `out_fmt` arg with default value as before

+ smallbaselineApp.plot_result(): use floor() instead of rint() as a more conservative num calc for parallel processes

+ unwrap_error_phase_closure: print out # of ifg/triplets

+ `mintpy/__inti__.py`: 
   - remove try/except for print and MINTPY_HOME as it's not really used anywhere, and their corresponding module imports.
   - remove `sys.path.insert()` calls. These were replicates from the isce-2 style (isceobj, iscesys, etc.), but they are not really applicable to and used in mintpy, nor had we encouraged in any other files besides this one.

**NOTE**: however, this might still potentially impact downstream workflows, thus, should be noted in the release notes/changelog.

+ test_smallbaselineApp.py:
   - use the relative path to locate config file, instead of using mintpy module
   - remove the occurrence of MINTPY_HOME
   - remove print view.py cmd as it's now included inside view.py if --noverbose is turned ON
   - use `pathlib.Path().resolve()` instead of `os.path.dirname()`

+ `read/plot`: support `geometry` h5 file with other undefined datasets, e.g. "displacement", which is useful for single-pair displacement products for generic sharing purposes.
+ `read.read_attribute()`: ignore Std while grabbing `UNIT`
+ `writefile.write()`: add optional `ds_unit_dict` arg to specify different data unit for each dataset, same as `layout_hdf5()`
+ `geocode`: same h5 compression bwt. input/output

…670)

This PR adds the following new features for more flexible visualization:

1. add `--mask-dem` option to support masking out DEM pixels to be consistent with the masked data matrix

2. add `--mask-gps` option to mask out GNSS sites out of the displayed data matrix.

3. support `--gps-comp horz / vert` to plotting horizontal and vertical GPS components. The horizontal azimuth angle can be adjusted using `--hz-az` option.

4. support American length unit for display.

Detailed changes:

+ asc_desc2horz_vert: set FILE_TYPE to displacement for ifgramStack, timeseries and HDFEOS file types, instead of the previous unique but meaningless name.

+ objects/gps.py:
   - get_gps_los_obs(): always write both displacement and velocity to CSV file for simplicity
   - use az_angle for LOS projection, instead of head_angle, to be consistent with the rest of mintpy convention.
   - support `horz_az_angle` to project GPS horizontal displacement/velocity to a custom azimuth angle

+ view.py: 
   - save `self.msk` as the final flag matrix for masked out pixels
   - turn OFF auto mask file detection when --zero-mask is specified.

+ utils/plot.py:
   - prepare_dem_background(): support masking of DEM shade and contour for --mask-gps
   - plot_gps(): pruning GNSS list based on self.msk for --mask-gps
   - scale_data2disp_unit(): support American unit: inch, foot, yard and mile.

Co-authored-by: Zhang Yunjun <yunjunzgeo@gmail.com>

+ docs/api/attributes: add BANDS and INTERLEAVE to the standard mintpy self-generated metadata list

+ use "BANDS" instead of "number_bands" across mintpy

+ use "INTERLEAVE" instead of "scheme" across mintpy

+ readfile: grabbing BANDS and INTERLEAVE through standard metadata dict whenever they are available

+ writefile:
   - write(): update BANDS according to the input data list
   - write_isce_xml(): refactor to take mintpy attributes dict as input, for user friendly usage

+ add/update write_isce_xml() usage in geocode.py, subset.py and multilook.py

+ utils.plot.auto_figure_title: keep suffix for single-subplot from multi-dset file

+ writefile: add write_binary() for generic binary file writing, similar to the generic binary reading in readfile.read_binary().

+ writefile.write(): use write_binary() for simpler and more powerful writing support

* fix bug related to `--mask-dem` option when DEM shades and contours do not exist at the same time.

+ sensor:
   - add NISAR L-band SAR: only a few parameters from the handbook
   - add altitude value for all sensors
   - add range pixel size for ALOS-1 stripmap

+ utils.utils0.py: add is_number()

+ view: YYYY-MM-DD style subplot title for py2-mintpy TS file

…ce (#682)

+ utils.writefile.layout_hdf5(): support using binary file as structure reference to create empty HDF5 files, using the metadata and slice(s) info.

+ simplify the code with vprint()

+ sensor:
   - add seasat PRF
   - add NISAR range_pixel_size

+ ERA5: consistent naming with better error msg
   - use ERA5 thoughout mintpy without hyphen, to avoid confusion.
   - smallbaselineApp.py: raise error for un-recognized GAM names

+ timeseries_rms: simplify plot

+ utils/plot: omit "Time [year]" xaxis label to save space as it's not informative

+ prep_snap: fix typo

* Dockerfile: rewrite using Micromamba Image

- Rewrites the MintPy dockerfile using the mambaorg/micromamba image
- Forces Python=3.6 for faster image build
- Sets the user as micromamba, not root
- Optionally allows the image to start with a Jupyter Lab instance

* Dockerfile: fix codacy issues

- tag micromamba version
- remove apt-get lists

* Update docker/Dockerfile

Co-authored-by: Joseph H Kennedy <me@jhkennedy.org>

* Dockerfile: reconfigure user

* Dockerfile: reconfigure user 2

* Dockerfile: pull-request updates

- hard code MINTPY_HOME and PYAPS_HOME
- install wget
- update installation.md and docker.md

* Update docker.md

* Update installation.md

* Update Dockerfile

* Update docker/Dockerfile

Co-authored-by: Joseph H Kennedy <me@jhkennedy.org>

* Update docker/Dockerfile

Co-authored-by: Joseph H Kennedy <me@jhkennedy.org>

Co-authored-by: Joseph H Kennedy <me@jhkennedy.org>
Co-authored-by: Zhang Yunjun <yunjunzgeo@gmail.com>

* spatial_filter: refactor double difference

- combine the local and regional filter into
  one filter to reduce number of
  convolutional operations
- change regional filter shape from a disk to
  a doughnut

* spatial_filter: update double_difference docs

+ cluster.format_num_worker(): divide the number of cores by the number of threads if found [for Linux only] using lscpu command. Note again that this only affects the translation of numWorker = all. 

+ smallbaselineApp.plot_result(): translate numWorker = all

+ update API hierarchy of cluster.py as it now depends on utils0.py

ignore the whitespace in all keys while reading the HyP3 metadata file, to be immune to the potential whitespace adding/removing in the upstream HyP3 metadata, such as the UTC time key change from `UTCtime` to `UTC time`.

+ sensor: add pulse_length and chirp_slope for ERS

+ prep_hyp3: replace inc_map with lv_theta, to be consistent with readthedoc

+ save_kmz: more doc on radar-coded file support

+ .circleci/config.yml: add resource_class

+ cluster.DaskCluster:
   - run(): set the num of scaled workers to the num of boxes, to avoid unnecessary resource initiation
   - format_num_worker(): revert "divide num core by num of threads per core" (#691) as it's not right.
   - format_num_worker(): support num of workers in percentage, e.g. 80% to use 80% of all cores

+ ifgram_inversion: use ceil instead of rint to prevent the occurrence of extra small patches.

+ cluster.split_box2sub_boxes:
   - add a min step size constrain
   - trim the final number of boxes, to avoid negative dimension

…699)

* Replace np.float128 object with np.longdouble for a platform-neutral syntax

+ info.py: fix bug introduced in #674. Thank you @falkamelung for reporting it.

+ tropo_pyaps3.snwe2str(): simplify syntax

+ README/badge: use native color for circle CI test result

+ decorrelation: add cross_correlation_std() based on Balmer and Eineder (2005) and De Zan (2014) for the coherent and incoherent speckle tracking.

+ network: add simulate_coherence_v2() for more pythonic usage

to support changing reference point in lat/lon for estimation.

+ view/plot: add --ex-gps option to manually exclude a list of GNSS sites from plotting

+ plot_gps(): for sites with nan value, do not plot dots, instead of plotting a transparent one previously, to be more clear; do not plot ref GNSS site label for a cleaner figure for publication

+ gps.get_gps_los_velocity(): ignore sites if its observation time overlap with InSAR time for less than 25%.

+ simplify the installation since now `pyaps3` and `pysolid` are available via conda-forge, so they are no longer need to be manually cloned and installed anymore. This simplifies the environment setup files and installation notes.

+ since #659, there's no longer a need to manipulate PATH or PYTHONPATH for mintpy anymore, as a "pip install" will correctly place the mintpy package and all executable scripts to be available in the environment.

Co-authored-by: Zhang Yunjun <yunjunzgeo@gmail.com>

+ version.py: add release_history as a list of Tags
   - use Tag from the collection module to save the release history explicitly
   - distinguish between release version number/date and version number/date
   - update version_number/date/description usage in __inti__.py, view.py and smallbaselineApp.py

+ bump the release version number to 1.3.2

which leads error while saving figures to PDF files.

* revert "set matplotlib<3.5 temporarily due to upstream repo bug". This reverts commit d76edb9.

* rm `pykdtree/xarray/zarr` for `pyresample` as they are now properly installed by `conda install pyresample`, thus, no manual setup is needed anymore.

+ objects.resample: Use warnings.catch_warnings() to ignore the potential UserWarning while import pyresample without xarray/zarr installed.

+ objects.coord.geo2radar(): support lon > 180.

+ README: use shields API instead of hardwired value to auto grab the version number in the badge

+ utils0: add round_up_to_odd()

+ github bot: fix typo

+ view: fix argv bug for pip installed version. Catch the manually specified arguments via `sys.argv` for cmd or via `iargs` through python call, and save it to `inps.argv` for later-on checking. Fixed the same issue in save_gbis.py as well.

+ view: add `--math rad2deg/deg2rad`

This PR adds a function to read GMT lon/lat file so that one can plot the faults dataset (created by GMT from KML file) on top of the view.py plot, in Python level ONLY.

+ add `utils.plot.read_gmt_lonlat_file()` to read and plot faults on top of `view.plot_slice()` output
   - add notes and examples on how to prepare the GMT lonlat file from KML file, and use the function in python

+ `objects/gps`:
   - add horz angle to the filename if it's horz and print out file name before the long calc
   - print warning instead of raise error if no GPS found
   - more print out num while comparing with GPS

+ `tsview`: support TS file w/o REF_Y/X

+ `legacy/2to3_timeseries`: change `P_BASELINE_TIMESERIES` to optional