Package {cantrends}

Title:	Fit Segmented Regression Models
Version:	0.1.0
Description:	Estimates piecewise linear spline models for assessing temporal trends in cancer incidence and mortality rates. Provides tools for identifying and reporting knot locations, annual percent changes (APCs), and average annual percent changes (AAPCs), facilitating the analysis and communication of changes in cancer rates over time.
License:	MIT + file LICENSE
Encoding:	UTF-8
RoxygenNote:	7.3.3.9000
Depends:	R (≥ 4.1)
Imports:	broom, carrier (≥ 0.3.0), cli, dplyr, glue, lspline, mirai (≥ 2.5.1), purrr (≥ 1.1.0), rlang, tibble
URL:	https://github.com/mattwarkentin/cantrends
BugReports:	https://github.com/mattwarkentin/cantrends/issues
NeedsCompilation:	no
Packaged:	2026-08-20 23:00:05 UTC; matt
Author:	Matthew T. Warkentin [aut, cre, cph], John Hutchinson [ctb], Yibing Ruan [ctb]
Maintainer:	Matthew T. Warkentin <matthew.warkentin@ucalgary.ca>
Repository:	CRAN
Date/Publication:	2026-08-26 20:00:08 UTC

cantrends: Fit Segmented Regression Models

Description

Estimates piecewise linear spline models for assessing temporal trends in cancer incidence and mortality rates. Provides tools for identifying and reporting knot locations, annual percent changes (APCs), and average annual percent changes (AAPCs), facilitating the analysis and communication of changes in cancer rates over time.

Author(s)

Maintainer: Matthew T. Warkentin matthew.warkentin@ucalgary.ca (ORCID) [copyright holder]

Other contributors:

• John Hutchinson john.hutchinson@ucalgary.ca [contributor]

• Yibing Ruan yibing.ruan@cancercarealberta.ca [contributor]

See Also

Useful links:

• https://github.com/mattwarkentin/cantrends

• Report bugs at https://github.com/mattwarkentin/cantrends/issues

Empiricial Quantile Confidence Intervals

Description

Empiricial Quantile Confidence Intervals

Usage

empirical_quantile_ci(x, reps = 10000, conf.level = 0.95)

Arguments

Value

x but with empirical quantile confidence intervals instead of parametric confidence intervals (i.e., for APC and AAPC).

Extract Information from Segmented Regression Objects

Description

Extract Information from Segmented Regression Objects

Usage

extract_fits(x, ...)

extract_best_fit(x, metric = NULL, nknots = NULL, ...)

extract_best_model(x, metric = NULL, nknots = NULL, ...)

extract_best_metrics(x, metric = NULL, nknots = NULL, ...)

extract_best_predictions(x, metric = NULL, nknots = NULL, ...)

extract_best_apc(x, metric = NULL, nknots = NULL, ...)

extract_best_aapc(x, metric = NULL, nknots = NULL, ...)

Arguments

Value

The following objects are returned by the extraction functions:

• extract_fits(): a tibble of statistics for model fits

• extract_best_fit(): a one-row tibble of statistics for a specific model fit

• ⁠extract_best_model*()⁠: a model object with class "cantrends_spline_fit"

• extract_best_metrics(): a named-list of model fit metrics

• extract_best_predictions(): a tibble with the variables used in the model formula and predictions based on the fitted model

• extract_best_apc(): a tibble with data for the Annual Percent Change (APC) for the chosen model

• extract_best_aapc(): a tibble with data for the Avergae Annual Percent Change (AAPC) for the chosen model

Examples

df <- read.delim(system.file("example.txt", package = "cantrends"), header = FALSE)
res <- segmented_reg(V3 ~ V2, data = df)

extract_best_fit(res)
extract_best_model(res)
extract_best_metrics(res)
extract_best_predictions(res)
extract_best_apc(res)
extract_best_aapc(res)

Knot Options

Description

Define rules for selecting knot locations for segmented regression.

Usage

knot_opts(
  min_knots = 1L,
  max_knots = NULL,
  min_obs_end = 2L,
  min_obs_between = 2L,
  pts_between = 0L,
  force = FALSE
)

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

make_knot_sets(x, opts)

make_point_set(x, opts)

Arguments

Details

The minimum number of observations required to run the segmented regression analysis is estimated as (2 * min_obs_end) + (max_knots - 1) * min_obs_between + max_knots.

Value

knot_opts() returns a list with class "cantrends_knot_opts". make_knot_sets() returns a two-item list with (1) a list of vectors that specify the knot locations to evaluate in grid search and (2) the updated opts object. make_point_set() returns the vector of points used to generate the knot sets'.

Examples

knot_opts()

Segmented Regression using Linear Splines

Description

segmented_reg() fits a linear spline model for the outcome (e.g., rates) against a time variables (e.g., years). Grid search is performed to find the best model (i.e., optimal knot locations) according to the metric criterion. Information about the best model can be extracted from the returned object using the ⁠extract_best_*()⁠ set of functions.

Usage

segmented_reg(
  formula,
  data,
  events = NULL,
  opts = knot_opts(),
  metric = "bic3",
  conf_level = 0.95,
  progress = rlang::is_interactive(),
  knots,
  ...
)

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

Arguments

Details

lspline::lspline() is used to compute the basis for a piecewise linear spline to estimate coefficients in the segmented regression model.

If mirai::daemons() has been used to set persistent background processes, this function will fit segmented regression models in parallel using all available processes.

Value

A named-list of class "cantrends_segmented_reg".

Examples

df <- read.delim(system.file("example.txt", package = "cantrends"), header = FALSE)
res <- segmented_reg(V3 ~ V2, data = df)