Skip to contents

Population Model LTRE Range Analysis

Source: R/pop_model_ltre_range.R
pop_model_ltre_range.Rd

Run an uncertainty-based LTRE (Life Table Response Experiment) using Monte Carlo sampling and Partial Rank Correlation Coefficients (PRCC) for global sensitivity analysis.

Usage

pop_model_ltre_range(life_cycle_params, n_samples = 500, seed = NULL)

Arguments

life_cycle_params

Data frame. Life cycle parameters with extended columns for distribution specifications. See Details for required columns.

n_samples

Integer. Number of Monte Carlo samples to draw. Default is 500.

seed

Integer or NULL. Optional random seed for reproducibility.

Value

A list containing:

prcc_rankings

Data frame of PRCC results sorted by absolute importance, with columns: parameter, prcc, p_value, abs_prcc

lambda_summary

List with summary statistics: mean, median, sd, quantiles (2.5%, 5%, 10%, 25%, 50%, 75%, 90%, 95%, 97.5%), prob_lambda_gt_1, prob_lambda_lt_1, n_valid, n_failed

samples

Data frame with all sample data including sample_id, lambda, log_lambda, and all sampled parameter values

parameter_specs

Data frame of parameter specifications for sampled parameters

metadata

List with run metadata: n_samples, n_parameters_tested, seed

Details

Unlike pop_model_ltre which perturbs parameters by a fixed step size, this function samples from user-defined probability distributions to propagate uncertainty and identify which parameters most influence lambda (population growth rate).

The input data frame must contain the following columns:

Parameters

Parameter description

Name

Parameter name (e.g., "SE", "S0", "surv_1")

Value

Parameter value (used as mean for normal/beta, mode for PERT)

Notes

Optional notes

Test_Parameter

TRUE/FALSE indicating if parameter should be sampled

Distribution

Distribution type: "normal", "beta", or "pert"

SD

Standard deviation (required for normal and beta distributions)

Low_Limit

Lower bound for sampling

Up_Limit

Upper bound for sampling

Examples

if (FALSE) { # \dontrun{
library(CEMPRA)

# Load the sample input file
lc_file <- system.file("extdata/ltre/life_cycles_input_ltre.csv", package = "CEMPRA")
life_cycle_params <- read.csv(lc_file)

# Run the analysis
result <- pop_model_ltre_range(life_cycle_params, n_samples = 500, seed = 42)

# View top influential parameters
head(result$prcc_rankings, 10)

# View lambda distribution summary
result$lambda_summary

# Plot lambda distribution
hist(result$samples$lambda, main = "Lambda Distribution", xlab = "Lambda")
abline(v = 1, col = "red", lty = 2)

# ============================================
# Horizontal bar chart of PRCC rankings
# ============================================

library(ggplot2)

# Prepare data for plotting (already sorted by abs_prcc in output)
prcc_data <- result$prcc_rankings

# Reorder factor levels by absolute PRCC (highest at top, lowest at bottom)
prcc_data$parameter <- factor(
  prcc_data$parameter,
  levels = rev(prcc_data$parameter)
)

# Define significance based on p_value
prcc_data$significant <- prcc_data$p_value < 0.01

ggplot(prcc_data, aes(x = abs_prcc, y = parameter, fill = significant)) +
  geom_col(width = 0.7) +
  scale_fill_manual(
    values = c("TRUE" = "steelblue", "FALSE" = "coral"),
    labels = c("TRUE" = "(p < 0.01)", "FALSE" = "(p > 0.01)"),
    name = "Statistical Significance"
  ) +
  scale_x_continuous(limits = c(0, 1), breaks = seq(0, 1, 0.25)) +
  labs(
    x = "Absolute PRCC with Lambda",
    y = "Model Parameter",
    title = "Parameter Sensitivity Rankings",
    subtitle = paste0("Based on ", result$metadata$n_samples, " Monte Carlo samples")
  ) +
  theme_minimal(base_size = 12) +
  theme(
    panel.grid.major.y = element_blank(),
    panel.grid.minor = element_blank(),
    legend.position = "bottom"
  )
} # }