Eddy covariance (EC) flux towers provide invaluable measurements of water, energy, and carbon fluxes. However, using EC measurments to develop or evaluate models of water, energy, and carbon requires linking measurements at the sesnor to the source area on land. The Kljun footprint model applies a 2-dimensional parameterization of the Flux Footprint Prediction (FFP) model (Kljun et al., 2015) to delineate the source area. Here, we build on the FFP model by optimizing functions to improve processing speed and customizing the footprint outputs (weighted GeoTIFF & GeoJSON) to more easily compare satellite-based evapotranspiration models with on-ground measurements.

• Python 3.10+
• Powershell (Windows)

Use a terminal to follow the steps below to get setup.

1. Clone the repository

   git clone https://github.com/aetriusgx/footprints.git

2. Open folder

   cd footprints

3. Activate a virtual environment and install dependencies

   1. (Method 1) Run the setup script

      # For Linux/Unix:
      source ./Scripts/setup.sh
      
      # For Windows Powershell:
      ./Scripts/setup.ps1
      
      # For Windows Terminal (experimental):
      ./Scripts/setup.bat

   2. (Method 2) Manually start and install

      # Start the virtual environment
      python -m venv .
      source bin/activate # <- Linux/Unix
      .\Scripts\Activate.ps1 # <- Windows
      
      # Update pip, if necessary
      python -m pip --upgrade pip
      
      # Install dependencies
      pip install -r requirements.txt

This is the configuration file and should be the only file you modify. The configuration schema is explained below.

An optional parameter for naming the run. This has the effect of using run_name for file outputs instead of extracting the filename from inputs.
If left empty, continues using filename for outputs.

Path to the input file.
Input data must contain the following columns (case-sensitive):
["date_time", "WS", "USTAR", "WD", "V_SIGMA", "MO_LENGTH", "instr_height_m", "canopy_height_m", "Z0_roughness"]

# Example (relative)
file = "./mydata.csv"
# Example (absolute)
file = "/Users/you/Downloads/data.csv"

A tuple of latitude and longitude of tower location. This is used in the transformation matrix for the footprint geometry. Uses EPSG:4326.

Enables weighing the footprint data by reference ETo data. This data is assumed to be a separate file that must be provided in eto_file.

Path to the reference ETo data. This field is ignored if weigh_by_eto is false.

Estimated height of the boundary layer in meters.

Percentage of source area for which to provide contours, must be between 10% and 90%

• Affects daily footprint calculation.
• Can be either a single value (e.g., "80") or a list of values (e.g., "[10, 20, 30]")
• Expressed either in percentages ("80") or as fractions of 1 ("0.8").

Specify the amount of rows that will be read from input data. Use -1 to read all rows.

Directory/Folder to place the output files in.

The spatial resolution (meters) to use for the polygon in meters per pixel.

Minimum percentile of footprint overlaps to be included in a time-integrated footprint. A value of `0.2' means cells included in generation of the output GeoJSON footprint were included in 20% of all daily footprints.

The number of pixel steps to smooth the output geometry. Higher number results in a smoother shape. See https://pypi.org/project/shapelysmooth/#taubin

If the resulting footprint results in disjointed polygons, uses best-effort approach to combine disjointed polygons.
A convex hull is performed on the polygons to create the smallest possible polygon that contains all the vertices in the geometries.

Whether to export a heatmap image showing the cummulative contribution.

Whether to export a chart displaying the footprint polygon.

This is the script application that generates the footprint and exports:

• A folder containing a shapefile
• A GeoJSON file with the geometry of the time-integrated footprint polygon.
• A heatmap image centered around the tower. Values representing the % of footprints covering a pixel.
• A figure of the footprint polygon centered around the tower.

# To run the script, simply run:
python app.py

• Shapefile containing footprint polygon
• Raster GeoTiFF containing 3 bands:
  • Band 1: Normalized dataset
  • Band 2: Polygon Mask
  • Band 3: Raw dataset containing cummulative overlaps
• Daily timeseries GeoJSON containing two columns:
  • Time: YYYY-MM-DD
  • Geometry: Footprint polygon for each timestep
• GeoJSON of footprint polygon
• Any specified charts from the [graphs] options

The footprint scripts were developed from work of Natascha Kljun of Swansea University in Swansea, UK. Please see Kljun Flux Footprint Prediction model for more information on the methods.

Copyright (c) 2015 - 2024 Natascha Kljun

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.