FluxFootprints is a fast, fully‑featured Python implementation of the Kljun et al. (2015) flux‑footprint parameterisation for eddy‑covariance research. It provides vectorised and xarray‑enabled utilities to compute per‑timestamp footprints, aggregate footprint climatologies, extract source‑area contours, and visualise results—scaling seamlessly from single towers to multi‑year datasets.
- Key Features
- Installation
- Quick‑start Example
- Command‑line Interface
- Documentation
- Input Requirements
- Citing & Referencing
- Contributing
- Development Road‑map
- License
| Category | Highlights |
|---|---|
| Core model | • Implements Eq. 14 & 17 of Kljun et al. (2015) with stability‑specific coefficients • Optional roughness‑sublayer corrections • Supports per‑footprint filtering based on theoretical validity limits |
| Performance | • Pure NumPy + xarray for vectorised calculations • Lazy computation and Dask compatibility for large archives |
| I/O & preprocessing | • Pandas helpers to map tower log fields automatically • Quality‑control filters for u* ≥ 0.1 m s⁻¹, finite σᵥ, etc. |
| Analysis tools | • Aggregate footprint climatologies • Compute r% source‑area contours (10–90 %) • Functions to derive transects, footprint peak statistics, and 80 % area coverage |
| Visualisation | • Matplotlib helpers for heat‑maps & contour overlays • Geospatial export to GeoTIFF / shapefile (EPSG aware) |
| Extensibility | • Modular class design (FFPModel, FFPClimatology)• Plug‑in hooks for alternative parameter sets or dispersion schemes |
| Reproducibility | • 100 % test coverage with pytest• Pre‑commit hooks (black, ruff, isort, doc8) |
# Stable release (PyPI)
pip install fluxfootprints
# Development version (GitHub)
pip install git+https://github.com/YourOrg/fluxfootprint.gitMinimum Python 3.9. Core dependencies:
numpy,pandas,xarray,scipy,matplotlib. Optional:dask,rioxarray,pyprojfor advanced geospatial export.
Full API docs, tutorials, and example notebooks are hosted at Read the Docs:
https://fluxfootprints.readthedocs.io/en/latest/
To build locally:
pip install -r docs/requirements.txt
sphinx-build -M html docs/ docs/_build| Column | Units | Description |
|---|---|---|
USTAR |
m s⁻¹ | Friction velocity, u* |
V_SIGMA |
m s⁻¹ | Lateral velocity std. dev., σᵥ |
MO_LENGTH |
m | Monin–Obukhov length, L |
WD |
° | Wind direction (0–360) |
WS |
m s⁻¹ | Mean wind speed at zₘ |
(optional) crop_height |
m | Canopy height, h_c |
(optional) atm_bound_height |
m | Boundary‑layer height, h |
Any additional columns are ignored unless you plug in custom routines.
If you use Flux-Footprints in a publication, please cite the original parameterisation:
Kljun, N., Calanca, P., Rotach, M.W., & Schmid, H.P. (2015). A simple two‑dimensional parameterisation for flux footprint prediction (FFP). Geoscientific Model Development, 8(11), 3695–3713. https://doi.org/10.5194/gmd-8-3695-2015
You may also cite the software directly (see CITATION.cff).
- Fork → 2. Create branch → 3. Commit changes
- Run tests (
pytest) & linters (pre‑commit run --all-files) - Open a pull‑request
All contributions—bug reports, suggestions, or code—are welcome!
- Footprint uncertainty quantification via Monte‑Carlo resampling
- GPU acceleration using CuPy
- Footprint aggregation across different time periods
- QGIS plug‑in for in‑map footprint visualisation
This project is licensed under the MIT License – see the
LICENSE file for details.
Happy footprinting!