goAquaFlux

Diffusive and ebullitive GHG flux partitioning for aquatic floating chambers

Overview

goAquaFlux extends the goFlux R package (Rheault et al., 2024) to aquatic floating-chamber measurements, where methane reaches the atmosphere by two pathways with very different behaviour:

  • Diffusion — a smooth, near-linear accumulation in the chamber headspace.
  • Ebullition — bubbles, appearing as abrupt steps in concentration.

Standard chamber-flux software models a single smooth signal, so a naive fit either discards bubble-affected incubations or silently folds ebullition into a biased “diffusive” estimate. goAquaFlux detects the steps, fits the diffusive flux on a bubble-free window using goFlux’s validated LM/HM models and QA/QC, and returns a partitioned total.

How it works

The workflow is a pipeline of four steps, one function each, coordinated by goAquaFlux() across all incubations in a dataset (split by UniqueID):

  1. Detect the bubbles. find.bubbles() robustly standardises the concentration series (typically CH4dry_ppb) and scans it with a rolling variance, taken either over the first differences ("diff", the default, robust to a steep diffusive trend) or over the concentration itself ("variance", more sensitive to small steps on quiet traces). Contiguous periods above an adaptive threshold are flagged as bubbling events, and each event’s size is then estimated as a local step on top of the diffusive trend.
  2. Fit the diffusive flux. goAquaFlux.diffusive() fits the diffusive component on the bubble-free window (truncated at the first event) using goFlux’s linear (LM) and non-linear (HM) models and the model-selection criteria. For non-bubble gases, the window is only cut at a bubble that coincides with an abrupt slope change.
  3. Compute the ebullitive flux. goAquaFlux.ebullition() converts the summed bubble magnitudes into a flux, \(F_E = \frac{\sum \Delta C_{\text{bubble}}}{t_{inc}} \times K\), with standard errors propagated from the per-event magnitudes, and returns an independent two-point endpoint estimate for diagnosis.
  4. Combine and check. goAquaFlux.total() adds the two components, \(F_T = F_E + F_D\), propagates the error assuming independence (\(SE_T = \sqrt{SE_E^2 + SE_D^2}\)), and flags results that are suspiciously larger than the endpoint estimate (e.g. a diffusive ramp mistaken for a bubble step).

flux.plot.aqua() then produces one diagnostic plot per incubation: the concentration series, the shaded diffusive window, the detected bubbling events, and a legend of the total / diffusive / ebullitive fluxes.

Installation

# install.packages("remotes")
# The aquatic extension is part of goFlux from v0.3.2 onwards.
remotes::install_github("Qepanna/goFlux")

Quick start

library(goFlux)

fluxres <- goAquaFlux(
  dataframe            = IDed,          # output of goFlux::autoID()
  gastype              = "CH4dry_ppb",
  use_bubble_detection = TRUE
)

# The detector is tunable. "diff" is the default; "variance" can be more
# sensitive to small bubbles on low-emission incubations.
fluxres <- goAquaFlux(
  dataframe            = IDed,
  gastype              = "CH4dry_ppb",
  use_bubble_detection = TRUE,
  bubble.method        = "variance",
  bubble.args          = list(min_magnitude = 10)
)

flux.plot.aqua(fluxres, IDed, gastype = "CH4dry_ppb",
               plot.display = c("diffusive.window", "ebullition.events"))

Functions

goAquaFlux for computing gas fluxes from aquatic chamber measurements

Main entry point: partitions aquatic GHG fluxes into diffusive and ebullitive components across many incubations.

Note

Code chunks under Usage sections are not part of the demonstration. They are meant to show how to use the function arguments.

View the goAquaFlux source code on GitHub

Usage

goAquaFlux(
  dataframe,
  gastype,
  H2O_col = "H2O_ppm",
  prec = NULL,
  criteria = c("MAE", "RMSE", "AICc", "SE", "g.factor", "kappa", "MDF", "nb.obs",
    "intercept", "p-value"),
  Area = NULL,
  offset = NULL,
  Vtot = NULL,
  Vcham = NULL,
  Pcham = NULL,
  Tcham = NULL,
  use_bubble_detection = TRUE,
  bubble.window.size = 15,
  bubble_gas = "CH4dry_ppb",
  bubble.method = "diff",
  bubble.args = list(),
  ebullition.final_window_min = 30,
  ebullition.window_C0Cf = 10,
  diffusion.minimum_window = 30,
  diagnostics.args = list(),
  return_df = TRUE
)

