# install.packages("remotes")
# The aquatic extension is part of goFlux from v0.3.2 onwards.
remotes::install_github("Qepanna/goFlux")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):
- Detect the bubbles.
find.bubbles()robustly standardises the concentration series (typicallyCH4dry_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. - 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. - 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. - 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
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.
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.checkconcerns the diffusive fit. It is the column returned bybest.fluxfor the diffusive window, so that a diffusive flux fromgoAquaFlux()is checked exactly as one fromgoFlux().ebullition.checkconcerns the ebullitive component and is computed only for the gas on which bubbles are detected (bubble_gas), bygoAquaFlux.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 isNA: its fluxes are then assessed from its own observations only, throughquality.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.diffusioninflux_summaryand 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(columnmodelofdiffusive) 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 amodelcolumn (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 byfind.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 (seebubble.gas), and only when it has an ebullitive component: a finite, non-zeroflux_ebullitionand a total flux that differs from the diffusive flux. Redrawing a model requires the columnsintercept,t.bubble,t.step,t.peak,fit.startandfit.endreturned byfind.bubbles; ifbubbleslacks 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 ofgoAquaFlux. The quality check of the diffusive fit (quality.checkandmodelfrombest.flux) is shown for every gas, as influx.plot. The ebullition check (ebullition.check, seegoAquaFlux.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()