Package {ltvlms}

Type:	Package
Title:	Linear Time-Variant Logistic Models with a Shape Parameter
Version:	0.1.0
Description:	Evaluates and fits the Linear Time-Variant Logistic Model with Shape Parameter (LTVLMS) for dynamic growth processes. The model combines a linearly time-varying growth rate with a shape parameter for asymmetric trajectories and includes numerically stable prediction utilities. Methodological details are provided by Betrouni and Kernane (2026) "Linear Time-Varying Logistic Model With Shape Parameter for Dynamic Epidemic Modeling" <doi:10.1155/jama/4928447>.
Depends:	R (≥ 4.0.0)
License:	MIT + file LICENSE
Copyright:	Package code and documentation are copyright the listed authors. The included UNAIDS-derived datasets remain subject to the UNAIDS terms identified in inst/COPYRIGHTS.
Encoding:	UTF-8
NeedsCompilation:	no
Packaged:	2026-10-15 18:03:31 UTC; bander
Author:	Redouane Betrouni [aut], Tewfik Kernane [aut], Bander Hussein [aut, cre]
Maintainer:	Bander Hussein <bshussein@gmail.com>
Repository:	CRAN
Date/Publication:	2026-10-24 16:20:08 UTC

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

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

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

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

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

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

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.