A single entry point that reads a delimited or Excel file, fits the requested Beta-Danish model or models, assembles the results into tidy tables, and optionally writes those tables and the diagnostic figures to a directory.
Usage
bd_analyze_csv(
file,
time_col = NULL,
status_col = NULL,
covariates = NULL,
cause_col = NULL,
analysis = c("univariate", "aft", "cure", "competing"),
model = c("both", "BD", "ED"),
compare = TRUE,
bayes = FALSE,
cure_formula = NULL,
cure_type = c("mixture", "promotion"),
competing_submodel = FALSE,
output_dir = NULL,
n_starts = 10,
seed = NULL,
quiet = FALSE
)
# S3 method for class 'bd_analysis'
print(x, ...)
# S3 method for class 'bd_analysis'
summary(object, ...)
# S3 method for class 'summary.bd_analysis'
print(x, ...)
# S3 method for class 'bd_analysis'
plot(x, type = "survival", ...)Arguments
- file
Path to a `.csv`, `.txt`, `.tsv`, `.xls` or `.xlsx` file.
- time_col, status_col, cause_col
Column names, passed to [read_survival_data()]. `NULL` means guess.
- covariates
Covariate columns to use. `NULL` means none for `analysis = "univariate"`, and every non-response column for the regression analyses.
- analysis
Which analysis to run: `"univariate"` (default), `"aft"`, `"cure"` or `"competing"`.
- model
For `analysis = "univariate"`, whether to fit the four-parameter Beta-Danish (`"BD"`), the three-parameter Exponentiated Danish submodel (`"ED"`), or `"both"` (default) and compare them.
- compare
Logical; benchmark against standard lifetime distributions via [compare_distributions()]. Requires the `flexsurv` package; skipped with a recorded note if it is absent. Default `TRUE`.
- bayes
Logical; also run [bayes_betadanish()]. Requires `MCMCpack`. Default `FALSE`, since it is slow.
- cure_formula
Right-hand-side formula for the cure fraction when `analysis = "cure"`, for example `~ group`. Defaults to the retained covariates.
- cure_type
`"mixture"` (default) or `"promotion"`.
- competing_submodel
Logical; for `analysis = "competing"`, use the three-parameter Exponentiated Danish kernel for every cause. This is more stable for small or weakly identified samples. Default `FALSE`.
- output_dir
Directory to write results to. `NULL` (default) writes nothing. The directory is created if it does not exist.
- n_starts
Number of random starting points for each fit.
- seed
Optional integer seed, for reproducible multi-start fitting.
- quiet
Logical; suppress progress messages.
- x
A `"bd_analysis"` object.
- ...
Ignored.
- object
A `"bd_analysis"` object.
- type
Plot type passed to [plot.betadanish()].
Value
An object of class `"bd_analysis"`: a list with `call`, `analysis`, `data`, `data_report`, `fits`, `tables`, `extras`, `warnings`, `failures`, `output_dir` and `files`. It has `print`, `summary` and `plot` methods.
Details
Nothing is written to disk unless `output_dir` is supplied. When it is, the function writes one CSV per result table and a PNG per diagnostic figure, and records the paths in the `files` component.
Each fit is attempted independently. If one fails, the message is recorded in `failures` and the remaining analyses still run, so a difficult four-parameter fit does not cost you the submodel results alongside it.
Warnings raised during fitting are captured in `warnings` rather than printed as they occur. This is where the identifiability diagnostics appear, so it is worth reading: a four-parameter fit that converges cleanly but sits on the `b = 1` ridge will say so there.
For `analysis = "univariate"` with `model = "both"`, a likelihood ratio test of the submodel is included. Read it alongside those diagnostics: see the Identifiability section of [fit_betadanish()].
See also
[read_survival_data()], [bd_csv_template()], [fit_betadanish()], [fit_bd_aft()], [fit_bd_cure()], [fit_bd_competing()]
Examples
f <- system.file("extdata", "censored_sample.csv", package = "BetaDanish")
# Submodel only, no benchmarking: fast enough for an example
res <- bd_analyze_csv(f, analysis = "univariate", model = "ED",
compare = FALSE, n_starts = 3, seed = 1, quiet = TRUE)
res
#>
#> BetaDanish CSV analysis
#> -----------------------
#> Analysis: univariate
#> Observations: 91 (events: 69, censored: 24.2%)
#> Models fitted: ED
#>
#> model n npar logLik AIC BIC
#> ED 91 3 -476.8013 959.6026 967.1352
#>
#> Warnings: 1 (see $warnings)
#>
res$tables$information_criteria
#> model n npar logLik AIC BIC
#> 1 ED 91 3 -476.8013 959.6026 967.1352
# \donttest{
# Both models, with tables and figures written to a temporary directory
out <- file.path(tempdir(), "bd_results")
res2 <- bd_analyze_csv(f, model = "both", compare = FALSE,
output_dir = out, n_starts = 5, seed = 1)
#> Using 'time' as the time column.
#> Using 'status' as the event indicator (1 = event, 0 = censored).
#> Not retained: group. Pass covar_cols to keep specific columns, or covar_cols = "all".
#> Times appear recorded on a grid of 1. For coarsely rounded data the point-density likelihood understates uncertainty.
#> Read 91 row(s); 69 event(s); 24.2% censored.
#> Fitting the four-parameter Beta-Danish model.
#> Fitting the three-parameter Exponentiated Danish submodel.
#> Likelihood Ratio Test (a = 1 vs a != 1)
#>
#> Model LogLik Chisq Df Pr(>Chisq)
#> 1 Submodel (3-param) -476.8013 NA NA NA
#> 2 Full Model (4-param) -476.8225 0 1 1
#> Wrote 10 file(s) to /tmp/Rtmpwgv1YV/bd_results
#> Completed with 5 model warning(s); see $warnings. Identifiability diagnostics appear here.
basename(res2$files)
#> [1] "likelihood_ratio_test.csv" "estimates.csv"
#> [3] "information_criteria.csv" "goodness_of_fit.csv"
#> [5] "data_report.csv" "survival.png"
#> [7] "hazard.png" "density.png"
#> [9] "pp.png" "qq.png"
# AFT regression, covariates taken from the file
g <- system.file("extdata", "covariate_sample.csv", package = "BetaDanish")
res3 <- bd_analyze_csv(g, analysis = "aft", covariates = c("age", "thickness"),
n_starts = 5, seed = 1)
#> Using 'time' as the time column.
#> Using 'event' as the event indicator (1 = event, 0 = censored).
#> Not retained: ulcer. Pass covar_cols to keep specific columns, or covar_cols = "all".
#> Times appear recorded on a grid of 1. For coarsely rounded data the point-density likelihood understates uncertainty.
#> Read 205 row(s); 57 event(s); 72.2% censored.
#> Fitting the AFT model: age + thickness
#> Completed with 35 model warning(s); see $warnings. Identifiability diagnostics appear here.
#> Completed with 1 recorded failure(s); see $failures.
summary(res3)
#>
#> BetaDanish CSV analysis
#> -----------------------
#> Analysis: aft
#> Observations: 205 (events: 57, censored: 72.2%)
#> Covariates: age, thickness
#> Models fitted: none
#>
#> Warnings: 35 (see $warnings)
#>
#> Failures: 1 (see $failures)
#>
#> -- data report --
#> file
#> /home/runner/work/_temp/Library/BetaDanish/extdata/covariate_sample.csv
#> time_col status_col rows_read rows_kept n_events censoring_prop covariates
#> time event 205 205 57 0.7219512 age; thickness
#> grid_step
#> 1
#>
#> -- model warnings --
#> fit_bd_aft: Parameters a, b, c and k must be strictly positive; NaN returned for 205 element(s).
#> fit_bd_aft: Parameters a, b, c and k must be strictly positive; NaN returned for 204 element(s).
#> fit_bd_aft: Parameters a, b, c and k must be strictly positive; NaN returned for 198 element(s).
#> fit_bd_aft: Parameters a, b, c and k must be strictly positive; NaN returned for 1 element(s).
#> fit_bd_aft: Parameters a, b, c and k must be strictly positive; NaN returned for 205 element(s).
#> fit_bd_aft: Parameters a, b, c and k must be strictly positive; NaN returned for 205 element(s).
#> fit_bd_aft: Parameters a, b, c and k must be strictly positive; NaN returned for 205 element(s).
#> fit_bd_aft: Parameters a, b, c and k must be strictly positive; NaN returned for 201 element(s).
#> fit_bd_aft: Parameters a, b, c and k must be strictly positive; NaN returned for 6 element(s).
#> fit_bd_aft: Parameters a, b, c and k must be strictly positive; NaN returned for 203 element(s).
#> fit_bd_aft: Parameters a, b, c and k must be strictly positive; NaN returned for 34 element(s).
#> fit_bd_aft: Parameters a, b, c and k must be strictly positive; NaN returned for 205 element(s).
#> fit_bd_aft: Parameters a, b, c and k must be strictly positive; NaN returned for 205 element(s).
#> fit_bd_aft: Parameters a, b, c and k must be strictly positive; NaN returned for 205 element(s).
#> fit_bd_aft: Parameters a, b, c and k must be strictly positive; NaN returned for 200 element(s).
#> fit_bd_aft: Parameters a, b, c and k must be strictly positive; NaN returned for 2 element(s).
#> fit_bd_aft: Parameters a, b, c and k must be strictly positive; NaN returned for 205 element(s).
#> fit_bd_aft: Parameters a, b, c and k must be strictly positive; NaN returned for 204 element(s).
#> fit_bd_aft: Parameters a, b, c and k must be strictly positive; NaN returned for 118 element(s).
#> fit_bd_aft: Parameters a, b, c and k must be strictly positive; NaN returned for 202 element(s).
#> fit_bd_aft: Parameters a, b, c and k must be strictly positive; NaN returned for 18 element(s).
#> fit_bd_aft: Parameters a, b, c and k must be strictly positive; NaN returned for 205 element(s).
#> fit_bd_aft: Parameters a, b, c and k must be strictly positive; NaN returned for 205 element(s).
#> fit_bd_aft: Parameters a, b, c and k must be strictly positive; NaN returned for 205 element(s).
#> fit_bd_aft: Parameters a, b, c and k must be strictly positive; NaN returned for 204 element(s).
#> fit_bd_aft: Parameters a, b, c and k must be strictly positive; NaN returned for 159 element(s).
#> fit_bd_aft: Parameters a, b, c and k must be strictly positive; NaN returned for 202 element(s).
#> fit_bd_aft: Parameters a, b, c and k must be strictly positive; NaN returned for 19 element(s).
#> fit_bd_aft: Parameters a, b, c and k must be strictly positive; NaN returned for 201 element(s).
#> fit_bd_aft: Parameters a, b, c and k must be strictly positive; NaN returned for 14 element(s).
#> fit_bd_aft: Parameters a, b, c and k must be strictly positive; NaN returned for 205 element(s).
#> fit_bd_aft: Parameters a, b, c and k must be strictly positive; NaN returned for 205 element(s).
#> fit_bd_aft: Parameters a, b, c and k must be strictly positive; NaN returned for 204 element(s).
#> fit_bd_aft: Parameters a, b, c and k must be strictly positive; NaN returned for 194 element(s).
#> fit_bd_aft: Parameters a, b, c and k must be strictly positive; NaN returned for 150 element(s).
#>
#> -- failures --
#> fit_bd_aft: AFT optimization failed to converge.
#>
# }