Arguments

Argument Description
dataframe A data.frame containing time series observations for one or more chamber incubations.
gastype Character string indicating the gas concentration column to use for flux calculation. Allowed values include: "CO2dry_ppm", "CH4dry_ppb", "COdry_ppb", "N2Odry_ppb", "NH3dry_ppb", "NO2dry_ppb", "NOdry_ppb", and "H2O_ppm".
H2O_col Character string specifying the column containing water vapor concentration used for dilution correction. Default is "H2O_ppm". If NULL, water vapor correction is disabled.
prec Numeric scalar specifying instrument precision for the gas analyzer. If NULL, precision is retrieved from the corresponding precision column in dataframe (e.g. CH4_prec).
criteria Character vector specifying model selection criteria used by goFlux. Default criteria include "MAE", "RMSE", "AICc", "SE", "g.factor", "kappa", "MDF", "nb.obs", "intercept", and "p-value".
Area Numeric scalar; chamber base area in cm2 (as in goFlux; note the internal factor of 10,000 to m2). If NULL, the value is retrieved from the Area column in dataframe.
offset Numeric scalar; height between the water surface and the chamber top in cm, used to compute Vtot as Vcham + Area * offset / 1000 when Vtot is not provided.
Vtot Numeric scalar specifying total chamber volume (L). If NULL, it is calculated as: \(Vtot = Vcham + (Area * offset) / 1000\)
Vcham Numeric scalar representing chamber headspace volume (L). Used only when Vtot is not provided.
Pcham Numeric scalar representing chamber pressure (kPa). If NULL, atmospheric pressure (101.325 kPa) is assumed.
Tcham Numeric scalar representing chamber temperature (°C). If NULL, a default temperature of 15 °C is assumed.
use_bubble_detection Logical; if TRUE (default) bubbling events are detected using bubble_gas and, when gastype == bubble_gas, the flux is partitioned into diffusive and ebullitive components. If FALSE, no bubble detection is performed and only a diffusive flux is returned.
bubble.window.size Integer specifying the rolling window size (number of observations) used for bubble detection.
bubble_gas Character string specifying the gas used to detect bubbling events. Default is "CH4dry_ppb".
bubble.method Character; dispersion metric passed to find.bubbles: "mad" (default), "variance" or "diff" (rolling variance of increments, robust to a diffusive trend).
bubble.args Named list of additional arguments forwarded to find.bubbles (e.g. list(k = 5, min_magnitude = 10)). Values here override the defaults for advanced tuning.
ebullition.final_window_min Minimum time window (seconds) required after the last bubble event to define the incubation end for ebullition flux calculation.
ebullition.window_C0Cf Time window (seconds) used to compute initial and final concentrations for the endpoint flux estimate.
diffusion.minimum_window Minimum number of observations required to compute diffusive flux before the first bubble event.
diagnostics.args Named list of arguments passed to goAquaFlux.diagnostics (window_C0Cf, tolerance, min_snr, dl_sigma).
return_df Logical. If TRUE (default) the function returns a tidy list of four data frames (see Value). If FALSE, the raw per-incubation results list is returned instead, which is convenient for advanced users who want the untidied intermediate objects.

Details

The workflow includes: (1) data validation and cleaning; (2) calculation of auxiliary variables (flux conversion term and MDF); (3) bubble detection (typically using CH4 concentration); (4) estimation of ebullition flux based on detected bubble magnitudes; (5) estimation of diffusive flux using model selection; (6) combination of the diffusive and ebullitive components into a total flux; and (7) quality checks: best.flux for the diffusive fit and, for the gas on which bubbles are detected, goAquaFlux.diagnostics for the ebullitive component.

The function operates on datasets containing multiple chamber incubations, which are automatically split using the UniqueID column.

