Package 'ltvlms'

Linear Time-Variant Logistic Models with a Shape Parameter

Description

Tools to evaluate, fit, compare, and validate Logistic, Gompertz, Richards, and Linear Time-Variant Logistic Models with a Shape Parameter. Fitting uses bounded multi-start optimization initialized by Latin hypercube sampling.

Details

Start with fit_growth_model() for a single model or compare_growth_models() for all four models. Use cross_validate_growth() to distinguish random interpolation assessment from forward-in-time forecasting assessment.

---

Compare Growth Models

Description

Fits multiple models under the same workflow and reports consistently computed performance metrics. Failed models remain visible rather than being discarded.

Usage

compare_growth_models(time, response,
  models = c("logistic", "gompertz", "richards", "ltvlms"),
  n_starts = 50L, seed = 42, bounds = NULL,
  convention = c("standard", "paper"))

## S3 method for class 'growth_comparison'
print(x, ...)
## S3 method for class 'growth_comparison'
plot(x, ..., xlab = "Time", ylab = "Response")

Arguments

time	Numeric observation times.
response	Positive numeric observations.
models	Character vector of model names.
n_starts	Number of multi-start attempts per model.
seed	Seed for reproducible starting points.
bounds	Optional named list of model-specific bound lists.
convention	Information-criterion convention.
x	A growth_comparison object.
xlab, ylab	Plot axis labels.
...	Additional graphical arguments.

Value

An object containing successful fits, metrics, and failure messages.

---

Cross-Validate a Growth Model

Description

Random folds assess interpolation similarly to the manuscript. Forward folds train only on earlier observations and assess forecasting of later observations.

Usage

cross_validate_growth(time, response,
  model = c("ltvlms", "logistic", "gompertz", "richards"),
  folds = 5L, method = c("random", "forward"),
  n_starts = 20L, seed = 42, bounds = NULL)

## S3 method for class 'growth_cv'
print(x, ...)

Arguments

time	Numeric observation times.
response	Positive numeric observations.
model	Growth model name.
folds	Number of validation folds.
method	Random interpolation folds or forward forecasting folds.
n_starts	Multi-start attempts per training fold.
seed	Seed for folds and starting values.
bounds	Optional parameter bounds.
x	A growth_cv object.
...	Additional arguments reserved for methods.

Value

An object containing fold results, predictions, fitted models, and mean errors.

---

Fit a Nonlinear Growth Model

Description

Fits a growth model using bounded PORT optimization from multiple Latin hypercube starting values. Failed starts are retained in the convergence count rather than silently treated as successful.

Usage

fit_growth_model(
  time,
  response,
  model = c("ltvlms", "logistic", "gompertz", "richards"),
  n_starts = 50L,
  bounds = NULL,
  seed = 42,
  control = list(iter.max = 10000L, eval.max = 20000L)
)

Arguments

time	Finite numeric observation times.
response	Finite positive observed responses.
model	Name of the growth model to fit.
n_starts	Number of Latin hypercube starting points.
bounds	Optional named list of lower and upper parameter bounds.
seed	Seed used to generate starting points.
control	Control list passed to nlminb.

Value

An object of class growth_fit.

Examples

time <- 0:12
response <- logistic_growth(time, K = 20, r = 0.4, y0 = 1)
fit <- fit_growth_model(time, response, model = "logistic", n_starts = 5)
fit

---

Evaluate Growth Curves

Description

Evaluates the logistic, Gompertz, Richards, or Linear Time-Variant Logistic Model with Shape Parameter using numerically stable calculations.

Usage

logistic_growth(t, K, r, y0)

gompertz_growth(t, K, r, t0)

richards_growth(t, K, r, t0, alpha, nu)

ltvlms(t, K, y0, r0, r1 = 0, nu = 1)

Arguments

t	Numeric vector of time points measured from the model origin.
K	Positive carrying capacity.
r	Positive constant growth rate.
y0	Positive initial response at time zero, not exceeding K.
t0	Location parameter for the Gompertz or Richards curve.
alpha	Positive Richards scale parameter.
nu	Positive shape parameter.
r0	Initial LTVLMS growth rate.
r1	Linear change in the LTVLMS growth rate.

