diff --git a/.gitignore b/.gitignore
index 275fbfee..0972d26a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -45,4 +45,5 @@ data/
# Python bytecode files
.mypy_cache/
-.vscode/
\ No newline at end of file
+.vscode/
+/data
diff --git a/warehouse/SolarIrradiation_BQ_Quickstart.ipynb b/warehouse/SolarIrradiation_BQ_Quickstart.ipynb
new file mode 100644
index 00000000..28e936f3
--- /dev/null
+++ b/warehouse/SolarIrradiation_BQ_Quickstart.ipynb
@@ -0,0 +1,513 @@
+{
+ "cells": [
+ {
+ "metadata": {
+ "ExecuteTime": {
+ "end_time": "2025-09-03T13:18:31.511829Z",
+ "start_time": "2025-09-03T13:18:31.493016Z"
+ }
+ },
+ "cell_type": "code",
+ "source": [
+ "%load_ext autoreload\n",
+ "%autoreload 2"
+ ],
+ "id": "845341adbe4e6b26",
+ "outputs": [],
+ "execution_count": 1
+ },
+ {
+ "cell_type": "markdown",
+ "id": "fbf5cd51",
+ "metadata": {},
+ "source": [
+ "\n",
+ "# Solar Irradiation — BigQuery Quickstart (Kampala variables + irradiation)\n",
+ "\n",
+ "This notebook shows how to:\n",
+ "- Connect to our BigQuery dataset\n",
+ "- (Optionally) create the long NASA variables table\n",
+ "- Create a table function to fetch nearest-grid **daily** variables\n",
+ "- Fetch **Kampala** nearest variables and join with **irradiation**\n",
+ "- Plot **daily** and **monthly** normalized series together\n",
+ "\n",
+ "**Dataset:** `solar-irradiation-estimation.solar_warehouse` (EU) \n",
+ "**Tables you will use:**\n",
+ "- `irradiance_daily` — daily GHI/DHI/DNI (kWh/m²/day), partitioned by `date`\n",
+ "- `nasa_daily_vars_long` — daily NASA variables in long format (one row per `(date, lat, lon, variable_id)`)\n"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "1fd46623",
+ "metadata": {},
+ "source": [
+ "\n",
+ "## Prerequisites\n",
+ "\n",
+ "Authenticate once on your machine:\n",
+ "```bash\n",
+ "gcloud auth application-default login\n",
+ "gcloud config set project solar-irradiation-estimation\n",
+ "```\n"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "5e9a8178",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# Optional: install needed libs (uncomment)\n",
+ "# %pip install --quiet google-cloud-bigquery pandas pyarrow matplotlib\n"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "id": "2d234cb0",
+ "metadata": {
+ "ExecuteTime": {
+ "end_time": "2025-09-03T13:18:34.736315Z",
+ "start_time": "2025-09-03T13:18:33.821076Z"
+ }
+ },
+ "source": [
+ "from __future__ import annotations\n",
+ "\n",
+ "from typing import Optional, Sequence, Iterable, List\n",
+ "from datetime import date\n",
+ "from pathlib import Path\n",
+ "\n",
+ "import pandas as pd\n",
+ "import matplotlib.pyplot as plt # one chart per cell, no custom colors\n",
+ "from google.cloud import bigquery\n",
+ "from google.cloud.bigquery import ScalarQueryParameter\n",
+ "from matplotlib.typing import MarkerType\n",
+ "\n",
+ "PROJECT_ID: str = \"solar-irradiation-estimation\"\n",
+ "DATASET: str = \"solar_warehouse\"\n",
+ "DATASET_FQN: str = f\"{PROJECT_ID}.{DATASET}\"\n",
+ "print(f\"Using dataset: {DATASET_FQN}\")"
+ ],
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "Using dataset: solar-irradiation-estimation.solar_warehouse\n"
+ ]
+ }
+ ],
+ "execution_count": 2
+ },
+ {
+ "cell_type": "code",
+ "id": "62552875",
+ "metadata": {
+ "ExecuteTime": {
+ "end_time": "2025-09-03T13:18:36.584615Z",
+ "start_time": "2025-09-03T13:18:36.566548Z"
+ }
+ },
+ "source": [
+ "def create_client(project: Optional[str] = None) -> bigquery.Client:\n",
+ " \"\"\"Create an authenticated BigQuery client using ADC or a service account.\"\"\"\n",
+ " return bigquery.Client(project=project or None)\n",
+ "\n",
+ "\n",
+ "def query_to_dataframe(\n",
+ " client: bigquery.Client,\n",
+ " sql: str,\n",
+ " parameters: Optional[Sequence[ScalarQueryParameter]] = None,\n",
+ ") -> pd.DataFrame:\n",
+ " \"\"\"Run a (parameterized) query and return results as a pandas DataFrame.\"\"\"\n",
+ " job_config: Optional[bigquery.QueryJobConfig] = None\n",
+ " if parameters:\n",
+ " job_config = bigquery.QueryJobConfig(query_parameters=list(parameters))\n",
+ " job = client.query(sql, job_config=job_config)\n",
+ " result = job.result()\n",
+ " try:\n",
+ " df: pd.DataFrame = result.to_dataframe(create_bqstorage_client=True)\n",
+ " except Exception:\n",
+ " df = result.to_dataframe(create_bqstorage_client=False)\n",
+ " return df\n",
+ "\n",
+ "\n",
+ "def call_fn_nearest_point(\n",
+ " client: bigquery.Client,\n",
+ " dataset_fqn: str,\n",
+ " *,\n",
+ " lat: float,\n",
+ " lon: float,\n",
+ " start_date: date,\n",
+ " end_date: date,\n",
+ " max_km: Optional[float] = 100.0,\n",
+ ") -> pd.DataFrame:\n",
+ " \"\"\"Call the irradiance nearest-point function and return daily rows by source.\"\"\"\n",
+ " sql = f\"\"\"\n",
+ " SELECT *\n",
+ " FROM `{dataset_fqn}.fn_nearest_point`(@lat, @lon, @start_date, @end_date, @max_km)\n",
+ " ORDER BY date, source\n",
+ " \"\"\"\n",
+ " params = [\n",
+ " ScalarQueryParameter(\"lat\", \"FLOAT64\", lat),\n",
+ " ScalarQueryParameter(\"lon\", \"FLOAT64\", lon),\n",
+ " ScalarQueryParameter(\"start_date\", \"DATE\", start_date),\n",
+ " ScalarQueryParameter(\"end_date\", \"DATE\", end_date),\n",
+ " ScalarQueryParameter(\"max_km\", \"FLOAT64\", max_km),\n",
+ " ]\n",
+ " return query_to_dataframe(client, sql, params)\n",
+ "\n",
+ "def fetch_nearest_vars_daily(\n",
+ " client: bigquery.Client,\n",
+ " dataset_fqn: str,\n",
+ " *,\n",
+ " lat: float,\n",
+ " lon: float,\n",
+ " start_date: date,\n",
+ " end_date: date,\n",
+ " variable_ids: Iterable[str],\n",
+ " max_km: Optional[float] = 100.0,\n",
+ ") -> pd.DataFrame:\n",
+ " \"\"\"Fetch nearest-grid daily values for multiple variables and return a wide DataFrame.\"\"\"\n",
+ " dfs: List[pd.DataFrame] = []\n",
+ " for var in variable_ids:\n",
+ " sql = f\"\"\"\n",
+ " SELECT date, value AS {var}\n",
+ " FROM `{dataset_fqn}.fn_nearest_var_daily`(@var_id, @lat, @lon, @start_date, @end_date, @max_km)\n",
+ " ORDER BY date\n",
+ " \"\"\"\n",
+ " params = [\n",
+ " ScalarQueryParameter(\"var_id\", \"STRING\", var),\n",
+ " ScalarQueryParameter(\"lat\", \"FLOAT64\", lat),\n",
+ " ScalarQueryParameter(\"lon\", \"FLOAT64\", lon),\n",
+ " ScalarQueryParameter(\"start_date\", \"DATE\", start_date),\n",
+ " ScalarQueryParameter(\"end_date\", \"DATE\", end_date),\n",
+ " ScalarQueryParameter(\"max_km\", \"FLOAT64\", max_km),\n",
+ " ]\n",
+ " df_var = query_to_dataframe(client, sql, params)\n",
+ " dfs.append(df_var)\n",
+ "\n",
+ " df_wide = dfs[0]\n",
+ " for df_next in dfs[1:]:\n",
+ " df_wide = pd.merge(df_wide, df_next, on=\"date\", how=\"outer\")\n",
+ " df_wide = df_wide.sort_values(\"date\").reset_index(drop=True)\n",
+ " return df_wide"
+ ],
+ "outputs": [],
+ "execution_count": 3
+ },
+ {
+ "cell_type": "markdown",
+ "id": "d37503a3",
+ "metadata": {},
+ "source": [
+ "\n",
+ "## Fetch Kampala nearest variables and join with irradiation\n"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "id": "fb7813d4",
+ "metadata": {
+ "ExecuteTime": {
+ "end_time": "2025-09-03T13:18:49.527042Z",
+ "start_time": "2025-09-03T13:18:40.112899Z"
+ }
+ },
+ "source": [
+ "client = create_client(PROJECT_ID)\n",
+ "# Kampala\n",
+ "site_lat: float = 0.3476\n",
+ "site_lon: float = 32.5825\n",
+ "start_date: date = date(2024, 1, 1)\n",
+ "end_date: date = date(2024, 12, 31)\n",
+ "\n",
+ "# Variables to pull\n",
+ "vars_to_get: List[str] = [\"temperature\", \"relative_humidity\", \"aod_550\"]\n",
+ "\n",
+ "# Variables (nearest daily)\n",
+ "df_vars_daily = fetch_nearest_vars_daily(\n",
+ " client, DATASET_FQN,\n",
+ " lat=site_lat, lon=site_lon,\n",
+ " start_date=start_date, end_date=end_date,\n",
+ " variable_ids=vars_to_get, max_km=100.0\n",
+ ")\n",
+ "\n",
+ "# Irradiance (nearest daily, NASA only for overlay)\n",
+ "df_irr_daily = call_fn_nearest_point(\n",
+ " client, DATASET_FQN,\n",
+ " lat=site_lat, lon=site_lon,\n",
+ " start_date=start_date, end_date=end_date,\n",
+ " max_km=100.0\n",
+ ")\n",
+ "df_irr_nasa = df_irr_daily[df_irr_daily[\"source\"] == \"NASA\"][[\"date\", \"ghi_kwh_m2_day\"]].copy()\n",
+ "\n",
+ "# Join\n",
+ "df_join_daily = pd.merge(df_irr_nasa, df_vars_daily, on=\"date\", how=\"inner\").sort_values(\"date\")\n",
+ "df_join_daily.head()"
+ ],
+ "outputs": [
+ {
+ "name": "stderr",
+ "output_type": "stream",
+ "text": [
+ "/home/jan/.pyenv/versions/.venv_irradiation/lib/python3.11/site-packages/google/cloud/bigquery/table.py:1994: UserWarning: BigQuery Storage module not found, fetch data with the REST endpoint instead.\n",
+ " warnings.warn(\n",
+ "/home/jan/.pyenv/versions/.venv_irradiation/lib/python3.11/site-packages/google/cloud/bigquery/table.py:1994: UserWarning: BigQuery Storage module not found, fetch data with the REST endpoint instead.\n",
+ " warnings.warn(\n"
+ ]
+ },
+ {
+ "data": {
+ "text/plain": [
+ " date ghi_kwh_m2_day temperature relative_humidity aod_550\n",
+ "0 2024-01-01 4.00 21.17 85.40 0.38\n",
+ "1 2024-01-02 4.52 21.32 85.46 0.29\n",
+ "2 2024-01-03 4.09 21.24 82.15 0.36\n",
+ "3 2024-01-04 5.80 21.66 78.62 0.41\n",
+ "4 2024-01-05 3.68 22.82 73.85 0.39"
+ ],
+ "text/html": [
+ "\n",
+ "\n",
+ "
\n",
+ " \n",
+ " \n",
+ " | \n",
+ " date | \n",
+ " ghi_kwh_m2_day | \n",
+ " temperature | \n",
+ " relative_humidity | \n",
+ " aod_550 | \n",
+ "
\n",
+ " \n",
+ " \n",
+ " \n",
+ " | 0 | \n",
+ " 2024-01-01 | \n",
+ " 4.00 | \n",
+ " 21.17 | \n",
+ " 85.40 | \n",
+ " 0.38 | \n",
+ "
\n",
+ " \n",
+ " | 1 | \n",
+ " 2024-01-02 | \n",
+ " 4.52 | \n",
+ " 21.32 | \n",
+ " 85.46 | \n",
+ " 0.29 | \n",
+ "
\n",
+ " \n",
+ " | 2 | \n",
+ " 2024-01-03 | \n",
+ " 4.09 | \n",
+ " 21.24 | \n",
+ " 82.15 | \n",
+ " 0.36 | \n",
+ "
\n",
+ " \n",
+ " | 3 | \n",
+ " 2024-01-04 | \n",
+ " 5.80 | \n",
+ " 21.66 | \n",
+ " 78.62 | \n",
+ " 0.41 | \n",
+ "
\n",
+ " \n",
+ " | 4 | \n",
+ " 2024-01-05 | \n",
+ " 3.68 | \n",
+ " 22.82 | \n",
+ " 73.85 | \n",
+ " 0.39 | \n",
+ "
\n",
+ " \n",
+ "
\n",
+ "