Bubble detection is performed using a rolling window approach applied to concentration variability of the selected gas (typically CH4). Detected bubbling events are used to estimate ebullition fluxes and restrict the time window used for diffusive flux estimation.

Diffusive fluxes are calculated using the goFlux framework, which evaluates multiple regression models and selects the best model according to user-defined criteria.

Quality is reported in two complementary columns, following the conventions of best.flux (an empty string means that all checks were passed):

  • quality.check concerns the diffusive fit. It is the column returned by best.flux for the diffusive window, so that a diffusive flux from goAquaFlux() is checked exactly as one from goFlux() .
  • ebullition.check concerns the ebullitive component and is computed only for the gas on which bubbles are detected ( bubble_gas ), by goAquaFlux.diagnostics : whether the diffusive and ebullitive components account for the gas that accumulated in the chamber (mass-balance closure), and which ebullitive flux could have gone undetected when no bubble was found. For any other gas it is NA : its fluxes are then assessed from its own observations only, through quality.check .

Incubations with a non-empty quality.check or ebullition.check should be inspected, e.g. with flux.plot.aqua.

Examples

# Not run:

results <- goAquaFlux(
  dataframe = chamber_data,
  gastype = "CH4dry_ppb"
)

find.bubbles for detecting ebullition events

Detects bubbling (ebullition) events as abrupt steps in a concentration series.

View the find.bubbles source code on GitHub

Usage

find.bubbles(
  df,
  bubble_source,
  window.size = 15,
  dt = 1,
  method = c("diff", "variance"),
  var.quantile = 0.7,
  k = 4,
  min_ratio = 3,
  min_sd = NULL,
  min_gap = 10,
  min_length = 5,
  max_reg_window = 120,
  reg.min.obs = 10,
  min_magnitude = 5,
  min_snr = NULL,
  magnitude.model = c("step_reequil", "step"),
  tau.range = c(2, NA),
  exclude.ramp = TRUE,
  allow.slow.approach = FALSE
)

Arguments

Argument Description
df A data.frame containing the incubation time series. Must include an Etime column (elapsed time, seconds) and the concentration column named by bubble_source.
bubble_source Character; name of the concentration column used for detection (e.g. "CH4dry_ppb").
window.size Integer; width of the moving window (in interpolated time steps) used to compute rolling dispersion. Default 15.
dt Numeric; temporal resolution (seconds) of the regular grid the signal is interpolated onto before rolling statistics. Default 1.
method Character; dispersion metric. Either "diff" (default), the rolling variance of the first differences, or "variance", the rolling variance of the concentration itself. "diff" is largely insensitive to a linear diffusive trend and is the safer general-purpose choice; "variance" is more sensitive to small steps on quiet, low-emission traces (see Details).
var.quantile Numeric in (0, 1); empirical quantile of the rolling dispersion distribution used in the adaptive threshold. Default 0.7.
k Numeric; multiplier on the MAD of the rolling dispersion in the robust threshold (\(median + k \times MAD\)). Larger values are more conservative. Default 4.
min_ratio Numeric; minimum ratio of the maximum to the median rolling dispersion required before any detection is attempted. Guards against detections in flat, low-variance incubations. Default 3.
min_sd Numeric or NULL; if set, incubations whose overall standard deviation is below this value return NULL (no detection).
min_gap Numeric; events separated by less than this gap (seconds) are merged. Default 10.
min_length Numeric; minimum event duration (seconds) to retain. Default 5.
max_reg_window Numeric; maximum half-window (seconds) used for the local magnitude regression around each event. Default 120.
reg.min.obs Integer; minimum observations required for the magnitude regression. Default 10.
min_magnitude Numeric or NULL; minimum step magnitude (same units as bubble_source) to retain an event. Default 5.
min_snr Numeric or NULL; if set, minimum signal-to-noise ratio (magnitude / SE) to retain an event.
magnitude.model Character; model used to estimate event magnitude. "step_reequil" (default) adds an exponential re-equilibration term after the transient peak, so that magnitude is the settled step, i.e. the gas that remains in the headspace once the bubble has mixed (see Details). "step" is the plain step regression without a re-equilibration term.
tau.range Numeric vector of length 2; lower and upper bounds (seconds) of the re-equilibration time constant \(\tau\) explored when magnitude.model = "step_reequil". An NA upper bound (default) means the length of the post-peak data available for the regression. Default c(2, NA).
exclude.ramp Logical; if TRUE (default), the observations on the steep rise of the bubble (between the last pre-bubble observation and the transient peak) are excluded from the magnitude regression, because they belong neither to the pre-bubble nor to the post-bubble level.
allow.slow.approach Logical; if FALSE (default), the re-equilibration term must describe a positive overshoot that decays towards the settled level (\(\beta_3 > 0\)). If TRUE, a gradual approach from below (\(\beta_3 < 0\)) is also allowed. This can recover steps that mix slowly into the headspace, but it can also turn a change in diffusive slope into a spurious step.