Value

A numeric vector with the same length as t.

Examples

time <- 0:10
ltvlms(time, K = 100, y0 = 2, r0 = 0.5, r1 = -0.02, nu = 1.2)
logistic_growth(time, K = 100, r = 0.5, y0 = 2)

---

Methods for Fitted Growth Models

Description

Extract coefficients, fitted values, and residuals; predict, print, or plot a fitted growth model.

Usage

## S3 method for class 'growth_fit'
coef(object, ...)
## S3 method for class 'growth_fit'
fitted(object, ...)
## S3 method for class 'growth_fit'
residuals(object, ...)
## S3 method for class 'growth_fit'
predict(object, newdata = NULL, ...)
## S3 method for class 'growth_fit'
print(x, ...)
## S3 method for class 'growth_fit'
plot(x, ..., xlab = "Time", ylab = "Response")

Arguments

object, x	A growth_fit object.
newdata	Optional numeric vector of new time values.
xlab, ylab	Plot axis labels.
...	Additional arguments, including graphical parameters for plotting.

Value

The return value depends on the method:

• coef returns a named numeric vector containing the estimated model parameters.

• fitted returns a numeric vector of fitted responses at the observed time values.

• residuals returns a numeric vector of observed responses minus their fitted values.

• predict returns a numeric vector of fitted responses when newdata is NULL, or predictions at the supplied time values otherwise.

• print invisibly returns the original growth_fit object after displaying a summary of the fit.

• plot invisibly returns the original growth_fit object after drawing the observations and fitted curve.

---

Growth Model Performance Metrics

Description

Calculates prediction metrics and consistently defined information criteria.

Usage

growth_metrics(observed, predicted, n_parameters,
  convention = c("standard", "paper"))

metrics(object, convention = c("standard", "paper"), ...)

## S3 method for class 'growth_fit'
metrics(object,
  convention = c("standard", "paper"), ...)

Arguments

observed	Numeric observed values.
predicted	Numeric predicted values.
n_parameters	Number of fitted curve parameters, excluding variance.
convention	Information-criterion convention. Use "paper" for the constant-free least-squares formulas used for manuscript-comparison reporting.
object	A fitted growth model.
...	Additional arguments reserved for methods.

Value

A one-row data frame containing MSE, RMSE, R-squared, AIC, BIC, and AICc.

---

Adult HIV Prevalence Estimates for 63 Countries and Regions

Description

Complete prevalence series used by the manuscript's cross-country comparison. The data contain 34 annual observations for each of 63 countries or regions.

Usage

data(hiv_prevalence_63)

Format

A data frame with 2,142 rows and 4 variables:

year

Calendar year from 1990 through 2023.

code

UNAIDS country or region code.

country

Country or region name.

prevalence

Estimated HIV prevalence percentage among adults aged 15-49.

Note

These UNAIDS-derived data are not covered by the package's MIT software license. Their use remains subject to the UNAIDS terms at https://www.unaids.org/en/terms-of-use.

Source

UNAIDS 2024, HIV estimates with uncertainty bounds, 1990-2023, as distributed with the manuscript authors' public analysis repository. Official UNAIDS dataset portal: https://aidsinfo.unaids.org/dataset.

---

South Africa Adult HIV Prevalence Estimates, 1990-2023

Description

Annual national HIV prevalence estimates used for the manuscript's South Africa case study. These are modeled UNAIDS estimates, not raw diagnosis counts.

Usage

data(south_africa_hiv)

Format

A data frame with 34 rows and 4 variables:

year

Calendar year.

code

UNAIDS country code, "ZAF".

country

Country name.

prevalence

Estimated HIV prevalence percentage among adults aged 15-49.

Note

These UNAIDS-derived data are not covered by the package's MIT software license. Their use remains subject to the UNAIDS terms at https://www.unaids.org/en/terms-of-use.

Source

UNAIDS 2024, HIV estimates with uncertainty bounds, 1990-2023, as distributed with the manuscript authors' public analysis repository. Official UNAIDS dataset portal: https://aidsinfo.unaids.org/dataset.

---