dyco — dynamic lag compensation

dyco takes eddy covariance raw data files as input and produces lag-compensated raw data files as output, ready for flux calculation software such as EddyPro.

The method is pre-whitening with block-bootstrap (PWB), following Vitale et al. (2024). An AR(p) filter strips the serial autocorrelation out of both series before the cross-correlation is computed, which sharpens a peak that turbulence would otherwise smear. The lag is then re-estimated on block-bootstrap resamples, so each detection carries a 95% uncertainty interval instead of a bare number. The PWBOPT decision rule reads that interval, discards the detections it cannot trust, and puts a reliable neighbouring lag in their place. This is what makes low-SNR gases such as N₂O and CH₄ workable.

Start with the terminal UI, or run dyco detect-remove on the command line.

One detection method

v3 has a single way of finding the time lag between the vertical wind W and a scalar S: PWB. The covariance-maximization method that dyco shipped up to v2 was removed. CHANGELOG.md records what went and why.

Getting started

• Installation
  • From a checkout
  • Checking the install
  • Running without data
• The terminal UI
  • Its relationship to the command line
  • Settings file location
  • The two panes
  • The Check preflight
  • Stopping a run
• Worked example: a 20 Hz IRGA file
  • The raw file
  • There is no timestamp column
  • One file, two averaging periods
  • The search window
  • The command
  • What the run found
  • What the run wrote
  • Where to go next
• Worked example: a 10 Hz QCL record
  • Where the half-hourly file came from
  • The raw file
  • Settings you cannot read off the file
  • The command
  • What the run found
  • What the run wrote
  • The same run in the TUI

Reference

• Command reference
  • dyco detect-remove
  • dyco pwb-batch
  • dyco apply-batch
  • dyco tui
  • Taking a gas’s lag from another gas
  • Limiting how far a lag may be carried
  • The two-step route
  • Input file formats
• What a run writes
  • Folder layout
  • Which lag was applied, and why
  • The summary CSV
  • Diagnostic plots
  • log.txt and run_settings.txt
  • Feeding the output to flux software
• Library API
  • Splitting and rotating raw files
  • Wind rotation
  • Flux detection limit
  • Covariance maximization

Background

• The PWB method
  • Why chunks
  • The two phases
  • Pre-whitening
  • Block-bootstrap
  • The four combinations
  • PWBOPT: S1, S2, S3
  • Search windows are doing real work
  • Validation against the reference implementation
  • Further reading
• Motivation and background
  • Why lag compensation needs its own tool
  • Scientific background
  • Real-world examples
  • References
• Migrating from v2
  • What replaces what
  • Why the old method went
  • The published paper describes v1.1.2

Citing dyco

Cite the software by its Zenodo DOI, 10.5281/zenodo.4964067. That is the concept DOI: it resolves to the latest version and is the one to use for all versions. Zenodo also mints a DOI for each individual release, if the work depends on a particular one. CITATION.cff in the repository carries the full metadata.

dyco was first published in 2021 and has kept developing since. The detection method was replaced in v3, so the paper from that first release describes an algorithm the current version does not implement — see Migrating from v2.

For the method itself, cite Vitale et al. (2024); the PWB method carries the reference.

Acknowledgements

This work was supported by the Swiss National Science Foundation SNF (ICOS CH, grant nos. 20FI21_148992, 20FI20_173691) and the EU project Readiness of ICOS for Necessities of integrated Global Observations RINGO (grant no. 730944).