Details

Detection. The signal is first robustly standardised (median / MAD) and interpolated onto a regular dt-second grid. Rolling dispersion is then computed and compared to an adaptive threshold defined as the maximum of an empirical quantile (var.quantile) and a robust bound (\(median + k \times MAD\)). Contiguous supra-threshold runs are merged (min_gap) and filtered by duration (min_length).

The two methods differ in what the variance is taken over. "variance" uses the concentration itself, which responds strongly to a step but is also inflated by a steep diffusive rise, so its detection power falls as the trend grows relative to the step. "diff" uses the increments: an ebullition step produces one large increment and a sharp spike, whereas a linear diffusive trend produces roughly constant increments and therefore low differenced dispersion. "diff" is consequently the more robust default across emission regimes, while "variance" retains an advantage for small steps on quiet traces, where differencing amplifies measurement noise.

A rolling median absolute deviation was evaluated as a third metric and removed: being robust by construction, it suppresses the very outlier that marks a bubble. On test incubations it produced only weak contrast, fragmented single events into several, and inflated summed event magnitude accordingly.

Magnitude, plain step model. With magnitude.model = "step", event magnitude is estimated with the local model \(C_t = \beta_0 + \beta_1 (t - t_b) + \beta_2 I(t \ge t_s)\) where \(t_b\) is the time of the largest positive increment within the event, \(I(t \ge t_s)\) is a step dummy and \(\beta_2\) is the magnitude. The pre- and post-bubble lines share the slope \(\beta_1\), so \(\beta_2\) is their vertical offset. The dummy switches at \(t_s = t_b\), or at the transient peak \(t_p\) when exclude.ramp = TRUE (with the rise removed, both choices separate the same two groups of observations). The regression uses the observations between the neighbouring events, limited to max_reg_window seconds on each side of \(t_b\).

Magnitude, step + re-equilibration model. Chamber records of bubbling events usually show a jump, a transient peak and a re-equilibration, rather than a clean step: the bubble gas reaches the analyser before it is mixed through the headspace. In the plain step model the whole transient falls on the post-bubble side, which raises the fitted post-bubble level and biases the magnitude upward, in proportion to the size and duration of the overshoot. With magnitude.model = "step_reequil" (default) the model becomes \(C_t = \beta_0 + \beta_1 (t - t_b) + I(t \ge t_s) [\beta_2 + \beta_3 e^{-(t - t_p)/\tau}]\) where \(\beta_2\) is the settled step (the gas added to the headspace), \(\beta_3\) the amplitude of the transient at the peak and \(\tau\) the re-equilibration time constant. For a given \(\tau\) the model is linear; \(\tau\) is profiled on a logarithmic grid within tau.range and refined with a one-dimensional search that minimises the residual sum of squares. The re-equilibration term is retained only if it lowers the AIC of the plain step model, with an additional penalty of 2 for the profiled \(\tau\); otherwise the plain step estimate is returned. The pre-bubble window of the next event starts after \(t_p + 3 \tau\) of the previous event (when this leaves at least 3 pre-bubble observations), so that the tail of one event does not bias the baseline of the next.

Only events with a positive magnitude are retained, since ebullition adds gas to the headspace. Note that \(\beta_1\) next to a large event may still reflect post-bubble dynamics rather than a diffusive rate, because a single slope is shared by the pre- and post-bubble segments.

