Metadata-Version: 2.4
Name: fluxfootprints
Version: 0.2.1
Summary: A comprehensive Python package for micrometeorological footprint analysis
Author-email: Paul Inkenbrandt <paulinkenbrandt@utah.gov>, Natascha Kljun <natascha.kljun@cec.lu.se>, John Volk <John.Volk@dri.edu>
License: GNU General Public License v3.0
Project-URL: Homepage, https://github.com/inkenbrandt/fluxfootprints
Project-URL: Documentation, https://fluxfootprints.readthedocs.io/en/stable/
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=1.5
Requires-Dist: xarray>=2023.1.0
Requires-Dist: scipy>=1.9
Requires-Dist: matplotlib>=3.6
Requires-Dist: shapely>=2.0
Requires-Dist: fiona>=1.9
Requires-Dist: geopandas>=0.14
Requires-Dist: rasterio>=1.3
Requires-Dist: pyproj>=3.5
Requires-Dist: affine>=2.4
Requires-Dist: requests>=2.28
Requires-Dist: netcdf4>=1.6
Requires-Dist: refet>=0.4
Provides-Extra: docs
Requires-Dist: sphinx>=7.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.2; extra == "docs"
Requires-Dist: myst-parser>=2.0; extra == "docs"
Requires-Dist: sphinxcontrib-bibtex>=2.5; extra == "docs"
Requires-Dist: sphinx-copybutton>=0.5; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints>=1.20; extra == "docs"
Requires-Dist: sphinx-gallery>=0.14; extra == "docs"
Requires-Dist: nbsphinx>=0.9; extra == "docs"
Requires-Dist: nbsphinx-link>=1.4; extra == "docs"
Requires-Dist: numpydoc>=1.1; extra == "docs"
Provides-Extra: examples
Requires-Dist: jupyter>=1.0; extra == "examples"
Requires-Dist: ipykernel>=6.0; extra == "examples"
Requires-Dist: matplotlib>=3.6; extra == "examples"
Requires-Dist: seaborn>=0.12; extra == "examples"
Requires-Dist: plotly>=5.15; extra == "examples"
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: pytest-cov>=4.0; extra == "test"
Requires-Dist: tox>=4.0; extra == "test"
Requires-Dist: black>=23.0; extra == "test"
Requires-Dist: ruff>=0.1; extra == "test"
Dynamic: license-file

# Flux-footprints

> **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.

---

### Table of Contents

1. [Key Features](#key-features)
2. [Installation](#installation)
3. [Quick‑start Example](#quick-start-example)
4. [Command‑line Interface](#command-line-interface)
5. [Documentation](https://fluxfootprints.readthedocs.io/en/latest/)
6. [Input Requirements](#input-requirements)
7. [Citing & Referencing](#citing--referencing)
8. [Contributing](#contributing)
9. [Development Road‑map](#development-road-map)
10. [License](#license)

---

### Key Features

| Category                | Highlights                                                                                                                                                                                                   |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Core model**          | • Implements Eq. 14 & 17 of Kljun et al. (2015) with stability‑specific coefficients<br>• Optional roughness‑sublayer corrections<br>• Supports per‑footprint filtering based on theoretical validity limits |
| **Performance**         | • Pure NumPy + xarray for vectorised calculations<br>• Lazy computation and Dask compatibility for large archives                                                                                            |
| **I/O & preprocessing** | • Pandas helpers to map tower log fields automatically<br>• Quality‑control filters for *u\* ≥ 0.1 m s⁻¹*, finite σᵥ, etc.                                                                                   |
| **Analysis tools**      | • Aggregate footprint climatologies<br>• Compute *r%* source‑area contours (10–90 %)<br>• Functions to derive transects, footprint peak statistics, and 80 % area coverage                                   |
| **Visualisation**       | • Matplotlib helpers for heat‑maps & contour overlays<br>• Geospatial export to GeoTIFF / shapefile (EPSG aware)                                                                                             |
| **Extensibility**       | • Modular class design (`FFPModel`, `FFPClimatology`)<br>• Plug‑in hooks for alternative parameter sets or dispersion schemes                                                                                |
| **Reproducibility**     | • 100 % test coverage with `pytest`<br>• Pre‑commit hooks (black, ruff, isort, doc8)                                                                                                                         |

---

### Installation

```bash
# Stable release (PyPI)
pip install fluxfootprints

# Development version (GitHub)
pip install git+https://github.com/YourOrg/fluxfootprint.git
```

> Minimum Python 3.9.  Core dependencies: `numpy`, `pandas`, `xarray`,
> `scipy`, `matplotlib`.  Optional: `dask`, `rioxarray`, `pyproj` for advanced
> geospatial export.

---

### Documentation

Full API docs, tutorials, and example notebooks are hosted at **Read the Docs**:

```
https://fluxfootprints.readthedocs.io/en/latest/
```

To build locally:

```bash
pip install -r docs/requirements.txt
sphinx-build -M html docs/ docs/_build
```

---

### Input Requirements

| 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.

---

### Citing & Referencing

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](https://doi.org/10.5194/gmd-8-3695-2015)

You may also cite the software directly (see `CITATION.cff`).

---

### Contributing

1. **Fork** → 2. **Create branch** → 3. **Commit changes**
2. **Run tests** (`pytest`) & linters (`pre‑commit run --all-files`)
3. **Open a pull‑request**

All contributions—bug reports, suggestions, or code—are welcome!

---

### Development Road‑map

* [ ] 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

---

### License

This project is licensed under the **MIT License** – see the
[`LICENSE`](LICENSE) file for details.

---

*Happy footprinting!*

