update documentation text

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

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,15 +27,15 @@
     "\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",
     "```sh\n",
     "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)"
    ]

docs/operations.md

@@ -1,51 +1,50 @@
 # 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:
 
 ```python
 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
 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)

docs/setup.md

@@ -9,7 +9,7 @@ pip install stmtools
 or from the source:
 
 ```sh
-git clone [email protected]:MotionbyLearning/stmtools.git
+git clone [email protected]: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.

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/).
+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/).