dm.growth.fit: Fit dendrometer growth curves by vegetation season

In dendRoAnalyst: A Tool for Processing and Analyzing Dendrometer Data

Fit dendrometer growth curves by vegetation season

Description

Fits cumulative growth curves to daily dendrometer series using one of several supported methods: generalized additive model "gam", Gompertz "gompertz", logistic "logistic", Richards "richards", local regression "loess", or smoothing spline "spline".

The function:

• resamples dendrometer data to daily maxima using [dendro.resample()],

• assigns each daily observation to a vegetation season,

• optionally converts daily stem-size values to cumulative growth with fit_GRO = TRUE,

• fits one curve per series and season with year_mode = "yearly" or one pooled curve across retained seasons with year_mode = "pooled",

• estimates growing-season timing from the fitted cumulative-growth curve,

• additionally identifies active-growth timing from the fitted growth-rate curve.

For Gompertz, logistic, and Richards fits, the asymptote parameter a, representing maximum seasonal growth, can optionally be fixed to the observed maximum cumulative growth for that series and vegetation season. This is controlled by fix_a_to_observed_max.

Usage

dm.growth.fit(
  df,
  TreeNum = "all",
  method = c("gam", "gompertz", "logistic", "richards", "loess", "spline"),
  years = "all",
  year_mode = c("yearly", "pooled"),
  fit_GRO = TRUE,
  site_mode = c("NH", "SH", "CS"),
  custom_veg_season = c(275, 274),
  growth_fraction = c(0.1, 0.9),
  min_unique_growth = 10,
  rate_threshold_fraction = 0.1,
  fix_a_to_observed_max = FALSE,
  fixed_a_multiplier = 1,
  start_value_gompertz_parameters = list(a = NA_real_, b = NA_real_, k = NA_real_),
  start_value_richards_parameters = list(a = NA_real_, k = NA_real_, t0 = NA_real_, v =
    1),
  loess_span = 0.2,
  spline_df = 10,
  verbose = TRUE
)

Arguments

df	A data frame or tibble. The first column must be a timestamp Date, POSIXct, or parseable date-time string. All selected remaining columns must be numeric dendrometer series.
TreeNum	Either "all" to use all dendrometer series, a numeric vector selecting dendrometer columns by position, or a character vector with series names.
method	Fitting method. One of "gam", "gompertz", "logistic", "richards", "loess", or "spline".
years	Either "all" to fit all available vegetation seasons, or a character vector of season labels to retain.
year_mode	Either "yearly" to fit one curve per vegetation season, or "pooled" to fit one pooled curve across all retained seasons.
fit_GRO	Logical. If TRUE, processed daily series are converted to cumulative growth using a cumulative maximum within each vegetation season.
site_mode	Vegetation season definition. One of "NH", "SH", or "CS".
custom_veg_season	Numeric vector of length two giving the start and end day-of-year for custom vegetation seasons in "CS" mode. Cross-year seasons are supported, for example c(275, 274).
growth_fraction	Numeric vector of length two giving the lower and upper fractions of final fitted seasonal growth used to define cumulative growth onset and cessation, for example c(0.1, 0.9).
min_unique_growth	Minimum number of unique non-missing cumulative growth values required before a fit is attempted.
rate_threshold_fraction	Numeric scalar between 0 and 1. Active-growth dates are derived from the fitted growth-rate curve as the first and last days where fitted growth rate exceeds this fraction of the peak fitted growth rate.
fix_a_to_observed_max	Logical. If TRUE and method = "gompertz", "logistic", or "richards", the asymptote parameter a, representing maximum seasonal growth, is fixed to the observed maximum cumulative growth of the corresponding series and vegetation season. This is most appropriate with year_mode = "yearly". For year_mode = "pooled", one pooled maximum is used.
fixed_a_multiplier	Numeric multiplier applied to the observed maximum when fix_a_to_observed_max = TRUE. The default is 1, meaning a is fixed exactly to the observed seasonal maximum. Values slightly above 1, for example 1.01 or 1.05, allow the fitted asymptote to sit just above the observed maximum.
start_value_gompertz_parameters	Optional named list with starting values for Gompertz fits. Supported names are a, b, and k. If fix_a_to_observed_max = TRUE, supplied a is ignored.
start_value_richards_parameters	Optional named list with starting values for Richards and logistic fits. Supported names are a, k, t0, and v. If fix_a_to_observed_max = TRUE, supplied a is ignored.
loess_span	Span used when method = "loess".
spline_df	Degrees of freedom used when method = "spline".
verbose	Logical. If TRUE, prints a short completion message.

Details

The first column of df is treated as the time column and renamed to "TIME" internally. If it is not already a date-time object, the function attempts to parse it using [lubridate::parse_date_time()].

growth_start_* and growth_end_* are based on cumulative fitted growth. rate_start_* and rate_end_* are based on the fitted growth-rate curve.

For Gompertz, logistic, and Richards models, a is the upper asymptote. When fix_a_to_observed_max = TRUE, this parameter is not estimated by nonlinear least squares. Instead, it is fixed to:

a = max(y_{obs}) \times fixed\_a\_multiplier

where y_{obs} is the observed cumulative growth for that series and vegetation season.

Value

An object of class "dm_growth_fit" with elements:

call

The matched function call.

original_daily_data

Raw daily dendrometer data after resampling to daily maxima and assigning vegetation seasons, but before centering and optional cumulative-growth transformation.

processed_data

Daily processed data used for fitting.

fitted_data

Daily fitted values on the full vegetation-season grid.

fit_statistics

Table with fit-level statistics and estimated timing.

fit_parameters

Table with fit-level model parameters and convergence information.

season_table

Vegetation seasons retained for fitting.

See Also

[summary.dm_growth_fit()], [print.dm_growth_fit()]

Examples

# fit <- dm.growth.fit(
#   df = dendro_data,
#   TreeNum = "all",
#   method = "gompertz",
#   year_mode = "yearly",
#   fit_GRO = TRUE,
#   fix_a_to_observed_max = TRUE
# )

# fit2 <- dm.growth.fit(
#   df = dendro_data,
#   TreeNum = "all",
#   method = "richards",
#   year_mode = "yearly",
#   fit_GRO = TRUE,
#   fix_a_to_observed_max = TRUE,
#   fixed_a_multiplier = 1.02
# )

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