From d29a3adb8ae3087ae64bf189de6d5dfcdcdcece6 Mon Sep 17 00:00:00 2001 From: Matt Secrest Date: Thu, 4 Apr 2024 11:32:01 -0700 Subject: [PATCH] Tweaks for cran (#278) --- .github/workflows/R-CMD-check.yaml | 3 +- DESCRIPTION | 8 +-- NAMESPACE | 6 +-- R/borrowing_details.R | 11 +++- R/check_data_matrix_has_columns.R | 5 +- R/generics.R | 58 +++++++++++++-------- R/helpers.R | 19 ++++--- R/make_model_string_data.R | 10 ++-- R/make_model_string_functions.R | 8 +-- R/make_model_string_parameters.R | 10 ++-- R/make_model_string_transf_params.R | 10 ++-- R/outcome_bin_logistic.R | 6 +++ R/outcome_surv_exponential.R | 6 +++ R/outcome_surv_weibull_ph.R | 6 +++ R/prior_bernoulli.R | 6 +++ R/prior_beta.R | 6 +++ R/prior_cauchy.R | 6 +++ R/prior_class.R | 2 - R/prior_exponential.R | 6 +++ R/prior_gamma.R | 6 +++ R/prior_half_cauchy.R | 6 +++ R/prior_normal.R | 12 +++++ R/prior_poisson.R | 6 +++ R/sim_borrowing_list.R | 2 + R/sim_covariate_list.R | 2 + R/sim_data_list.R | 6 +++ R/sim_is_null_effect_covered.R | 2 +- R/sim_is_true_effect_covered.R | 2 +- R/sim_outcome_list.R | 2 + R/sim_treatment_list.R | 2 + R/simulation_class.R | 2 +- R/simvar_class.R | 2 + README.md | 7 ++- man/bernoulli_prior.Rd | 5 ++ man/beta_prior.Rd | 5 ++ man/bin_var.Rd | 3 ++ man/borrowing_details.Rd | 8 ++- man/borrowing_none.Rd | 2 +- man/c.Rd | 2 + man/cauchy_prior.Rd | 5 ++ man/check_data_matrix_has_columns.Rd | 5 +- man/cont_var.Rd | 3 ++ man/exp_surv_dist.Rd | 5 ++ man/exponential_prior.Rd | 5 ++ man/gamma_prior.Rd | 5 ++ man/generate.Rd | 3 ++ man/get_cmd_stan_models.Rd | 3 ++ man/get_covariate_constraints.Rd | 30 ----------- man/get_prior_string.Rd | 20 ------- man/get_results.Rd | 3 ++ man/half_cauchy_prior.Rd | 5 ++ man/half_normal_prior.Rd | 5 ++ man/logistic_bin_outcome.Rd | 5 ++ man/make_model_string_data.Rd | 29 ----------- man/make_model_string_functions.Rd | 29 ----------- man/make_model_string_model.Rd | 26 ++++++--- man/make_model_string_parameters.Rd | 29 ----------- man/make_model_string_transf_param.Rd | 29 ----------- man/normal_prior.Rd | 5 ++ man/parse_constraint.Rd | 21 -------- man/plot.Rd | 3 ++ man/plot_pdf.Rd | 3 ++ man/plot_pmf.Rd | 3 ++ man/poisson_prior.Rd | 5 ++ man/psborrow2-package.Rd | 2 +- man/show_guide.Rd | 3 ++ man/sim_borrowing_list.Rd | 5 +- man/sim_covariate_list.Rd | 3 ++ man/sim_data_list.Rd | 4 ++ man/sim_outcome_list.Rd | 3 ++ man/sim_treatment_list.Rd | 3 ++ man/weib_ph_surv_dist.Rd | 5 ++ tests/testthat/test-create_simulation_obj.R | 39 ++++++++++++++ vignettes/original/_psborrow2.Rmd | 9 ++++ vignettes/psborrow2.Rmd | 9 ++++ 75 files changed, 376 insertions(+), 269 deletions(-) delete mode 100644 man/get_covariate_constraints.Rd delete mode 100644 man/get_prior_string.Rd delete mode 100644 man/make_model_string_data.Rd delete mode 100644 man/make_model_string_functions.Rd delete mode 100644 man/make_model_string_parameters.Rd delete mode 100644 man/make_model_string_transf_param.Rd delete mode 100644 man/parse_constraint.Rd diff --git a/.github/workflows/R-CMD-check.yaml b/.github/workflows/R-CMD-check.yaml index 1afb64bf..85b86cbb 100644 --- a/.github/workflows/R-CMD-check.yaml +++ b/.github/workflows/R-CMD-check.yaml @@ -17,7 +17,7 @@ jobs: matrix: config: - {os: macOS-latest, r: 'release'} - - {os: windows-latest, r: 'release'} + #- {os: windows-latest, r: 'release'} - {os: ubuntu-latest, r: 'release'} env: GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} @@ -38,6 +38,7 @@ jobs: with: extra-packages: rcmdcheck, survival, flexsurv, testthat, usethis, vdiffr, tibble, xml2, knitr, rmarkdown, bayesplot, matrixcalc, WeightIt, MatchIt, BayesPPD, ggsurvfit, gbm, ggplot2, cobalt, table1, gt, gtsummary dependencies: '"hard"' + cache: false - name: Install system dependencies on Linux if: runner.os == 'Linux' diff --git a/DESCRIPTION b/DESCRIPTION index f3067ba0..f2694143 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -27,9 +27,9 @@ Authors@R: c( Description: Bayesian dynamic borrowing is an approach to incorporating external data to supplement a randomized, controlled trial analysis in which external data are incorporated in a dynamic way (e.g., based on similarity - of outcomes); see Viele 2013 \doi{10.1002/pst.1589} for an overview. + of outcomes); see Viele 2013 for an overview. This package implements the hierarchical commensurate prior approach to dynamic borrowing - as described in Hobbes 2011 \doi{10.1111/j.1541-0420.2011.01564.x}. + as described in Hobbes 2011 . There are three main functionalities. First, 'psborrow2' provides a user-friendly interface for applying dynamic borrowing on the study results handles the Markov Chain Monte Carlo sampling on behalf of the user. Second, 'psborrow2' provides a @@ -37,7 +37,9 @@ Description: Bayesian dynamic borrowing is an approach to incorporating external borrowing, dynamic borrowing) and other trial and borrowing characteristics (e.g. sample size, covariates) in a unified way. Third, 'psborrow2' provides a set of functions to generate data for simulation studies, and also allows - the user to specify their own data generation process. + the user to specify their own data generation process. This package is designed to + use the sampling functions from 'cmdstanr' which can be installed from + . URL: https://github.com/Genentech/psborrow2, https://genentech.github.io/psborrow2/index.html BugReports: https://github.com/Genentech/psborrow2/issues License: Apache License 2.0 diff --git a/NAMESPACE b/NAMESPACE index 1640cade..f29a1556 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -18,21 +18,18 @@ export(check_cmdstanr) export(check_data_matrix_has_columns) export(cont_var) export(covariance_matrix) -export(create_alpha_string) export(create_analysis_obj) export(create_baseline_object) export(create_data_matrix) export(create_data_simulation) export(create_event_dist) export(create_simulation_obj) -export(create_tau_string) export(custom_enrollment) export(cut_off_after_events) export(cut_off_after_first) export(cut_off_after_last) export(cut_off_none) export(enrollment_constant) -export(eval_constraints) export(exp_surv_dist) export(exponential_prior) export(gamma_prior) @@ -81,11 +78,10 @@ export(sim_outcome_list) export(sim_samplesize) export(sim_treatment_list) export(treatment_details) -export(trim_cols) -export(trim_rows) export(uniform_prior) export(variable_dictionary) export(weib_ph_surv_dist) +exportMethods(c) exportMethods(generate) exportMethods(mcmc_sample) exportMethods(set_transformations) diff --git a/R/borrowing_details.R b/R/borrowing_details.R index 61eaa9ae..d3b63208 100644 --- a/R/borrowing_details.R +++ b/R/borrowing_details.R @@ -1,11 +1,18 @@ #' Legacy function for specifying borrowing details #' -#' Please use one of `hierarchical_commensurate_borrowing()`, `no_borrowing()`, or `full_borrowing()` instead. +#' Please use one of `borrowing_hierarchical_commensurate()`, `borrowing_none()`, or `borrowing_full()` instead. #' @export +#' +#' @return +#' This function does not return a value. When called, it triggers an error +#' message indicating that `borrowing_details()` is deprecated and that +#' one of `borrowing_hierarchical_commensurate()`, `borrowing_none()`, or +#' `borrowing_full()` should be used instead. +#' #' @param ... Deprecated arguments to `borrowing_details`. borrowing_details <- function(...) { .Defunct( - "hierarchical_commensurate_borrowing()", + "borrowing_hierarchical_commensurate()", "psborrow2", paste( "`borrowing_details()` is deprecated. Use `borrowing_hierarchical_commensurate()` for dynamic borrowing,", diff --git a/R/check_data_matrix_has_columns.R b/R/check_data_matrix_has_columns.R index b4414292..37ce78a1 100644 --- a/R/check_data_matrix_has_columns.R +++ b/R/check_data_matrix_has_columns.R @@ -7,7 +7,7 @@ #' @return `stop()` if some columns are missing. #' @export #' @examples -#' anls <- psborrow2:::.analysis_obj( +#' anls <- create_analysis_obj( #' data_matrix = example_matrix, #' covariates = add_covariates( #' covariates = c("cov1", "cov2"), @@ -25,8 +25,7 @@ #' treatment = treatment_details( #' "trt", #' prior_normal(0, 1000) -#' ), -#' ready_to_sample = FALSE +#' ) #' ) #' #' check_data_matrix_has_columns(anls) diff --git a/R/generics.R b/R/generics.R index 5fb9bf2a..d5754205 100644 --- a/R/generics.R +++ b/R/generics.R @@ -10,14 +10,13 @@ #' @param y Not used. #' @param add logical. Add density to existing plot. #' @param ... Optional arguments for plotting. -#' +#' @return No return value, this function generates a plot in the current graphics device. #' @export #' @details #' Plot ranges are selected by default to show 99% of the density for unbounded distributions. #' The limits can be changed by specifying `xlim = c(lower, upper)`. #' #' Colors, line types, and other typical [par()] parameters can be used. -#' if (!isGeneric("plot")) setGeneric("plot", function(x, y, ...) standardGeneric("plot")) @@ -29,7 +28,7 @@ if (!isGeneric("plot")) setGeneric("plot", function(x, y, ...) standardGeneric(" #' @aliases get_vars #' #' @param object Object -#' @returns A `character` vector containing variable names +#' @return A `character` vector containing variable names #' @export #' setGeneric("get_vars", function(object) standardGeneric("get_vars")) @@ -57,6 +56,8 @@ setGeneric("mcmc_sample", function(x, ...) standardGeneric("mcmc_sample")) #' #' @rdname show_guide #' +#' @return A `data.frame` showing all simulation scenarios. +#' #' @export #' setGeneric("show_guide", function(object) standardGeneric("show_guide")) @@ -68,6 +69,8 @@ setGeneric("show_guide", function(object) standardGeneric("show_guide")) #' @param object `MCMCSimulationResults` object #' #' @rdname get_results +#' +#' @return data.frame with simulation results. #' #' @export #' @@ -80,6 +83,8 @@ setGeneric("get_results", function(object) standardGeneric("get_results")) #' @param object `MCMCSimulationResults` object #' #' @rdname get_cmd_stan_models +#' +#' @return List of lists of `CmdStanModel` objects for each model. #' #' @export #' @@ -92,6 +97,8 @@ setGeneric("get_cmd_stan_models", function(object) standardGeneric("get_cmd_stan #' #' @rdname generate #' +#' @return Object of class [`SimDataList`][SimDataList-class]. +#' #' @export setGeneric("generate", function(x, ...) standardGeneric("generate")) @@ -101,8 +108,6 @@ setGeneric("generate", function(x, ...) standardGeneric("generate")) #' @param analysis_object analysis object #' #' @rdname trim_rows -#' -#' @export setGeneric("trim_rows", function(borrowing_object, analysis_object) standardGeneric("trim_rows")) #' Trim columns from Data Matrix Based on Borrowing object type @@ -111,8 +116,6 @@ setGeneric("trim_rows", function(borrowing_object, analysis_object) standardGene #' @param analysis_object analysis object #' #' @rdname trim_cols -#' -#' @export setGeneric("trim_cols", function(borrowing_object, analysis_object) standardGeneric("trim_cols")) #' Create alpha string @@ -121,8 +124,6 @@ setGeneric("trim_cols", function(borrowing_object, analysis_object) standardGene #' @param outcome_object outcome object #' #' @rdname create_alpha_string -#' -#' @export setGeneric("create_alpha_string", function(borrowing_object, outcome_object) standardGeneric("create_alpha_string")) #' Create tau string @@ -130,11 +131,8 @@ setGeneric("create_alpha_string", function(borrowing_object, outcome_object) sta #' @param borrowing_object borrowing object #' #' @rdname create_tau_string -#' -#' @export setGeneric("create_tau_string", function(borrowing_object) standardGeneric("create_tau_string")) - #' Create Stan Code for Model #' #' @param borrowing borrowing object @@ -145,12 +143,26 @@ setGeneric("create_tau_string", function(borrowing_object) standardGeneric("crea #' @return `glue` `character` containing the Stan code for the data block. #' @export #' @examples -#' anls_obj <- psborrow2:::.analysis_obj( -#' data_matrix = example_matrix, -#' outcome = outcome_surv_exponential("time", "cnsr", prior_normal(0, 100)), -#' borrowing = borrowing_full("ext"), -#' treatment = treatment_details("trt", prior_normal(0, 100)) -#' ) +#' anls_obj <- create_analysis_obj( +#' data_matrix = example_matrix, +#' outcome = outcome_surv_exponential( +#' "time", +#' "cnsr", +#' baseline_prior = prior_normal(0, 1000) +#' ), +#' borrowing = borrowing_hierarchical_commensurate( +#' "ext", +#' prior_exponential(.001) +#' ), +#' treatment = treatment_details( +#' "trt", +#' prior_normal(0, 1000) +#' ), +#' covariates = add_covariates( +#' covariates = c("cov1", "cov2"), +#' priors = prior_normal(0, 1000) +#' ) +#' ) #' make_model_string_model(anls_obj@borrowing, anls_obj@outcome, anls_obj) setGeneric("make_model_string_model", function(borrowing, outcome, analysis_obj) { standardGeneric("make_model_string_model") @@ -164,7 +176,7 @@ setGeneric("make_model_string_model", function(borrowing, outcome, analysis_obj) #' #' @param x object of type: [BaselineDataList-class] #' @param ... Optional arguments for passed to [data.frame] -#' @returns A `data.frame` +#' @return A `data.frame` NULL #' @title Combine objects in `psborrow2` @@ -173,7 +185,7 @@ NULL #' @name c #' @param x object of type: [SimDataList-class] #' @param ... additional objects to combine -#' @returns A combined object +#' @return A combined object NULL #' Get Simulated Data from `SimDataList` object @@ -183,7 +195,7 @@ NULL #' @param object `SimDataList` object #' @param index the index of the scenario (see guide with print(`SimDataList`)) #' @param dataset the dataset out of `n_datasets_per_param` -#' @returns Simulated data as a data frame if the index is specified, else as a list +#' @return Simulated data as a data frame if the index is specified, else as a list #' @export setGeneric("get_data", function(object, index = 1, dataset = 1) standardGeneric("get_data")) @@ -192,12 +204,12 @@ setGeneric("get_data", function(object, index = 1, dataset = 1) standardGeneric( #' @param object `BaselineObject` object #' @param ... Additional arguments passed to methods #' @param overwrite logical. Overwrite existing transformations? -#' @returns `BaselineObject` object with transformations +#' @return `BaselineObject` object with transformations #' @export setGeneric("set_transformations", function(object, ..., overwrite = FALSE) standardGeneric("set_transformations")) #' Get method for Stan model #' @param object `Analysis` object -#' @returns String containing the Stan model +#' @return String containing the Stan model #' @export setGeneric("get_stan_code", function(object) standardGeneric("get_stan_code")) diff --git a/R/helpers.R b/R/helpers.R index 399e2d05..b44dd7b3 100644 --- a/R/helpers.R +++ b/R/helpers.R @@ -6,8 +6,11 @@ #' #' Plots the density values as a curve with the lower vertical limit set to 0. #' -#' @export +#' +#' @return No return value, this function generates a plot in the current graphics device. #' +#' @export +#' #' @examples #' x <- seq(-2, 2, len = 100) #' y <- dnorm(x) @@ -36,6 +39,8 @@ plot_pdf <- function(x, y, ...) { #' #' Plots the probability values as a barplot. #' +#' @return No return value, this function generates a plot in the current graphics device. +#' #' @export #' #' @examples @@ -73,12 +78,12 @@ plot_pmf <- function(x, y, ..., col = "grey", add = FALSE) { #' @param collapse_sep string. A character string to separate the original strings in the collapsed string. #' #' @return A character (of class `glue`). -#' @noRd #' @examples #' name <- "Tom" #' psborrow2:::h_glue("hello, my name is {{name}}.") #' name <- c("Tom", "Fred") #' psborrow2:::h_glue("hello, my name is {{name}}.", collapse = TRUE) +#' @noRd h_glue <- function(..., collapse = FALSE, collapse_sep = "\n") { result <- glue::glue(..., .open = "{{", .close = "}}", .envir = parent.frame()) if (isTRUE(collapse)) { @@ -94,7 +99,7 @@ h_glue <- function(..., collapse = FALSE, collapse_sep = "\n") { #' #' @return A `matrix` with columns "lower" and "upper" with rows for each `Prior`. #' @examples -#' psborrow2:::get_covariate_constraints( +#' get_covariate_constraints( #' add_covariates( #' c("cov1", "cov2", "cov3"), #' list( @@ -104,7 +109,7 @@ h_glue <- function(..., collapse = FALSE, collapse_sep = "\n") { #' ) #' ) #' ) -#' +#' @noRd get_covariate_constraints <- function(cov_obj) { n_covs <- length(cov_obj@covariates) if (is(cov_obj@priors, "Prior")) { @@ -125,7 +130,8 @@ get_covariate_constraints <- function(cov_obj) { #' A list with upper and lower bounds. Any unspecified bounds are set to `-Inf` or `Inf`. #' @examples #' np <- prior_normal(0, 100) -#' psborrow2:::parse_constraint(np) +#' parse_constraint(np) +#' @noRd parse_constraint <- function(object) { assert_class(object, "Prior") s <- eval_constraints(object) @@ -214,7 +220,8 @@ variable_dictionary <- function(analysis_obj) { #' #' @return A string containing the Stan code sampling from specified distribution. #' @examples -#' psborrow2:::get_prior_string(prior_normal(0, 100)) +#' get_prior_string(prior_normal(0, 100)) +#' @noRd get_prior_string <- function(object) { assert_multi_class(object, c("Prior", "list")) if (is(object, "list")) { diff --git a/R/make_model_string_data.R b/R/make_model_string_data.R index f6e09a1d..76e09b90 100644 --- a/R/make_model_string_data.R +++ b/R/make_model_string_data.R @@ -3,20 +3,20 @@ #' Create the Stan string encompassed by data `{}` #' #' @param analysis_obj `Analysis`. Object of class [`Analysis`][Analysis-class] created by -#' `psborrow2:::.analysis_obj()`. +#' `.analysis_obj()`. #' #' @return `glue` `character` containing the text for the data block. #' #' @examples -#' anls_obj <- psborrow2:::.analysis_obj( +#' anls_obj <- .analysis_obj( #' data_matrix = example_matrix, #' outcome = outcome_surv_exponential("time", "cnsr", prior_normal(0, 100)), #' borrowing = borrowing_full("ext"), #' treatment = treatment_details("trt", prior_normal(0, 100)) #' ) -#' -#' psborrow2:::make_model_string_data(anls_obj) -#' +#' +#' make_model_string_data(anls_obj) +#' @noRd make_model_string_data <- function(analysis_obj) { outcome_string <- analysis_obj@outcome@data_stan_code diff --git a/R/make_model_string_functions.R b/R/make_model_string_functions.R index 017ee034..6acbe7b1 100644 --- a/R/make_model_string_functions.R +++ b/R/make_model_string_functions.R @@ -3,20 +3,20 @@ #' Create the Stan string encompassed by functions `{}` #' #' @param analysis_obj `Analysis`. Object of class [`Analysis`][Analysis-class] created by -#' `psborrow2:::.analysis_obj()`. +#' `.analysis_obj()`. #' #' @return `glue` `character` containing the text for the functions block. #' #' @examples -#' anls_obj <- psborrow2:::.analysis_obj( +#' anls_obj <- .analysis_obj( #' data_matrix = example_matrix, #' outcome = outcome_surv_exponential("time", "cnsr", prior_normal(0, 100)), #' borrowing = borrowing_full("ext"), #' treatment = treatment_details("trt", prior_normal(0, 100)) #' ) #' -#' psborrow2:::make_model_string_functions(anls_obj) -#' +#' make_model_string_functions(anls_obj) +#' @noRd make_model_string_functions <- function(analysis_obj) { ## Bring in analysis_obj functions h_glue(" diff --git a/R/make_model_string_parameters.R b/R/make_model_string_parameters.R index 6a2d7c41..53c349f6 100644 --- a/R/make_model_string_parameters.R +++ b/R/make_model_string_parameters.R @@ -3,20 +3,20 @@ #' Create the Stan string encompassed by parameters `{}` #' #' @param analysis_obj `Analysis`. Object of class [`Analysis`][Analysis-class] created by -#' `psborrow2:::.analysis_obj()`. +#' `.analysis_obj()`. #' #' @return `glue` `character` containing the Stan code for the functions block. #' #' @examples -#' anls_obj <- psborrow2:::.analysis_obj( +#' anls_obj <- .analysis_obj( #' data_matrix = example_matrix, #' outcome = outcome_surv_exponential("time", "cnsr", prior_normal(0, 100)), #' borrowing = borrowing_full("ext"), #' treatment = treatment_details("trt", prior_normal(0, 100)) #' ) -#' -#' psborrow2:::make_model_string_parameters(anls_obj) -#' +#' +#' make_model_string_parameters(anls_obj) +#' @noRd make_model_string_parameters <- function(analysis_obj) { ## Parameters string trt_string <- h_glue("real{{eval_constraints(analysis_obj@treatment@trt_prior)}} beta_trt;") diff --git a/R/make_model_string_transf_params.R b/R/make_model_string_transf_params.R index 870a8e5a..831fe876 100644 --- a/R/make_model_string_transf_params.R +++ b/R/make_model_string_transf_params.R @@ -3,20 +3,20 @@ #' Create the Stan string encompassed by transformed parameters `{}` #' #' @param analysis_obj `Analysis`. Object of class [`Analysis`][Analysis-class] created by -#' `psborrow2:::.analysis_obj()`. +#' `.analysis_obj()`. #' #' @return `glue` `character` containing the Stan code for the functions block. #' #' @examples -#' anls_obj <- psborrow2:::.analysis_obj( +#' anls_obj <- .analysis_obj( #' data_matrix = example_matrix, #' outcome = outcome_surv_exponential("time", "cnsr", prior_normal(0, 100)), #' borrowing = borrowing_full("ext"), #' treatment = treatment_details("trt", prior_normal(0, 100)) #' ) -#' -#' psborrow2:::make_model_string_transf_param(anls_obj) -#' +#' +#' make_model_string_transf_param(anls_obj) +#' @noRd make_model_string_transf_param <- function(analysis_obj) { transformed_parameters_string <- if (is(analysis_obj@outcome, "TimeToEvent")) { "real HR_trt = exp(beta_trt);" diff --git a/R/outcome_bin_logistic.R b/R/outcome_bin_logistic.R index 283a0822..ae52ae5e 100644 --- a/R/outcome_bin_logistic.R +++ b/R/outcome_bin_logistic.R @@ -99,6 +99,12 @@ outcome_bin_logistic <- function(binary_var, #' #' Please use `outcome_bin_logistic()` instead. #' @param ... Deprecated arguments to `logistic_bin_outcome`. +#' +#' @return +#' This function does not return a value. When called, it triggers an error +#' message indicating that `logistic_bin_outcome()` is deprecated and that +#' `outcome_bin_logistic()` should be used instead. +#' #' @export logistic_bin_outcome <- function(...) { .Defunct( diff --git a/R/outcome_surv_exponential.R b/R/outcome_surv_exponential.R index a2da1e95..e5165c66 100644 --- a/R/outcome_surv_exponential.R +++ b/R/outcome_surv_exponential.R @@ -109,6 +109,12 @@ outcome_surv_exponential <- function(time_var, cens_var, baseline_prior, weight_ #' #' Please use `outcome_surv_exponential()` instead. #' @param ... Deprecated arguments to `exp_surv_dist()`. +#' +#' @return +#' This function does not return a value. When called, it triggers an error +#' message indicating that `exp_surv_dist()` is deprecated and that +#' `outcome_surv_exponential()` should be used instead. +#' #' @export exp_surv_dist <- function(...) { .Defunct( diff --git a/R/outcome_surv_weibull_ph.R b/R/outcome_surv_weibull_ph.R index 8b898ef5..2c6af10e 100644 --- a/R/outcome_surv_weibull_ph.R +++ b/R/outcome_surv_weibull_ph.R @@ -144,6 +144,12 @@ outcome_surv_weibull_ph <- function(time_var, #' #' Please use `outcome_surv_weibull_ph()` instead. #' @param ... Deprecated arguments to `weib_ph_surv_dist()`. +#' +#' @return +#' This function does not return a value. When called, it triggers an error +#' message indicating that `weib_ph_surv_dist()` is deprecated and that +#' `outcome_surv_weibull_ph()` should be used instead. +#' #' @export weib_ph_surv_dist <- function(...) { .Defunct( diff --git a/R/prior_bernoulli.R b/R/prior_bernoulli.R index ebb549f3..8b25a0e1 100644 --- a/R/prior_bernoulli.R +++ b/R/prior_bernoulli.R @@ -83,6 +83,12 @@ setMethod( #' #' Please use `prior_bernoulli()` instead. #' @param ... Deprecated arguments to `bernoulli_prior()`. +#' +#' @return +#' This function does not return a value. When called, it triggers an error +#' message indicating that `bernoulli_prior()` is deprecated and that +#' `prior_bernoulli()` should be used instead. +#' #' @export bernoulli_prior <- function(...) { .Defunct( diff --git a/R/prior_beta.R b/R/prior_beta.R index 056d2d50..2f4ce346 100644 --- a/R/prior_beta.R +++ b/R/prior_beta.R @@ -90,6 +90,12 @@ setMethod( #' #' Please use `prior_beta()` instead. #' @param ... Deprecated arguments to `beta_prior()`. +#' +#' @return +#' This function does not return a value. When called, it triggers an error +#' message indicating that `beta_prior()` is deprecated and that +#' `prior_beta()` should be used instead. +#' #' @export beta_prior <- function(...) { .Defunct( diff --git a/R/prior_cauchy.R b/R/prior_cauchy.R index 6c8c74e4..79fd8aab 100644 --- a/R/prior_cauchy.R +++ b/R/prior_cauchy.R @@ -92,6 +92,12 @@ setMethod( #' #' Please use `prior_cauchy()` instead. #' @param ... Deprecated arguments to `cauchy_prior()`. +#' +#' @return +#' This function does not return a value. When called, it triggers an error +#' message indicating that `cauchy_prior()` is deprecated and that +#' `prior_cauchy()` should be used instead. +#' #' @export cauchy_prior <- function(...) { .Defunct( diff --git a/R/prior_class.R b/R/prior_class.R index 606f5df8..6972c20b 100644 --- a/R/prior_class.R +++ b/R/prior_class.R @@ -91,8 +91,6 @@ setMethod( #' #' @rdname eval_constraints #' -#' @export -#' setGeneric("eval_constraints", function(object) standardGeneric("eval_constraints")) #' @rdname eval_constraints diff --git a/R/prior_exponential.R b/R/prior_exponential.R index aa97bc3e..ba8dca89 100644 --- a/R/prior_exponential.R +++ b/R/prior_exponential.R @@ -85,6 +85,12 @@ setMethod( #' #' Please use `prior_exponential()` instead. #' @param ... Deprecated arguments to `exponential_prior()`. +#' +#' @return +#' This function does not return a value. When called, it triggers an error +#' message indicating that `exponential_prior()` is deprecated and that +#' `prior_exponential()` should be used instead. +#' #' @export exponential_prior <- function(...) { .Defunct( diff --git a/R/prior_gamma.R b/R/prior_gamma.R index 5de9366d..2ed645b3 100644 --- a/R/prior_gamma.R +++ b/R/prior_gamma.R @@ -90,6 +90,12 @@ setMethod( #' #' Please use `prior_gamma()` instead. #' @param ... Deprecated arguments to `gamma_prior()`. +#' +#' @return +#' This function does not return a value. When called, it triggers an error +#' message indicating that `gamma_prior()` is deprecated and that +#' `prior_gamma()` should be used instead. +#' #' @export gamma_prior <- function(...) { .Defunct( diff --git a/R/prior_half_cauchy.R b/R/prior_half_cauchy.R index 6831bb73..4d319c65 100644 --- a/R/prior_half_cauchy.R +++ b/R/prior_half_cauchy.R @@ -97,6 +97,12 @@ setMethod( #' #' Please use `prior_half_cauchy()` instead. #' @param ... Deprecated arguments to `half_cauchy_prior()`. +#' +#' @return +#' This function does not return a value. When called, it triggers an error +#' message indicating that `half_cauchy_prior()` is deprecated and that +#' `prior_half_cauchy()` should be used instead. +#' #' @export half_cauchy_prior <- function(...) { .Defunct( diff --git a/R/prior_normal.R b/R/prior_normal.R index f250cc22..cf6683ae 100644 --- a/R/prior_normal.R +++ b/R/prior_normal.R @@ -91,6 +91,12 @@ setMethod( #' #' Please use `prior_normal()` instead. #' @param ... Deprecated arguments to `normal_prior()`. +#' +#' @return +#' This function does not return a value. When called, it triggers an error +#' message indicating that `normal_prior()` is deprecated and that +#' `prior_normal()` should be used instead. +#' #' @export normal_prior <- function(...) { .Defunct( @@ -105,6 +111,12 @@ normal_prior <- function(...) { #' #' Please use `prior_half_normal()` instead. #' @param ... Deprecated arguments to `half_normal_prior()`. +#' +#' @return +#' This function does not return a value. When called, it triggers an error +#' message indicating that `half_normal_prior()` is deprecated and that +#' `prior_half_normal()` should be used instead. +#' #' @export half_normal_prior <- function(...) { .Defunct( diff --git a/R/prior_poisson.R b/R/prior_poisson.R index 879eb065..7e535027 100644 --- a/R/prior_poisson.R +++ b/R/prior_poisson.R @@ -87,6 +87,12 @@ setMethod( #' #' Please use `prior_poisson()` instead. #' @param ... Deprecated arguments to `poisson_prior()`. +#' +#' @return +#' This function does not return a value. When called, it triggers an error +#' message indicating that `poisson_prior()` is deprecated and that +#' `prior_poisson()` should be used instead. +#' #' @export poisson_prior <- function(...) { .Defunct( diff --git a/R/sim_borrowing_list.R b/R/sim_borrowing_list.R index a9806615..62bd56a5 100644 --- a/R/sim_borrowing_list.R +++ b/R/sim_borrowing_list.R @@ -45,6 +45,8 @@ #' @param borrowing_list named list of objects of class `Borrowing` created #' by `borrowing_full()`, `borrowing_none()`, or `borrowing_hierarchical_commensurate()`. #' +#' @return Object of class [`SimBorrowingList`][SimBorrowingList-class]. +#' #' @export #' #' @family simulation classes diff --git a/R/sim_covariate_list.R b/R/sim_covariate_list.R index 04801005..ce9407f8 100644 --- a/R/sim_covariate_list.R +++ b/R/sim_covariate_list.R @@ -50,6 +50,8 @@ #' #' @family simulation classes #' +#' @return Object of class [`SimCovariateList`][SimCovariateList-class]. +#' #' @export #' #' @examples diff --git a/R/sim_data_list.R b/R/sim_data_list.R index a8cbea7d..41d96130 100644 --- a/R/sim_data_list.R +++ b/R/sim_data_list.R @@ -172,6 +172,9 @@ #' drift = "driftOR", #' index = "ind" #' ) +#' +#' @return Object of class [`SimDataList`][SimDataList-class]. +#' #' @export sim_data_list <- function(data_list, guide, @@ -209,6 +212,9 @@ setMethod( # c ---- #' @rdname c +#' +#' @return list of [`SimDataList`][SimDataList-class] objects. +#' @export setMethod( f = "c", signature = "SimDataList", diff --git a/R/sim_is_null_effect_covered.R b/R/sim_is_null_effect_covered.R index d89e70b3..3fbe3f52 100644 --- a/R/sim_is_null_effect_covered.R +++ b/R/sim_is_null_effect_covered.R @@ -62,7 +62,7 @@ #' treatment = treatment_details("trt", prior_normal(0, 1000)) #' ) #' -#' \dontrun{ +#' \donttest{ #' i <- 1 #' j <- 1 #' anls_obj <- x@analysis_obj_list[[i]][[j]] diff --git a/R/sim_is_true_effect_covered.R b/R/sim_is_true_effect_covered.R index f5bd1591..7a30ee9a 100644 --- a/R/sim_is_true_effect_covered.R +++ b/R/sim_is_true_effect_covered.R @@ -63,7 +63,7 @@ #' treatment = treatment_details("trt", prior_normal(0, 1000)) #' ) #' -#' \dontrun{ +#' \donttest{ #' i <- 1 #' j <- 1 #' true_effect <- x@guide[i, x@data_matrix_list@effect] diff --git a/R/sim_outcome_list.R b/R/sim_outcome_list.R index 0b8d89a5..78093017 100644 --- a/R/sim_outcome_list.R +++ b/R/sim_outcome_list.R @@ -45,6 +45,8 @@ #' by `outcome_details()`. #' #' @family simulation classes +#' +#' @return Object of class [`SimOutcomeList`][SimOutcomeList-class]. #' #' @export #' diff --git a/R/sim_treatment_list.R b/R/sim_treatment_list.R index b5a6d211..429a1157 100644 --- a/R/sim_treatment_list.R +++ b/R/sim_treatment_list.R @@ -44,6 +44,8 @@ #' #' @family simulation classes #' +#' @return Object of class [`SimTreatmentList`][SimTreatmentList-class]. +#' #' @export #' #' @examples diff --git a/R/simulation_class.R b/R/simulation_class.R index a39c5301..f2e7c83c 100644 --- a/R/simulation_class.R +++ b/R/simulation_class.R @@ -112,6 +112,6 @@ setMethod( f = "show_guide", signature = "Simulation", definition = function(object) { - print(object@guide) + object@guide } ) diff --git a/R/simvar_class.R b/R/simvar_class.R index e28017de..da1cc6ba 100644 --- a/R/simvar_class.R +++ b/R/simvar_class.R @@ -41,6 +41,7 @@ setClass( #' #' @param mu_internal numeric. Mean covariate value for the internal arms. #' @param mu_external numeric. Mean covariate value for the external arm. +#' @return Object of class [`SimVarCont`][SimVarCont-class]. #' @export #' @family simvar #' @examples @@ -134,6 +135,7 @@ setMethod( #' `mu_internal_before_bin` and `mu_external_before_bin` are `0`, and #' it is not recommended to change these without good reason. #' +#' @return Object of class [`SimVarBin`][SimVarBin-class]. #' #' @export #' @family simvar diff --git a/README.md b/README.md index 98fe95ab..82df5635 100644 --- a/README.md +++ b/README.md @@ -40,8 +40,11 @@ or you can install the development version with: remotes::install_github("Genentech/psborrow2") ``` -Please note that [`cmdstanr`](https://mc-stan.org/cmdstanr/) is highly recommended, but will not be installed by default when installing `psborrow2`. To install `cmdstanr`, follow the instructions outlined by the [`cmdstanr` documentation](https://mc-stan.org/cmdstanr/). - +Please note that [`cmdstanr`](https://mc-stan.org/cmdstanr/) is highly recommended, but will not be installed by default when installing `psborrow2`. +To install `cmdstanr`, follow the instructions outlined by the [`cmdstanr` documentation](https://mc-stan.org/cmdstanr/) or use: +``` +install.packages("cmdstanr", repos = c("https://mc-stan.org/r-packages/", getOption("repos"))) +``` ## Tutorial diff --git a/man/bernoulli_prior.Rd b/man/bernoulli_prior.Rd index c0980f2e..ee886534 100644 --- a/man/bernoulli_prior.Rd +++ b/man/bernoulli_prior.Rd @@ -9,6 +9,11 @@ bernoulli_prior(...) \arguments{ \item{...}{Deprecated arguments to \code{bernoulli_prior()}.} } +\value{ +This function does not return a value. When called, it triggers an error +message indicating that \code{bernoulli_prior()} is deprecated and that +\code{prior_bernoulli()} should be used instead. +} \description{ Please use \code{prior_bernoulli()} instead. } diff --git a/man/beta_prior.Rd b/man/beta_prior.Rd index 3a95a309..6ba0d30e 100644 --- a/man/beta_prior.Rd +++ b/man/beta_prior.Rd @@ -9,6 +9,11 @@ beta_prior(...) \arguments{ \item{...}{Deprecated arguments to \code{beta_prior()}.} } +\value{ +This function does not return a value. When called, it triggers an error +message indicating that \code{beta_prior()} is deprecated and that +\code{prior_beta()} should be used instead. +} \description{ Please use \code{prior_beta()} instead. } diff --git a/man/bin_var.Rd b/man/bin_var.Rd index ada2ef01..457ca099 100644 --- a/man/bin_var.Rd +++ b/man/bin_var.Rd @@ -22,6 +22,9 @@ for the internal arms. The default is 0. See \code{details} for more information \item{mu_external_before_bin}{numeric. Mean value of the covariate before binarization for the external arm. The default is 0. See \code{details} for more information.} } +\value{ +Object of class \code{\link[=SimVarBin-class]{SimVarBin}}. +} \description{ Create an object of class \code{SimVarBin} to hold proportions of binary variables specified in a simulation study. diff --git a/man/borrowing_details.Rd b/man/borrowing_details.Rd index e861c5bb..c9164762 100644 --- a/man/borrowing_details.Rd +++ b/man/borrowing_details.Rd @@ -9,6 +9,12 @@ borrowing_details(...) \arguments{ \item{...}{Deprecated arguments to \code{borrowing_details}.} } +\value{ +This function does not return a value. When called, it triggers an error +message indicating that \code{borrowing_details()} is deprecated and that +one of \code{borrowing_hierarchical_commensurate()}, \code{borrowing_none()}, or +\code{borrowing_full()} should be used instead. +} \description{ -Please use one of \code{hierarchical_commensurate_borrowing()}, \code{no_borrowing()}, or \code{full_borrowing()} instead. +Please use one of \code{borrowing_hierarchical_commensurate()}, \code{borrowing_none()}, or \code{borrowing_full()} instead. } diff --git a/man/borrowing_none.Rd b/man/borrowing_none.Rd index 4ae70b0e..d1a16df6 100644 --- a/man/borrowing_none.Rd +++ b/man/borrowing_none.Rd @@ -35,7 +35,7 @@ db <- borrowing_none( ) } \seealso{ -Other borrowing: +Other borrowing: \code{\link{borrowing_full}()} } \concept{borrowing} diff --git a/man/c.Rd b/man/c.Rd index 9eed8b0f..f17e93a8 100644 --- a/man/c.Rd +++ b/man/c.Rd @@ -14,6 +14,8 @@ } \value{ A combined object + +list of \code{\link[=SimDataList-class]{SimDataList}} objects. } \description{ Creates \code{data.frame} objects from various classes in \code{psborrow2} diff --git a/man/cauchy_prior.Rd b/man/cauchy_prior.Rd index b91f618e..daac4dd5 100644 --- a/man/cauchy_prior.Rd +++ b/man/cauchy_prior.Rd @@ -9,6 +9,11 @@ cauchy_prior(...) \arguments{ \item{...}{Deprecated arguments to \code{cauchy_prior()}.} } +\value{ +This function does not return a value. When called, it triggers an error +message indicating that \code{cauchy_prior()} is deprecated and that +\code{prior_cauchy()} should be used instead. +} \description{ Please use \code{prior_cauchy()} instead. } diff --git a/man/check_data_matrix_has_columns.Rd b/man/check_data_matrix_has_columns.Rd index cea5cdda..ab9318d9 100644 --- a/man/check_data_matrix_has_columns.Rd +++ b/man/check_data_matrix_has_columns.Rd @@ -16,7 +16,7 @@ check_data_matrix_has_columns(object) Check that an \code{Analysis} object's \code{data_matrix} has all the required variables. } \examples{ -anls <- psborrow2:::.analysis_obj( +anls <- create_analysis_obj( data_matrix = example_matrix, covariates = add_covariates( covariates = c("cov1", "cov2"), @@ -34,8 +34,7 @@ anls <- psborrow2:::.analysis_obj( treatment = treatment_details( "trt", prior_normal(0, 1000) - ), - ready_to_sample = FALSE + ) ) check_data_matrix_has_columns(anls) diff --git a/man/cont_var.Rd b/man/cont_var.Rd index 5762c77d..365ee9cd 100644 --- a/man/cont_var.Rd +++ b/man/cont_var.Rd @@ -11,6 +11,9 @@ cont_var(mu_internal, mu_external) \item{mu_external}{numeric. Mean covariate value for the external arm.} } +\value{ +Object of class \code{\link[=SimVarCont-class]{SimVarCont}}. +} \description{ Create an object of class \code{SimVarCont} to hold mean values of of continuous variables specified in a simulation study. diff --git a/man/exp_surv_dist.Rd b/man/exp_surv_dist.Rd index eee3f5e2..422ec94a 100644 --- a/man/exp_surv_dist.Rd +++ b/man/exp_surv_dist.Rd @@ -9,6 +9,11 @@ exp_surv_dist(...) \arguments{ \item{...}{Deprecated arguments to \code{exp_surv_dist()}.} } +\value{ +This function does not return a value. When called, it triggers an error +message indicating that \code{exp_surv_dist()} is deprecated and that +\code{outcome_surv_exponential()} should be used instead. +} \description{ Please use \code{outcome_surv_exponential()} instead. } diff --git a/man/exponential_prior.Rd b/man/exponential_prior.Rd index b9b15263..c6e8bcae 100644 --- a/man/exponential_prior.Rd +++ b/man/exponential_prior.Rd @@ -9,6 +9,11 @@ exponential_prior(...) \arguments{ \item{...}{Deprecated arguments to \code{exponential_prior()}.} } +\value{ +This function does not return a value. When called, it triggers an error +message indicating that \code{exponential_prior()} is deprecated and that +\code{prior_exponential()} should be used instead. +} \description{ Please use \code{prior_exponential()} instead. } diff --git a/man/gamma_prior.Rd b/man/gamma_prior.Rd index 28e81329..eee08c03 100644 --- a/man/gamma_prior.Rd +++ b/man/gamma_prior.Rd @@ -9,6 +9,11 @@ gamma_prior(...) \arguments{ \item{...}{Deprecated arguments to \code{gamma_prior()}.} } +\value{ +This function does not return a value. When called, it triggers an error +message indicating that \code{gamma_prior()} is deprecated and that +\code{prior_gamma()} should be used instead. +} \description{ Please use \code{prior_gamma()} instead. } diff --git a/man/generate.Rd b/man/generate.Rd index 213766ba..4f0ea1ef 100644 --- a/man/generate.Rd +++ b/man/generate.Rd @@ -11,6 +11,9 @@ generate(x, ...) \item{...}{Other arguments passed to methods} } +\value{ +Object of class \code{\link[=SimDataList-class]{SimDataList}}. +} \description{ Generate Data from Object } diff --git a/man/get_cmd_stan_models.Rd b/man/get_cmd_stan_models.Rd index f3168678..ac2df346 100644 --- a/man/get_cmd_stan_models.Rd +++ b/man/get_cmd_stan_models.Rd @@ -12,6 +12,9 @@ get_cmd_stan_models(object) \arguments{ \item{object}{\code{MCMCSimulationResults} object} } +\value{ +List of lists of \code{CmdStanModel} objects for each model. +} \description{ Show the \code{CmdStanModel} objects from \code{MCMCSimulationResults} objects. } diff --git a/man/get_covariate_constraints.Rd b/man/get_covariate_constraints.Rd deleted file mode 100644 index 736f1a5a..00000000 --- a/man/get_covariate_constraints.Rd +++ /dev/null @@ -1,30 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/helpers.R -\name{get_covariate_constraints} -\alias{get_covariate_constraints} -\title{Get constraints from a list of \code{Prior}s} -\usage{ -get_covariate_constraints(cov_obj) -} -\arguments{ -\item{cov_obj}{A \code{Covariates} object.} -} -\value{ -A \code{matrix} with columns "lower" and "upper" with rows for each \code{Prior}. -} -\description{ -Get constraints from a list of \code{Prior}s -} -\examples{ -psborrow2:::get_covariate_constraints( - add_covariates( - c("cov1", "cov2", "cov3"), - list( - prior_normal(0, 10), - prior_beta(0.3, 0.3), - prior_gamma(30, 1) - ) - ) -) - -} diff --git a/man/get_prior_string.Rd b/man/get_prior_string.Rd deleted file mode 100644 index 3d8b4ba0..00000000 --- a/man/get_prior_string.Rd +++ /dev/null @@ -1,20 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/helpers.R -\name{get_prior_string} -\alias{get_prior_string} -\title{Get Stan code for a \code{Prior}} -\usage{ -get_prior_string(object) -} -\arguments{ -\item{object}{\code{Prior} or list of \code{Prior} objects.} -} -\value{ -A string containing the Stan code sampling from specified distribution. -} -\description{ -Get Stan code for a \code{Prior} -} -\examples{ -psborrow2:::get_prior_string(prior_normal(0, 100)) -} diff --git a/man/get_results.Rd b/man/get_results.Rd index 20ed35d0..9c4b2e2d 100644 --- a/man/get_results.Rd +++ b/man/get_results.Rd @@ -12,6 +12,9 @@ get_results(object) \arguments{ \item{object}{\code{MCMCSimulationResults} object} } +\value{ +data.frame with simulation results. +} \description{ Get the results \code{data.frame} from \code{MCMCSimulationResults} objects. } diff --git a/man/half_cauchy_prior.Rd b/man/half_cauchy_prior.Rd index 268093b8..e05856ae 100644 --- a/man/half_cauchy_prior.Rd +++ b/man/half_cauchy_prior.Rd @@ -9,6 +9,11 @@ half_cauchy_prior(...) \arguments{ \item{...}{Deprecated arguments to \code{half_cauchy_prior()}.} } +\value{ +This function does not return a value. When called, it triggers an error +message indicating that \code{half_cauchy_prior()} is deprecated and that +\code{prior_half_cauchy()} should be used instead. +} \description{ Please use \code{prior_half_cauchy()} instead. } diff --git a/man/half_normal_prior.Rd b/man/half_normal_prior.Rd index f02ad58b..e60a41dd 100644 --- a/man/half_normal_prior.Rd +++ b/man/half_normal_prior.Rd @@ -9,6 +9,11 @@ half_normal_prior(...) \arguments{ \item{...}{Deprecated arguments to \code{half_normal_prior()}.} } +\value{ +This function does not return a value. When called, it triggers an error +message indicating that \code{half_normal_prior()} is deprecated and that +\code{prior_half_normal()} should be used instead. +} \description{ Please use \code{prior_half_normal()} instead. } diff --git a/man/logistic_bin_outcome.Rd b/man/logistic_bin_outcome.Rd index d08fab18..14c14e66 100644 --- a/man/logistic_bin_outcome.Rd +++ b/man/logistic_bin_outcome.Rd @@ -9,6 +9,11 @@ logistic_bin_outcome(...) \arguments{ \item{...}{Deprecated arguments to \code{logistic_bin_outcome}.} } +\value{ +This function does not return a value. When called, it triggers an error +message indicating that \code{logistic_bin_outcome()} is deprecated and that +\code{outcome_bin_logistic()} should be used instead. +} \description{ Please use \code{outcome_bin_logistic()} instead. } diff --git a/man/make_model_string_data.Rd b/man/make_model_string_data.Rd deleted file mode 100644 index c262890a..00000000 --- a/man/make_model_string_data.Rd +++ /dev/null @@ -1,29 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/make_model_string_data.R -\name{make_model_string_data} -\alias{make_model_string_data} -\title{Make model string of Stan's data block} -\usage{ -make_model_string_data(analysis_obj) -} -\arguments{ -\item{analysis_obj}{\code{Analysis}. Object of class \code{\link[=Analysis-class]{Analysis}} created by -\code{psborrow2:::.analysis_obj()}.} -} -\value{ -\code{glue} \code{character} containing the text for the data block. -} -\description{ -Create the Stan string encompassed by data \code{{}} -} -\examples{ -anls_obj <- psborrow2:::.analysis_obj( - data_matrix = example_matrix, - outcome = outcome_surv_exponential("time", "cnsr", prior_normal(0, 100)), - borrowing = borrowing_full("ext"), - treatment = treatment_details("trt", prior_normal(0, 100)) -) - -psborrow2:::make_model_string_data(anls_obj) - -} diff --git a/man/make_model_string_functions.Rd b/man/make_model_string_functions.Rd deleted file mode 100644 index 03b708f4..00000000 --- a/man/make_model_string_functions.Rd +++ /dev/null @@ -1,29 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/make_model_string_functions.R -\name{make_model_string_functions} -\alias{make_model_string_functions} -\title{Make model string of Stan's functions model bloc} -\usage{ -make_model_string_functions(analysis_obj) -} -\arguments{ -\item{analysis_obj}{\code{Analysis}. Object of class \code{\link[=Analysis-class]{Analysis}} created by -\code{psborrow2:::.analysis_obj()}.} -} -\value{ -\code{glue} \code{character} containing the text for the functions block. -} -\description{ -Create the Stan string encompassed by functions \code{{}} -} -\examples{ -anls_obj <- psborrow2:::.analysis_obj( - data_matrix = example_matrix, - outcome = outcome_surv_exponential("time", "cnsr", prior_normal(0, 100)), - borrowing = borrowing_full("ext"), - treatment = treatment_details("trt", prior_normal(0, 100)) -) - -psborrow2:::make_model_string_functions(anls_obj) - -} diff --git a/man/make_model_string_model.Rd b/man/make_model_string_model.Rd index b3a071a2..24b532e4 100644 --- a/man/make_model_string_model.Rd +++ b/man/make_model_string_model.Rd @@ -32,11 +32,25 @@ make_model_string_model(borrowing, outcome, analysis_obj) Create Stan Code for Model } \examples{ -anls_obj <- psborrow2:::.analysis_obj( - data_matrix = example_matrix, - outcome = outcome_surv_exponential("time", "cnsr", prior_normal(0, 100)), - borrowing = borrowing_full("ext"), - treatment = treatment_details("trt", prior_normal(0, 100)) -) +anls_obj <- create_analysis_obj( + data_matrix = example_matrix, + outcome = outcome_surv_exponential( + "time", + "cnsr", + baseline_prior = prior_normal(0, 1000) + ), + borrowing = borrowing_hierarchical_commensurate( + "ext", + prior_exponential(.001) + ), + treatment = treatment_details( + "trt", + prior_normal(0, 1000) + ), + covariates = add_covariates( + covariates = c("cov1", "cov2"), + priors = prior_normal(0, 1000) + ) + ) make_model_string_model(anls_obj@borrowing, anls_obj@outcome, anls_obj) } diff --git a/man/make_model_string_parameters.Rd b/man/make_model_string_parameters.Rd deleted file mode 100644 index 772fc041..00000000 --- a/man/make_model_string_parameters.Rd +++ /dev/null @@ -1,29 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/make_model_string_parameters.R -\name{make_model_string_parameters} -\alias{make_model_string_parameters} -\title{Make model string of Stan's parameters model block} -\usage{ -make_model_string_parameters(analysis_obj) -} -\arguments{ -\item{analysis_obj}{\code{Analysis}. Object of class \code{\link[=Analysis-class]{Analysis}} created by -\code{psborrow2:::.analysis_obj()}.} -} -\value{ -\code{glue} \code{character} containing the Stan code for the functions block. -} -\description{ -Create the Stan string encompassed by parameters \code{{}} -} -\examples{ -anls_obj <- psborrow2:::.analysis_obj( - data_matrix = example_matrix, - outcome = outcome_surv_exponential("time", "cnsr", prior_normal(0, 100)), - borrowing = borrowing_full("ext"), - treatment = treatment_details("trt", prior_normal(0, 100)) -) - -psborrow2:::make_model_string_parameters(anls_obj) - -} diff --git a/man/make_model_string_transf_param.Rd b/man/make_model_string_transf_param.Rd deleted file mode 100644 index c65a2b4b..00000000 --- a/man/make_model_string_transf_param.Rd +++ /dev/null @@ -1,29 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/make_model_string_transf_params.R -\name{make_model_string_transf_param} -\alias{make_model_string_transf_param} -\title{Make model string of Stan's transformed parameters model block} -\usage{ -make_model_string_transf_param(analysis_obj) -} -\arguments{ -\item{analysis_obj}{\code{Analysis}. Object of class \code{\link[=Analysis-class]{Analysis}} created by -\code{psborrow2:::.analysis_obj()}.} -} -\value{ -\code{glue} \code{character} containing the Stan code for the functions block. -} -\description{ -Create the Stan string encompassed by transformed parameters \code{{}} -} -\examples{ -anls_obj <- psborrow2:::.analysis_obj( - data_matrix = example_matrix, - outcome = outcome_surv_exponential("time", "cnsr", prior_normal(0, 100)), - borrowing = borrowing_full("ext"), - treatment = treatment_details("trt", prior_normal(0, 100)) -) - -psborrow2:::make_model_string_transf_param(anls_obj) - -} diff --git a/man/normal_prior.Rd b/man/normal_prior.Rd index 4a6c1e2a..3438fc72 100644 --- a/man/normal_prior.Rd +++ b/man/normal_prior.Rd @@ -9,6 +9,11 @@ normal_prior(...) \arguments{ \item{...}{Deprecated arguments to \code{normal_prior()}.} } +\value{ +This function does not return a value. When called, it triggers an error +message indicating that \code{normal_prior()} is deprecated and that +\code{prior_normal()} should be used instead. +} \description{ Please use \code{prior_normal()} instead. } diff --git a/man/parse_constraint.Rd b/man/parse_constraint.Rd deleted file mode 100644 index 5e24f82e..00000000 --- a/man/parse_constraint.Rd +++ /dev/null @@ -1,21 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/helpers.R -\name{parse_constraint} -\alias{parse_constraint} -\title{Extract Upper and Lower Bounds from a Prior object} -\usage{ -parse_constraint(object) -} -\arguments{ -\item{object}{\code{Prior} Object of class Prior} -} -\value{ -A list with upper and lower bounds. Any unspecified bounds are set to \code{-Inf} or \code{Inf}. -} -\description{ -Extract Upper and Lower Bounds from a Prior object -} -\examples{ -np <- prior_normal(0, 100) -psborrow2:::parse_constraint(np) -} diff --git a/man/plot.Rd b/man/plot.Rd index 51d02876..219c7449 100644 --- a/man/plot.Rd +++ b/man/plot.Rd @@ -63,6 +63,9 @@ \item{...}{Optional arguments for plotting.} } +\value{ +No return value, this function generates a plot in the current graphics device. +} \description{ Plot prior distributions as densities. Continuous distributions are plotted as curves and discrete distributions as bar plots. diff --git a/man/plot_pdf.Rd b/man/plot_pdf.Rd index 62419daa..4da9e709 100644 --- a/man/plot_pdf.Rd +++ b/man/plot_pdf.Rd @@ -15,6 +15,9 @@ plot_pdf(x, y, ...) Plots the density values as a curve with the lower vertical limit set to 0.} } +\value{ +No return value, this function generates a plot in the current graphics device. +} \description{ Plot Probability Density Function Values } diff --git a/man/plot_pmf.Rd b/man/plot_pmf.Rd index c7b8dcda..2c1149f7 100644 --- a/man/plot_pmf.Rd +++ b/man/plot_pmf.Rd @@ -19,6 +19,9 @@ plot_pmf(x, y, ..., col = "grey", add = FALSE) Plots the probability values as a barplot.} } +\value{ +No return value, this function generates a plot in the current graphics device. +} \description{ Plot Probability Mass Function Values } diff --git a/man/poisson_prior.Rd b/man/poisson_prior.Rd index debc9ada..d86a4cd3 100644 --- a/man/poisson_prior.Rd +++ b/man/poisson_prior.Rd @@ -9,6 +9,11 @@ poisson_prior(...) \arguments{ \item{...}{Deprecated arguments to \code{poisson_prior()}.} } +\value{ +This function does not return a value. When called, it triggers an error +message indicating that \code{poisson_prior()} is deprecated and that +\code{prior_poisson()} should be used instead. +} \description{ Please use \code{prior_poisson()} instead. } diff --git a/man/psborrow2-package.Rd b/man/psborrow2-package.Rd index c11291b4..d6988437 100644 --- a/man/psborrow2-package.Rd +++ b/man/psborrow2-package.Rd @@ -6,7 +6,7 @@ \alias{psborrow2-package} \title{psborrow2: Bayesian Dynamic Borrowing Analysis and Simulation} \description{ -Bayesian dynamic borrowing is an approach to incorporating external data to supplement a randomized, controlled trial analysis in which external data are incorporated in a dynamic way (e.g., based on similarity of outcomes); see Viele et al (2013) \doi{10.1002/pst.1589} for an overview. This package implements the hierarchical commensurate prior approach to dynamic borrowing as described in Hobbes et al (2011) \doi{10.1111/j.1541-0420.2011.01564.x}. There are three main functionalities. First, 'psborrow2' provides a user-friendly interface for applying dynamic borrowing on the study results handles the MCMC sampling on behalf of the user. Second, 'psborrow2' provides a simulation framework to compare different borrowing parameters (e.g. full borrowing, no borrowing, dynamic borrowing) and other trial and borrowing characteristics (e.g. sample size, covariates) in a unified way. Third, 'psborrow2' provides a set of functions to generate data for simulation studies, and also allows the user to specify their own data generation process. +Bayesian dynamic borrowing is an approach to incorporating external data to supplement a randomized, controlled trial analysis in which external data are incorporated in a dynamic way (e.g., based on similarity of outcomes); see Viele 2013 \doi{10.1002/pst.1589} for an overview. This package implements the hierarchical commensurate prior approach to dynamic borrowing as described in Hobbes 2011 \doi{10.1111/j.1541-0420.2011.01564.x}. There are three main functionalities. First, 'psborrow2' provides a user-friendly interface for applying dynamic borrowing on the study results handles the Markov Chain Monte Carlo sampling on behalf of the user. Second, 'psborrow2' provides a simulation framework to compare different borrowing parameters (e.g. full borrowing, no borrowing, dynamic borrowing) and other trial and borrowing characteristics (e.g. sample size, covariates) in a unified way. Third, 'psborrow2' provides a set of functions to generate data for simulation studies, and also allows the user to specify their own data generation process. This package is designed to use the sampling functions from 'cmdstanr' which can be installed from \url{https://mc-stan.org/r-packages/}. } \seealso{ Useful links: diff --git a/man/show_guide.Rd b/man/show_guide.Rd index adc04e24..cfee2fb3 100644 --- a/man/show_guide.Rd +++ b/man/show_guide.Rd @@ -12,6 +12,9 @@ show_guide(object) \arguments{ \item{object}{\code{Simulation} object} } +\value{ +A \code{data.frame} showing all simulation scenarios. +} \description{ Show the guide in \code{Simulation} objects. } diff --git a/man/sim_borrowing_list.Rd b/man/sim_borrowing_list.Rd index 00c2e906..e23a840c 100644 --- a/man/sim_borrowing_list.Rd +++ b/man/sim_borrowing_list.Rd @@ -10,6 +10,9 @@ sim_borrowing_list(borrowing_list) \item{borrowing_list}{named list of objects of class \code{Borrowing} created by \code{borrowing_full()}, \code{borrowing_none()}, or \code{borrowing_hierarchical_commensurate()}.} } +\value{ +Object of class \code{\link[=SimBorrowingList-class]{SimBorrowingList}}. +} \description{ A function for defining which borrowing scenarios should be evaluated as part of a simulation study. @@ -33,7 +36,7 @@ borrow_scenarios <- sim_borrowing_list( } \seealso{ -Other simulation classes: +Other simulation classes: \code{\link{sim_covariate_list}()}, \code{\link{sim_data_list}()}, \code{\link{sim_outcome_list}()}, diff --git a/man/sim_covariate_list.Rd b/man/sim_covariate_list.Rd index 06b30d2b..e68dac9a 100644 --- a/man/sim_covariate_list.Rd +++ b/man/sim_covariate_list.Rd @@ -10,6 +10,9 @@ sim_covariate_list(covariate_list) \item{covariate_list}{named list of objects of class \code{Covariate} created by \code{add_covariates()}.} } +\value{ +Object of class \code{\link[=SimCovariateList-class]{SimCovariateList}}. +} \description{ A function for defining which covariate adjustment scenarios should be evaluated as part of a simulation study. diff --git a/man/sim_data_list.Rd b/man/sim_data_list.Rd index b96857de..2776a259 100644 --- a/man/sim_data_list.Rd +++ b/man/sim_data_list.Rd @@ -25,6 +25,9 @@ A drift >1 means the external arm experiences greater effects.} \item{index}{character. The column in \code{guide} that corresponds to the index column.} } +\value{ +Object of class \code{\link[=SimDataList-class]{SimDataList}}. +} \description{ A function for defining generated data for use as part of a simulation study. @@ -107,6 +110,7 @@ sdl <- sim_data_list( drift = "driftOR", index = "ind" ) + } \seealso{ Other simulation classes: diff --git a/man/sim_outcome_list.Rd b/man/sim_outcome_list.Rd index fe05ed96..3a8c5575 100644 --- a/man/sim_outcome_list.Rd +++ b/man/sim_outcome_list.Rd @@ -10,6 +10,9 @@ sim_outcome_list(outcome_list) \item{outcome_list}{named list of objects of class \code{Outcome} created by \code{outcome_details()}.} } +\value{ +Object of class \code{\link[=SimOutcomeList-class]{SimOutcomeList}}. +} \description{ A function for defining which outcome scenarios should be evaluated as part of a simulation study. diff --git a/man/sim_treatment_list.Rd b/man/sim_treatment_list.Rd index 152f48cc..c70b8ee8 100644 --- a/man/sim_treatment_list.Rd +++ b/man/sim_treatment_list.Rd @@ -10,6 +10,9 @@ sim_treatment_list(treatment_list) \item{treatment_list}{named list of objects of class \code{Treatment} created by \code{treatment_details()}.} } +\value{ +Object of class \code{\link[=SimTreatmentList-class]{SimTreatmentList}}. +} \description{ A function for defining which treatment scenarios should be evaluated as part of a simulation study. diff --git a/man/weib_ph_surv_dist.Rd b/man/weib_ph_surv_dist.Rd index 72c211cc..c1c8fa58 100644 --- a/man/weib_ph_surv_dist.Rd +++ b/man/weib_ph_surv_dist.Rd @@ -9,6 +9,11 @@ weib_ph_surv_dist(...) \arguments{ \item{...}{Deprecated arguments to \code{weib_ph_surv_dist()}.} } +\value{ +This function does not return a value. When called, it triggers an error +message indicating that \code{weib_ph_surv_dist()} is deprecated and that +\code{outcome_surv_weibull_ph()} should be used instead. +} \description{ Please use \code{outcome_surv_weibull_ph()} instead. } diff --git a/tests/testthat/test-create_simulation_obj.R b/tests/testthat/test-create_simulation_obj.R index 32984361..e33f5fe7 100644 --- a/tests/testthat/test-create_simulation_obj.R +++ b/tests/testthat/test-create_simulation_obj.R @@ -378,3 +378,42 @@ test_that("`create_simulation_obj()` does not create deep copies", { } } }) + +test_that("`show_guide()` gives correct output", { + + valid_simulation_obj <- create_simulation_obj( + data_matrix_list = valid_data_list, + covariate = valid_covariate, + outcome = valid_outcome, + borrowing = valid_borrowing, + treatment = valid_treatment + ) + + guide <- show_guide(valid_simulation_obj) + + expect_class( + guide, + "data.frame" + ) + + expect_equal( + NROW(guide), + 8 + ) + + expect_equal( + NCOL(guide), + 8 + ) + + expect_equal( + 1, + NROW(guide[ + guide$true_hr == 0.6 & + guide$drift_hr == 1.0 & + guide$borrowing_scenario == "bdb" & + guide$covariate_scenario == "cov1" & + guide$treatment_scenario == "standard_tx", + ]) + ) +}) \ No newline at end of file diff --git a/vignettes/original/_psborrow2.Rmd b/vignettes/original/_psborrow2.Rmd index 3121e6df..bb35a97c 100644 --- a/vignettes/original/_psborrow2.Rmd +++ b/vignettes/original/_psborrow2.Rmd @@ -91,4 +91,13 @@ how to generate data for simulation studies: [https://genentech.github.io/psborr Please refer to [https://genentech.github.io/psborrow2/articles/index.html](https://genentech.github.io/psborrow2/articles/index.html) for additional articles on `psborrow2` functionality. +## Installing `cmdstanr` + +`cmdstanr` is highly recommended for use with `psborrow2`. To install `cmdstanr`, follow the instructions outlined by the [`cmdstanr` documentation](https://mc-stan.org/cmdstanr/) or use: + +``` +install.packages("cmdstanr", repos = c("https://mc-stan.org/r-packages/", getOption("repos"))) +``` + + ## References diff --git a/vignettes/psborrow2.Rmd b/vignettes/psborrow2.Rmd index e4a25a77..d5e52d40 100644 --- a/vignettes/psborrow2.Rmd +++ b/vignettes/psborrow2.Rmd @@ -85,4 +85,13 @@ how to generate data for simulation studies: [https://genentech.github.io/psborr Please refer to [https://genentech.github.io/psborrow2/articles/index.html](https://genentech.github.io/psborrow2/articles/index.html) for additional articles on `psborrow2` functionality. +## Installing `cmdstanr` + +`cmdstanr` is highly recommended for use with `psborrow2`. To install `cmdstanr`, follow the instructions outlined by the [`cmdstanr` documentation](https://mc-stan.org/cmdstanr/) or use: + +``` +install.packages("cmdstanr", repos = c("https://mc-stan.org/r-packages/", getOption("repos"))) +``` + + ## References