Package {joinpointR}

Type:	Package
Title:	Tidy Tools for Joinpoint Regression Models
Version:	1.0.0
Description:	Provides tools to fit joinpoint regression models with a log-linear specification by levels of a categorical variable. The package acts as a wrapper around the 'segmented' package, facilitating model fitting, selection, and interpretation. It includes functions to estimate the Annual Percent Change (APC) and the Average Annual Percent Change (AAPC), along with their 95% confidence intervals, and to generate formatted summary tables and plots of results.
License:	MIT + file LICENSE
Encoding:	UTF-8
Imports:	dplyr, purrr, tidyr, tibble, ggplot2, segmented, scales, flextable, rlang, stringr, stats, officer, forcats, cols4all
URL:	https://github.com/datos-ine/joinpointR
BugReports:	https://github.com/datos-ine/joinpointR/issues
Suggests:	knitr, rmarkdown, testthat (≥ 3.0.0)
Config/testthat/edition:	3
Config/roxygen2/version:	8.0.0
VignetteBuilder:	knitr
Depends:	R (≥ 4.1.0)
LazyData:	true
NeedsCompilation:	no
Packaged:	2026-06-10 16:03:54 UTC; user
Author:	Tamara Ricardo [aut, cre]
Maintainer:	Tamara Ricardo <tamararicardo83@gmail.com>
Repository:	CRAN
Date/Publication:	2026-06-10 17:10:08 UTC

Average Annual Percent Change (AAPC)

Description

Estimates the Average Annual Percent Change (AAPC) and its corresponding 95% confidence interval for one or more regression models. Optionally, statistical significance can be displayed using significance stars instead of confidence intervals.

Usage

get_aapc(mods, digits = 1, show_ci = TRUE, dec = ".")

Arguments

Value

A tibble with one row per model containing the estimated AAPC and either its 95% confidence interval or significance stars.

Author(s)

Tamara Ricardo

Examples

# Load example data
data(hiv_data)

# Fit joinpoint models
mods <- model_jp(
  data = hiv_data,
  value = "hiv_rate",
  time = "year",
  group = "region",
  k = 2,
  test = TRUE
)

# AAPC with 95% confidence intervals
get_aapc(mods, digits = 1, show_ci = TRUE, dec = ".")

# AAPC with significance stars
get_aapc(mods, show_ci = FALSE)

# AAPC for a single model
get_aapc(mods$Central)

Annual Percent Change by Segment

Description

Calculates the Annual Percent Change (APC) and corresponding 95% confidence intervals for each segment of one or more joinpoint regression models.

Usage

get_apc(mods, digits = 1, dec = ".")

Arguments

Value

A tibble with one row per segment and the variables group, segment, apc, lower, and upper, where lower and upper correspond to the limits of the 95\

Author(s)

Tamara Ricardo

Examples

# Load example data
data(hiv_data)

# Fit joinpoint models
mods <- model_jp(
  data = hiv_data,
  value = "hiv_rate",
  time = "year",
  group = "region",
  k = 2,
  test = TRUE
)

# APC and 95% confidence intervals for all models
get_apc(mods, digits = 1, dec = ".")

# APC and 95% confidence intervals for a single model
get_apc(mods$Central)

Plot Joinpoint Regression Models

Description

Creates a ggplot showing observed values, fitted joinpoint regression lines, and optional joinpoints.

Usage

gg_jpoint(
  mods,
  obs = TRUE,
  psize = 2.5,
  ptr = 0.75,
  jp = TRUE,
  facets = c("wrap", "grid", "none"),
  ncol = 4,
  cb = TRUE,
  cbpal = c("viridis", "managua", "plasma", "roma", "vanimo", "algae", "arches2",
    "glasgow", "tokyo", "blue_fluoride")
)

Arguments

Details

Available colorblind-friendly palettes from the cols4all package include:

Diverging palettes:

• "managua"

• "plasma"

• "roma"

• "vanimo"

• "viridis"

Sequential palettes:

• "algae"

• "arches2"

• "blue_fluoride"

• "glasgow"

• "tokyo"

Value

A ggplot object showing observed values, fitted joinpoint regression lines, and optional joinpoints.

Examples

# Load example data
data(hiv_data)

# Fit the joinpoint models
mods <- model_jp(
  data = hiv_data,
  value = hiv_rate,
  time = year,
  group = c("region", "sex"),
  k = 2,
  test = TRUE
)

