From a649c655b1f6576e1d04ad8788e292fac18a10f5 Mon Sep 17 00:00:00 2001 From: Ou Ku Date: Mon, 15 Jan 2024 11:02:58 +0100 Subject: [PATCH] update documentation text --- docs/index.md | 4 ++-- docs/notebooks/demo_stm.ipynb | 12 +++++----- docs/operations.md | 43 +++++++++++++++++------------------ docs/setup.md | 4 ++-- docs/stm_init.md | 6 ++--- 5 files changed, 34 insertions(+), 35 deletions(-) diff --git a/docs/index.md b/docs/index.md index 0676205..8d34f37 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,12 +1,12 @@ # STMTools -STMTools (Space-Time Matrix Tools) is an Xarray extension for Space-Time Matrix (*Bruna et al., 2021; van Leijen et al., 2021*). It provides tools to read, write, enrich, and manipulate a Space-Time Matrix (STM). +STMTools (Space-Time Matrix Tools) is an Xarray extension for Space-Time Matrix operations (*Bruna et al., 2021; van Leijen et al., 2021*). It provides tools to read, write, enrich and manipulate a Space-Time Matrix (STM). An STM is a dataset containing data with a space (point, location) and time (epoch) component, as well as contextual data. STMTools utilizes Xarray’s multi-dimensional labeling feature, and Zarr's chunk storage feature, to efficiently read and write large Space-Time matrices. The contextual data enrichment functionality is implemented with Dask. Therefore it can be performed in a paralleled style on High Performance Computing (HPC) systems. -At this stage, stmtools specifically focus on the implementation for radar interferometry measurements, e.g. Persistent Scatterer, Distributed Scatterer, etc, with the possibility to be extended to other measurements with space and time attributes. +At this stage, STMTools specifically focuses on the implementation for radar interferometry measurements, e.g. Point Scatterers, Distributed Scatterers, etc, with the possibility to be extended to other measurements with space and time attributes. ## References [1] Bruna, M. F. D., van Leijen, F. J., & Hanssen, R. F. (2021). A Generic Storage Method for Coherent Scatterers and Their Contextual Attributes. In 2021 IEEE International Geoscience and Remote Sensing Symposium IGARSS: Proceedings (pp. 1970-1973). [9553453] (International Geoscience and Remote Sensing Symposium (IGARSS); Vol. 2021-July). IEEE . https://doi.org/10.1109/IGARSS47720.2021.9553453 diff --git a/docs/notebooks/demo_stm.ipynb b/docs/notebooks/demo_stm.ipynb index 8c92514..6b320bf 100644 --- a/docs/notebooks/demo_stm.ipynb +++ b/docs/notebooks/demo_stm.ipynb @@ -9,8 +9,8 @@ "\n", "In this example notebook, we will demonstrate how to:\n", "\n", - "1. Locate the entries in an STM which intersects building polygons;\n", - "2. Add year of construction as a data variable to the STM." + "1. Locate the entries in an STM which intersect building polygons;\n", + "2. Add year of construction as an attribute to the STM." ] }, { @@ -27,7 +27,7 @@ "\n", "### Environment\n", "\n", - "For the python environment setup, we assume you already started an independent Python environment with Python version later than 3.10.\n", + "For the Python environment setup, we assume you already started an independent Python environment with Python version higher than 3.10.\n", "\n", "To execute this notebook, install `stmtools` with the extra option `demo`:\n", "\n", @@ -35,7 +35,7 @@ "pip install stmtools[demo]\n", "```\n", "\n", - "After installation, execute the notebook in a JupyterLab session, which can be started by running `jupyterlab` command in your command line:\n", + "After installation, execute the notebook in a JupyterLab session, which can be started by running the `jupyterlab` command in your command line:\n", "```bash\n", "jupyter-lab\n", "```\n", @@ -67,7 +67,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "### Load SpaceTime Matrix from Zarr\n", + "### Load Space-Time Matrix from Zarr\n", "\n", "We load the STM stored in Zarr format. " ] @@ -102,7 +102,7 @@ "source": [ "path_stm = Path('./stm.zarr')\n", "stmat = xr.open_zarr(path_stm)\n", - "stmat = stmat.chunk({\"space\": 10000, \"time\":-1})\n", + "stmat = stmat.chunk({\"space\": 10000, \"time\":-1}) # Chunk 10000 space, no chunk in time\n", "\n", "print(stmat)" ] diff --git a/docs/operations.md b/docs/operations.md index 376ea32..c1b2789 100644 --- a/docs/operations.md +++ b/docs/operations.md @@ -1,35 +1,34 @@ # Operations on STM -STMTools supports various operations on STM. +STMTools supports various operations on an STM. ## Enrich an STM -Contextual data can be added to an STM by enrichment. At present, stmtools supports enriching an STM by static polygons. +Contextual data can be added to an STM by enrichment. At present, STMTools supports enriching an STM by static polygons. -For example, if soil type data (`soil_map.gpkg`) is available together with an STM, then we can add the soil type and corresponding type code to the STM, using `enrich_from_polygon`: +For example, if soil type data (`soil_map.gpkg`) is available together with an STM, one can first read `soil_map.gpkg` using the `GeoPandas` library as a `GeoDataFrame`, then add the soil type and corresponding type ID to the STM, using the `enrich_from_polygon` function. ```python -path_polygon = Path('soil_map.gpkg') -fields_to_query = ['soil_type', 'type_code'] -stmat_enriched = stmat.stm.enrich_from_polygon(path_polygon, fields_to_query) +import geopandas as gpd +polygon = gpd.read_file('soil_map.gpkg') +fields_to_query = ['soil_type', 'type_id'] +stmat_enriched = stmat.stm.enrich_from_polygon(polygon, fields_to_query) ``` +Two attributes from `soil_map.gpkg`: `soil_type` and `type_id`, will be added as data variables to the STM. -Two attributes from `soil_map.gpkg` to the STM: `soil_type` and `type_id`, will be added as data variables to the STM. - -When `soil_map.gpkg` is small, loading it as an `GeoDataFrame` is faster: +In case of a large file `soil_map.gpkg`, one can directly pass the file path to `enrich_from_polygon` to trigger the chunked enrichment: ```python -import geopandas as gpd -polygon = gpd.read_file('soil_map.gpkg') -fields_to_query = ['soil_type', 'type_code'] -stmat_enriched = stmat.stm.enrich_from_polygon(polygon, fields_to_query) +path_polygon = Path('soil_map.gpkg') +fields_to_query = ['soil_type', 'type_id'] +stmat_enriched = stmat.stm.enrich_from_polygon(path_polygon, fields_to_query) ``` ## Subset an STM -A subset of an STM can be calculated based on 1) thresholding on a data-variable, or 2) intersection with a background polygon. +A subset of an STM can be obtained based on 1) thresholding on an attribute, or 2) intersection with a background polygon. -### By an attribute +### Subset by an attribute For example, select entries with `pnt_enscoh` higher than 0.7: @@ -37,7 +36,7 @@ For example, select entries with `pnt_enscoh` higher than 0.7: stmat_subset = stmat.stm.subset(method="threshold", var="pnt_enscoh", threshold='>0.7') ``` -This is equivelent to Xarray filtering: +This is equivalent to Xarray filtering: ```python mask = stmat["pnt_enscoh"] > 0.7 @@ -45,7 +44,7 @@ mask = mask.compute() stmat_subset = stmat.where(mask, drop=True) ``` -### By polygon +### Subset by a polygon Select all entries inside the polygons in `example_polygon.shp`: @@ -64,14 +63,14 @@ stmat_subset = stm_demo.stm.subset(method='polygon', polygon='example_polygon.gp ## Regulate the dimensions of an STM -Use `regulate_dims` to add missing `space` or `time` dimension. +Use `regulate_dims` to add a missing `space` or `time` dimension. ```python # An STM witout time dimension nspace = 10 -stm_only_spcae = xr.Dataset(data_vars=dict(data=(["space"], np.arange(nspace)))) +stm_only_space = xr.Dataset(data_vars=dict(data=(["space"], np.arange(nspace)))) -stm_only_spcae +stm_only_space ``` ```output @@ -83,7 +82,7 @@ Data variables: ``` ```python -stm_only_spcae.regulate_dims() +stm_only_space.regulate_dims() ``` ```output @@ -96,7 +95,7 @@ Data variables: ## Assign metadata -Use `register_metadata` to assign dictionary metadata to an STM. +Use `register_metadata` to assign metadata to an STM by a Python dictionary. ```python metadata_normal = dict(techniqueId="ID0001", datasetId="ID_datasetID", crs=4326) diff --git a/docs/setup.md b/docs/setup.md index 10624bc..24524b7 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -9,7 +9,7 @@ pip install stmtools or from the source: ```sh -git clone git@github.com:MotionbyLearning/stmtools.git +git clone git@github.com:TUDelftGeodesy/stmtools.git cd stmtools pip install . ``` @@ -18,4 +18,4 @@ Note that Python version `>=3.10` is required for STMTools. ## Tips -We strongly recommend installing separately from your default Python envrionment. E.g. you can use enviroment manager e.g. [mamba](https://mamba.readthedocs.io/en/latest/mamba-installation.html) to create separate environment. +We strongly recommend installing separately from your default Python environment. E.g. you can use environment manager e.g. [mamba](https://mamba.readthedocs.io/en/latest/mamba-installation.html) to create separate environment. diff --git a/docs/stm_init.md b/docs/stm_init.md index 74e39a6..44d0576 100644 --- a/docs/stm_init.md +++ b/docs/stm_init.md @@ -1,6 +1,6 @@ # Initiate a Space-Time Matrix -In Python, STM can be represented by an [`Xarray.Dataset`](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html) object. An STM instance can be initiated as an `Xarray.Dataset` in different ways. +We implemented STM in Python as an [`Xarray.Dataset`](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html) object. An STM instance can be initiated as an `Xarray.Dataset` in different ways. STMTools provides a reader to perform lazy loading from a csv file. However, we recommend to store STM in [`zarr`](https://zarr.readthedocs.io/en/stable/) format, and directly load them as an Xarray object by [`xarray.open_zarr`](https://docs.xarray.dev/en/stable/generated/xarray.open_zarr.html). @@ -49,7 +49,7 @@ Data variables: ## From a Zarr storage -If an STM is stored in `.zarr` format, it can be read by `xarray.open_zarr` funtcion: +If an STM is stored in `.zarr` format, it can be read by the `xarray.open_zarr` funtcion: ```python stm = xr.open_zarr('./stm.zarr') @@ -101,4 +101,4 @@ Data variables: (12/13) ## By pixel selection from an image stack -An STM can also be generated by selecting pixels from an SLC stack or interferogram stack. An example of the selection is [`point_seclection`](https://motionbylearning.github.io/sarxarray/common_ops/#point-selection) implementation of [`sarxarray`](https://motionbylearning.github.io/sarxarray/). \ No newline at end of file +An STM can also be generated by selecting pixels from an SLC stack or interferogram stack. An example of the selection is the [`point_selection`](https://motionbylearning.github.io/sarxarray/common_ops/#point-selection) implementation of [`sarxarray`](https://motionbylearning.github.io/sarxarray/). \ No newline at end of file