emergence_analyze: Predict the Emergence Period from a Stage-Structure Survey

In insectecol: Insect Ecology Data Analysis Toolkit

Predict the Emergence Period from a Stage-Structure Survey

Description

Non-interactive, fully parameter-driven entry point for the emergence-period module (the stage-grading method: one field survey of the population stage structure — e.g. a dissected-sample count of pupal grades — is turned into the projected eclosion dates of the 16 the beginning, peak and end of the adult emergence period). In the same style as gdd_analyze and lc50_analyze, it (1) obtains the data — user column vectors (stage = d$stage, count = d$n, days = d$days), a whole data frame, or a csv/xlsx file / folder read via emergence_read —, (2) computes the cumulative development and the interpolated quantile dates via emergence_calc and (3) optionally draws the projection with plot.emergence. Larval hatch dates are projected as well when pre_ovip / egg_days are supplied. Nothing is written to disk unless plot_file is supplied; tabular export is handled separately by emergence_export.

Usage

emergence_analyze(
  stage = NULL,
  count = NULL,
  percent = NULL,
  days = NULL,
  data = NULL,
  path = NULL,
  stage_col = NULL,
  count_col = NULL,
  percent_col = NULL,
  days_col = NULL,
  survey_date,
  p = c(0.16, 0.5, 0.84),
  labels = NULL,
  pre_ovip = 0,
  egg_days = 0,
  encoding = "UTF-8",
  header = TRUE,
  pattern = "\\.(csv|xlsx|xls)$",
  plot = FALSE,
  plot_file = NULL,
  show_hatch = 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

stage, count, days	User-supplied column vectors, e.g. stage = d$stage, count = d$n, days = d$days after d <- read.csv("XXX.csv"): the stage names, the individuals per stage and the average days from that stage to adult eclosion. percent may be used instead of count when the survey recorded percentages. When supplied, these vectors take precedence over data and path.
percent	Alternative to count: the stage shares in percent (any scaling works; the shares are normalised).
data	A data.frame with a stage column, a count (or percent) column and a days column. Used when the vectors are not supplied; takes precedence over path.
path	Optional; path to a csv/xlsx file or a folder (batch mode), read with emergence_read. Used only when neither the column vectors nor data are supplied.
stage_col, count_col, percent_col, days_col	Column names; auto-detected by default (ignored when the column vectors are supplied).
survey_date	The survey date: a Date or a character string ("2026-03-20", "2026/3/20"). Required.
p	Numeric vector of emergence quantiles, default c(0.16, 0.5, 0.84) (beginning / peak / end).
labels	Optional labels of the quantiles, see emergence_calc.
pre_ovip	Pre-oviposition period in days (default 0 = not used). Counted from female eclosion to egg deposition.
egg_days	Egg duration in days (default 0 = not used).
encoding, header, pattern	Reading options for emergence_read (only used when path is supplied).
plot	Logical; whether to draw the projection (default FALSE).
plot_file	Optional png path: when supplied together with plot = TRUE the figure is written to this file (same machinery as emergence_export_plot); when NULL the plot is drawn on the current device (fully customisable afterwards by calling plot() on the returned fit).
show_hatch	Plot option, see plot.emergence.
plot_title, plot_sub, plot_xlab, plot_ylab	Plot options (title, subtitle, axis labels); NULL keeps the defaults of plot.emergence.
plot_family	Text font family, see plot.emergence (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, plot_units, plot_res	Physical size and resolution of the exported png (only used when plot_file is supplied), same semantics as in gdd_analyze: the composition is identical at every resolution, plot_res only adds pixels.
...	Further arguments passed to emergence_calc (reserved for future options; keeps user code forward compatible).

Value

A list with components:

data	the survey table actually analysed
fit	the "emergence" object returned by emergence_calc — fit$predictions (the quantile dates), fit$table (cumulative development), fit$interpolate (a closure for arbitrary quantiles); print / summary / plot / predict S3 methods are available
plot_file	the png path when plot_file was supplied, otherwise NULL

See Also

emergence_read, emergence_calc, emergence_export, emergence_export_plot

Examples

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

## --- way 1 (recommended): read the file yourself, pass columns in ---
d <- read.csv(f)
out <- emergence_analyze(stage = d$stage, count = d$count,
                         days = d$days, survey_date = "2026-03-20")
out$fit                            # three quantile dates
out$fit$table                      # cumulative development
predict(out$fit, c(0.25, 0.75))    # arbitrary quantiles

## --- way 2: pass the whole data frame ---
out2 <- emergence_analyze(data = d, survey_date = "2026-03-20")

## --- way 3: let the function read the file ---
out3 <- emergence_analyze(path = f, survey_date = "2026-03-20")

## --- hatch projection + png export + custom labels ---
## plot_title / plot_xlab / plot_ylab accept custom labels; Chinese
## labels are rendered through the device's font fallback (SimSun
## on Chinese Windows)
out4 <- emergence_analyze(path = f, survey_date = "2026-03-20",
                          pre_ovip = 3, egg_days = 10,
                          plot = TRUE,
                          plot_file = tempfile(fileext = ".png"))
out4$fit$predictions

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