Examples

# Not run:

# Default: step + re-equilibration model (settled step)
bubbles <- find.bubbles(df = incubation_data,
                        bubble_source = "CH4dry_ppb",
                        window.size = 15,
                        method = "diff")

# Plain step regression, as in earlier versions
bubbles_step <- find.bubbles(df = incubation_data,
                             bubble_source = "CH4dry_ppb",
                             window.size = 15,
                             method = "diff",
                             magnitude.model = "step",
                             exclude.ramp = FALSE)

goAquaFlux.diffusive for estimating diffusive gas flux

Diffusive flux on a bubble-free window, via goFlux’s LM/HM models.

View the goAquaFlux.diffusive source code on GitHub

Usage

goAquaFlux.diffusive(
  df,
  gastype,
  criteria = c("MAE", "RMSE", "AICc", "SE", "g.factor", "kappa", "MDF", "nb.obs",
    "intercept", "p-value"),
  bubble_gas = "CH4dry_ppb",
  bubbles = NULL,
  minimum_window = 30,
  abrupt.window = 30,
  abrupt.min.points = 10,
  abrupt.threshold = 0.5
)

Arguments

Argument Description
df A data.frame for a single incubation, as prepared by goAquaFlux. Must contain Etime (starting at 0), flag, the gas column named by gastype, the instrument precision column (*_prec), Vtot, Area, Pcham, Tcham, and (for non-water gases) H2O_mol and/or H2O_ppm.
gastype Character; name of the gas concentration column.
criteria Character vector of model-selection criteria passed to best.flux. Defaults to the full goFlux criteria set.
bubble_gas Character; the gas used to detect bubbles (typically "CH4dry_ppb"). When gastype == bubble_gas the diffusive window is always truncated at the first detected bubble. For other gases the window is only truncated if a bubble coincides with an abrupt change in that gas (see Details).
bubbles Data.frame of bubbling events from find.bubbles (or NULL). Must contain a start column.
minimum_window Integer; minimum number of observations required in the diffusive window. If fewer are available the function returns NA.
abrupt.window Numeric; half-width (seconds) of the window used on each side of a candidate bubble time when testing for an abrupt slope change (non-bubble gases only). Default 30.
abrupt.min.points Integer; minimum points required on each side of the candidate time to run the abrupt-change test. Default 10.
abrupt.threshold Numeric; relative slope-change threshold above which a bubble is deemed to perturb the gas. Default 0.5 (i.e. 50%).

Details

For the bubble gas itself, ebullition by definition perturbs the signal, so the diffusive window ends at the first detected bubble. For other gases a bubble does not necessarily perturb the concentration; the window is only cut at the first bubble time that is accompanied by an abrupt change in local slope (the ratio of the post- to pre-bubble slope exceeds abrupt.threshold). If no such change is found, the full series is used.

goAquaFlux.ebullition for estimating ebullitive gas flux

Ebullitive flux from detected bubble magnitudes.

View the goAquaFlux.ebullition source code on GitHub

Usage

goAquaFlux.ebullition(
  df,
  gastype,
  bubbles,
  flux.term,
  final_window.min = 30,
  window_C0Cf = 10
)

Arguments

Argument Description
df A data.frame for a single incubation. Must contain an Etime column (elapsed time, seconds, starting at 0) and the gas concentration column named by gastype. Rows are assumed to be sorted by Etime.
gastype Character; name of the gas concentration column (e.g. "CH4dry_ppb").
bubbles Data.frame of bubbling events from find.bubbles (or NULL). Must contain start, end and magnitude; an optional SE column enables error propagation.
flux.term Numeric; conversion factor turning a concentration change per unit time into flux units (from flux.term).
final_window.min Numeric; minimum time (seconds) that must remain after the last bubble for the full deployment length to be used as the incubation time. If less time remains, the incubation time is truncated to the start of the last bubbling event. Default 30.
window_C0Cf Numeric; duration (seconds) of the initial and final windows used to compute mean start and end concentrations for the two-point endpoint estimate. Default 10.

Details

