# README — EBC_code repository

**Associated publication:**
Bridging the energy balance gap in Eddy-Covariance measurements: insights from standardized network data.

**Authors:** **Giacomo Nicolini**, David Durden, Luca Di Fiore, Christopher Florian, Simone Sabbatini, Bert Gielen, Arne Iserbyt, Benjamin Loubet, Ivan Mammarella, Adriana Mariotti, Maarten Op de Beeck, Caleb Slemmons, Carlo Trotta, Adam Young, Abad Chabbi, Iris Feigenwinter, Bernard Heinesch, Natalia Kowalska, Matthias Mauder, Ladislav Šigut, Michiel van der Molen, Flavio Bastos Campos, Daniel Berveiller, Christian Brümmer, Matthias Cuntz, Jean-Christophe Domec, Benjamin Dumont, Silvano Fares, Damiano Gianelle, Rasmus Jensen, Carmen Kalalian, Natascha Kljun, Holger Lange, Jean-Marc Limousin, Erik Lundin, Antonio Manco, Leonardo Montagnani, Eiko Nemitz, Matthias Peichl, Erkka Rinne, Marilyn Roland, Marius Schmidt, Guillaume Simioni, Abin Thomas, Caroline Vincke, Dario Papale.

**License:** [MIT License](https://opensource.org/licenses/MIT)

---

## Overview

This repository contains the core R scripts used to process eddy-covariance flux data and compute Energy Balance Closure (EBC) metrics for the analyses and figures presented in the associated publication. The code covers the full processing pipeline, from loading network data to exporting the final tabular outputs deposited in the companion data repository (see [Related repositories](#related-repositories)).

> **Note:** These scripts are working research code extracted from the analysis pipeline. They contain comments partially in Italian and are not formatted for general-purpose distribution. Users wishing to adapt the code should expect to adjust file paths and input data structures to their local environment (see [Input data and path configuration](#input-data-and-path-configuration)).

---

## Repository structure

```
EBC_code/
├── README.md                              ← this file
├── EBC_pipeline.R                         ← Main pipeline script (entry point)
└── Functions/
    ├── Solar_zenith_time_functions.R      ← Solar zenith angle and twilight classification
    ├── SWIN_slope_correction_v3.R         ← Topographic corrections for incoming shortwave radiation
    ├── RadOUT_tower_disturbance.R         ← Tower structure disturbance on outgoing SW and LW radiation
    ├── Make_combos_filtered.R             ← Generation and filtering of AE/TE variable combinations
    └── EBC_calc.R                         ← EBC computation via OLS and RMA regression
```

---

## Pipeline summary overview

The main script `EBC_pipeline.R` executes the following steps in sequence:

1. **Load data** — Reads pre-processed half-hourly flux and meteorological lists for ICOS and NEON stations (non-gap-filled and gap-filled), u\* threshold outputs from OneFlux, near-real-time 2024 ICOS data, and ancillary datasets (biomass, canopy height, layer-weighted air temperature).

2. **Prepare EBC base data** — Computes half-hourly energy storage terms (Sbio, Spho) and applies radiometric corrections (topographic shading, tower shadow, field-of-view/footprint mismatch). Constructs all available combinations of available energy (AE) and turbulent energy (TE) variables, including proxy variables, for both non-gap-filled and gap-filled data.

3. **Build input lists** — Assembles the processed non-gap-filled and gap-filled data lists that feed into the EBC computation block.

4. **EBC computation** — Applies `EBC_calc.R` across all sites, AE/TE combinations, temporal scales, and stratification factors (GPP classes, atmospheric stability, relative humidity, sun elevation angle, twilight, season, year). Metrics include OLS and RMA regression statistics and energy balance imbalance/ratio.

5. **Export results** — Saves final tabular outputs to local disk. These correspond directly to the files deposited in the companion data repository (`EBC_results.csv`, `EBC_results_gapfilled.csv`, `Sbio_Spho_NRcorr.csv`).

---

## Functions

#### `Solar_zenith_time_functions.R`
A set of functions to compute the solar zenith angle and classify half-hourly periods into daytime, nighttime, and twilight. Functions used in the pipeline: `solar_zenith()` and `classify_daynight()`.

#### `SWIN_slope_correction_v3.R`
Functions to compute topographic corrections for incoming shortwave radiation (SW_IN), accounting for slope and aspect effects at each site.

#### `RadOUT_tower_disturbance.R`
Functions to estimate the disturbance of the tower structure on outgoing shortwave (SW_OUT) and longwave (LW_OUT) radiation measurements, and associated visualizations.

#### `Make_combos_filtered.R`
Function to generate and filter all valid combinations of available energy (AE) and turbulent energy (TE) variables for EBC computation.

#### `EBC_calc.R`
Core EBC computation function. Performs OLS and RMA regressions of TE vs. AE and computes energy balance imbalance (Σ(TE) − Σ(AE)) and ratio (Σ(TE)/Σ(AE)) for a given site, combination, temporal scale, and stratification factor.

---

## Input data and path configuration

The pipeline requires the following input data objects, which must be constructed from the raw network data prior to running `EBC_pipeline.R`. Raw data are publicly available from the sources listed in the companion data repository (see [Related repositories](#related-repositories)).

**File paths** throughout the scripts are set for the original analysis environment and must be updated to match local directory structure before running.

### ICOS flux data (from ICOS L2 release 2025-1)

| Object | Description |
|---|---|
| `ebc.icos.data` | Half-hourly lists built from ICOS "FLUXES" and "METEO" files |
| `flxnt.icos.data` | Lists built from ICOS "FLUXNET" files |
| `flxnt.icos.usttrhd` | u\* thresholds from OneFlux processing outputs (ARCHIVE files, GPP\_\*\_\*\_REF) |
| `ebc.GF.icos.data` | As `ebc.icos.data` but gap-filled |
| `nrt.icos.data` | Near-real-time flux data for 2024 (downloaded from the [ICOS Carbon Portal](https://data.icos-cp.eu/portal/)) |

### NEON flux data (from NEON DP4.00200.001 RELEASE-2025)

| Object | Description |
|---|---|
| `ebc.neon.data` | Half-hourly lists built from NEON "FLUXES" and "METEO" files |
| `flxnt.neon.data` | Lists built from NEON "FLUXNET" files |
| `flxnt.neon.usttrhd` | u\* thresholds from OneFlux processing outputs (ARCHIVE files, GPP\_\*\_\*\_REF) |
| `ebc.GF.neon.data` | As `ebc.neon.data` but gap-filled |

### Ancillary data (extracted from network BADMs — not redistributed)

These datasets must be prepared at half-hourly timestep from the Biological, Ancillary, Disturbance and Metadata (BADM) records of each network. They are not included in the data repository as they cannot be straightforwardly extracted and redistributed.

| Object | Description |
|---|---|
| `bio.data.dyn.icos` | Biomass data for ICOS stations (interpolated at half-hourly timestep) |
| `bio.data.dyn.neon` | Biomass data for NEON stations (interpolated at half-hourly timestep) |
| `hc.data.dyn` | Canopy height data for ICOS stations (interpolated at half-hourly timestep) |
| `TA.lw.files` | Layer-weighted mean air temperature from vertical profile data for ICOS stations (half-hourly timestep) |

---

## R environment

```
R version 4.2.1 (2022-06-23 ucrt)
Platform: x86_64-w64-mingw32/x64 (64-bit)
Running under: Windows 10 x64 (build 19045)
```

### Required packages

| Package | Version | Main use |
|---|---|---|
| `data.table` | 1.14.2 | Data manipulation |
| `dplyr` | 1.0.10 | Data manipulation |
| `tidyr` | 1.2.1 | Data reshaping |
| `purrr` | 0.3.5 | Functional programming / list operations |
| `ggplot2` | 3.5.1 | Visualization |
| `ggridges` | 0.5.7 | Ridge plots |
| `ggrepel` | 0.9.1 | Plot label repulsion |
| `vioplot` | 0.3.7 | Violin plots |
| `viridis` | 0.6.2 | Color scales |
| `scales` | 1.4.0 | Axis/scale formatting |
| `lubridate` | 1.8.0 | Date/time handling |
| `zoo` | 1.8-11 | Time series / rolling operations |
| `stringr` | 1.6.0 | String manipulation |
| `terra` | 1.6-17 | Spatial data (raster/vector) |

---

## Related repositories

- **Data repository:** [10.5281/zenodo.19608436 — EBC_data] — processed datasets produced by this pipeline
- **Raw ICOS data:** ICOS RI et al. (2025). *Ecosystem final quality (L2) product in ETC-Archive format - release 2025-1*. https://doi.org/10.18160/S6HM-CP8Q
- **Raw NEON data:** NEON (National Ecological Observatory Network). *Bundled data products - eddy covariance (DP4.00200.001), RELEASE-2025*. https://doi.org/10.48443/r7zp-y487

---

## How to cite this repository

> Nicolini, G.(2026). *EBC_code: R pipeline for energy balance closure analysis of ICOS and NEON eddy-covariance data* [Software]. Zenodo. https://doi.org/10.5281/zenodo.19631582


---

## Contact

For questions about the code or methodology, please contact the corresponding author of the associated publication.

ORCID: [0000-0002-9800-3351](https://orcid.org/0000-0002-9800-3351)
