gdd_analyze: Analyse Temperature-Dependent Development (Main Function)

In insectecol: Insect Ecology Data Analysis Toolkit

Analyse Temperature-Dependent Development (Main Function)

Description

Non-interactive, fully parameter-driven entry point for the degree-day module, in the same style as lifeTable_analyze and lc50_analyze. It (1) obtains the long-format data — user-supplied column vectors (temp = d$T, duration = d$days, group = d$stage), a whole data frame, or a csv/xlsx file / folder read via gdd_read —, (2) optionally validates the data with gdd_check (including the linear-range check), (3) fits the chosen model — or selects the best model per group by AICc with model = "auto" — via gdd_calc and (4) optionally draws the fitted curves with gdd_plot — in the same style as the lc50_analyze entry point of the bioassay module. Nothing is written to disk unless plot_file is supplied; tabular export is handled separately by gdd_export.

Usage

gdd_analyze(
  temp = NULL,
  duration = NULL,
  group = NULL,
  data = NULL,
  path = NULL,
  temp_col = NULL,
  duration_col = NULL,
  by = NULL,
  model = c("linear", "logan", "lactin", "briere1", "briere2", "wang", "auto"),
  start = NULL,
  conf_level = 0.95,
  min_n = 3,
  maxiter = 1000,
  check = TRUE,
  encoding = "UTF-8",
  header = TRUE,
  temp_from_file = FALSE,
  pattern = "\\.(csv|xlsx|xls)$",
  plot = FALSE,
  plot_file = NULL,
  plot_group = NULL,
  show_C = TRUE,
  show_Topt = TRUE,
  plot_title = NULL,
  plot_sub = NULL,
  plot_xlab = NULL,
  plot_ylab = NULL,
  plot_family = NULL,
  plot_width = 10.67,
  plot_height = 6,
  plot_units = c("in", "cm", "px"),
  plot_res = 150,
  ...
)

Arguments

temp, duration, group	User-supplied column vectors, e.g. temp = d$T, duration = d$days, group = d$stage after d <- read.csv("XXX.csv"). This is the recommended entry when many data sets live in one file. group is optional (omit it to fit the overall model). When supplied, these vectors take precedence over data and path.
data	A data.frame in the long format required by gdd_calc (one row per observation, with a temperature and a duration column). Used when temp / duration are not supplied; takes precedence over path.
path	Optional; path to a csv/xlsx file or a folder (batch mode), read with gdd_read. Used only when neither the column vectors nor data are supplied.
temp_col, duration_col	Column names; auto-detected by default (ignored when the column vectors are supplied).
by	Grouping variable(s), e.g. "stage"; NULL fits the overall model (ignored when the group vector is supplied, which then serves as the grouping).
model	Single model name or "auto" (best per group by AICc); default "linear". See gdd_calc for the model list and the minimum number of temperature points per model.
start	Optional named list of starting values for a nonlinear model, e.g. list(a = 1e-4, T0 = 10, Tm = 35).
conf_level	Confidence level, default 0.95.
min_n	Minimum rows per group, default 3.
maxiter	Iteration limit passed to the nonlinear fitter.
check	Logical; whether to validate the data with gdd_check before fitting (default TRUE). The result is attached to the returned list; a rate decline at high temperature triggers a targeted warning.
encoding, header, temp_from_file, pattern	Reading options for gdd_read (only used when path is supplied).
plot	Logical; whether to draw the fitted curves (default FALSE).
plot_file	Optional png path: when supplied together with plot = TRUE the figure is written to this file (same machinery as gdd_export_plot); when NULL the plot is drawn on the current device (fully customisable afterwards by calling gdd_plot on the returned fit).
plot_group, show_C, show_Topt	Plot options, see gdd_plot.
plot_title	Custom plot title; NULL = the automatic per-group caption (group + fitted statistics). A named vector is matched per group, e.g. c(Egg = "egg", Pupa = "pupa").
plot_sub	Custom subtitle; NULL keeps the automatic statistics caption (as subtitle when plot_title is set).
plot_xlab, plot_ylab	Custom axis labels; NULL keeps the defaults of gdd_plot.
plot_family	Text font family, see gdd_plot (NULL keeps the default "serif" — Times New Roman on 'Windows'; Chinese characters are rendered through the device's font fallback, i.e. SimSun on Chinese 'Windows').
plot_width, plot_height	Physical size of the exported figure in plot_units (only used when plot_file is supplied). Defaults 10.67 x 6 in reproduce the former 1600 x 900 px canvas at 150 dpi. Because the size is physical, the composition is identical at every resolution — plot_res only adds pixels.
plot_units	Unit of plot_width / plot_height: "in" (default), "cm" or "px". Use "in" / "cm" for publication figures. With "px" the canvas is a fixed pixel count; the text size is compensated internally so that changing plot_res keeps the 150-dpi composition (only the recorded dpi metadata changes).
plot_res	Resolution (dpi) of the exported png, default 150. Higher values add pixels (sharper print) without changing the layout or the physical size. E.g. a journal requiring 300 dpi at 8 cm width: plot_units = "cm", plot_width = 8, plot_res = 300.
...	Further arguments passed to gdd_calc (reserved for future model options; keeps user code forward compatible).

Value

A list with components:

data	the long-format data actually analysed
check	the gdd_check result, or NULL when check = FALSE
fit	the "gdd" object returned by gdd_calc — fit$results (summary table), fit$fits (per-group details incl. coefficient tables), fit$comparison (model comparison, "auto" mode); print/summary/plot/predict S3 methods are available
plot_file	the png path when plot_file was supplied, otherwise NULL

See Also

gdd_read, gdd_check, gdd_calc, gdd_plot, gdd_predict, gdd_compare, gdd_export, gdd_export_plot, gdd_daily

Examples

f <- system.file("extdata", "gdd_example.csv", package = "insectecol")

## --- way 1 (recommended): read the file yourself, pass columns in ---
## Typical when many data sets live in one csv: the user reads the
## file and picks the columns with $, exactly like lifeTable_analyze()
d <- read.csv(f)
out1 <- gdd_analyze(temp = d$temp, duration = d$duration, group = d$stage)
out1$fit$results          # C, K, SE and CI per stage
summary(out1$fit)         # detailed coefficient tables

## Without a grouping column: one overall model
out1b <- gdd_analyze(temp = d$temp, duration = d$duration)

## --- way 2: pass the whole data frame ---
out2 <- gdd_analyze(data = d, by = "stage")
gdd_predict(out2$fit, temp = c(20, 25), group = "Egg")

## --- way 3: let the function read the file ---
out3 <- gdd_analyze(path = f, by = "stage")

## --- AICc model selection + png export + custom labels ---
## plot_title / plot_xlab / plot_ylab accept custom labels; Chinese
## labels are rendered through the device's font fallback

out4 <- gdd_analyze(temp = d$temp, duration = d$duration, group = d$stage,
                    model = "auto", plot = TRUE,
                    plot_file = tempfile(fileext = ".png"))
out4$fit$comparison       # full comparison table, best flag included

insectecol documentation built on Oct. 5, 2026, 5:08 p.m.