Ebullitive flux: \(F_E = \frac{\sum \Delta C_{bubble}}{t_{inc}} \times K\) with \(K\) the flux conversion term and \(t_{inc}\) the effective incubation time. Standard errors are propagated assuming independent bubble magnitude estimates: \(SE(F_E) = \frac{K}{t_{inc}} \sqrt{\sum SE_{bubble}^2}\)

goAquaFlux.total for combining diffusive and ebullitive flux

Combine components with error propagation and consistency checks.

View the goAquaFlux.total source code on GitHub

Usage

goAquaFlux.total(ebullition_flux, diffusive_flux)

Arguments

Argument Description
ebullition_flux A list returned by goAquaFlux.ebullition. Must contain at least flux (ebullitive flux), SE (its standard error) and F_tot2pts (the endpoint total-flux estimate).
diffusive_flux A list returned by goAquaFlux.diffusive. Must contain at least flux (diffusive flux) and SE.

Details

Total flux: \(F_T = F_E + F_D\) Error propagation (independent errors): \(SE_T = \sqrt{SE_E^2 + SE_D^2}\)

goAquaFlux.diagnostics for checking the ebullitive component

Checks the part of a goAquaFlux estimate that best.flux does not cover: the separation into diffusive and ebullitive components, via mass-balance closure.

View the goAquaFlux.diagnostics source code on GitHub

Usage

goAquaFlux.diagnostics(
  df,
  gastype,
  bubbles = NULL,
  diffusive_flux,
  flux.term,
  window_C0Cf = 10,
  tolerance = 0.2,
  min_snr = 10,
  dl_sigma = 20
)

Arguments

Argument Description
df data.frame of one incubation (flag == 1 rows).
gastype Character; gas column, the gas on which bubbles are detected (e.g. "CH4dry_ppb").
bubbles data.frame of bubbles from find.bubbles, or NULL.
diffusive_flux List returned by goAquaFlux.diffusive.
flux.term Numeric; flux term of the incubation.
window_C0Cf Numeric; seconds averaged at the start and end of the incubation for \(\Delta C_{obs}\). Default 10.
tolerance Numeric; accepted deviation of closure from 1. Default 0.2.
min_snr Numeric; minimum \(\vert \Delta C_{obs}\vert /\sigma\) to evaluate the closure. Default 10.
dl_sigma Numeric; bubble detection limit in multiples of \(\sigma\). Default 20.

Details

Mass-balance closure. When bubbles were detected, the separation is checked against the gas that actually accumulated in the chamber, in concentration units and with mean rates only: \(closure = (\bar{s}_D \, T + \sum_i M_i) / \Delta C_{obs}\) \(\bar{s}_D\) is the mean diffusive accumulation rate over the diffusive window (slope of the linear model fitted by goFlux on that window, whatever model best.flux selected), \(T\) the incubation length, \(M_i\) the settled bubble steps and \(\Delta C_{obs}\) the difference between the mean concentrations of the last and first window_C0Cf seconds.

  • \(closure < 1\) : part of the accumulated gas is not explained (undetected bubbles, or diffusion faster after the first bubble than before it);
  • \(closure > 1\) : more gas is attributed than accumulated (over-estimated bubbles, or diffusion slowing down after the first bubble, e.g. a curved accumulation measured on a short window).

Mean rates are used because the reported diffusive flux is an initial slope when best.flux selects the Hutchinson-Mosier model, whereas the ebullitive flux and the observed change are mean rates. Comparing the total flux with a two-point estimate would therefore flag curvature, which is already assessed by the g-factor of best.flux.

The closure is evaluated only when the observed change is large compared with the noise, estimated robustly from first differences as \(\sigma = MAD(\Delta C_t)/\sqrt{2}\): \(|\Delta C_{obs}| >\) min_snr \(\times \sigma\).

Detection limit. An incubation without detected bubbles does not prove the absence of ebullition. bubble_detection_limit is the smallest bubble detected reliably (dl_sigma \(\times \sigma\); isolated bubbles of 20 \(\sigma\) were detected in 96-100% of synthetic incubations) and ebullition_detection_limit the ebullitive flux of one such bubble over the incubation.

