dm.detrend.fit: Detrend and standardize dendrometer series from growth-fit...

In dendRoAnalyst: A Tool for Processing and Analyzing Dendrometer Data

Detrend and standardize dendrometer series from growth-fit residuals

Description

Creates detrended standardized dendrometer series from objects returned by [dm.growth.fit()] or [dm.growth.fit.double()].

The function compares the original daily dendrometer series ('x$original_daily_data') with the fitted growth curve from 'x$fitted_data'. Because fitted values are stored on the processed scale used for modelling, the function first reconstructs fitted values on the original daily scale by adding back the seasonal baseline (the first non-missing original daily value of each series within each vegetation season).

Residuals are then calculated as:

residual = observed_{daily} - fitted_{original\ scale}

To obtain a detrended standardized series with mean equal to 1 and no negative values, residuals are transformed within each series × season_label as:

z = \frac{residual - \min(residual) + \epsilon}{\mathrm{mean}(residual - \min(residual) + \epsilon)}

where \epsilon > 0 is a small constant ensuring strictly positive values. If all residuals within a season are identical, the standardized series becomes a constant vector of 1.

Usage

dm.detrend.fit(
  x,
  series = NULL,
  seasons = NULL,
  epsilon = 1e-06,
  keep_na_rows = FALSE
)

Arguments

x	An object of class "dm_growth_fit" returned by [dm.growth.fit()] or [dm.growth.fit.double()].
series	Optional character vector of dendrometer series to retain. Default is NULL, meaning all available series are used.
seasons	Optional character vector of vegetation-season labels to retain. Default is NULL, meaning all available seasons are used.
epsilon	Small positive constant added after shifting residuals by their seasonal minimum. Default is 1e-6. Use 0 to allow exact zeros.
keep_na_rows	Logical. If TRUE, rows are retained even when the observed or fitted value is missing; detrended values remain NA. If FALSE (default), rows with missing observed or fitted values are removed from the long output before standardization.

Details

The function uses x$original_daily_data, which must be present in the input object. If the object was created by an older version of [dm.growth.fit()] or [dm.growth.fit.double()] that did not store original_daily_data, the function will stop with an informative error.

Standardization is carried out separately within each vegetation season. This means the mean of the detrended standardized series is 1 for each series × season_label, not necessarily across the entire dataset.

Value

A list of class "dm_detrended" with elements:

call

The matched function call.

detrended_data

Wide-format tibble with metadata columns and one detrended standardized series column per dendrometer.

detrended_long

Long-format tibble containing original daily values, reconstructed fitted values on the original scale, residuals, shifted residuals, and detrended standardized values.

parameters

Per-series and per-season summary table containing baseline values and residual standardization parameters.

source_fit_statistics

The original x$fit_statistics table.

Examples

data(gf_nepa17)

fit1 <- dm.growth.fit(
  df = gf_nepa17,
  TreeNum = 1:2,
  method = "gompertz",
  year_mode = "yearly",
  verbose = FALSE
)

det1 <- dm.detrend.fit(fit1)
head(det1$detrended_data)
head(det1$parameters)

fit2 <- dm.growth.fit.double(
  df = gf_nepa17,
  TreeNum = 1,
  method = "gompertz",
  year_mode = "yearly",
  verbose = FALSE
)

det2 <- dm.detrend.fit(fit2)
head(det2$detrended_long)

dendRoAnalyst documentation built on May 20, 2026, 5:07 p.m.