Merge documentation improvements from joss branch

CONTRIBUTING.md

@@ -71,7 +71,7 @@ For bug fixes, a good practice is to write a test which fails with the current c
 ## Creating Documentation
 
 We use [MKDocs](https://www.mkdocs.org/) to generate the documentation.
-The reference documentation is generated from the code docstrings using [mkdocstrings](mkdocstrings.github.io/).
+The reference documentation is generated from the code docstrings using [mkdocstrings](https://mkdocstrings.github.io/python/)
 
 The dependencies for building and viewing the documentation locally can be installed:
 

README.md

@@ -2,6 +2,7 @@
 
 [![Pytest and build docker image](https://github.com/isce-framework/dolphin/actions/workflows/test-build-push.yml/badge.svg?branch=main)](https://github.com/isce-framework/dolphin/actions/workflows/test-build-push.yml)
 [![pre-commit.ci status](https://results.pre-commit.ci/badge/github/isce-framework/dolphin/main.svg)](https://results.pre-commit.ci/latest/github/isce-framework/dolphin/main)
+[![Documentation Status][rtd-badge]][rtd-link]
 [![Conda-Forge][conda-badge]][conda-link]
 [![PyPI platforms][pypi-platforms]][pypi-link]
 [![GitHub Discussion][github-discussions-badge]][github-discussions-link]
@@ -13,6 +14,8 @@
 [pypi-platforms]:           https://img.shields.io/pypi/pyversions/dolphin
 [github-discussions-badge]: https://img.shields.io/static/v1?label=Discussions&message=Ask&color=blue&logo=github
 [github-discussions-link]:  https://github.com/isce-framework/dolphin/discussions
+[rtd-badge]:                https://readthedocs.org/projects/dolphin-insar/badge/?version=latest
+[rtd-link]:                 https://dolphin-insar.readthedocs.io/en/latest/?badge=latest
 <!-- prettier-ignore-end -->
 
 High resolution wrapped phase estimation for Interferometric Synthetic Aperture Radar (InSAR) using combined persistent scatterer (PS) and distributed scatterer (DS) processing.
@@ -21,7 +24,7 @@ High resolution wrapped phase estimation for Interferometric Synthetic Aperture
 
 ## Install
 
-`dolphin` is available on conda:
+`dolphin` may be installed via conda-forge:
 
 ```bash
 # if mamba is not already installed, see here: https://mamba.readthedocs.io/en/latest/
@@ -33,12 +36,12 @@ It is also available via [`PyPI`](https://pypi.org/project/dolphin/) and may be
 `dolphin` has the ability to unwrap interferograms using several options, which can be toggled using the `unwrap_method` configuration option:
 
 1. [`snaphu-py`](https://github.com/isce-framework/snaphu-py), a lightweight Python bindings to [SNAPHU](https://web.stanford.edu/group/radar/softwareandlinks/sw/snaphu/). Available on both pip and conda.
-2. [`isce3`](https://github.com/isce-framework/isce3) offers bindings to the `PHASS` or the `ICU` unwrapping algorithms.
+2. [`isce3`](https://github.com/isce-framework/isce3)'s python bindings to SNAPHU, PHASS, or ICU
 3. [`spurt`](https://github.com/isce-framework/spurt), a 3D unwrapper, implementing the Extended Minimum Cost Flow (ECMF) algorithm
 4. [`tophu`](https://github.com/isce-framework/tophu), a multi-scale unwrapper designed to unwrap large interferograms in parallel tiles at multiple resolution.
 
-These may be installed via conda or (in the case of `snaphu-py`) pip.
 
+These may be installed via conda or (in the case of `snaphu-py`) pip.
 
 To install locally:
 
@@ -80,6 +83,8 @@ Example usage:
 
 ```bash
 dolphin config --slc-files /path/to/slcs/*tif
+# OR: to make a coarser output 4x as quickly:
+# dolphin config --slc-files /path/to/slcs/*tif --strides 2 2
 dolphin run dolphin_config.yaml
 ```
 
@@ -94,8 +99,6 @@ If the SLC files are spread over multiple files, you can either
 
 The full set of options is written to the configuration file; you can edit this file, or you can see which commonly tuned options by are changeable running `dolphin config --help`.
 
-See the [documentation](https://dolphin-insar.readthedocs.io/) for more details.
-
 ## Building and running via Docker
 
 `dolphin` can also be run using Docker. You can use the one built on [Github](https://github.com/isce-framework/dolphin/pkgs/container/dolphin), or build it locally using the script
@@ -104,7 +107,13 @@ See the [documentation](https://dolphin-insar.readthedocs.io/) for more details.
 ./docker/build-docker-image.sh
 ```
 
-See `./docker/build-docker-image.sh --help` for more building options.
+## Contributing
+
+We welcome many forms of contributing, including testing, bug reports, and documentation fixes. If you think you've found a problem, please let us know! You can raise an [issue](https://github.com/isce-framework/dolphin/issues) on the repository, where there are templates for Bug Reports and Feature Requests. If you have a general question of idea, feel free to raise it in the [Discussions](https://github.com/isce-framework/dolphin/discussions) page.
+
+For more detailed guidance on setting up a development environment, including how make and test changes to the code, see [Contributing to Dolphin](CONTRIBUTING.md).
+
+For more general Q&A, please use the [Discussions](https://github.com/isce-framework/dolphin/discussions) page.
 
 ## License
 

docs/getting-started.md

@@ -1,5 +1,5 @@
---8<-- "README.md:19:107"
+--8<-- "README.md:25:100"
 
-For a more complete tutorial, see our [tutorials page](tutorials.md)
+For a more complete tutorial, see our [notebooks](notebooks)
 
 For help with installing locally and contributing, see the [full developer setup instructions](developer-setup.md).

docs/index.md

@@ -6,6 +6,7 @@
 -->
 
 1. [Getting started](./getting-started.md)
+1. [Overview of processing modules](./overview.md)
 1. [Tutorials](tutorials.md)
 1. [Code Reference](reference/summary.md)
 1. [Changelog](changelog.md)

docs/overview.md

@@ -0,0 +1,16 @@
+
+# Overview of Dolphin
+
+Dolphin processes coregistered single-look complex (SLC) radar images into a time series of surface displacement. The software has an end-to-end surface displacement processing workflow, accessible through a command line tool, which calls core algorithms for PS/DS processing:
+
+- The `shp` subpackage estimates the SAR backscatter distribution to find neighborhoods of statistically homogeneous pixels (SHPs) using the generalized likelihood ratio test from @Parizzi2011AdaptiveInSARStack or the Kolmogorov-Smirnov test from @Ferretti2011NewAlgorithmProcessing.
+- The `phase_link` subpackage processes the complex SAR covariance matrix into a time series of wrapped phase using the CAESAR algorithm [@Fornaro2015CAESARApproachBased], the eigenvalue-based maximum likelihood estimator of interferometric phase (EMI) [@Ansari2018EfficientPhaseEstimation], or the combined phase linking (CPL) approach from @Mirzaee2023NonlinearPhaseLinking.
+- The `ps` module selects persistent scatterer pixels from the full-resolution SLCs to be integrated into the wrapped interferograms [@Ferretti2001PermanentScattersSAR].
+- The `unwrap` subpackage exposes multiple phase unwrapping algorithms, including the Statistical-cost, Network-flow Algorithm for Phase Unwrapping (SNAPHU) [@Chen2001TwodimensionalPhaseUnwrapping], the PHASS algorithm (available in the InSAR Scientific Computing Environment [@Rosen2018InSARScientificComputing]), and the Extended Minimum Cost Flow (EMCF) 3D phase unwrapping algorithm via the `spurt` library. Dolphin has pre- and post-processing options, including Goldstein filtering [@Goldstein1998RadarInterferogramFiltering] or interferogram masking and interpolation [@Chen2015PersistentScattererInterpolation].
+- The `timeseries` module contains basic functionality to invert an overdetermined network of unwrapped interferograms into a time series and estimate the average surface velocity. The outputs of Dolphin are also compatible with the Miami INsar Time-series software for users who are already comfortable with MintPy [@Yunjun2019SmallBaselineInSAR].
+
+To meet the computational demands of large-scale InSAR processing, Dolphin leverages Just-in-time (JIT) compilation, maintaining the readability of Python while matching the speed of compiled languages. The software's compute-intensive routines use the XLA compiler within JAX [@Bradbury2018JAXComposableTransformations] for efficient CPU or GPU processing. Users with compatible GPUs can see 5-20x speedups by simply installing additional packages. Dolphin manages memory efficiently through batch processing and multi-threaded I/O, allowing it to handle datasets larger than available memory while typically using a few gigabytes for most processing stages. These optimizations enable Dolphin to process hundreds of full-frame Sentinel-1 images with minimal configuration, making it well-suited for large-scale projects such as OPERA.
+
+![Overview of main workflow to generate surface displacement. Rectangular stacks indicate input or intermediate raster images. Arrows show the flow of data through the configurable submodules of Dolphin.](./figures/dolphin-modules.png)
+
+For more on running the `dolphin` command line tool, see the walkthroughs on the [Tutorials page](tutorials.md).

docs/references.bib

@@ -51,7 +51,6 @@ @article{Bekaert2021IntroducingOPERAProject
   urldate = {2024-05-15}
 }
 
-
 @article{Berardino2002NewAlgorithmSurface,
   title = {A {{New Algorithm}} for {{Surface Deformation Monitoring Based}} on {{Small Baseline Differential SAR Interferograms}}},
   author = {Berardino, Paolo and Fornaro, Dianfranco and Linari, Riccardo and Sansosti, Eugenio},
@@ -97,6 +96,7 @@ @article{Chen2001TwodimensionalPhaseUnwrapping
   urldate = {2024-05-16},
   langid = {english}
 }
+
 @article{Chen2012IonosphericArtifactsSimultaneous,
   title = {Ionospheric {{Artifacts}} in {{Simultaneous L-Band InSAR}} and {{GPS Observations}}},
   author = {Chen, Jingyi and Zebker, Howard A.},
@@ -125,14 +125,29 @@ @article{Chen2015PersistentScattererInterpolation
 }
 
 @article{Fattahi2019FRInGEFullResolutionInSAR,
-  title = {{{FRInGE}}; {{Full-Resolution InSAR}} Timeseries Using {{Generalized Eigenvectors}}},
-  author = {Fattahi, H. and Agram, P. S. and Tymofyeyeva, E. and Bekaert, D. P.},
-  year = {2019},
-  month = dec,
+  author = {{Fattahi}, H. and {Agram}, P.S. and {Tymofyeyeva}, E. and {Bekaert}, D.P.},
+  title = {{FRInGE; Full-Resolution InSAR timeseries using Generalized Eigenvectors}},
+  keywords = {1209 Tectonic deformation, GEODESY AND GRAVITY, 1211 Non-tectonic deformation, GEODESY AND GRAVITY, 1240 Satellite geodesy: results, GEODESY AND GRAVITY, 1241 Satellite geodesy: technical issues, GEODESY AND GRAVITY},
+  booktitle = {AGU Fall Meeting Abstracts},
+  year = 2019,
   volume = {2019},
+  month = dec,
+  eid = {G11B-0514},
   pages = {G11B-0514},
-  urldate = {2024-05-16},
-  keywords = {1209 Tectonic deformation,1211 Non-tectonic deformation,1240 Satellite geodesy: results,1241 Satellite geodesy: technical issues,GEODESY AND GRAVITY}
+  adsurl = {https://ui.adsabs.harvard.edu/abs/2019AGUFM.G11B0514F},
+  adsnote = {Provided by the SAO/NASA Astrophysics Data System}
+}
+
+@article{Ferretti2001PermanentScattersSAR,
+  title = {Permanent {{Scatters}} in {{SAR Interferometry}}},
+  author = {Ferretti, Alessandro and Prati, Claudio and Rocca, Fabrio},
+  year = {2001},
+  journal = {IEEE Transactions on Geoscience and Remote Sensing},
+  volume = {39},
+  number = {1},
+  pages = {8--20},
+  issn = {01962892},
+  doi = {10.1109/36.898661}
 }
 
 @article{Ferretti2011NewAlgorithmProcessing,
@@ -304,6 +319,7 @@ @article{Yunjun2019SmallBaselineInSAR
   urldate = {2020-08-14},
   langid = {english}
 }
+
 @article{Zwieback2022CheapValidRegularizers,
   title = {Cheap, Valid Regularizers for Improved Interferometric Phase Linking},
   author = {Zwieback, S.},

mkdocs.yml

@@ -56,6 +56,7 @@ watch:
 nav:
 - index.md
 - getting-started.md
+- overview.md
 - tutorials.md
 # - Tutorials:
 #   - Notebook page: notebooks/walkthrough-basic.ipynb