Run an uncertainty-based LTRE (Life Table Response Experiment) using Monte Carlo sampling and Partial Rank Correlation Coefficients (PRCC) for global sensitivity analysis.
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, and failure_reasons (a table of error messages from failed samples, NULL when every sample succeeded)
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 the mean for "normal" and "beta", the mode (most likely value) for "pert", and ignored for "uniform".
- Notes
Optional notes
- Test_Parameter
TRUE/FALSE indicating if parameter should be sampled
- Distribution
Distribution type: "normal", "beta", "pert", or "uniform" (case-insensitive). See the Distributions section below.
- SD
Standard deviation (required for "normal" and "beta"; ignored for "pert" and "uniform")
- Low_Limit
Lower bound for sampling (required for every tested parameter)
- Up_Limit
Upper bound for sampling (required for every tested parameter)
Distributions
Every tested parameter is sampled independently, and every draw is
guaranteed to fall inside [Low_Limit, Up_Limit]. The four
distribution types differ in which columns they read and in the shape of
the draws:
"normal"Truncated normal.
Valueis the mean andSDthe standard deviation of the underlying normal; draws are restricted to the limits by inverse-CDF sampling (no clumping at the bounds). Best when you have a central estimate with symmetric, roughly bell-shaped uncertainty. Suitable for any parameter scale (e.g. fecundity in the thousands).Valueshould lie inside the limits; if it does not, every draw collapses to the mean and the parameter's PRCC is NA (a warning is issued)."beta"Beta on the 0-1 scale, intended for survival, maturity and other proportions.
Valueis the mean andSDthe standard deviation; the two are converted to beta shape parameters withbeta_param()(which caps very large SD values).Valuemust be strictly between 0 and 1. Draws are then clamped to the limits, so narrow limits relative to SD will pile mass at the bounds; use limits mainly as a safety net and let SD carry the spread."pert"PERT (a rescaled beta used in expert elicitation).
Low_Limitis the minimum,Valuethe most likely value (mode) andUp_Limitthe maximum;SDis ignored. The density is zero at both limits, peaks atValue, and can be skewed whenValuesits off-centre. The shape parameter is fixed at 4, giving a mean of(Low + 4*Value + Up)/6. Best when an expert can state a minimum, a most likely value and a maximum but not a standard deviation.Valuemust lie within the limits (hard error otherwise)."uniform"Uniform ("random between"). Every value in
[Low_Limit, Up_Limit]is equally likely; bothValueandSDare ignored for sampling. Use this when only a plausible range is known, or to give every parameter an equal-footing range screen for PRCC ranking. The parameter'sValuestill appears inparameter_specsfor reference but has no influence on the draws.
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 = 1000, seed = 42)
# View top influential parameters
head(result$prcc_rankings, 10)
# How many simulations had ngative growth rates
# Lambda less than 1
sum(result$samples$lambda < 1) / nrow(result$samples)
# View lambda distribution summary
result$lambda_summary
# Plot lambda distribution
hist(result$samples$lambda, main = "Lambda Distribution", xlab = "Lambda")
abline(v = 1, col = "black", lty = 1)
abline(v = result$lambda_summary$median, col = "red", lty = 2, lwd = 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"
)
} # }