diff --git a/docs/getting-started.md b/docs/getting-started.md index 040edbf2e..9485a81de 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,6 +1,5 @@ ## Install - `dolphin` is available on conda-forge: ```bash @@ -126,3 +125,6 @@ mkdocs serve ``` then open http://localhost:8000 in your browser. Creating new files or updating existing files will automatically trigger a rebuild of the documentation while `mkdocs serve` is running. + +For citations, use the notation `[@Ansari2018EfficientPhaseEstimation]` to refer to a Bibtex key in `docs/references.bib` (e.g. [@Ansari2018EfficientPhaseEstimation]). +This can be done in either a markdown file, or in a docstring. diff --git a/docs/references.bib b/docs/references.bib new file mode 100644 index 000000000..c7557bcd5 --- /dev/null +++ b/docs/references.bib @@ -0,0 +1,153 @@ +@article{Ansari2017SequentialEstimatorEfficient, + title = {Sequential {{Estimator}}: {{Toward Efficient InSAR Time Series Analysis}}}, + shorttitle = {Sequential {{Estimator}}}, + author = {Ansari, Homa and De Zan, Francesco and Bamler, Richard}, + year = {2017}, + month = oct, + journal = {IEEE Transactions on Geoscience and Remote Sensing}, + volume = {55}, + number = {10}, + pages = {5637--5652}, + issn = {1558-0644}, + doi = {10.1109/TGRS.2017.2711037}, + keywords = {Big Data,Coherence,coherence estimation error,data compression,differential interferometric synthetic aperture radar (DInSAR),distributed scatterers,Earth,efficiency,error analysis,low-rank approximation,Maximum likelihood estimation,maximum-likelihood estimation (MLE),Monitoring,Synthetic aperture radar,Time series analysis} +} + +@article{Ansari2018EfficientPhaseEstimation, + title = {Efficient {{Phase Estimation}} for {{Interferogram Stacks}}}, + author = {Ansari, Homa and De Zan, Francesco and Bamler, Richard}, + year = {2018}, + month = jul, + journal = {IEEE Transactions on Geoscience and Remote Sensing}, + volume = {56}, + number = {7}, + pages = {4109--4125}, + issn = {1558-0644}, + doi = {10.1109/TGRS.2018.2826045}, + keywords = {Big Data,coherence matrix,covariance estimation,differential interferometric synthetic aperture radar,distributed scatterers (DS),efficiency,Electromagnetic interference,error analysis,Maximum likelihood estimation,maximum-likelihood estimation,near real-time (NRT) processing,Strain,Synthetic aperture radar,Systematics,Time series analysis} +} + +@article{Ansari2021StudySystematicBias, + title = {Study of {{Systematic Bias}} in {{Measuring Surface Deformation With SAR Interferometry}}}, + author = {Ansari, H. and Zan, F. De and Parizzi, A.}, + year = {2021}, + month = feb, + journal = {IEEE Transactions on Geoscience and Remote Sensing}, + volume = {59}, + number = {2}, + pages = {1285--1301}, + issn = {1558-0644}, + doi = {10.1109/TGRS.2020.3003421}, + keywords = {Big Data,Decorrelation,deformation estimation,differential interferometric synthetic aperture radar (SAR) (DInSAR),distributed scatterers (DSs),error analysis,Fading channels,Moisture,near real-time (NRT) processing,phase inconsistencies,signal decorrelation,Strain,Synthetic aperture radar,Systematics,Time series analysis,time-series analysis} +} + +@article{Chen2012IonosphericArtifactsSimultaneous, + title = {Ionospheric {{Artifacts}} in {{Simultaneous L-Band InSAR}} and {{GPS Observations}}}, + author = {Chen, Jingyi and Zebker, Howard A.}, + year = {2012}, + month = apr, + journal = {IEEE Transactions on Geoscience and Remote Sensing}, + volume = {50}, + number = {4}, + pages = {1227--1239}, + issn = {1558-0644}, + doi = {10.1109/TGRS.2011.2164805}, + keywords = {Advanced Land Observation Satellite (ALOS) PhasedArray L-band Synthetic Aperture Radar (PALSAR),Azimuth,California,correlation signatures,Delay,dual-frequency GPS carrier phase data,global positioning system,Global Positioning System,global positioning system (GPS),GPS observations,Hawaii,Iceland,InSAR images,interferograms,interferometric synthetic aperture radar,interpretability,Ionosphere,ionospheric artifacts,ionospheric delay,ionospheric electromagnetic wave propagation,ionospheric propagation delays,ionospheric total electron content,ionospheric variability,L-band InSAR data,L-band InSAR observations,L-band SAR interferometry,neutral atmospheric delays,phase artifacts,pixel misregistration,radar imaging,radar interferometry,radiowave propagation,SAR acquisition times,Satellites,Spaceborne radar,synthetic aperture length scales,synthetic aperture radar,terrain,total electron content (TEC)} +} + +@article{Fornaro2015CAESARApproachBased, + title = {{{CAESAR}}: {{An Approach Based}} on {{Covariance Matrix Decomposition}} to {{Improve Multibaseline}}{\textendash}{{Multitemporal Interferometric SAR Processing}}}, + shorttitle = {{{CAESAR}}}, + author = {Fornaro, Gianfranco and Verde, Simona and Reale, Diego and Pauciullo, Antonio}, + year = {2015}, + month = apr, + journal = {IEEE Transactions on Geoscience and Remote Sensing}, + volume = {53}, + number = {4}, + pages = {2050--2065}, + issn = {1558-0644}, + doi = {10.1109/TGRS.2014.2352853}, + keywords = {3-D,4-D and multidimensional (Multi-D) SAR imaging,Covariance matrices,Covariance matrix decomposition,differential SAR tomography,differential synthetic aperture radar (SAR) interferometry (DInSAR),Interferometry,Monitoring,principal component analysis (PCA),SAR interferometry (InSAR),SAR tomography,Scattering,Spatial resolution,Synthetic aperture radar,Tomography} +} + +@article{Guarnieri2008ExploitationTargetStatistics, + title = {On the {{Exploitation}} of {{Target Statistics}} for {{SAR Interferometry Applications}}}, + author = {Guarnieri, A. M. and Tebaldini, S.}, + year = {2008}, + month = nov, + journal = {IEEE Transactions on Geoscience and Remote Sensing}, + volume = {46}, + number = {11}, + pages = {3436--3443}, + issn = {0196-2892}, + doi = {10.1109/TGRS.2008.2001756}, + keywords = {Decorrelation,decorrelation models,ENVISAT images,geophysical techniques,geophysics computing,image processing,Information retrieval,interferometric phases,Interferometry,line-of-sight displacement,line-of-sight motion,Maximum likelihood estimation,Monte Carlo simulations,multiimage synthetic aperture radar interferometry,Phase estimation,physical parameters,radar interferometry,Radar scattering,remote sensing by radar,residual topography,SAR interferometry applications,Statistical distributions,statistics,Statistics,stochastic processes,Surfaces,synthetic aperture radar,Synthetic aperture radar interferometry,target statistics,topography (Earth),Yield estimation} +} + +@article{Mirzaee2023NonlinearPhaseLinking, + title = {Non-Linear Phase Linking Using Joined Distributed and Persistent Scatterers}, + author = {Mirzaee, Sara and Amelung, Falk and Fattahi, Heresh}, + year = {2023}, + month = feb, + journal = {Computers \& Geosciences}, + volume = {171}, + pages = {105291}, + issn = {00983004}, + doi = {10.1016/j.cageo.2022.105291}, + urldate = {2023-03-08}, + langid = {english}, + keywords = {Distributed scatterer,MiaplPy InSAR,Phase linking,Sequential} +} + +@article{Parizzi2011AdaptiveInSARStack, + title = {Adaptive {{InSAR Stack Multilooking Exploiting Amplitude Statistics}}: {{A Comparison Between Different Techniques}} and {{Practical Results}}}, + shorttitle = {Adaptive {{InSAR Stack Multilooking Exploiting Amplitude Statistics}}}, + author = {Parizzi, Alessandro and Brcic, Ramon}, + year = {2011}, + month = may, + journal = {IEEE Geoscience and Remote Sensing Letters}, + volume = {8}, + number = {3}, + pages = {441--445}, + issn = {1558-0571}, + doi = {10.1109/LGRS.2010.2083631}, + keywords = {adaptive InSAR stack multilooking,Adaptive multilooking,amplitude-based algorithm,backscatter,backscatter amplitude statistics,Coherence,coherence estimation,complex correlation,interferometric phase,interferometric synthetic aperture radar capability,interferometry,Kernel,phase signatures,Pixel,radar backscatter statistics,radar imaging,radar interferometry,Remote sensing,Shape,synthetic aperture radar,Synthetic aperture radar,synthetic aperture radar (SAR)} +} + +@article{Siddiqui1962ProblemsConnectedRayleigh, + title = {Some Problems Connected with {{Rayleigh}} Distributions}, + author = {Siddiqui, M.M.}, + year = {1962}, + month = mar, + journal = {Journal of Research of the National Bureau of Standards, Section D: Radio Propagation}, + volume = {66D}, + number = {2}, + pages = {167}, + issn = {1060-1783}, + doi = {10.6028/jres.066D.020}, + urldate = {2023-05-03}, + langid = {english} +} + +@article{Wang2022AccuratePersistentScatterer, + title = {Accurate {{Persistent Scatterer Identification Based}} on {{Phase Similarity}} of {{Radar Pixels}}}, + author = {Wang, Ke and Chen, Jingyi}, + year = {2022}, + journal = {IEEE Transactions on Geoscience and Remote Sensing}, + volume = {60}, + pages = {1--13}, + issn = {1558-0644}, + doi = {10.1109/TGRS.2022.3210868}, + keywords = {Decorrelation,Interferometric Synthetic Aperture Radar (InSAR),Persistent Scatterer (PS),Phase measurement,phase similarity,Radar,Radar measurements,Radar scattering,Strain,surface deformation,Synthetic aperture radar} +} + +@article{Zwieback2022CheapValidRegularizers, + title = {Cheap, Valid Regularizers for Improved Interferometric Phase Linking}, + author = {Zwieback, S.}, + year = {2022}, + journal = {IEEE Geoscience and Remote Sensing Letters}, + pages = {1--1}, + issn = {1558-0571}, + doi = {10.1109/LGRS.2022.3197423}, + keywords = {Coherence,Decorrelation,Dispersion,Eigenvalues and eigenfunctions,Estimation,History,Snow} +} diff --git a/docs/requirements.txt b/docs/requirements.txt index 99de283a2..c9205f5a0 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,4 +1,6 @@ +# For citations: # mkdocs requirements +mdx_bib @ git+https://github.com/bobmyhill/mdx_bib.git@6b13bbbc407617a5e93ed0f8a0e5e4c52f73f677 mkdocs mkdocs-gen-files mkdocs-jupyter diff --git a/mkdocs.yml b/mkdocs.yml index 74652e3c9..0a02398ae 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -29,11 +29,15 @@ plugins: docstring_style: numpy members_order: alphabetical # source - mkdocs-jupyter: - include: ["*.ipynb"] + include: ["docs/notebooks/*.ipynb"] markdown_extensions: - pymdownx.arithmatex: generic: true + - footnotes + - mdx_bib: + bibtex_file: docs/references.bib + order: 'unsorted' extra_javascript: - javascripts/mathjax.js diff --git a/src/dolphin/atmosphere/troposphere.py b/src/dolphin/atmosphere/troposphere.py index 69d19f747..01c495561 100644 --- a/src/dolphin/atmosphere/troposphere.py +++ b/src/dolphin/atmosphere/troposphere.py @@ -302,7 +302,7 @@ def compute_pyaps(delay_parameters: DelayParams) -> np.ndarray: Returns ------- np.ndarray - tropospheric delay datacube. + tropospheric delay datacube. """ import pyaps3 as pa @@ -377,7 +377,7 @@ def compute_raider(delay_parameters: DelayParams) -> np.ndarray: Returns ------- np.ndarray - tropospheric delay datacube. + tropospheric delay datacube. """ from RAiDER.delay import tropo_delay as raider_tropo_delay from RAiDER.llreader import BoundingBox diff --git a/src/dolphin/phase_link/__init__.py b/src/dolphin/phase_link/__init__.py index e353b2b29..ea1aa1d3a 100644 --- a/src/dolphin/phase_link/__init__.py +++ b/src/dolphin/phase_link/__init__.py @@ -1,7 +1,8 @@ """Package for phase linking stacks of SLCs. -Currently implements the eigenvalue-based maximum likelihood (EMI) -algorithm from (Ansari, 2018). +Currently implements the eigenvalue-based maximum likelihood (EMI) algorithm from +[@Ansari2018EfficientPhaseEstimation], as well as the EVD based approach from +[@Fornaro2015CAESARApproachBased] and [@Mirzaee2023NonlinearPhaseLinking] """ from ._compress import compress # noqa: F401 diff --git a/src/dolphin/phase_link/mle.py b/src/dolphin/phase_link/mle.py index 21ae6a59b..611230358 100644 --- a/src/dolphin/phase_link/mle.py +++ b/src/dolphin/phase_link/mle.py @@ -196,6 +196,7 @@ def mle_stack( Will use cupy if available, (and if the input is a GPU array). Otherwise, uses numpy (for CPU version). + Parameters ---------- C_arrays : ndarray, shape = (rows, cols, nslc, nslc) @@ -203,7 +204,7 @@ def mle_stack( (e.g. from [dolphin.phase_link.covariance.estimate_stack_covariance_cpu][]) use_evd : bool, default = False Use eigenvalue decomposition on the covariance matrix instead of - the EMI algorithm. + the EMI algorithm of [@Ansari2018EfficientPhaseEstimation]. beta : float, optional The regularization parameter for inverting Gamma = |C| The regularization is applied as (1 - beta) * Gamma + beta * I @@ -219,13 +220,6 @@ def mle_stack( ------- ndarray, shape = (nslc, rows, cols) The estimated linked phase, same shape as the input slcs (possibly multilooked) - - References - ---------- - [1] Ansari, H., De Zan, F., & Bamler, R. (2018). Efficient phase - estimation for interferogram stacks. IEEE Transactions on - Geoscience and Remote Sensing, 56(7), 4109-4125. - """ xp = get_array_module(C_arrays) # estimate the wrapped phase based on the EMI paper diff --git a/src/dolphin/shp/__init__.py b/src/dolphin/shp/__init__.py index e8e146104..1953f27c7 100644 --- a/src/dolphin/shp/__init__.py +++ b/src/dolphin/shp/__init__.py @@ -30,6 +30,9 @@ def estimate_neighbors( ) -> np.ndarray: """Estimate the statistically similar neighbors of each pixel. + GLRT method on the [@Parizzi2011AdaptiveInSARStack]. + Assumes Rayleigh distributed amplitudes ([@Siddiqui1962ProblemsConnectedRayleigh]). + Parameters ---------- halfwin_rowcol : Tuple[int, int] diff --git a/src/dolphin/shp/_glrt.py b/src/dolphin/shp/_glrt.py index 219a1e407..be46ef3eb 100644 --- a/src/dolphin/shp/_glrt.py +++ b/src/dolphin/shp/_glrt.py @@ -32,7 +32,8 @@ def estimate_neighbors( ): """Estimate the number of neighbors based on the GLRT. - Assumes Rayleigh distributed amplitudes, based on the method described [1]_. + Based on the method described in [@Parizzi2011AdaptiveInSARStack]. + Assumes Rayleigh distributed amplitudes ([@Siddiqui1962ProblemsConnectedRayleigh]) Parameters ---------- @@ -73,12 +74,6 @@ def estimate_neighbors( `[dolphin.io.compute_out_shape][]` `window_rows = 2 * halfwin_rowcol[0] + 1` `window_cols = 2 * halfwin_rowcol[1] + 1` - - References - ---------- - [1] Parizzi and Brcic, 2011, "Adaptive InSAR Stack Multilooking Exploiting - Amplitude Statistics" - [2] Siddiqui, M. M. (1962). Some problems connected with Rayleigh distributions. """ half_row, half_col = halfwin_rowcol rows, cols = mean.shape diff --git a/src/dolphin/workflows/sequential.py b/src/dolphin/workflows/sequential.py index 0b5fb78a7..cf88610cc 100644 --- a/src/dolphin/workflows/sequential.py +++ b/src/dolphin/workflows/sequential.py @@ -1,10 +1,6 @@ """Estimate wrapped phase using batches of ministacks. -References ----------- - [1] Ansari, H., De Zan, F., & Bamler, R. (2017). Sequential estimator: Toward - efficient InSAR time series analysis. IEEE Transactions on Geoscience and - Remote Sensing, 55(10), 5637-5652. +Initially based on [@Ansari2017SequentialEstimatorEfficient]. """ from __future__ import annotations