Add bibtex extension for mkdocs

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.

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}
+}

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

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

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

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

src/dolphin/phase_link/mle.py

@@ -196,14 +196,15 @@ 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)
         The sample covariance matrix at each pixel
         (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

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]

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

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