lifeTable_build: Build a Life Table Object from User-Supplied Columns

In insectecol: Insect Ecology Data Analysis Toolkit

Build a Life Table Object from User-Supplied Columns

Description

Assembles a life_table object (the same structure returned by lifeTable_read) from individual column vectors already loaded into the R session, e.g. after data <- read.csv("XXX.csv"). This is the entry point for analysing data that do not come from a package-conform csv file.

Usage

lifeTable_build(
  stages,
  adult_days,
  sex,
  oviposition = NULL,
  stage_names = NULL,
  file_name = "life_table",
  check = TRUE
)

Arguments

stages	Stage-duration columns, one column per immature stage: a data frame, a matrix or a list of equal-length vectors (column j = days spent in immature stage j; blank/NA for stages not reached). If it is a named data frame/list, the names are used as stage names.
adult_days	Numeric vector; adult survival days (NA for individuals that died before the adult stage).
sex	Character/factor vector; F, M or N (died before adult).
oviposition	Optional; daily oviposition records, one column per day: a data frame, a matrix (rows = individuals in the same order as sex) or a single vector (one column). NULL if the reproduction-related parameters should not be computed (see fecundity in lifeTable_calculate_all).
stage_names	Character vector of stage names (length = number of columns of stages). NULL (default) uses the names of stages if it has non-empty names, otherwise default_stage_names.
file_name	Character; data set name (default plot title, base name of the exported xlsx).
check	Logical; validate the data with lifeTable_check (default TRUE).

Value

A life_table object, ready for all calc_*, lifeTable_plot and lifeTable_export functions.

Examples

## The raw example data shipped with the package
f <- system.file("extdata", "lifetable_example.csv", package = "insectecol")
## ^^ change to the actual package name
d <- read.csv(f)

## 1) Standard build: column-range subset of stage columns + adult days
##    + sex + oviposition columns (positional indexing is robust to
##    the space-containing headers like "1st instar")
lt1 <- lifeTable_build(d[2:8], adult_days = d$Adult, sex = d$gender,
                        oviposition = d[, 11:17], file_name = "Example")
names(lt1)     # components of the life_table object
head(lt1$df)   # wide table: ID + stages + Adult + gender + oviposition

## 2) Survival analysis only: omit oviposition entirely. Legal since
##    the data checker skips the oviposition check when the table ends
##    at the sex column (use fecundity = FALSE in the analysis).
lt2 <- lifeTable_build(d[2:8], adult_days = d$Adult, sex = d$gender)

## 3) Named list: the list names become the stage names
lt3 <- lifeTable_build(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,
                        oviposition = d[, 11:17])

## 4) Friendly stage names via stage_names: exactly one per IMMATURE
##    stage. The adult labels "Female" and "Male" are appended
##    automatically and must NOT be included.
lt4 <- lifeTable_build(d[2:8], adult_days = d$Adult, sex = d$gender,
                        oviposition = d[, 11:17],
                        stage_names = c("Egg", "L1", "L2", "L3", "L4",
                                        "Prepupa", "Pupa"))

## 5) A common mistake, handled gracefully: stage_names wrongly
##    including the adult labels. The extra two entries are dropped
##    with a warning (only a WARNING - the build still succeeds).
lt5 <- lifeTable_build(d[2:8], adult_days = d$Adult, sex = d$gender,
                        oviposition = d[, 11:17],
                        stage_names = c("Egg", "L1", "L2", "L3", "L4",
                                        "Prepupa", "Pupa",
                                        "Female", "Male"))

## 6) Skip the consistency check (e.g. oviposition columns
##    deliberately shorter than the adult life span)
lt6 <- lifeTable_build(d[2:8], adult_days = d$Adult, sex = d$gender,
                        oviposition = d[, 11:17], check = FALSE)

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