Package 'cantrends'

Empiricial Quantile Confidence Intervals

Description

Empiricial Quantile Confidence Intervals

Usage

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

Arguments

x	A segmented_reg() object.
reps	Number of replicates.
conf.level	The confidence level to use for the confidence interval. Must be strictly greater than 0 and less than 1. Defaults to 0.95 which corresponds to a 95 percent confidence interval.

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

x	An object with class "egdy_segmented_reg"
...	Not currently used.
metric	Which metric to use for selecting the optimal model fit? Default is NULL which uses the metric chosen in segmented_reg().
nknots	Number of knots used in model fit. Default is NULL which returns the globally optimal model. Set this to a specific value to extract the optimal model for a given number of knots.

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

min_knots	Minimum number of knots to evaluate. Default is 1L.
max_knots	Maximum number of knots to evaluate. If NULL, the maximum number of knots will be estimated based on the number of data points.
min_obs_end	Minimum number of points from either end of the observed data range to allow a knot location. Default is 2L.
min_obs_between	Minimum number of data points between knot locations. Default is 2L.
pts_between	Number of new data points to place between adjacent observed data points. Default is 0L.
force	Force the knot locations to be generated despite guidelines around the mininum number of observaions recommended for analysis. Default is FALSE.
x	Observed time points.
...	Not currently used.
opts	A knot_opts() object.

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

formula	Model formula (e.g., year ~ rate).
data	Data frame or tibble::tibble with variables in formula.
events	Vector with the number of events (e.g., deaths) that correspond to the rate data in the formula. If provided, weighted least squares is used instead of ordinary least squares for fitting regression models.
opts	A knots_opt() object providing knot location options.
metric	Metric to use for model selection. One of "bic", "bic3", "aic", or ⁠"aicc".⁠ Default is "bic3".
conf_level	The confidence level to use for the confidence interval. Must be strictly greater than 0 and less than 1. Defaults to 0.95 which corresponds to a 95 percent confidence interval.
progress	Whether to show progress bars. By default, progress bars are enabled in interactive sessions (i.e., if rlang::is_interactive() returns TRUE).
knots	A numeric vector of knot locations or a list of numeric vectors specifying sets of knot locations. If provided, this overrides the automatic knot selection performed using knot_opts() and data.
...	Not currently used.
x	A segmented_reg() object.

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)

---