update docs

Fanchengyan · Aug 1, 2024 · 047bc82 · 047bc82
1 parent b622c3e
commit 047bc82
Show file tree

Hide file tree

Showing 25 changed files with 696 additions and 57 deletions.
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -7,5 +7,10 @@
             "addWords": true,
             "scope": "workspace"
         }
-    }
-}
+    },
+    "python.testing.pytestArgs": [
+        "tests"
+    ],
+    "python.testing.unittestEnabled": false,
+    "python.testing.pytestEnabled": true
+}
diff --git a/docs/Makefile b/docs/Makefile
@@ -12,6 +12,9 @@ BUILDDIR      = build
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
+clean:
+	rm -rf $(BUILDDIR)/*
+
 .PHONY: help Makefile
 
 # Catch-all target: route all unknown targets to Sphinx using the new

diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -4,5 +4,6 @@ myst-nb
 sphinx-copybutton
 sphinx-design
 pydata_sphinx_theme
+sphinx-togglebutton
 Jinja2
 git+https://github.com/Fanchengyan/FanInSAR.git@main
diff --git a/docs/source/api/datasets/datasets.rst b/docs/source/api/datasets/datasets.rst
@@ -1,3 +1,6 @@
+.. _geo_datasets:
+
+===================
 geospatial Datasets
 ===================
 
@@ -13,7 +16,7 @@ The following datasets are available:
       * :class:`.GACOS`
    * :class:`.PairDataset` : base Datasets for all Pair-like productions. Child classes:
       * :class:`.InterferogramDataset`
-      * :class:`.GACOSPairs` 
+      * :class:`.GACOSPairs`
    * :class:`.InterferogramDataset` : base Datasets for all Interferogram productions. Child classes (well known productions):
       * :class:`.HyP3S1`, :class:`.HyP3S1Burst`,
       * :class:`.LiCSAR`

diff --git a/docs/source/api/query/index.rst b/docs/source/api/query/index.rst
@@ -1,3 +1,5 @@
+.. _query_module:
+
 Queries
 =======
 
@@ -12,4 +14,4 @@ Query in FanInSAR is used to retrieve or sample values from a GeoDataset. It con
    :caption: Contents:
 
    query
-   query_result
+   query_result
diff --git a/docs/source/api/query/query.rst b/docs/source/api/query/query.rst
@@ -12,7 +12,7 @@ Geospatial Query in FanInSAR is used to retrieve or sample values from GeoDatase
 
    :class:`Points`, "A collection of points, can be used to sample multiple pixel values from GeoDataset."
    :class:`BoundingBox`, "A bounding box, can be used to sample rectangular region values from GeoDataset."
-   :class:`Polygons`, "A collection of polygons, can be used to sample multiple pixel values from GeoDataset."
+   :class:`Polygons`, "A collection of polygons, can be used to sample multiple polygon values from GeoDataset."
    :class:`GeoQuery`, "A combination of :class:`Points`, :class:`BoundingBox`, and :class:`Polygons`. It is highly recommended if you want to sample values using multiple query types simultaneously from a GeoDataset."
 
 
@@ -52,4 +52,4 @@ GeoQuery
    :members:
    :undoc-members:
    :member-order: bysource
-   :show-inheritance:
+   :show-inheritance:
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -23,6 +23,7 @@
     "myst_nb",
     "sphinx_copybutton",
     "sphinx_design",
+    "sphinx_togglebutton",
 ]
 source_suffix = {
     ".rst": "restructuredtext",
@@ -76,7 +77,7 @@
     ":show-inheritance:": True,
 }
 html_context = {
-    "github_url": "https://github.com",  # or your GitHub Enterprise site
+    "github_url": "https://github.com",
     "github_user": "Fanchengyan",
     "github_repo": "FanInSAR",
     "github_version": "main",

diff --git a/docs/source/examples/ARPs.ipynb b/docs/source/examples/ARPs.ipynb
@@ -0,0 +1,18 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Automatically Selecting Reference Points"
+   ]
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}
diff --git a/docs/source/examples/index.rst b/docs/source/examples/index.rst
@@ -0,0 +1,13 @@
+========
+Examples
+========
+
+We provide a number of examples to help you get started with using the **FanInSAR** package.
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents:
+
+   warp/index
+   ARPs
diff --git a/docs/source/examples/warp/index.rst b/docs/source/examples/warp/index.rst
@@ -0,0 +1,14 @@
+.. _warp_example:
+
+============
+Warp Example
+============
+
+This section demonstrates how to warp the raster datasets, such as reprojecting and resampling the raster datasets.
+
+.. toctree::
+   :maxdepth: 2
+
+   reproject
+   resample
+   match_raster
diff --git a/docs/source/examples/warp/match_raster.ipynb b/docs/source/examples/warp/match_raster.ipynb
@@ -0,0 +1,39 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Match to a reference raster\n",
+    "\n",
+    "This tutorial demonstrates how to match the extent, resolution, and projection of a raster to a reference raster. This is a common task when working with multiple rasters that have different properties."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "geo",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.11.9"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}
diff --git a/docs/source/examples/warp/reproject.ipynb b/docs/source/examples/warp/reproject.ipynb
@@ -0,0 +1,20 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Reproject dataset\n",
+    "\n",
+    "This notebook is a simple example of how to reproject a dataset by providing a new crs."
+   ]
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}
diff --git a/docs/source/examples/warp/resample.ipynb b/docs/source/examples/warp/resample.ipynb
@@ -0,0 +1,20 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Resampling dataset\n",
+    "\n",
+    "In this tutorial, you will discover how to resample your dataset, upscaling or downscaling the resolution, using the **FanInSAR**."
+   ]
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -54,10 +54,11 @@ Citation
 
 
 .. toctree::
-   :maxdepth: 3
+   :maxdepth: 2
    :caption: Contents:
 
    install
    user_guide/index
+   examples/index
    api/index
    terminology
diff --git a/docs/source/terminology.rst b/docs/source/terminology.rst
@@ -8,33 +8,19 @@ Terminology
     Acquisition
         The date of SAR acquisition or image, expressed as a ``datetime.datetime`` object.
 
-    Pair
-        A pair is a combination of two SAR acquisitions in acquisition order. 
+    Pair/Pairs
+        A pair is a combination of two SAR acquisitions in acquisition order.
 
         .. warning::
             In FanInSAR, a ``Pair`` must be in acquisition order, which means that the first acquisition should be earlier than the second acquisition. For example, a pair of (2018-01-01, 2018-02-01) is valid, but a pair of (2018-02-01, 2018-01-01) is invalid. If an invalid pair is provided, FanInSAR may yield unexpected results.
 
-    Pairs
-        A collection of pairs. 
-
-    Loop
+    Loop/Loops
         A loop contains a list of edge pairs and one diagonal pair. See paper [1]_ for more details.
 
-    Loops
-        A collection of loops.
-
-    TripletLoop
+    TripletLoop/TripletLoops
         triplet loop is a special loop that contains three pairs. See paper [1]_ for more details.
 
-    TripletLoops
-        A collection of triplet loops.
-
-    SBASNetwork
-        A collection of loops and pairs.
-
     CRS
         A coordinate reference system (CRS) is a coordinate-based local, regional, or global system used to locate geographical entities. In FanInSAR, the CRS is handled by the ``rasterio`` and ``pyproj`` packages. A valid CRS input for FanInSAR can be any type supported by the :meth:`pyproj.crs.CRS.from_user_input` method.
 
-.. [1] : Fan, Chengyan, Lin Liu, Zhuoyi Zhao and Cuicui Mu. “Unwrapping errors matter: Pronounced underestimation of surface deformation over Tibetan Plateau permafrost by Sentinel-1 InSAR and its correction”.
-
-
+.. [1] : Fan, Chengyan, Lin Liu, Zhuoyi Zhao and Cuicui Mu. “Pronounced Underestimation of Surface Deformation due to Unwrapping Errors over Tibetan Plateau Permafrost by Sentinel-1 InSAR and Its Correction”.
diff --git a/docs/source/user_guide/Indexing_data.rst b/docs/source/user_guide/Indexing_data.rst
diff --git a/docs/source/user_guide/colormap.ipynb b/docs/source/user_guide/colormap.ipynb
@@ -4,7 +4,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Colormap reference\n",
+    "# Colormap Reference\n",
     "\n",
     "FanInSAR provides four well-known colormap categories, including:\n",
     "\n",
@@ -398,7 +398,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.6"
+   "version": "3.11.9"
   }
  },
  "nbformat": 4,

diff --git a/docs/source/user_guide/custom/datasets.rst b/docs/source/user_guide/custom/datasets.rst
@@ -0,0 +1,18 @@
+.. _custom_datasets:
+
+===============
+Custom Datasets
+===============
+
+In this tutorial, we will discuss how to customize your own datasets in ``FanInSAR``.
+
+Choosing a base class
+---------------------
+
+To customize your own dataset, you need to choose a base class to inherit from. In ``FanInSAR``, the base class for datasets are as follows:
+
+- :class:`~faninsar.datasets.RasterDataset`: The base class for raster datasets, just like the files with the extension of ``.tif`` / ``.tiff``.
+- :class:`~faninsar.datasets.InterferogramDataset`: The base class for interferogram datasets.
+
+
+.. - :class:`~faninsar.datasets.HierarchicalDataset`: The base class for hierarchical datasets, just like the files with the extension of ``.h5`` (hdf5) or ``.nc`` (netcdf).
diff --git a/docs/source/user_guide/custom/index.rst b/docs/source/user_guide/custom/index.rst
@@ -0,0 +1,16 @@
+.. _customization:
+
+=============
+Customization
+=============
+
+Although the built-in time series models and datasets of ``FanInSAR``
+are powerful, you may want to customize them to better fit your own needs.
+
+In this section, we will discuss how to customize your own time series models and datasets.
+
+.. toctree::
+   :maxdepth: 1
+
+   datasets
+   ts_models
diff --git a/docs/source/user_guide/custom/ts_models.rst b/docs/source/user_guide/custom/ts_models.rst
@@ -0,0 +1,7 @@
+.. _custom_tsmodels:
+
+=========================
+Custom Time Series Models
+=========================
+
+In this tutorial, we will discuss how to customize your own time series models in ``FanInSAR``.
diff --git a/docs/source/user_guide/index.rst b/docs/source/user_guide/index.rst
@@ -13,5 +13,6 @@ examples that describe many common tasks that you can accomplish with FanInSAR.
    quick_start
    colormap
    data_structures
-   Indexing_data
+   indexing/index
    sampler
+   custom/index
diff --git a/docs/source/user_guide/filter.ipynb → docs/source/user_guide/indexing/filter.ipynb b/docs/source/user_guide/filter.ipynb → docs/source/user_guide/indexing/filter.ipynb
@@ -4,7 +4,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Filter Pairs"
+    "# Filtering Pairs"
    ]
   },
   {
@@ -190,7 +190,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.6"
+   "version": "3.11.9"
   }
  },
  "nbformat": 4,

diff --git a/docs/source/user_guide/indexing/index.rst b/docs/source/user_guide/indexing/index.rst
@@ -0,0 +1,13 @@
+.. _indexing:
+
+==================
+Indexing/Filtering
+==================
+
+This section demonstrates how to index/select
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents:
+
+   filter