Update README.md

Author: geonextgis

README.md

@@ -42,9 +42,123 @@ For a complete list of examples and use cases, visit the [notebooks](https://git
 
 ## Key Features
 
-- Extracting long-term time series data from GEE for both point and polygon geometries.
-- Extract image patches from satellite imagery in GEE to support local-scale computer vision model training.
-- Quickly transform complex multivariate datasets into a few principal components while preserving critical information.
-- Easy implementation of Harmonic Regression on vegetation or climate indices.
+* **Long-term Time Series Extraction** — Retrieve satellite or climate time series from Google Earth Engine (GEE) for both point and polygon geometries.
+* **Image Patch Generation** — Extract image tiles or patches from satellite imagery in GEE to support local-scale computer vision or deep learning model training.
+* **Multivariate Dimensionality Reduction** — Transform complex multivariate datasets into a few principal components while preserving essential information using PCA.
+* **Harmonic Regression Analysis** — Easily perform harmonic regression on vegetation or climate indices to study seasonal and periodic trends.
+* **Cloud-free Time Series Creation** — Generate regular, gap-filled, and cloud-free time series from irregular satellite observations.
+* **Phenology and Smoothing Tools** — Apply smoothing algorithms and extract phenological metrics (Start of Season, Peak of Season, End of Season) from high-resolution satellite data.
+
+---
+
+## Installation
+```bash
+conda create -n geeagri python=3.10
+conda activate geeagri
+pip install geeagri
+# (Optional) Upgrade to the latest version if already installed
+pip install --upgrade geeagri
+```
+
+---
+
+## Example Usage
+
+#### Example 1: Extract timeseries to point
+```python
+import ee
+import geeagri
+from geeagri.extract import extract_timeseries_to_point
+
+# Authenticate and initialize the Earth Engine API
+ee.Authenticate()
+ee.Initialize()
+
+# Define point location (longitude, latitude)
+lon, lat = -98.15, 30.50
+point = ee.Geometry.Point([lon, lat])
+
+# Load ERA5-Land daily aggregated climate dataset
+era5_land = ee.ImageCollection("ECMWF/ERA5_LAND/DAILY_AGGR")
+
+# Extract daily temperature, precipitation, and solar radiation time series
+era5_land_point_ts = extract_timeseries_to_point(
+    lat=lat,
+    lon=lon,
+    image_collection=era5_land,
+    start_date="2020-01-01",
+    end_date="2021-01-01",
+    band_names=[
+        "temperature_2m_min",
+        "temperature_2m_max",
+        "total_precipitation_sum",
+        "surface_solar_radiation_downwards_sum",
+    ],
+    scale=11132,  # spatial resolution in meters (~11 km)
+)
+```
+This example demonstrates how to use `geeagri` to extract daily climate variable time series (temperature, precipitation, and solar radiation) from the **ERA5-Land** dataset at a specific geographic point using the Google Earth Engine (GEE) Python API.
+
+**Output Plot:**
+![ERA5-Land Temperature Time Series](paper/figure.png)
+
+#### Example 2: Create regular satellite timeseries
+```python
+import ee
+from geeagri.preprocessing import Sentinel2CloudMask, RegularTimeseries
+
+# Authenticate and initialize the Earth Engine API
+ee.Authenticate()
+ee.Initialize()
+
+# Define the bounding box
+bbox = [-98.451233, 38.430732, -98.274765, 38.523996]
+region = ee.Geometry.BBox(*bbox)
+
+# Get cloud masked Sentinel-2 image collection
+s2_cloud_masker = Sentinel2CloudMask(
+    region=region,
+    start_date="2020-01-01",
+    end_date="2021-01-01",
+    cloud_filter=60,  
+    cloud_prob_threshold=50,
+    nir_dark_threshold=0.15,
+    shadow_proj_dist=1,  
+    buffer=50
+)
+
+s2_cloud_masked = s2_cloud_masker.get_cloudfree_collection()
+
+# Calculate NDVI
+def calculateNDVI(image):
+    ndvi = image.expression(
+        "(NIR - Red) / (NIR + Red)",
+        {"NIR": image.select("B8"), "Red": image.select("B4")},
+    ).copyProperties(image, ["system:time_start"])
+
+    ndvi = ee.Image(ndvi).rename("ndvi").clip(region)
+
+    return ndvi
+
+
+ndvi_col = s2_cloud_masked.map(calculateNDVI)
+
+# Instantiate a 'RegularTimeseries' object
+reg_timeseries = RegularTimeseries(
+    image_collection=ndvi_col,
+    interval=5,  # Interval (in days) between consecutive target dates
+    window=45,  # Temporal window in days
+)
+
+# Get the regular timeseries
+ndvi_regular = reg_timeseries.get_regular_timeseries()
+```
+This example demonstrates how to extract a regular, gap-filled NDVI time series from Sentinel-2 imagery using `geeagri`. First, a `Sentinel2CloudMask` object is created to mask clouds and shadows over a defined bounding box using thresholds for cloud probability, dark NIR pixels, and shadow projection. The cloud-masked images are then processed with a custom function to calculate NDVI for each image. Finally, a `RegularTimeseries` object generates a temporally consistent NDVI time series at a specified interval and temporal window. This workflow allows users to efficiently obtain high-quality, regular NDVI time series from raw Sentinel-2 imagery while handling cloud and shadow contamination.
+
+**Raw NDVI Time Series with Cloud Gaps:**
+![Raw Satellite Time Series with Cloud Gaps](docs/assets/ndvi_raw.gif)
+
+**Regular Gap-filled NDVI Time Series:**
+![Regular Gap-filled NDVI Time Series](docs/assets/ndvi_regular.gif)
 
 ---

docs/assets/ndvi_raw.gif

@@ -5,7 +5,8 @@ @article{gorelick2017google
   volume={202},
   pages={18--27},
   year={2017},
-  publisher={Elsevier}
+  publisher={Elsevier},
+  doi={10.1016/j.rse.2017.06.031}
 }
 
 @article{wu2020geemap,
@@ -15,7 +16,8 @@ @article{wu2020geemap
   volume={5},
   number={51},
   pages={2305},
-  year={2020}
+  year={2020},
+  doi={10.21105/joss.02305}
 }
 
 @article{ines2013assimilation,
@@ -25,7 +27,8 @@ @article{ines2013assimilation
   volume={138},
   pages={149--164},
   year={2013},
-  publisher={Elsevier}
+  publisher={Elsevier},
+  doi={10.1016/j.rse.2013.07.018}
 }
 
 @article{zhu2017deep,
@@ -36,7 +39,8 @@ @article{zhu2017deep
   number={4},
   pages={8--36},
   year={2017},
-  publisher={IEEE}
+  publisher={IEEE},
+  doi={10.1109/MGRS.2017.2762307}
 }
 
 @article{beck2006improved,
@@ -47,7 +51,8 @@ @article{beck2006improved
   number={3},
   pages={321--334},
   year={2006},
-  publisher={Elsevier}
+  publisher={Elsevier},
+  doi={10.1016/j.rse.2005.10.021}
 }
 
 @article{drusch2012sentinel,
@@ -57,7 +62,8 @@ @article{drusch2012sentinel
   volume={120},
   pages={25--36},
   year={2012},
-  publisher={Elsevier}
+  publisher={Elsevier},
+  doi={10.1016/j.rse.2011.11.026}
 }
 
 @article{wulder2016global,
@@ -67,7 +73,8 @@ @article{wulder2016global
   volume={185},
   pages={271--283},
   year={2016},
-  publisher={Elsevier}
+  publisher={Elsevier},
+  doi={10.1016/j.rse.2015.11.032}
 }
 
 @article{chen2004simple,
@@ -78,7 +85,8 @@ @article{chen2004simple
   number={3-4},
   pages={332--344},
   year={2004},
-  publisher={Elsevier}
+  publisher={Elsevier},
+  doi={10.1016/j.rse.2004.03.014}
 }
 
 @article{jonsson2004timesat,
@@ -89,7 +97,8 @@ @article{jonsson2004timesat
   number={8},
   pages={833--845},
   year={2004},
-  publisher={Elsevier}
+  publisher={Elsevier},
+  doi={10.1016/j.cageo.2004.05.006}
 }
 
 @article{mckinney2010data,
@@ -99,5 +108,6 @@ @article{mckinney2010data
   volume={445},
   number={1},
   pages={51--56},
-  year={2010}
+  year={2010},
+  doi={10.25080/Majora-92bf1922-00a}
 }