| Title: | Tidy Tools for Joinpoint Regression Models |
|---|---|
| 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. |
| Authors: | Tamara Ricardo [aut, cre] (ORCID: <https://orcid.org/0000-0002-0921-2611>) |
| Maintainer: | Tamara Ricardo <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 1.0.0 |
| Built: | 2026-06-10 22:59:24 UTC |
| Source: | https://github.com/cran/joinpointR |
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.
get_aapc(mods, digits = 1, show_ci = TRUE, dec = ".")get_aapc(mods, digits = 1, show_ci = TRUE, dec = ".")
mods |
A joinpoint regression model, a list of joinpoint regression
models returned by |
digits |
Integer. Number of decimal places used to display the results. |
show_ci |
Logical. If |
dec |
Character. Decimal separator to use ( |
A tibble with one row per model containing the estimated AAPC and either its 95% confidence interval or significance stars.
Tamara Ricardo
# 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)# 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)
Calculates the Annual Percent Change (APC) and corresponding 95% confidence intervals for each segment of one or more joinpoint regression models.
get_apc(mods, digits = 1, dec = ".")get_apc(mods, digits = 1, dec = ".")
mods |
A joinpoint regression model or a list of joinpoint regression
models returned by |
digits |
Integer. Number of decimal places used to display the results. |
dec |
Character. Decimal separator to use (e.g. |
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\
Tamara Ricardo
# 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)# 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)
Creates a ggplot showing observed values, fitted joinpoint regression lines, and optional joinpoints.
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") )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") )
mods |
A list of joinpoint regression models returned by |
obs |
Logical. If |
psize |
Numeric. Size of the observed data points. |
ptr |
Numeric. Transparency level of the observed data points (0-1). |
jp |
Logical. If |
facets |
Character. Determines the facet layout: |
ncol |
Numeric. Number of columns to display when |
cb |
Logical. If |
cbpal |
Character. Name of the colorblind-friendly palette to use. See 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"
A ggplot object showing observed values, fitted joinpoint regression
lines, and optional joinpoints.
# 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 )# 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 annual HIV rates by region and sex from 2010 to 2025.
hiv_datahiv_data
A data frame with 160 rows and 4 variables:
Calendar year.
Geographic region.
Sex ("Male" or "Female").
Simulated HIV rate.
Simulated data.
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.
jp_to_ft(tab, digits = 1, lan = c("en", "es"))jp_to_ft(tab, digits = 1, lan = c("en", "es"))
tab |
A tibble returned by |
digits |
Integer. Number of decimal places used to display the results. |
lan |
Character. Output language: "en" (English) or "es" (Spanish). |
A flextable object containing summary statistics for the joinpoint
regression models.
Tamara Ricardo
# 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")# 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")
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.
model_jp(data, value, time, group, k = 2, step = TRUE, test = TRUE)model_jp(data, value, time, group, k = 2, step = TRUE, test = TRUE)
data |
A data frame containing age-standardized rates. |
value |
Response variable. |
time |
Time variable. |
group |
Names of one or more grouping variables. |
k |
Maximum number of joinpoints to estimate. |
step |
Logical. If |
test |
Logical. If |
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.
A named list of joinpoint regression models by group.
Tamara Ricardo
# 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# 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
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.
summary_jp(mods, digits = 1, dec = c(".", ","))summary_jp(mods, digits = 1, dec = c(".", ","))
mods |
A list of models returned by |
digits |
Integer. Number of decimal places used to display the results. |
dec |
Character. Decimal separator to use (e.g. |
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.
Tamara Ricardo
# 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 = ".")# 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 = ".")