Calibration. On synthetic incubations with known fluxes and detected bubbles, with the defaults (tolerance = 0.2, min_snr = 10), 98% of the incubations whose closure failed had a total-flux error > 20%, while those that passed had median absolute errors of 2% (total flux) and 1.5% (ebullitive flux).

flux.plot.aqua for plotting aquatic chamber incubations

Per-incubation diagnostic plots of the diffusive window and ebullition events.

View the flux.plot.aqua source code on GitHub

Usage

flux.plot.aqua(
  flux.results.ls,
  dataframe,
  gastype,
  shoulder = 30,
  plot.display = c("diffusive.window", "ebullition.events", "bubble.fits"),
  bubble.snr = 2,
  bubble.gas = NULL,
  flux.unit = NULL,
  quality.check = TRUE,
  conversion.factor = 1
)

Arguments

Argument Description
flux.results.ls The list returned by goAquaFlux (with return_df = TRUE), containing flux_summary, bubbles, diffusive and diagnostics. bubbles may be NULL when no ebullition detection was run. For backwards compatibility a plain best.flux-style data.frame may also be supplied, in which case the call is delegated to flux.plot and only the diffusive component is plotted.
dataframe Data.frame of measurements used by goAquaFlux, containing at least UniqueID, Etime, flag and the column named by gastype.
gastype Character string; the gas column to plot. One of "CO2dry_ppm", "COdry_ppb", "CH4dry_ppb", "N2Odry_ppb", "NO2dry_ppb", "NOdry_ppb", "NH3dry_ppb" or "H2O_ppm".
shoulder Numeric; padding in seconds added before and after the measurement on the x-axis. Default 30.
plot.display Character vector of overlays to draw, any of "diffusive.window", "ebullition.events" and "bubble.fits"; other values are an error. Pass NULL to draw the observations and the diffusive fit only. All three overlays are shown by default.
bubble.snr Numeric or NULL; minimum signal-to-noise ratio (magnitude / SE) for an event’s fitted model to be drawn. The default 2 corresponds roughly to a magnitude significantly greater than zero at the 5% level. NULL draws the fit of every event, including those whose SE is missing.
bubble.gas Character string or NULL; the gas on which ebullition events were detected by goAquaFlux, e.g. "CH4dry_ppb". Bubble fits are drawn only when gastype matches it, and when it differs the legend names it (e.g. ebullition event (CH4)). A bubble.gas (or bubble_source) column in bubbles, when present, takes precedence. When neither is available, the events are assumed to belong to gastype.
flux.unit Character string or NULL; the flux unit shown in the caption. Plotmath syntax (for example "nmol~m^-2*s^-1") is accepted and converted to plain text. When NULL, a unit consistent with gastype is chosen.
quality.check Logical; if TRUE (default), the quality check of the diffusive fit and, for the bubble gas, the ebullition check are reported in the figures (see Details). Results of an earlier version without ebullition check show the quality check of the diffusive fit only, with a message.
conversion.factor Numeric greater than zero; multiplier applied to the displayed flux estimates and their standard errors, for reporting in a unit other than the one returned by goAquaFlux. Default 1.

Details

