Add mkdocs and PDFM notebook (#1)

* Add mkdocs

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Add uv

* Update branch name

* Removed pytest

* Fix site url

* Update toc

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

.github/workflows/docs-build.yml

@@ -0,0 +1,66 @@
+name: docs-build
+
+on:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  docs-build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "0.4.16"
+          # enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          uv venv
+          uv pip install -r requirements.txt
+
+      - name: Install optional dependencies
+        run: |
+          uv pip install --find-links https://girder.github.io/large_image_wheels GDAL pyproj
+
+      - name: Test import
+        run: |
+          uv run python -c "import leafmap; print('leafmap import successful')"
+          uv run python -c "from osgeo import gdal; print('gdal import successful')"
+          uv run gdalinfo --version
+
+      - name: Install mkdocs
+        run: |
+          uv pip install -r requirements_docs.txt
+          uv run mkdocs build
+
+      - name: Deploy to Netlify
+        uses: nwtgck/[email protected]
+        with:
+          publish-dir: "./site"
+          production-branch: master
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          deploy-message: "Deploy from GitHub Actions"
+          enable-pull-request-comment: true
+          enable-commit-comment: false
+          overwrites-pull-request-comment: true
+        env:
+          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
+          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
+
+      - name: Cleanup
+        if: always()
+        run: |
+          echo "Cleaning up resources."

.github/workflows/docs.yml

@@ -0,0 +1,47 @@
+name: docs
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "0.4.16"
+          # enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          uv venv
+          uv pip install -r requirements.txt
+
+      - name: Install optional dependencies
+        run: |
+          uv pip install --find-links https://girder.github.io/large_image_wheels GDAL pyproj
+
+      - name: Test import
+        run: |
+          uv run python -c "import leafmap; print('leafmap import successful')"
+          uv run python -c "from osgeo import gdal; print('gdal import successful')"
+          uv run gdalinfo --version
+
+      - name: Install mkdocs
+        run: |
+          uv pip install -r requirements_docs.txt
+          uv run mkdocs gh-deploy --force

.gitignore

@@ -2,6 +2,8 @@
 __pycache__/
 *.py[cod]
 *$py.class
+*.csv
+*.geojson
 
 # C extensions
 *.so

README.md

@@ -1,2 +1,3 @@
 # GeoAI-Tutorials
+
 A collection of Jupyter notebook examples for using GeoAI

docs/PDFM/zillow_home_value.ipynb

@@ -0,0 +1,197 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "**Predicting US Housing Prices at the Zip Code Level Using Google's Population Dynamics Foundation Model and Zillow Data**\n",
+    "\n",
+    "[![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/opengeos/GeoAI-Tutorials/blob/main/docs/PDFM/zillow_home_value.ipynb)\n",
+    "\n",
+    "## Useful Resources\n",
+    "\n",
+    "- [Google's Population Dynamics Foundation Model (PDFM)](https://github.com/google-research/population-dynamics)\n",
+    "- Request access to PDFM embeddings [here](https://github.com/google-research/population-dynamics?tab=readme-ov-file#getting-access-to-the-embeddings)\n",
+    "- Zillow data can be accessed [here](https://www.zillow.com/research/data/)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# %pip install leafmap scikit-learn"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import os\n",
+    "import pandas as pd\n",
+    "from sklearn.model_selection import train_test_split\n",
+    "from sklearn.linear_model import LinearRegression\n",
+    "from sklearn.neighbors import KNeighborsRegressor\n",
+    "from leafmap.common import evaluate_model, plot_actual_vs_predicted, download_file"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "zhvi_url = \"https://github.com/opengeos/datasets/releases/download/us/zillow_home_value_index_by_zipcode.csv\"\n",
+    "zhvi_file = \"data/zillow_home_value_index_by_zipcode.csv\""
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "if not os.path.exists(zhvi_file):\n",
+    "    download_file(zhvi_url, zhvi_file)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "zhvi_df = pd.read_csv(zhvi_file, dtype={\"RegionName\": \"string\"})\n",
+    "zhvi_df.index = zhvi_df[\"RegionName\"].apply(lambda x: f\"zip/{x}\")\n",
+    "zhvi_df.head()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "embeddings_file_path = \"data/zcta_embeddings.csv\"\n",
+    "zipcode_embeddings = pd.read_csv(embeddings_file_path).set_index(\"place\")\n",
+    "zipcode_embeddings.head()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "data = zhvi_df.join(zipcode_embeddings, how=\"inner\")\n",
+    "data.head()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "embedding_features = [f\"feature{x}\" for x in range(330)]\n",
+    "label = \"2024-10-31\""
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "data = data.dropna(subset=[label])"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "data = data[embedding_features + [label]]\n",
+    "X = data[embedding_features]\n",
+    "y = data[label]\n",
+    "\n",
+    "X_train, X_test, y_train, y_test = train_test_split(\n",
+    "    X, y, test_size=0.2, random_state=42\n",
+    ")\n",
+    "\n",
+    "# Initialize and train a simple linear regression model\n",
+    "model = LinearRegression()\n",
+    "model.fit(X_train, y_train)\n",
+    "\n",
+    "# Make predictions\n",
+    "y_pred = model.predict(X_test)\n",
+    "\n",
+    "evaluation_df = pd.DataFrame({\"y\": y_test, \"y_pred\": y_pred})\n",
+    "# Evaluate the model\n",
+    "metrics = evaluate_model(evaluation_df)\n",
+    "print(metrics)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "plot_actual_vs_predicted(evaluation_df, xlim=(0, 3_000_000), ylim=(0, 3_000_000))"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "k = 5\n",
+    "model = KNeighborsRegressor(n_neighbors=k)\n",
+    "model.fit(X_train, y_train)\n",
+    "\n",
+    "y_pred = model.predict(X_test)\n",
+    "\n",
+    "evaluation_df = pd.DataFrame({\"y\": y_test, \"y_pred\": y_pred})\n",
+    "# Evaluate the model\n",
+    "metrics = evaluate_model(evaluation_df)\n",
+    "print(metrics)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "plot_actual_vs_predicted(evaluation_df, xlim=(0, 3_000_000), ylim=(0, 3_000_000))"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "geo",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.2"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

docs/index.md

@@ -0,0 +1,3 @@
+# GeoAI-Tutorials
+
+A collection of Jupyter notebook examples for using GeoAI

docs/overrides/main.html

@@ -0,0 +1,11 @@
+{% extends "base.html" %}
+
+{% block content %}
+{% if page.nb_url %}
+    <a href="{{ page.nb_url }}" title="Download Notebook" class="md-content__button md-icon">
+        {% include ".icons/material/download.svg" %}
+    </a>
+{% endif %}
+
+{{ super() }}
+{% endblock content %}