fluxfootprints 0.1.0__tar.gz

fluxfootprints-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+/.pytest_cache
+/.idea
+/__pycache__
+/.vscode
+/src/fluxfootprints/__pycache__
+/docs/_build
+/docs/notebooks/output
+/docs/notebooks/example.log
+/secrets
+/data/logs
+/data/station_data
+/data/station_config/output
+/docs/notebooks/NLDAS_data
+/docs/notebooks/2021_utah_merged.parquet
+/docs/notebooks/2021_utah_merged.nc

fluxfootprints-0.1.0/.idea/.gitignore

@@ -0,0 +1,8 @@
+# Default ignored files
+/shelf/
+/workspace.xml
+# Editor-based HTTP Client requests
+/httpRequests/
+# Datasource local storage ignored files
+/dataSources/
+/dataSources.local.xml

fluxfootprints-0.1.0/.idea/footprints.iml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="PYTHON_MODULE" version="4">
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$" />
+    <orderEntry type="jdk" jdkName="Python 3.13" jdkType="Python SDK" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+</module>

fluxfootprints-0.1.0/.idea/inspectionProfiles/Project_Default.xml

@@ -0,0 +1,19 @@
+<component name="InspectionProjectProfileManager">
+  <profile version="1.0">
+    <option name="myName" value="Project Default" />
+    <inspection_tool class="PyCompatibilityInspection" enabled="true" level="WARNING" enabled_by_default="true">
+      <option name="ourVersions">
+        <value>
+          <list size="6">
+            <item index="0" class="java.lang.String" itemvalue="3.13" />
+            <item index="1" class="java.lang.String" itemvalue="3.8" />
+            <item index="2" class="java.lang.String" itemvalue="3.9" />
+            <item index="3" class="java.lang.String" itemvalue="3.10" />
+            <item index="4" class="java.lang.String" itemvalue="3.11" />
+            <item index="5" class="java.lang.String" itemvalue="3.12" />
+          </list>
+        </value>
+      </option>
+    </inspection_tool>
+  </profile>
+</component>

fluxfootprints-0.1.0/.idea/inspectionProfiles/profiles_settings.xml

@@ -0,0 +1,6 @@
+<component name="InspectionProjectProfileManager">
+  <settings>
+    <option name="USE_PROJECT_PROFILE" value="false" />
+    <version value="1.0" />
+  </settings>
+</component>

fluxfootprints-0.1.0/.idea/misc.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="Black">
+    <option name="enabledOnReformat" value="true" />
+    <option name="enabledOnSave" value="true" />
+    <option name="sdkName" value="pygis12" />
+  </component>
+  <component name="ProjectRootManager" version="2" project-jdk-name="Python 3.13" project-jdk-type="Python SDK" />
+</project>

fluxfootprints-0.1.0/.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/footprints.iml" filepath="$PROJECT_DIR$/.idea/footprints.iml" />
+    </modules>
+  </component>
+</project>

fluxfootprints-0.1.0/.idea/vcs.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="$PROJECT_DIR$" vcs="Git" />
+  </component>
+</project>

fluxfootprints-0.1.0/.readthedocs.yaml

@@ -0,0 +1,23 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version, and other tools you might need
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+   configuration: docs/conf.py
+
+# Optionally, but recommended,
+# declare the Python requirements required to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+  install:
+    - requirements: docs/requirements.txt
+        

fluxfootprints-0.1.0/.vscode/launch.json

@@ -0,0 +1,15 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Python Debugger: Current File",
+            "type": "debugpy",
+            "request": "launch",
+            "program": "${file}",
+            "console": "integratedTerminal"
+        }
+    ]
+}

fluxfootprints-0.1.0/CITATION.cff

@@ -0,0 +1,19 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+authors:
+- family-names: "Kljun"
+  given-names: "Natascha"
+  orcid: "https://orcid.org/0000-0001-9650-2184"
+- family-names: "Volk"
+  given-names: "John"
+  orcid: "https://orcid.org/0000-0001-9994-1545"
+- family-names: "Inkenbrandt"
+  given-names: "Paul"
+  orcid: "https://orcid.org/0000-0002-9194-5936"
+- family-names: "Schroeder"
+  given-names: "Martin"
+title: "flux-footprints"
+version: 0.1.0
+doi: 10.5281/zenodo.1234
+date-released: 2025-05-01
+url: "https://github.com/inkenbrandt/footprints"

fluxfootprints-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 inkenbrandt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fluxfootprints-0.1.0/PKG-INFO

