lifeTable_analyze: Analyse a Life Table from User-Supplied Columns (Main...

In insectecol: Insect Ecology Data Analysis Toolkit

Analyse a Life Table from User-Supplied Columns (Main Function)

Description

Non-interactive, fully parameter-driven entry point for the age-stage, two-sex life table analysis. It (1) builds a life_table object from column vectors of an already loaded data frame (e.g. after data <- read.csv("XXX.csv"), or accepts a ready life_table object), (2) computes the life table parameters and (3) optionally draws the age-stage survival curves with customisable title, axis titles and legend labels, optionally written to disk as png when plot_file is supplied. Tabular export is handled separately by lifeTable_export.

Usage

lifeTable_analyze(
  lt = NULL,
  stages = NULL,
  adult_days = NULL,
  sex = NULL,
  oviposition = NULL,
  stage_names = NULL,
  file_name = "life_table",
  check = TRUE,
  fecundity = TRUE,
  bootstrap = FALSE,
  B = 1e+05,
  seed = NULL,
  plot = FALSE,
  title = NULL,
  x_title = "Age(days)",
  y_title = "Age-Stage Survival Rate(Sxj)",
  legend_labels = NULL,
  dpi = 300,
  plot_file = NULL,
  plot_width = 12,
  plot_height = 8,
  plot_units = "cm",
  plot_res = 300
)

Arguments

lt	Optional; an existing life_table object (from lifeTable_read or lifeTable_build). If NULL (default), the object is built from stages, adult_days, sex and oviposition.
stages, adult_days, sex, oviposition, stage_names, file_name, check	Passed to lifeTable_build (ignored when lt is supplied).
fecundity	Logical; whether to compute the reproduction-related parameters (F, F_xj, m_x, R0, r, lambda, T). FALSE skips them entirely - oviposition is then not required at all and may be left NULL.
bootstrap	Logical; whether to estimate the standard errors and percentile confidence intervals of all scalar parameters with the bootstrap technique of TWOSEX-MSChart via lifeTable_bootstrap (default FALSE). The result is attached as results$boot and is exported by lifeTable_export as an extra worksheet.
B	Integer; number of bootstrap replicates (only used when bootstrap = TRUE). The TWOSEX-MSChart standard is 100000 (the default).
seed	Integer; seed of the bootstrap random number generator (only used when bootstrap = TRUE); NULL uses the current R session state.
plot	Logical; whether to draw the age-stage survival curves (default FALSE). The returned ggplot object can be printed, customised further or passed to lifeTable_export.
title	Character; plot title. NULL = file_name.
x_title, y_title	Character; axis titles. Defaults "Age(days)" and "Age-Stage Survival Rate(Sxj)".
legend_labels	Character vector; legend labels, one per stage (immature stages + Female + Male), e.g. c("Egg", "1st instar", "Pupa", "Female", "Male"). NULL (default) = the stage names of the data (Egg, 1st instar, 2nd instar, ..., Female, Male).
dpi	Numeric; resolution used for scaling the text of the plot (default 300).
plot_file	Optional png path: when supplied together with plot = TRUE the figure is written to this file (via ggsave); when NULL the plot is only returned.
plot_width, plot_height, plot_units, plot_res	Physical size and resolution of the exported png (only used when plot_file is supplied); defaults 12 x 8 cm at 300 dpi.

Value

A list with components lt (the life_table object), results (the list returned by lifeTable_calculate_all; additionally containing boot, the lifeTable_bootstrap result, when bootstrap = TRUE), plot (the ggplot object when plot = TRUE, otherwise NULL) and plot_file (the png path when plot_file was supplied, otherwise NULL).

See Also

lifeTable_build, lifeTable_calculate_all, lifeTable_bootstrap, lifeTable_plot, lifeTable_export

Examples

## The example raw data shipped with the package (the same layout as
## the csv template: ID + immature stage columns + Adult + gender +
## one column per oviposition day of the females)
f <- system.file("extdata", "lifetable_example.csv", package = "insectecol")
## ^^ change "lifeTable" to the actual package name
d  <- read.csv(f)
names(d)   # with check.names = TRUE (default) the names become
          # ID, Egg, X1st.instar, X2nd.instar, ..., Prepupa, Pupa,
          # Adult, gender, ...

## --- way 1: pass a column-range subset of the data frame
## (positional indexing: works regardless of how the names were mangled)
out1 <- lifeTable_analyze(stages = d[2:8], adult_days = d$Adult,
                          sex = d$gender, oviposition = d[, 11:17],
                          file_name = "Example - way 1")
out1$results$N          # number of individuals
out1$results$R0         # net reproductive rate

## --- with bootstrap standard errors (small B for a fast example;
## use the default B = 100000 for publications)
out1b <- lifeTable_analyze(stages = d[2:8], adult_days = d$Adult,
                           sex = d$gender, oviposition = d[, 11:17],
                           file_name = "Example - way 1",
                           bootstrap = TRUE, B = 2000, seed = 1)
out1b$results$boot$summary

## --- way 2: pass a named list of single columns
## (the list names become the stage names in plots and results)
out2 <- lifeTable_analyze(stages = list(Egg = d[[2]], "1st instar" = d[[3]],
                                        "2nd instar" = d[[4]], "3rd instar" = d[[5]],
                                        "4th instar" = d[[6]], Prepupa = d[[7]],
                                        Pupa = d[[8]]),
                         adult_days = d$Adult, sex = d$gender,
                         fecundity = FALSE)   # survival analysis only,
                                              # oviposition not supplied
out2$results$N

## --- way 3: select the stage columns by their original names
## (re-read with check.names = FALSE to keep "1st instar", "2nd instar", ...)
d3 <- read.csv(f, check.names = FALSE)
out3 <- lifeTable_analyze(stages = d3[, c("Egg", "1st instar", "2nd instar",
                                          "3rd instar", "4th instar",
                                          "Prepupa", "Pupa")],
                         adult_days = d3$Adult, sex = d3$gender,
                         oviposition = d3[, 11:17],
                         stage_names = c("Egg", "L1", "L2", "L3", "L4",
                                         "Prepupa", "Pupa"),
                         plot = TRUE,
                         legend_labels = c("Egg", "L1", "L2", "L3", "L4",
                                           "Prepupa", "Pupa",
                                           "Female", "Male"))
out3$plot               # print or further customise the ggplot object

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