Update documentation and add harmonic regression example notebook

README.md

@@ -45,4 +45,4 @@ For a complete list of examples and use cases, visit the [notebooks](https://git
 - Extracting long-term time series data from GEE for both point and polygon geometries.
 - Easy implementation of Harmonic Regression on vegetation or climate indices.
 
----
+---

docs/examples/harmonic_regression.ipynb

@@ -0,0 +1,172 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "0",
+   "metadata": {},
+   "source": [
+    "# Harmonic Regression Analysis with geeagri\n",
+    "\n",
+    "This notebook demonstrates how to use the `HarmonicRegression` class in geeagri to analyze time series data from satellite imagery using Google Earth Engine."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "1",
+   "metadata": {},
+   "source": [
+    "## Setup and Imports\n",
+    "Install geeagri if needed and import required libraries."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "2",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# !pip install geeagri\n",
+    "import ee\n",
+    "import geeagri\n",
+    "from geeagri.timeseries import HarmonicRegression\n",
+    "import matplotlib.pyplot as plt\n",
+    "import pandas as pd"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "3",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "ee.Authenticate()\n",
+    "ee.Initialize()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "4",
+   "metadata": {},
+   "source": [
+    "## Select Region and Data\n",
+    "Define a point of interest and select an image collection and band for analysis."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "5",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "lat, lon = 37.0510, -120.3022  # Example: Central California\n",
+    "point = ee.Geometry.Point([lon, lat])\n",
+    "\n",
+    "collection = ee.ImageCollection(\"MODIS/061/MOD13Q1\")\n",
+    "band = \"NDVI\"\n",
+    "start_date = \"2015-01-01\"\n",
+    "end_date = \"2017-01-01\"\n",
+    "scale = 250"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "6",
+   "metadata": {},
+   "source": [
+    "## Extract Time Series\n",
+    "Extract the NDVI time series for the selected point."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "7",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "df = geeagri.extract_timeseries_to_point(\n",
+    "    lat, lon, collection, start_date, end_date, band_names=[band], scale=scale\n",
+    ")\n",
+    "df[\"NDVI\"] = df[\"NDVI\"] * 0.0001  # Apply scale factor for MODIS NDVI\n",
+    "df.head()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "8",
+   "metadata": {},
+   "source": [
+    "## Fit Harmonic Regression\n",
+    "Create a HarmonicRegression object and fit the model to the NDVI time series."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "9",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "ref_date = start_date\n",
+    "order = 2  # Number of harmonics\n",
+    "hr = HarmonicRegression(collection, ref_date, band, order=order)\n",
+    "harmonic_coeffs = hr.get_harmonic_coeffs()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "10",
+   "metadata": {},
+   "source": [
+    "## Visualize Fitted Harmonics\n",
+    "Compute and plot the fitted harmonic time series alongside the original NDVI data."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "11",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "fitted_coll = hr.get_fitted_harmonics(harmonic_coeffs)\n",
+    "# Extract fitted values at the point\n",
+    "fitted_list = fitted_coll.getRegion(point, scale=scale).getInfo()\n",
+    "fitted_df = pd.DataFrame(fitted_list[1:], columns=fitted_list[0])\n",
+    "fitted_df[\"time\"] = pd.to_datetime(fitted_df[\"time\"], unit=\"ms\")\n",
+    "fitted_df = fitted_df[[\"time\", \"fitted\"]].dropna()\n",
+    "# Merge with original NDVI\n",
+    "merged = pd.merge(df, fitted_df, on=\"time\", how=\"inner\")\n",
+    "plt.figure(figsize=(10, 5))\n",
+    "plt.plot(merged[\"time\"], merged[\"NDVI\"], label=\"Observed NDVI\", marker=\"o\")\n",
+    "plt.plot(merged[\"time\"], merged[\"fitted\"], label=\"Fitted Harmonic\", linestyle=\"--\")\n",
+    "plt.xlabel(\"Date\")\n",
+    "plt.ylabel(\"NDVI\")\n",
+    "plt.title(\"Harmonic Regression Fit to NDVI Time Series\")\n",
+    "plt.legend()\n",
+    "plt.show()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "12",
+   "metadata": {},
+   "source": [
+    "## Next Steps\n",
+    "- Try different harmonic orders for more/less complex fits.\n",
+    "- Use other bands or regions.\n",
+    "- Explore phase and amplitude extraction for phenology analysis."
+   ]
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

docs/usage.md

@@ -1,7 +1,71 @@
+
 # Usage
 
-To use geeagri in a project:
+geeagri provides utilities for extracting, analyzing, and visualizing time series data from Google Earth Engine. Below are some common usage examples.
 
-```
+
+## 1. Importing geeagri
+
+```python
 import geeagri
 ```
+
+ee.Initialize()
+df = geeagri.extract_timeseries_to_point(
+
+## 2. Extracting a Time Series at a Point
+
+```python
+import ee
+ee.Authenticate()
+ee.Initialize()
+
+lat, lon = 6.5244, 3.3792  # Example: Lagos, Nigeria
+collection = ee.ImageCollection('LANDSAT/LC08/C01/T1_SR')
+band = 'NDVI'
+start_date = '2020-01-01'
+end_date = '2020-12-31'
+scale = 30
+df = geeagri.extract_timeseries_to_point(
+    lat, lon, collection, start_date, end_date, band_names=[band], scale=scale
+)
+print(df.head())
+```
+
+df_poly = geeagri.extract_timeseries_to_polygon(
+
+## 3. Extracting a Time Series for a Polygon
+
+```python
+polygon = ee.Geometry.Polygon([
+    [[3.37, 6.52], [3.38, 6.52], [3.38, 6.53], [3.37, 6.53], [3.37, 6.52]]
+])
+df_poly = geeagri.extract_timeseries_to_polygon(
+    polygon, collection, start_date, end_date, band_names=[band], scale=scale, reducer="MEAN"
+)
+print(df_poly.head())
+```
+
+
+## 4. Harmonic Regression Example
+
+```python
+from geeagri.timeseries import HarmonicRegression
+
+ref_date = start_date
+order = 2
+hr = HarmonicRegression(collection, ref_date, band, order=order)
+harmonic_coeffs = hr.get_harmonic_coeffs()
+# You can now use hr.get_fitted_harmonics(harmonic_coeffs) for fitted values
+```
+
+df.plot(x='time', y=band, marker='o')
+
+## 5. Plotting the Results
+
+```python
+import matplotlib.pyplot as plt
+df.plot(x='time', y=band, marker='o')
+plt.title('Time Series at Point')
+plt.show()
+```

geeagri/preprocessing.py

@@ -1,4 +1,26 @@
-"""Module for preprocessing Earth Observation data using Google Earth Engine."""
+"""
+geeagri.preprocessing
+=====================
+
+This module provides preprocessing utilities for Earth Observation data using Google Earth Engine (GEE).
+It includes classes for band-wise normalization and scaling of multi-band images, enabling standardized analysis and machine learning workflows.
+
+Available scalers:
+
+- MeanCentering: Subtracts the mean of each band over a region.
+- StandardScaler: Applies z-score normalization (zero mean, unit variance).
+- MinMaxScaler: Scales each band to [0, 1] using min and max values.
+- RobustScaler: Scales each band to [0, 1] using percentiles, reducing the influence of outliers.
+
+Each scaler operates on an ee.Image and a region (ee.Geometry), and supports custom scale and pixel limits.
+
+Example usage:
+    from geeagri.preprocessing import StandardScaler
+    scaler = StandardScaler(image, region)
+    standardized = scaler.transform()
+
+These tools are useful for preparing satellite imagery for further analysis, feature extraction, or machine learning tasks.
+"""
 
 import ee