diive is currently being prepared for the v1.0 release.
diive is a Python library for time series processing, focused on ecosystem data. It was originally developed by the
ETH Grassland Sciences group for Swiss FluxNet: eddy
covariance flux processing, gap-filling, quality control, and the plots that go with them.
There are three ways to use it, and you can pick whichever fits:
- a library —
import diive as dv, ten domain namespaces - a desktop GUI —
diive-gui, for interactive work without writing code - command-line tools — batch time-lag detection for high-resolution eddy covariance data
Project overview | Examples | GUI manual | CHANGELOG | Releases
Requires Python 3.12 or 3.13.
pip install diive # core library
pip install 'diive[gui]' # + desktop GUI, then launch with: diive-gui
pip install 'diive[gui,gui3d]' # + 3-D surface views (PyVista/VTK)
pip install 'diive[db]' # + InfluxDB read/writeWorking from a clone? CONTRIBUTING.md has the uv setup, including which optional pieces are extras
(--extra) and which are dependency groups (--group).
import diive as dv
df = dv.load_exampledata_parquet() # bundled multi-year 30-min eddy covariance record
dv.plotting.TimeSeries(series=df['NEE_CUT_REF_f']).plot()
dv.plotting.HeatmapDateTime(series=df['NEE_CUT_REF_f']).plot()Plots follow a two-phase pattern throughout: the constructor takes the data, .plot() takes the styling.
From here, the cookbook walks through six minimal workflows — load data, clean timestamps, remove outliers, gap-fill, run the flux chain, visualize.
import diive as dv exposes ten domain namespaces. Each row links to runnable examples for that area:
| Namespace | Covers | Examples |
|---|---|---|
dv.plotting |
18 plot types: time series, heatmaps, diel cycle, cumulative, ridgeline, scatter, hexbin, wind rose, tree ring, 3-D surface, ... | visualization/ |
dv.gapfilling |
RandomForestTS, XGBoostTS, FluxMDS, linear interpolation, long-term variants, FeatureEngineer |
gapfilling/ |
dv.flux |
Flux processing chain (L2–L4.2), NEE partitioning, USTAR filtering, uncertainty, high-resolution EC | flux/ |
dv.outliers |
Nine detection methods (Hampel, z-score variants, local SD, LOF, absolute limits, ...) | outlier_detection/ |
dv.corrections |
Offset corrections (measurement, radiation, humidity, wind direction), thresholds, missing values | corrections/ |
dv.qaqc |
FlagQCF quality flags, EddyPro flag handling, meteo screening |
qaqc/ |
dv.analysis |
Seasonal-trend decomposition, lagged correlation, grid aggregation, gap statistics, spectral analysis | analysis/ |
dv.times |
Timestamp sanitization, frequency detection, resampling, date-range handling | times/ |
dv.variables |
Derived variables (VPD, potential radiation, day/night flags, air properties), feature engineering | features/ |
dv.events |
Time-stamped event markers, 0/1 flag columns, plot overlays | events/ |
I/O helpers are top-level (dv.load_parquet, dv.save_parquet, dv.ReadFileType) — see io/.
For the authoritative symbol list, check diive.__all__ and each namespace's __all__.
Flux processing chain — post-processing from quality flags through gap-filling and NEE partitioning (Levels 2 to
4.2), following Swiss FluxNet standards.
Either run_chain(data, config) for the standard workflow, or composable per-level callables when you need every
detector, hyperparameter and diagnostic flag. → examples/flux/fluxprocessingchain/
NEE partitioning — four faithful ports of the reference routines, each validated against its original implementation: nighttime and daytime (Reichstein 2005, Lasslop 2010) × ONEFlux and REddyProc. Output columns are tagged so all four coexist in one dataframe. → examples/flux/partitioning/
Gap-filling — Random Forest and XGBoost with SHAP-based feature reduction, plus a faithful MDS port that needs no training. An 8-stage feature engineer feeds them all. → examples/gapfilling/
Desktop GUI — the same library code behind an interactive app: plotting, cleaning, gap-filling and flux tabs, a
guided processing chain, per-variable metadata with full provenance, and portable .diive project folders.
→ GUI manual
| Where | What |
|---|---|
| OVERVIEW.md | How the pieces fit together: library, GUI, CLI, docs, packaging |
| examples/COOKBOOK.md | Six minimal workflows — the place to start |
| examples/CATALOG.md | All 124 examples, indexed by use case |
| examples/EXAMPLE_DATASET.md | The bundled 37-variable dataset |
| diive/gui/MANUAL.md | Desktop GUI user manual |
| diive/gui/README.md | GUI architecture, for developers |
| notebooks/README.md | Jupyter workflows, including the InfluxDB database |
| packaging/README.md | Building the standalone Windows app |
| CONTRIBUTING.md | Development setup, coding standards, testing |
| CHANGELOG.md | Version history |
Examples run as plain scripts:
uv run python examples/visualization/plot_heatmap_datetime_basic.py
uv run python examples/gapfilling/gapfill_randomforest.py
uv run python examples/flux/fluxprocessingchain/fluxprocessingchain_composable.pyCite diive using DOI 10.5281/zenodo.10884017. This concept DOI resolves to
the latest release, so include the version number in your citation.
@software{diive2026,
author = {Hörtnagl, Lukas},
title = {diive: Python library for time series processing},
version = {0.91.0},
year = {2026},
doi = {10.5281/zenodo.10884017}
}Replace version and year with the values for your target release.
diive is released under the GNU General Public License v3.0.