From 82f87b6f737abf5633fc848487ec5a42f917d003 Mon Sep 17 00:00:00 2001 From: SarahAlidoost Date: Fri, 23 May 2025 16:57:24 +0200 Subject: [PATCH] add doc for enrich_from_dataset --- docs/operations.md | 40 +++++++++++++++++++++++++++++++++++++--- 1 file changed, 37 insertions(+), 3 deletions(-) diff --git a/docs/operations.md b/docs/operations.md index 5fbd2ca..37998ed 100644 --- a/docs/operations.md +++ b/docs/operations.md @@ -4,9 +4,15 @@ 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. STMTools supports enriching an STM by static polygons or a dataset. -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. +### Enrich from a polygon + +STMTools supports enriching an STM by static polygons. 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 import geopandas as gpd @@ -24,6 +30,34 @@ fields_to_query = ['soil_type', 'type_id'] stmat_enriched = stmat.stm.enrich_from_polygon(path_polygon, fields_to_query) ``` +### Enrich from a dataset + +STMTools supports enriching an STM by a dataset or a data array. For example, if +a dataset (`meteo_data.nc`) is available together with an STM, one can first +read `meteo_data.nc` using the `Xarray` library, then add the dataset to the +STM, using the `enrich_from_dataset` function. + +```python +import xarray as xr +dataset = xr.open_dataset('meteo_data.nc') + +# one field +stmat_enriched = stmat.stm.enrich_from_dataset(dataset, 'temperature') + +# multiple fields +stmat_enriched = stmat.stm.enrich_from_dataset(dataset, ['temperature', 'precipitation']) +``` + +By default `"nearest"` is used for the interpolation. But you can choose [any +method provided by +Xarray](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.interp.html). +For example, if you want to use `"linear"` interpolation, you can do it like +this: + +```python +stmat_enriched = stmat.stm.enrich_from_dataset(dataset, 'temperature', method='linear') +``` + ## Subset an STM A subset of an STM can be obtained based on 1) thresholding on an attribute, or 2) intersection with a background polygon. @@ -42,7 +76,7 @@ This is equivalent to Xarray filtering: mask = stmat['pnt_enscoh'] > 0.7 mask = mask.compute() stmat_subset = stmat.where(mask, drop=True) -``` +``` ### Subset by a polygon