# Plot results
gg_jpoint(mods, obs = TRUE, jp = TRUE, facets = "wrap")

# Facet by group and subgroup
gg_jpoint(mods, obs = TRUE, jp = TRUE, facets = "grid")

# Single panel without joinpoints
gg_jpoint(mods, jp = FALSE, facets = "none")

# Use a different colorblind-friendly palette
gg_jpoint(
  mods,
  obs = TRUE,
  jp = TRUE,
  facets = "grid",
  cb = TRUE,
  cbpal = "managua"
)

# Use default ggplot2 palette (can be changed using `scale_color_`)
gg_jpoint(
mods,
cb = FALSE
)

Simulated HIV rates

Description

Simulated annual HIV rates by region and sex from 2010 to 2025.

Usage

hiv_data

Format

A data frame with 160 rows and 4 variables:

year

Calendar year.

region

Geographic region.

sex

Sex ("Male" or "Female").

hiv_rate

Simulated HIV rate.

Source

Simulated data.

Summary Flextable for Joinpoint Regression Models

Description

Creates a flextable object from the output of summary_jp(), displaying the number of joinpoints, time periods, Annual Percent Change (APC) with 95% confidence intervals, and Average Annual Percent Change (AAPC) with statistical significance.

Usage

jp_to_ft(tab, digits = 1, lan = c("en", "es"))

Arguments

Value

A flextable object containing summary statistics for the joinpoint regression models.

Author(s)

Tamara Ricardo

Examples

# Load example data
data(hiv_data)

# Fit the joinpoint models
mods <- model_jp(
  data = hiv_data,
  value = hiv_rate,
  time = year,
  group = c("region", "sex")
)

# Generate a flextable summary
tab <- summary_jp(mods, digits = 1)
jp_to_ft(tab)

# Change table language
jp_to_ft(tab, lan = "es")

Joinpoint Regression Models by Groups

Description

Fits segmented linear regression models by groups for age-standardized rates using joinpoint regression. Models can be fitted using either a stepwise selection procedure based on the Bayesian Information Criterion (BIC) or a fixed number of joinpoints. Internally, the function calls segmented::selgmented() or segmented::segmented() and applies a log transformation to the response variable.

Usage

model_jp(data, value, time, group, k = 2, step = TRUE, test = TRUE)

Arguments

Details

The National Cancer Institute (NCI) recommends the following maximum number of joinpoints according to the length of the time series (Kim et al., 2000):

• 0–6 time points: 0 joinpoints.

• 7–11 time points: 1 joinpoint.

• 12–16 time points: 2 joinpoints.

• 17–21 time points: 3 joinpoints.

• 22–26 time points: 4 joinpoints.

• 27–31 time points: 5 joinpoints.

• 32–36 time points: 6 joinpoints.

• 37 or more time points: 7 joinpoints.

#' @references Kim HJ, Fay MP, Feuer EJ, Midthune DN (2000). "Permutation Tests for Joinpoint Regression with Applications to Cancer Rates." Statistics in Medicine, 19(3), 335–351. doi:10.1002/(sici)1097-0258(20000215)19:3<335::aid-sim336>3.0.co;2-z.

Value

A named list of joinpoint regression models by group.

Author(s)

Tamara Ricardo

Examples

# Load example data
data("hiv_data")

# Check group levels
levels(hiv_data$region)

# Fit models
mods <- model_jp(data = hiv_data, value = hiv_rate, time = year, group = c("region", "sex"),
 k = 2, step = TRUE, test = TRUE)

# Show the output of the first model by calling its index
mods[[1]]

# Same output will be obtained when calling model name
mods$Central

Summary Tables for Joinpoint Regression Models

Description

Generates summary tables for one or more joinpoint regression models, including the number of joinpoints (JP), time periods, Annual Percent Change (APC) with 95% confidence intervals, and Average Annual Percent Change (AAPC) with statistical significance.

Usage

summary_jp(mods, digits = 1, dec = c(".", ","))

Arguments

Value

A tibble with one row per segment containing the grouping variable(s), number of joinpoints (JP), time period(s), APC and its 95% confidence interval, and AAPC with significance stars.

Author(s)

Tamara Ricardo

Examples

# Load example data
data(hiv_data)

# Fit joinpoint models
mods <- model_jp(
  data = hiv_data,
  value = hiv_rate,
  time = year,
  group = "region"
)

# Summarize models
summary_jp(mods, digits = 1, dec = ".")