@@ -0,0 +1,230 @@
+Metadata-Version: 2.4
+Name: fluxfootprints
+Version: 0.1.0
+Summary: A comprehensive Python package for micrometeorological footprint analysis
+Author-email: Paul Inkenbrandt <paulinkenbrandt@utah.gov>, Kathryn Ladig <kladig@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/micromet
+Project-URL: Documentation, https://micromet.readthedocs.io/en/stable/
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: python>=3.10
+Requires-Dist: numpy>=1.20
+Requires-Dist: pandas>=1.3
+Requires-Dist: scipy>=1.7
+Requires-Dist: matplotlib>=3.4
+Requires-Dist: plotly>=5.0
+Requires-Dist: sqlalchemy>=1.4
+Requires-Dist: pyyaml>=5.4
+Requires-Dist: requests>=2.25
+Requires-Dist: xarray>=0.18
+Requires-Dist: netcdf4>=1.5
+Requires-Dist: pyproj>=3.2
+Requires-Dist: rasterio>=1.2
+Requires-Dist: geopandas>=0.9
+Requires-Dist: shapely>=1.7
+Requires-Dist: affine>=2.3
+Requires-Dist: cv2>=4.5
+Requires-Dist: fluxdataqaqc>=0.1.0
+Requires-Dist: refet>=0.1.0
+Provides-Extra: docs
+Requires-Dist: sphinx>=4.0; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=1.0; extra == "docs"
+Requires-Dist: sphinx-copybutton>=0.5; extra == "docs"
+Requires-Dist: sphinx-autodoc-typehints>=1.12; extra == "docs"
+Requires-Dist: myst-parser>=0.15; extra == "docs"
+Requires-Dist: numpydoc>=1.1; extra == "docs"
+Requires-Dist: nbsphinx>=0.8; extra == "docs"
+Provides-Extra: test
+Requires-Dist: pytest>=6.0; extra == "test"
+Requires-Dist: pytest-cov>=2.0; extra == "test"
+Dynamic: license-file
+
+# Flux-footprints
+
+> **FluxFootprint** 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](#documentation)
+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 fluxfootprint
+
+# 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.
+
+---
+
+### Quick‑start Example
+
+```python
+import pandas as pd
+from fluxfootprint import FFPModel
+
+# 1. Load half‑hourly tower data ----------------------------
+df = pd.read_csv("AMF_US-CRT_BASE_HH_3-5_abb.csv", parse_dates=["TIMESTAMP"])
+
+# Minimal renaming if your columns differ
+df = df.rename(
+    columns={
+        "V_SIGMA": "V_SIGMA",
+        "USTAR": "USTAR",
+        "MO_LENGTH": "MO_LENGTH",
+        "WD": "WD",
+        "WS": "WS",
+    }
+)
+
+# 2. Instantiate the model ----------------------------------
+model = FFPModel(
+    df,
+    domain=[-1_000, 1_000, -1_000, 1_000],
+    dx=2,
+    dy=2,
+    inst_height=3.5,
+    crop_height=0.2,
+    smooth_data=True,
+)
+
+# 3. Run & retrieve results ---------------------------------
+result = model.run()            # dict with x_2d, y_2d, fclim_2d …
+
+# 4. Plot 80 % source area ----------------------------------
+model.plot_contour(r=0.8)
+```
+
+---
+
+### Command‑line Interface
+
+```bash
+# Compute footprint climatology for a CSV file
+fluxfootprint run \
+  --input  met_data.csv \
+  --dz     3.5 \
+  --domain -1000 1000 -1000 1000 \
+  --dx     2 \
+  --out    footprint.nc
+```
+
+Run `fluxfootprint --help` for all options.
+
+---
+
+### Documentation
+
+Full API docs, tutorials, and example notebooks are hosted at **Read the Docs**:
+
+```
+https://fluxfootprint.readthedocs.io
+```
+
+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!*
+

fluxfootprints-0.1.0/README.md

@@ -0,0 +1,187 @@
+# Flux-footprints
+
+> **FluxFootprint** 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](#documentation)
+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 fluxfootprint
+
+# 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.
+
+---
+
+### Quick‑start Example
+
+```python
+import pandas as pd
+from fluxfootprint import FFPModel
+
+# 1. Load half‑hourly tower data ----------------------------
+df = pd.read_csv("AMF_US-CRT_BASE_HH_3-5_abb.csv", parse_dates=["TIMESTAMP"])
+
+# Minimal renaming if your columns differ
+df = df.rename(
+    columns={
+        "V_SIGMA": "V_SIGMA",
+        "USTAR": "USTAR",
+        "MO_LENGTH": "MO_LENGTH",
+        "WD": "WD",
+        "WS": "WS",
+    }
+)
+
+# 2. Instantiate the model ----------------------------------
+model = FFPModel(
+    df,
+    domain=[-1_000, 1_000, -1_000, 1_000],
+    dx=2,
+    dy=2,
+    inst_height=3.5,
+    crop_height=0.2,
+    smooth_data=True,
+)
+
+# 3. Run & retrieve results ---------------------------------
+result = model.run()            # dict with x_2d, y_2d, fclim_2d …
+
+# 4. Plot 80 % source area ----------------------------------
+model.plot_contour(r=0.8)
+```
+
+---
+
+### Command‑line Interface
+
+```bash
+# Compute footprint climatology for a CSV file
+fluxfootprint run \
+  --input  met_data.csv \
+  --dz     3.5 \
+  --domain -1000 1000 -1000 1000 \
+  --dx     2 \
+  --out    footprint.nc
+```
+
+Run `fluxfootprint --help` for all options.
+
+---
+
+### Documentation
+
+Full API docs, tutorials, and example notebooks are hosted at **Read the Docs**:
+
+```
+https://fluxfootprint.readthedocs.io
+```
+
+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!*
+