{ "cells": [ { "cell_type": "markdown", "id": "d8ba1d9a", "metadata": {}, "source": [ "\n", "# Getting Started: Daily & Monthly Flux Footprints\n", "\n", "This notebook shows how to use **`ffp_daily_monthly_helper.py`** to:\n", "1) load AmeriFlux half‑hourly data, \n", "2) compute an xarray-based footprint climatology, \n", "3) summarize to daily/monthly periods (optionally ET‑weighted), and \n", "4) export **80%** source‑area contours to a GeoPackage or rasters to GeoTIFF.\n", "\n", "References: `ffp_daily_monthly_helper.py`【8†source】 and `ffp_xr.py`【9†source】.\n" ] }, { "cell_type": "markdown", "id": "96c9ab5d", "metadata": {}, "source": [ "\n", "## Requirements\n", "\n", "This workflow uses: `numpy`, `pandas`, `xarray`, `matplotlib`, and for exports `geopandas`, `pyproj`, `shapely`, `rasterio`.\n" ] }, { "cell_type": "code", "execution_count": 1, "id": "04085113", "metadata": { "ExecuteTime": { "end_time": "2025-08-30T01:49:43.629173Z", "start_time": "2025-08-30T01:49:43.613147Z" } }, "outputs": [], "source": [ "\n", "# --- Imports ---\n", "import os\n", "from pathlib import Path\n", "import matplotlib.pyplot as plt\n", "import pandas as pd\n", "import numpy as np\n", "\n", "import xarray as xr\n", "import sys\n", "\n", "sys.path.append(\"../../src\")\n", "\n", "from fluxfootprints import (\n", " load_config,\n", " load_amf_df,\n", " build_climatology,\n", " summarize_periods,\n", " export_contours_gpkg,\n", " export_rasters_geotiff,\n", " export_contour_stats_csv,\n", ")" ] }, { "cell_type": "markdown", "id": "fbb533d5", "metadata": {}, "source": [ "\n", "## 1) Set Paths\n", "\n", "Update these to point at your AmeriFlux config (`.ini`) and half‑hourly `.csv`.\n" ] }, { "cell_type": "code", "execution_count": 2, "id": "9487e5ba", "metadata": { "ExecuteTime": { "end_time": "2025-08-30T01:35:58.080725Z", "start_time": "2025-08-30T01:35:58.054343Z" } }, "outputs": [], "source": [ "\n", "ini_path = Path(\"./input_data/US-UTE.ini\")\n", "csv_path = Path(\"./input_data/US-UTE_HH_202406241430_202409251400.csv\")\n", "\n", "assert ini_path.exists(), f\"Config not found: {ini_path}\"\n", "assert csv_path.exists(), f\"CSV not found: {csv_path}\"\n", "\n", "out_dir = Path(\"ffp_outputs\")\n", "out_dir.mkdir(parents=True, exist_ok=True)\n" ] }, { "cell_type": "markdown", "id": "3805d386", "metadata": {}, "source": [ "\n", "## 2) Load Configuration & Data\n", "`load_config` parses a minimal INI for site metadata and column mappings. \n", "`load_amf_df` reads the CSV, parses timestamps, sets the index to time, and replaces missing value sentinels【8†source】.\n" ] }, { "cell_type": "code", "execution_count": 3, "id": "c0cb0176", "metadata": {}, "outputs": [ { "data": { "text/plain": [ "{'station_latitude': 37.7353,\n", " 'station_longitude': -111.5708,\n", " 'missing_data_value': -9999.0,\n", " 'skiprows': 0,\n", " 'date_parser': '%Y%m%d%H%M',\n", " 'ts_col': 'TIMESTAMP_START',\n", " 'wind_dir_col': 'WD',\n", " 'wind_spd_col': 'WS',\n", " 'ustar_col': 'USTAR',\n", " 'mo_length_col': 'MO_LENGTH',\n", " 'v_sigma_col': 'V_SIGMA'}" ] }, "execution_count": 3, "metadata": {}, "output_type": "execute_result" } ], "source": [ "\n", "cfg = load_config(str(ini_path))\n", "cfg\n" ] }, { "cell_type": "code", "execution_count": 4, "id": "0381143d", "metadata": {}, "outputs": [ { "data": { "application/vnd.microsoft.datawrangler.viewer.v0+json": { "columns": [ { "name": "TIMESTAMP_START", "rawType": "datetime64[ns]", "type": "datetime" }, { "name": "datetime_start", "rawType": "object", "type": "string" }, { "name": "TIMESTAMP_END", "rawType": "int64", "type": "integer" }, { "name": "CO2", "rawType": "float64", "type": "float" }, { "name": "CO2_SIGMA", "rawType": "float64", "type": "float" }, { "name": "H2O", "rawType": "float64", "type": "float" }, { "name": "H2O_SIGMA", "rawType": "float64", "type": "float" }, { "name": "FC", "rawType": "float64", "type": "float" }, { "name": "FC_SSITC_TEST", "rawType": "float64", "type": "float" }, { "name": "LE", "rawType": "float64", "type": "float" }, { "name": "LE_SSITC_TEST", "rawType": "float64", "type": "float" }, { "name": "ET", "rawType": "float64", "type": "float" }, { "name": "ET_SSITC_TEST", "rawType": "int64", "type": "integer" }, { "name": "H", "rawType": "float64", "type": "float" }, { "name": "H_SSITC_TEST", "rawType": "float64", "type": "float" }, { "name": "G", "rawType": "float64", "type": "float" }, { "name": "SG", "rawType": "float64", "type": "float" }, { "name": "FETCH_MAX", "rawType": "float64", "type": "float" }, { "name": "FETCH_90", "rawType": "float64", "type": "float" }, { "name": "FETCH_55", "rawType": "float64", "type": "float" }, { "name": "FETCH_40", "rawType": "float64", "type": "float" }, { "name": "WD", "rawType": "float64", "type": "float" }, { "name": "WS", "rawType": "float64", "type": "float" }, { "name": "WS_MAX", "rawType": "float64", "type": "float" }, { "name": "USTAR", "rawType": "float64", "type": "float" }, { "name": "ZL", "rawType": "float64", "type": "float" }, { "name": "TAU", "rawType": "float64", "type": "float" }, { "name": "TAU_SSITC_TEST", "rawType": "float64", "type": "float" }, { "name": "MO_LENGTH", "rawType": "float64", "type": "float" }, { "name": "U", "rawType": "float64", "type": "float" }, { "name": "U_SIGMA", "rawType": "float64", "type": "float" }, { "name": "V", "rawType": "float64", "type": "float" }, { "name": "V_SIGMA", "rawType": "float64", "type": "float" }, { "name": "W", "rawType": "float64", "type": "float" }, { "name": "W_SIGMA", "rawType": "float64", "type": "float" }, { "name": "PA", "rawType": "float64", "type": "float" }, { "name": "TA_1_1_1", "rawType": "float64", "type": "float" }, { "name": "RH_1_1_1", "rawType": "float64", "type": "float" }, { "name": "T_DP_1_1_1", "rawType": "float64", "type": "float" }, { "name": "VPD", "rawType": "float64", "type": "float" }, { "name": "T_SONIC", "rawType": "float64", "type": "float" }, { "name": "T_SONIC_SIGMA", "rawType": "float64", "type": "float" }, { "name": "TS_1_1_1", "rawType": "float64", "type": "float" }, { "name": "SWC_1_1_1", "rawType": "float64", "type": "float" }, { "name": "ALB", "rawType": "float64", "type": "float" }, { "name": "NETRAD", "rawType": "float64", "type": "float" }, { "name": "SW_IN", "rawType": "float64", "type": "float" }, { "name": "SW_OUT", "rawType": "float64", "type": "float" }, { "name": "LW_IN", "rawType": "float64", "type": "float" }, { "name": "LW_OUT", "rawType": "float64", "type": "float" }, { "name": "P", "rawType": "float64", "type": "float" }, { "name": "file_no", "rawType": "float64", "type": "float" }, { "name": "TA_1_2_1", "rawType": "float64", "type": "float" }, { "name": "RH_1_2_1", "rawType": "float64", "type": "float" }, { "name": "T_DP_1_2_1", "rawType": "float64", "type": "float" }, { "name": "TA_1_3_1", "rawType": "float64", "type": "float" }, { "name": "RH_1_3_1", "rawType": "float64", "type": "float" }, { "name": "T_DP_1_3_1", "rawType": "float64", "type": "float" }, { "name": "TA_1_4_1", "rawType": "float64", "type": "float" }, { "name": "PBLH_F", "rawType": "float64", "type": "float" }, { "name": "TS_2_1_1", "rawType": "float64", "type": "float" }, { "name": "SWC_2_1_1", "rawType": "float64", "type": "float" } ], "ref": "8fd1ea10-d44b-4776-91d3-de9c966699f7", "rows": [ [ "2024-06-24 14:30:00", "2024-06-24 14:30:00", "202406241500", "427.0199", "0.6281331", "17.26862", "1.01929", "0.0692101", null, "156.4085", null, "0.2317847", "1", "68.15252", null, "74.8003", "46.48377", "20.10258", "55.5867", "28.58118", "21.63193", "83.82242", "4.118659", "11.398", "0.2854266", "-0.1000675", "-0.07743155", null, "-21.72663", "3.943613", "1.289412", "0.0", "1.243537", "0.0", "0.5457488", "83.32956", "30.37961", "32.53116", "12.07391", "28.36929", "31.6011", "0.7804169", "22.91248", null, "30.47296", "535.9557", "901.6483", "279.5316", "404.7657", "490.9268", "0.0", "2.0", "29.95141", "33.26877", "12.0526", "30.32464", "33.45364", "12.46181", "30.06976", "1665.467", "25.72815", "22.44161" ], [ "2024-06-24 15:00:00", "2024-06-24 15:00:00", "202406241530", "425.9499", "1.019297", "15.18936", "0.7030515", "0.2854458", null, "138.3092", null, "0.20497", "1", "43.44571", null, "-11.26564", "-34.50821", "19.01147", "52.56938", "27.02798", "20.45655", "84.50763", "3.128728", "8.11528", "0.2287946", "-0.130162", "-0.04976684", null, "-16.70326", "2.949647", "1.087555", "0.0", "1.085609", "3.72529e-09", "0.4690718", "83.3021", "30.43124", "28.59812", "10.17519", "30.22208", "31.47819", "0.6128186", "22.98583", null, "31.01464", "404.8066", "711.1035", "227.3555", "407.2817", "486.2231", "0.0", "2.0", "30.02516", "29.22197", "10.15524", "30.35956", "29.77183", "10.72635", "30.13765", "1765.935", "25.52736", "22.41975" ], [ "2024-06-24 15:30:00", "2024-06-24 15:30:00", "202406241600", "426.4163", "1.965228", "14.87533", "0.8080265", "1.081928", null, "154.1153", null, "0.2284687", "2", "30.66234", null, "-41.83331", "-63.57699", "24.54221", "67.84465", "34.89815", "26.41252", "98.6839", "2.669845", "6.715653", "0.2784614", "-0.05601415", "-0.07362495", "1.0", "-38.81393", "2.517204", "0.9474617", "0.0", "0.9015959", "3.72529e-09", "0.4148929", "83.27771", "30.85518", "27.38244", "9.86806", "31.03824", "31.67058", "0.7545337", "23.08474", null, "29.70208", "292.8351", "546.4703", "175.4796", "408.3091", "486.4648", "0.0", "2.0", "30.24634", "28.28498", "9.838229", "30.69433", "28.63222", "10.41335", "30.40344", "1495.735", "25.12511", "22.32785" ], [ "2024-06-24 16:00:00", "2024-06-24 16:00:00", "202406241630", "426.0534", "2.665907", "15.6114", "1.002919", "0.5196642", null, "135.5618", null, "0.2010524", "2", "35.2179", null, "-35.91724", "-55.3435", "25.22658", "69.73144", "35.87147", "27.14916", "99.19427", "2.552504", "7.758736", "0.307955", "-0.04485384", "-0.08986875", null, "-48.47143", "2.415924", "0.9642583", "0.0", "0.8306037", "7.450581e-09", "0.4433303", "83.25893", "31.35262", "27.86196", "10.56774", "31.70765", "32.24849", "0.7409122", "23.06612", null, "31.21184", "331.988", "619.2519", "209.6434", "410.9713", "488.5918", "0.0", "2.0", "30.75179", "28.75255", "10.53822", "31.14621", "29.16225", "11.09066", "30.90061", "1491.062", "24.63557", "22.18172" ], [ "2024-06-24 16:30:00", "2024-06-24 16:30:00", "202406241700", "427.8476", "1.102921", "15.21034", "0.7030841", "1.147608", null, "95.06287", null, "0.1407727", "2", "-13.31553", null, "-56.61974", "-71.7462", "26.52178", "74.34869", "37.88823", "28.65891", "115.6484", "1.786293", "6.475121", "0.3013755", "0.007892104", "-0.08651999", null, "275.4816", "1.65628", "0.8001992", "0.0", "0.6585423", "-9.313226e-10", "0.4075378", "83.24686", "29.68962", "29.8947", "10.19186", "28.14444", "30.6135", "0.5463738", "22.7616", null, "28.93153", "79.40314", "209.7798", "67.09201", "404.4651", "467.7497", "0.0", "2.0", "29.16274", "30.77158", "10.16581", "29.57434", "30.96792", "10.63069", "29.3051", "341.9711", "24.14865", "22.03216" ] ], "shape": { "columns": 61, "rows": 5 } }, "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", "| \n", " | layer | \n", "time | \n", "r | \n", "area_ha | \n", "centroid_lon | \n", "centroid_lat | \n", "
|---|---|---|---|---|---|---|
| 0 | \n", "daily_mean | \n", "2024-06-24T00:00:00 | \n", "0.8 | \n", "0.5904 | \n", "-111.570587 | \n", "37.735268 | \n", "
| 1 | \n", "daily_mean | \n", "2024-06-25T00:00:00 | \n", "0.8 | \n", "0.6004 | \n", "-111.570606 | \n", "37.735296 | \n", "
| 2 | \n", "daily_mean | \n", "2024-06-26T00:00:00 | \n", "0.8 | \n", "0.6028 | \n", "-111.570570 | \n", "37.735339 | \n", "
| 3 | \n", "daily_mean | \n", "2024-06-27T00:00:00 | \n", "0.8 | \n", "0.5960 | \n", "-111.570712 | \n", "37.735303 | \n", "
| 4 | \n", "daily_mean | \n", "2024-06-28T00:00:00 | \n", "0.8 | \n", "0.5828 | \n", "-111.570730 | \n", "37.735400 | \n", "