Package 'nih.joinpoint'

Browse the joinpoint files

Description

Open the directory in temporary files where joinpoint files are stored

Usage

browse(jp)

Arguments

jp	the joinpoint analysis to browse

Examples

jp = joinpoint_example()
print(dir)
#browseURL(dir)

---

Export options

Description

Create a character representation of the .ini file needed for export options.

Usage

export_options(
  models = c("best fit", "all"),
  remove_jp_flags = TRUE,
  remove_best_fit_flags = FALSE,
  output_bygroup_headers = FALSE,
  all_models_in_same_column = FALSE,
  include_jp_estimates = FALSE,
  include_apcs = TRUE,
  x_precision = 9,
  y_precision = 9,
  model_precision = 3,
  estimated_joinpoint_precision = 3,
  regression_coefficients_precision = 3,
  covariance_matrix_precision = 3,
  correlation_matrix_precision = 3,
  apc_precision = 3,
  aapc_precision = 3,
  aapc_segment_ranges_precision = 3,
  pvalue_precision = 3,
  aapc_full_range = FALSE,
  aapc_start_range1 = NULL,
  aapc_end_range1 = NULL,
  aapc_start_range2 = NULL,
  aapc_end_range2 = NULL,
  aapc_start_range3 = NULL,
  aapc_end_range3 = NULL,
  aapc_last_obs = FALSE,
  export_bad_cohorts = TRUE,
  export_report = TRUE,
  export_data = TRUE,
  export_apc = TRUE,
  export_aapc = TRUE,
  export_ftest = TRUE,
  export_pairwise = TRUE,
  export_jump_cr = TRUE
)

Arguments

models	one of c("best fit", "all"). Using all might be insightful but rather messes with the output.
remove_jp_flags	remove_jp_flags
remove_best_fit_flags	removes the final_selected_model column
output_bygroup_headers	should only be used if models==best. If FALSE, result table has model, apc, joinpoints. If TRUE, result table has jp2, apc2 (if selected model is with 2 joinpoints) but rather messes with the output.
all_models_in_same_column	all_models_in_same_column
include_jp_estimates	include_jp_estimates
include_apcs	include_apcs
x_precision	x_precision
y_precision	y_precision
model_precision	model_precision
estimated_joinpoint_precision	estimated_joinpoint_precision
regression_coefficients_precision	regression_coefficients_precision
covariance_matrix_precision	covariance_matrix_precision
correlation_matrix_precision	correlation_matrix_precision
apc_precision	apc_precision
aapc_precision	aapc_precision
aapc_segment_ranges_precision	aapc_segment_ranges_precision
pvalue_precision	pvalue_precision
aapc_full_range	aapc_full_range
aapc_start_range1	aapc_start_range1
aapc_end_range1	aapc_end_range1
aapc_start_range2	aapc_start_range2
aapc_end_range2	aapc_end_range2
aapc_start_range3	aapc_start_range3
aapc_end_range3	aapc_end_range3
aapc_last_obs	aapc_last_obs
export_bad_cohorts	export_bad_cohorts
export_report	export_report
export_data	export_data
export_apc	export_apc
export_aapc	export_aapc
export_ftest	export_ftest
export_pairwise	export_pairwise
export_jump_cr	export_jump_cr

Value

a string (character of length 1) representing the .ini file

Source

https://surveillance.cancer.gov/joinpoint/Joinpoint_Help_4.8.0.1.pdf

---

Temporary directory for joinpoint files

Description

Creates a timestamped directory in Local/Temp

Usage

get_tempdir()

Examples

dir = get_tempdir()
print(dir)
#browseURL(dir)

---

API to run a joinpoint model

Description

Use the Command-Line version of "Joinpoint Regression Software" provided by the NIH to run a regression. The software must be downloaded at https://surveillance.cancer.gov/joinpoint/callable/ and installed on a Windows computer. I am not aware of a version of this software for Linux or MacOS.

Usage

joinpoint(
  data,
  x,
  y,
  by = NULL,
  se = NULL,
  export_opts = export_options(),
  run_opts = run_options(),
  cmd_path = getOption("joinpoint_path",
    "C:/Program Files (x86)/Joinpoint Command/jpCommand.exe"),
  dir = get_tempdir(),
  verbose = FALSE
)

Arguments

data	A data frame
x	⁠<tidy-select>⁠ the independent variable (for instance the year)
y	⁠<tidy-select>⁠ the dependent variable
by	⁠<tidy-select>⁠ one or several stratification variable (for instance sex)
se	⁠<tidy-select>⁠ the standard error of the dependent variable. Can be left as NULL at the cost of a longer computation. See https://seer.cancer.gov/seerstat/WebHelp/Rate_Algorithms.htm for calculation formulas.
export_opts	the result of export_options()
run_opts	the result of run_options()
cmd_path	the path to the executable. Can usually be left default to "C:/Program Files (x86)/Joinpoint Command/jpCommand.exe". Can also be set through options(joinpoint_path="my/path/to/jp.exe").
dir	The temporary directory where all the temporary files will be written
verbose	Logical indicating whether or not to print out progress

