ConFluxPro

ConFluxPro: A toolkit for soil gas analysis - Published in JOSS (2025)

https://github.com/valentingar/confluxpro

Scientific Fields

Repository

A toolkit for soil gas analysis

README.Rmd

---
output: github_document
---



```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%",
  dev = 'svglite',
  fig.width = 8,
  fig.height = 4,
  message = FALSE,
  warning = FALSE
)
```


[![CRAN status](https://www.r-pkg.org/badges/version/ConFluxPro)](https://CRAN.R-project.org/package=ConFluxPro)
[![R-CMD-check](https://github.com/valentingar/ConFluxPro/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/valentingar/ConFluxPro/actions/workflows/R-CMD-check.yaml)
[![DOI](https://joss.theoj.org/papers/10.21105/joss.08094/status.svg)](https://doi.org/10.21105/joss.08094)



# ConFluxPro 

ConFluxPro is a free toolbox for modelling soil gas fluxes using the Flux Gradient Method (FGM). It provides functions for data preparation, a framework for model set-up and implements different FGM models, including an inverse approach. 



## Installation

You can install the latest release from CRAN:
```{r}
install.packages("ConFluxPro")
```

Install the current development version from github: 

``` r
# install.packages("remotes")
remotes::install_github("valentingar/ConFluxPro", build_vignettes = TRUE, dependencies = TRUE)
```

To get started, check out the provided vignette after installation:


``` r
vignette("ConFluxPro",package = "ConFluxPro")
```

## Basis

The Flux Gradient Method (FGM) calculates diffusive flux rates $F$ of gases from vertical concentration gradients $dc/dz$ in the soil air and the apparent diffusion coefficient coefficient $D_s$.

$$
F= -D_s\cdot \frac{dc}{dz}
$$

The FGM is an excellent alternative to other methods, such as Eddy-Covariance or chamber measurements, that can be costly or work intensive. By measuring the concentration gradients in the soil and deriving the apparent diffusion coefficient from soil physical parameters, a continuous and low-impact measurement of soil gas fluxes and vertical production profiles is possible.

While the basic calculation of fluxes may be simple, FGM requires the combination of different datasets of varying methods. This is where ConFluxPro comes in. This package can help to easily process raw data, combine datasets and set up different model variants in a straightforward and reproducible manner.

For more background, see a [review](https://doi.org/10.1016/j.agrformet.2014.03.006) on the method and how it can be deployed especially for [long-term monitoring](https://doi.org/10.3390/app10238653) of soil gas fluxes.



## Workflow

### Data handling

A central idea in ConFluxPro is that each distinct profile, i.e. a single time point at a given site for a given gas, can be uniquely identified by a set of columns called `id_cols`. 

Different classes help to set up and validate datasets:

- `cfp_gasdata()` A `data.frame` where for each profile there is concentration data in a column `x_ppm` at different depths in column `depth`.
- `cfp_soilphys()` A `data.frame` with soil physical information. Each profile is split into layers defined by their `upper` and `lower` boundary, without gaps or overlaps. Each layer has at least information of the density of the air `c_air` and the diffusion coefficient `DS` for a given gas. 
- `cfp_layers_map()` A `data.frame` that is layered similarly and gives information for the model structure, i.e. for which layers a production rate should be calculated.

```{r, echo = FALSE, message=FALSE}
library(ConFluxPro)
```


```{r, results='hide',message=TRUE}
gasdata <- cfp_gasdata(ConFluxPro::gasdata,
                       id_cols = c("site", "Date"))

soilphys <- cfp_soilphys(ConFluxPro::soilphys,
                         id_cols = c("site", "Date"))

layers_map <- cfp_layers_map(
  data.frame(site = rep(c("site_a", "site_b"), each = 3),
             upper = c(5,   0,  -20, 7,   0,  -20),
             lower = c(0, -20, -100, 0, -20, -100)),
  gas = "CO2", 
  lowlim = 0, 
  highlim = 1000,
  id_cols = "site")
```

These three datasets are then combined in the central data class `cfp_dat()`, and automatically adjusted to correctly match each other. This object contains then all necessary information.

```{r}
my_dat <- cfp_dat(gasdata, soilphys, layers_map)
my_dat
```


### Flux modeling

Once a `cfp_dat()` object is created successfully, the modelling is very easy:
```{r, message=FALSE, warning=FALSE}
# 'normal' forward model
FLUX <- fg_flux(my_dat)
# inverse model
PROFLUX <- pro_flux(my_dat)
```

Each modelling function can be adapted to different needs. For example, we can provide a different `modes` argument to `fg_flux()` to calculate the concentration gradient form an exponential fit instead of a linear model.
```{r,eval=FALSE}
FLUX <- fg_flux(my_dat, modes = "EF")
```

The result in both cases is an object that contains the original data `my_dat` and the flux rates in different soil layers for each of the profiles identified in `cfp_dat()`. From this, the soil/atmosphere efflux rate and the specific production rate in each model soil layer can be extracted.
```{r, eval=FALSE}
# soil/atmosphere efflux
efflux(FLUX)
efflux(PROFLUX)

# per-layer production rate
production(FLUX)
production(PROFLUX)
```

In the case of the forward model `FLUX`, this may require some consideration for which method of extrapolation to be used (see the manual `?efflux`), as different approaches are implemented.

`efflux()` returns a `data.frame` with one row per profile and the corresponding efflux rate. 
```{r}
library(ggplot2)
efflux(PROFLUX) %>%
  ggplot(aes(x = Date, y = efflux, col = site))+
  geom_line()+
  scale_color_viridis_d()+
  scale_x_date(date_minor_breaks = "1 month")+
  ylab(expression("CO"[2]~"efflux ["*mu*"mol m"^"-2"~"s"^"-1"*"]"))+
  theme_minimal()
```


### Extracting information

Most information stored in the objects can be easily extracted. Extraction functions have the prefix `cfp_`.
```{r, eval = FALSE}
# Get the id_cols that identify the unique profiles of an object:
cfp_id_cols(gasdata)
cfp_id_cols(FLUX)

# Get the layers_map from a combined dataset or model:
cfp_layers_map(my_dat)
cfp_layers_map(PROFLUX)
```

### Big datasets: Parallel processing and progress bars

For big datasets (1000+ profiles), some calculations may takes some time. ConFluxPro uses the excellent [`future`](https://github.com/futureverse/future) and [`progressr`](https://github.com/futureverse/progressr) packages for parallel processing and progress bars in some cpu-intensive functions. 

```{r, eval = FALSE}
library(future)
library(progressr)

# enable paralell processing with future
plan(multisession)
# disable
plan(sequential)

# enable progress bars for one function call
with_progress({pro_flux(my_dat)})
# or for all function calls automatically
handlers(global = TRUE)
# and change layout
handlers(handler_progress(format = ":percent [:bar] :eta"))
```


### Post processing

### Subsetting

Subsetting for all main data types happens analogous to `dplyr` by calling `filter()`. You can select profiles based on any `id_cols` or by selecting the `prof_id` generated in the call to `cfp_dat()`. This also works for model results.

```{r}
filter(soilphys, 
       Date == "2021-04-01",
       site == "site_b")
filter(my_dat, Date < "2021-05-01")
filter(PROFLUX, prof_id %in% c(1,7,9))
```

### Plotting 

To get a better understanding of your data, you can plot profiles with the `plot_profile()` function. This returns an editable `ggplot2` plot.

```{r, dev = 'svglite', fig.width=8, fig.height=4, out.width = '75%', fig.align='center'}
PROFLUX %>%
  filter(prof_id %in% c(16, 17)) %>%
  plot_profile()+
  ggplot2::theme_light()

soilphys %>%
  filter(Date == "2021-08-01") %>%
  plot_profile()+
  ggplot2::theme_light()
```

### Getting help

Most functionality, background and output is documented in the internal manual. Just run `?function_name` to access it. Furthermore, you can get descriptions of all parameters and their respective units with a special function `cfp_parameter()`.

```{r}
cfp_parameter("efflux")
cfp_parameter(soilphys)
```


## Contact

This package is being developed by Valentin Gartiser: 
code [at] valentingartiser.de

Please contact me if you experience any problems or have questions - I will be glad to help out where I can.

## Contribute

If you find an error or want to propose a feature you can open an issue in the github repository. Please follow the contribution guidelines.

Please note that the ConFluxPro project is released with a [Contributor Code of Conduct](https://valentingar.github.io/ConFluxPro/CODE_OF_CONDUCT.html). By contributing to this project, you agree to abide by its terms.

## License
This program is free software: you can redistribute it and/or modify it under the terms of the [GNU General Public License](https://www.gnu.org/licenses/gpl-3.0.html.en) as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

Owner

JOSS Publication

ConFluxPro: A toolkit for soil gas analysis

Published

June 26, 2025

DOI

10.21105/joss.08094

Volume 10, Issue 110, Page 8094

Authors

Valentin Gartiser
Forest Research Institute, Freiburg, Germany, Soil Physics, Department of Crop Sciences, Göttingen, Germany

Verena Lang
Forest Research Institute, Freiburg, Germany

Martin Maier
Soil Physics, Department of Crop Sciences, Göttingen, Germany

Editor

Kanishka B. Narayan

Tags

soil gas flux-gradient method flux

View PDF Review Thread Software Archive

GitHub Events

Issues and Pull Requests

Last synced: 6 months ago

Packages