{ "cells": [ { "cell_type": "markdown", "id": "7a8d8f9f", "metadata": {}, "source": [ "\n", "# Getting Started: Lagrangian Stochastic (LS) Footprint Model\n", "\n", "This notebook shows how to use the **`ls_footprint_model.py`** module to compute a simple\n", "2‑D flux footprint from eddy‑covariance tower data. It uses the attached example\n", "configuration (`US-UTE.ini`) and data file referenced therein.\n" ] }, { "cell_type": "markdown", "id": "68fa8701", "metadata": {}, "source": [ "\n", "## 1) Setup\n", "\n", "This section adjusts `sys.path` so you can import from your local source tree, then imports\n", "the LS model. If you've installed the package, the first `import` will also work.\n" ] }, { "cell_type": "code", "id": "358db358", "metadata": { "ExecuteTime": { "end_time": "2025-08-31T00:50:05.236950Z", "start_time": "2025-08-31T00:50:03.572392Z" } }, "source": [ "\n", "# --- Standard library\n", "import os, sys, math, pathlib, warnings\n", "\n", "# --- Third‑party\n", "import numpy as np\n", "import pandas as pd\n", "import matplotlib.pyplot as plt\n", "\n", "sys.path.append(\"../../src\")\n", "from fluxfootprints.ls_footprint_model import LSFootprintConfig, BackwardLSModel\n", "\n", "plt.rcParams[\"figure.dpi\"] = 120\n", "warnings.filterwarnings(\"ignore\")\n", "print(\"Imports ready.\")\n" ], "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Imports ready.\n" ] } ], "execution_count": 1 }, { "cell_type": "markdown", "id": "b811e1a9", "metadata": {}, "source": [ "\n", "## 2) Load site configuration and data\n", "\n", "We read `US-UTE.ini` to discover the time column, wind variables, and file names. Then we load the\n", "CSV it references and make a minimal set of variables needed by the LS model.\n" ] }, { "cell_type": "code", "id": "ae5371a3", "metadata": { "ExecuteTime": { "end_time": "2025-08-31T00:55:32.910237Z", "start_time": "2025-08-31T00:55:32.004735Z" } }, "source": [ "\n", "import configparser\n", "from pathlib import Path\n", "\n", "# Point to the example INI and CSV (adjust paths as needed)\n", "ini_path = Path(\"US-UTE.ini\")\n", "if not ini_path.exists():\n", " ini_path = Path(\"./input_data/US-UTE.ini\") # fallback for this shared environment\n", "\n", "cfg = configparser.ConfigParser(interpolation=None)\n", "cfg.read(ini_path)\n", "\n", "# Pull the essentials\n", "date_col = cfg.get(\"DATA\", \"datestring_col\")\n", "date_fmt = cfg.get(\"METADATA\", \"date_parser\")\n", "skiprows = cfg.getint(\"METADATA\", \"skiprows\", fallback=0)\n", "missing_val = cfg.getfloat(\"METADATA\", \"missing_data_value\", fallback=-9999.0)\n", "\n", "# Columns for wind speed and direction\n", "ws_col = cfg.get(\"DATA\", \"wind_spd_col\", fallback=\"WS\")\n", "wd_col = cfg.get(\"DATA\", \"wind_dir_col\", fallback=\"WD\")\n", "\n", "# Resolve the climate/data CSV next to the INI, or in the same folder\n", "csv_rel = cfg.get(\"METADATA\", \"climate_file_path\")\n", "csv_path = ini_path.parent / csv_rel\n", "if not csv_path.exists():\n", " csv_path = Path(\"/mnt/data\") / csv_rel # fallback\n", "\n", "# Load data\n", "parse = lambda s: pd.to_datetime(s, format=date_fmt, errors=\"coerce\")\n", "df = pd.read_csv(csv_path, skiprows=skiprows)\n", "df[date_col] = df[date_col].apply(parse)\n", "df = df.dropna(subset=[date_col]).set_index(date_col).sort_index()\n", "\n", "# Basic cleaning for common missing value flags\n", "df = df.replace({missing_val: np.nan, -9999: np.nan, -9999.0: np.nan})\n", "\n", "print(f\"Loaded {len(df):,} rows from:\", csv_path)\n", "df.head()\n" ], "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Loaded 4,463 rows from: input_data\\US-UTE_HH_202406241430_202409251400.csv\n" ] }, { "data": { "text/plain": [ " datetime_start TIMESTAMP_END CO2 CO2_SIGMA \\\n", "TIMESTAMP_START \n", "2024-06-24 14:30:00 2024-06-24 14:30:00 202406241500 427.0199 0.628133 \n", "2024-06-24 15:00:00 2024-06-24 15:00:00 202406241530 425.9499 1.019297 \n", "2024-06-24 15:30:00 2024-06-24 15:30:00 202406241600 426.4163 1.965228 \n", "2024-06-24 16:00:00 2024-06-24 16:00:00 202406241630 426.0534 2.665907 \n", "2024-06-24 16:30:00 2024-06-24 16:30:00 202406241700 427.8476 1.102921 \n", "\n", " H2O H2O_SIGMA FC FC_SSITC_TEST LE \\\n", "TIMESTAMP_START \n", "2024-06-24 14:30:00 17.26862 1.019290 0.069210 NaN 156.40850 \n", "2024-06-24 15:00:00 15.18936 0.703052 0.285446 NaN 138.30920 \n", "2024-06-24 15:30:00 14.87533 0.808026 1.081928 NaN 154.11530 \n", "2024-06-24 16:00:00 15.61140 1.002919 0.519664 NaN 135.56180 \n", "2024-06-24 16:30:00 15.21034 0.703084 1.147608 NaN 95.06287 \n", "\n", " LE_SSITC_TEST ... TA_1_2_1 RH_1_2_1 T_DP_1_2_1 \\\n", "TIMESTAMP_START ... \n", "2024-06-24 14:30:00 NaN ... 29.95141 33.26877 12.052600 \n", "2024-06-24 15:00:00 NaN ... 30.02516 29.22197 10.155240 \n", "2024-06-24 15:30:00 NaN ... 30.24634 28.28498 9.838229 \n", "2024-06-24 16:00:00 NaN ... 30.75179 28.75255 10.538220 \n", "2024-06-24 16:30:00 NaN ... 29.16274 30.77158 10.165810 \n", "\n", " TA_1_3_1 RH_1_3_1 T_DP_1_3_1 TA_1_4_1 PBLH_F \\\n", "TIMESTAMP_START \n", "2024-06-24 14:30:00 30.32464 33.45364 12.46181 30.06976 1665.4670 \n", "2024-06-24 15:00:00 30.35956 29.77183 10.72635 30.13765 1765.9350 \n", "2024-06-24 15:30:00 30.69433 28.63222 10.41335 30.40344 1495.7350 \n", "2024-06-24 16:00:00 31.14621 29.16225 11.09066 30.90061 1491.0620 \n", "2024-06-24 16:30:00 29.57434 30.96792 10.63069 29.30510 341.9711 \n", "\n", " TS_2_1_1 SWC_2_1_1 \n", "TIMESTAMP_START \n", "2024-06-24 14:30:00 25.72815 22.44161 \n", "2024-06-24 15:00:00 25.52736 22.41975 \n", "2024-06-24 15:30:00 25.12511 22.32785 \n", "2024-06-24 16:00:00 24.63557 22.18172 \n", "2024-06-24 16:30:00 24.14865 22.03216 \n", "\n", "[5 rows x 61 columns]" ], "text/html": [ "
| \n", " | datetime_start | \n", "TIMESTAMP_END | \n", "CO2 | \n", "CO2_SIGMA | \n", "H2O | \n", "H2O_SIGMA | \n", "FC | \n", "FC_SSITC_TEST | \n", "LE | \n", "LE_SSITC_TEST | \n", "... | \n", "TA_1_2_1 | \n", "RH_1_2_1 | \n", "T_DP_1_2_1 | \n", "TA_1_3_1 | \n", "RH_1_3_1 | \n", "T_DP_1_3_1 | \n", "TA_1_4_1 | \n", "PBLH_F | \n", "TS_2_1_1 | \n", "SWC_2_1_1 | \n", "
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| TIMESTAMP_START | \n", "\n", " | \n", " | \n", " | \n", " | \n", " | \n", " | \n", " | \n", " | \n", " | \n", " | \n", " | \n", " | \n", " | \n", " | \n", " | \n", " | \n", " | \n", " | \n", " | \n", " | \n", " |
| 2024-06-24 14:30:00 | \n", "2024-06-24 14:30:00 | \n", "202406241500 | \n", "427.0199 | \n", "0.628133 | \n", "17.26862 | \n", "1.019290 | \n", "0.069210 | \n", "NaN | \n", "156.40850 | \n", "NaN | \n", "... | \n", "29.95141 | \n", "33.26877 | \n", "12.052600 | \n", "30.32464 | \n", "33.45364 | \n", "12.46181 | \n", "30.06976 | \n", "1665.4670 | \n", "25.72815 | \n", "22.44161 | \n", "
| 2024-06-24 15:00:00 | \n", "2024-06-24 15:00:00 | \n", "202406241530 | \n", "425.9499 | \n", "1.019297 | \n", "15.18936 | \n", "0.703052 | \n", "0.285446 | \n", "NaN | \n", "138.30920 | \n", "NaN | \n", "... | \n", "30.02516 | \n", "29.22197 | \n", "10.155240 | \n", "30.35956 | \n", "29.77183 | \n", "10.72635 | \n", "30.13765 | \n", "1765.9350 | \n", "25.52736 | \n", "22.41975 | \n", "
| 2024-06-24 15:30:00 | \n", "2024-06-24 15:30:00 | \n", "202406241600 | \n", "426.4163 | \n", "1.965228 | \n", "14.87533 | \n", "0.808026 | \n", "1.081928 | \n", "NaN | \n", "154.11530 | \n", "NaN | \n", "... | \n", "30.24634 | \n", "28.28498 | \n", "9.838229 | \n", "30.69433 | \n", "28.63222 | \n", "10.41335 | \n", "30.40344 | \n", "1495.7350 | \n", "25.12511 | \n", "22.32785 | \n", "
| 2024-06-24 16:00:00 | \n", "2024-06-24 16:00:00 | \n", "202406241630 | \n", "426.0534 | \n", "2.665907 | \n", "15.61140 | \n", "1.002919 | \n", "0.519664 | \n", "NaN | \n", "135.56180 | \n", "NaN | \n", "... | \n", "30.75179 | \n", "28.75255 | \n", "10.538220 | \n", "31.14621 | \n", "29.16225 | \n", "11.09066 | \n", "30.90061 | \n", "1491.0620 | \n", "24.63557 | \n", "22.18172 | \n", "
| 2024-06-24 16:30:00 | \n", "2024-06-24 16:30:00 | \n", "202406241700 | \n", "427.8476 | \n", "1.102921 | \n", "15.21034 | \n", "0.703084 | \n", "1.147608 | \n", "NaN | \n", "95.06287 | \n", "NaN | \n", "... | \n", "29.16274 | \n", "30.77158 | \n", "10.165810 | \n", "29.57434 | \n", "30.96792 | \n", "10.63069 | \n", "29.30510 | \n", "341.9711 | \n", "24.14865 | \n", "22.03216 | \n", "
5 rows × 61 columns
\n", "