Each figure is composed of the following elements.

  • Observations: All records for the incubation are drawn. Points retained by the quality flag (flag == 1) are filled and opaque; discarded points are hollow and faded, so that they remain visible for diagnosis without competing with the retained series. For a gas other than the one the bubbles were detected on (e.g. CO2 with bubbles detected on CH4), when ebullition cut the diffusive window short, only the retained points of the diffusive window are black: those after it, which do not enter any flux estimate for that gas, are light grey (outside diffusive window).
  • Diffusive window: A full-height band from \(t = 0\) to the end of the window used to fit the diffusive flux. The extent of the window is taken from n_obs.diffusion in flux_summary and applied to the time-ordered retained series.
  • Ebullition events: Full-height bands spanning the start and end times of each detected bubbling event. Events are detected on a single gas (bubble.gas) and shared by all gases of an incubation. They are drawn for every gas, including one without ebullition, because they show whether the diffusive window was cut short by bubbling or by another selection step. When they come from another gas, the legend names it, e.g. ebullition event (CH4).
  • Diffusive fit: Only the model selected by best.flux (column model of diffusive) is drawn, in dark blue, and the legend names it, e.g. diffusive fit (HM). It is drawn only across the diffusive window, since it is not fitted to the ebullitive part of the series. A fit that stops short of, or runs past, the bubble-free portion of the record is then a direct indication that the window was misidentified. For output without a model column (earlier versions), both the LM (dark blue) and HM (sky blue) fits are drawn.
  • Bubble fits: For each event whose magnitude is significant (magnitude / SE >= bubble.snr), the step + re-equilibration model fitted by find.bubbles, in vermillion. It is drawn from the start of the event band to the end of that event’s fit window: pre-bubble lead-in, jump to the transient peak and exponential re-equilibration. When a re-equilibration term was retained, the settled post-bubble level is added as a dashed line; the estimated magnitude is the vertical offset between it and the pre-bubble trend. A curve that has not converged on the dashed line by the end of the fit window indicates an extrapolated settled level (reequil.complete = FALSE). The models are in the units of the gas the events were detected on, so they are drawn only on that gas’s panel (see bubble.gas), and only when it has an ebullitive component: a finite, non-zero flux_ebullition and a total flux that differs from the diffusive flux. Redrawing a model requires the columns intercept, t.bubble, t.step, t.peak, fit.start and fit.end returned by find.bubbles; if bubbles lacks them (output of an earlier version), the fits are skipped with a warning and the rest of the figure is unaffected.
  • Flux estimates: Reported in the plot subtitle, with their unit in the caption. They are placed outside the panel so that they cannot overlap the data for any incubation.
  • Quality checks: When quality.check = TRUE, the caption reports the two complementary checks of goAquaFlux. The quality check of the diffusive fit (quality.check and model from best.flux) is shown for every gas, as in flux.plot. The ebullition check (ebullition.check, see goAquaFlux.diagnostics) is shown only on the panel of the gas the bubbles were detected on, the only gas for which it is computed: the figure of any other gas (e.g. CO2 with bubbles detected on CH4) is assessed from that gas’s own fit alone. The closure is given in brackets and, when no bubble was detected, the detection limit of ebullition.

If the ggtext package is available, the subtitle is rendered with the diffusive and ebullitive estimates coloured to match their respective bands and fits; otherwise a plain-text subtitle is used. The two variants are identical in content.

Layers are drawn back to front: bands, observations, bubble fits, then the diffusive fit. The y-axis range covers every drawn element within the x-window, including discarded points and extrapolated bubble-fit levels, so that nothing is silently clipped.

Colours follow the Okabe-Ito palette, which remains distinguishable under the common forms of colour vision deficiency and in greyscale print.

Examples

# Not run:

res <- goAquaFlux(mydata, gastype = "CH4dry_ppb", return_df = TRUE)

plots <- flux.plot.aqua(res, mydata, gastype = "CH4dry_ppb")

# Inspect a single incubation by name
plots[["LAKE01-2026-05-12-01"]]

# CO2 of the same incubations, with bubbles detected on CH4: the CH4
# ebullition events are shown as bands, without the CH4 bubble fits
res_co2 <- goAquaFlux(mydata, gastype = "CO2dry_ppm",
                      bubble.gas = "CH4dry_ppb", return_df = TRUE)
plots_co2 <- flux.plot.aqua(res_co2, mydata, gastype = "CO2dry_ppm",
                            bubble.gas = "CH4dry_ppb")

# Only the incubations whose ebullition check failed
chk <- res$flux_summary$ebullition.check
plots[res$flux_summary$UniqueID[!is.na(chk) & nzchar(chk) &
                                  chk != "no bubble detected"]]

# Write all diagnostics to a multi-page PDF
pdf("ch4_diagnostics.pdf", width = 8, height = 5)
invisible(lapply(plots, print))
dev.off()

References

Rheault, K., Christiansen, J. R., & Larsen, K. S. (2024). goFlux: A user-friendly way to calculate GHG fluxes yourself, regardless of user experience. Journal of Open Source Software, 9(96), 6393. https://doi.org/10.21105/joss.06393