Details

This function will generate the .ini files, run the software, and then parse the result files as an plain old R list.

Value

the list of the output tables

---

Plot the output of a joinpoint analysis.

Description

Plot the output of a joinpoint analysis.

Usage

jp_plot(
  jp,
  by_level = NULL,
  legend_pattern = getOption("jp_plot_legend_pattern", "{xmin}-{xmax}: {slope}"),
  title_pattern = getOption("jp_plot_title_pattern", "{key}={val}"),
  ncol = 1,
  return_patchwork = TRUE,
  ...
)

Arguments

jp	A list generated using joinpoint().
by_level	One or several stratification levels. Works only if jp was made using one single stratification variable.
legend_pattern	glue::glue() pattern for the legend. Can use variables slope, xmin, and xmax. Can be set through options, e.g. options(jp_plot_legend_pattern="-{slope}-").
title_pattern	glue::glue() pattern for the title. Can use variables key (grouping variable) and val (current group). Can be set through options, e.g. options(jp_plot_title_pattern="-{val}-").
...	passed on to patchwork::wrap_plots()

Value

a patchwork if return_patchwork==TRUE, a list of ggplots otherwise

---

Sample dataset

Description

Sample dataset

Usage

nih_sample_data

Format

A dataframe with 105 observations on 4 variables

Source

Dataset that comes with NIH's Joinpoint software

---

Design options

Description

Create a character representation of the .ini file needed for run options.

Usage

run_options(
  model = c("linear", "ln"),
  data_shift = 0,
  min_joinpoints = 0,
  max_joinpoints = 4,
  pairwise = NULL,
  pairwise_signif_lvl = 0.05,
  pairwise_n_permut = 4499,
  method = c("grid", "hudsons"),
  min_obs_end = 2,
  min_obs_between = 2,
  n_obs_between = 0,
  model_selection_method = c("permutation test", "bic", "mbic",
    "data dependent selection", "wbic", "wbic-alt"),
  permutation_signif_lvl = 0.05,
  n_permutations = 4499,
  early_stopping = c("b-value", "curtailed", "fixed"),
  run_type = c("calculated", "provided"),
  rates_per_n = 1e+05,
  dependent_variable_type = c("count", "crude rate", "age-adjusted rate", "proportion",
    "percent"),
  het_error = c("constant variance", "standard error", "poisson rate", "poisson count"),
  het_error_var_location = NULL,
  ci_method = c("parametric", "empirical quantile method 1",
    "empirical quantile method 2"),
  n_cores = 1,
  delay_type = c("delay", "non-delay", "both"),
  autocorr_errors = c("number", "estimated"),
  jump_model = FALSE,
  comparability_ratio = FALSE,
  include_std_analysis = FALSE,
  jump_location = 9999,
  comparability_ratio_value = 0,
  cr_variance = 0,
  joinpoint_alpha_lvl = 0.05,
  apc_alpha_lvl = 0.05,
  aapc_alpha_lvl = 0.05,
  jump_cr_alpha_lvl = 0.05,
  random_seed = 7160,
  empirical_quantile_seed = 10000,
  empirical_quantile_seed_type = c("constant", "varying"),
  n_resample = 1000,
  madwd = FALSE,
  madwd_psi = 0
)

Arguments

model	one of c("linear", "ln")
data_shift	data_shift
min_joinpoints	min_joinpoints
max_joinpoints	max_joinpoints
pairwise	pairwise
pairwise_signif_lvl	pairwise_signif_lvl
pairwise_n_permut	pairwise_n_permut
method	method
min_obs_end	min_obs_end
min_obs_between	min_obs_between
n_obs_between	n_obs_between
model_selection_method	model_selection_method
permutation_signif_lvl	permutation_signif_lvl
n_permutations	n_permutations
early_stopping	early_stopping
run_type	run_type
rates_per_n	rates_per_n
dependent_variable_type	dependent_variable_type
het_error	het_error
het_error_var_location	het_error_var_location
ci_method	ci_method
n_cores	n_cores
delay_type	delay_type
autocorr_errors	autocorr_errors
jump_model	jump_model
comparability_ratio	comparability_ratio
include_std_analysis	include_std_analysis
jump_location	jump_location
comparability_ratio_value	comparability_ratio_value
cr_variance	cr_variance
joinpoint_alpha_lvl	joinpoint_alpha_lvl
apc_alpha_lvl	apc_alpha_lvl
aapc_alpha_lvl	aapc_alpha_lvl
jump_cr_alpha_lvl	jump_cr_alpha_lvl
random_seed	random_seed
empirical_quantile_seed	empirical_quantile_seed
empirical_quantile_seed_type	empirical_quantile_seed_type
n_resample	n_resample
madwd	madwd
madwd_psi	madwd_psi

Value

a string (character of length 1) representing the .ini file

---