Thank you for helping improve dampack. This guide covers how to report problems, how to propose changes, and the conventions the package follows. It applies to DARTH members and outside contributors alike.
By participating, you agree to follow the Code of Conduct.
Reporting a bug or asking for a feature
- Search the open issues first.
- For a bug, open an issue with the Bug report template and include a minimal reproducible example. The reprex package makes this easy:
reprex::reprex()runs your code in a clean session and formats the output for GitHub. Please includesessionInfo()orsessioninfo::session_info(). - For a new feature, open an issue with the Feature request template before writing code, so the design can be discussed. Explain the decision-analytic use case: what analysis you are trying to do and what output you expect.
Branches and pull requests
main is the only long-lived branch. It must always pass R CMD check.
- Open (or pick) an issue for the change.
- Create a short-lived branch from
main, named after the issue:<issue number>-<short-description>, for example203-currency-propagation. - Make focused commits. One pull request (PR) should address one issue.
- Open a PR into
mainand fill in the PR template. UseCloses #<issue>in the description so the issue closes when the PR is merged intomain, not before. - A PR is merged after CI passes and at least one other DARTH member approves it. The branch is deleted automatically after merging.
Do not push directly to main, and do not keep long-running integration branches; they are how the package’s history diverged before v1.1.0.
Definition of done
Every PR that changes package code includes:
-
Tests. A bug fix comes with a regression test that fails before the fix and passes after. A new function or argument comes with tests of its results, not only that it runs. Use
set.seed()in any test that draws random numbers. -
Documentation. roxygen2 comments updated, and
devtools::document()run soman/andNAMESPACEare current. New exported functions need@examplesthat run. -
A NEWS entry. One bullet in
NEWS.mdunder the development version, ending with the issue number, for example(#203). Mark behavior changes and breaking changes explicitly. -
A clean check.
devtools::check()passes locally with no errors or warnings.
Running the checks locally
# install the development dependencies once
install.packages(c("devtools", "lintr", "covr", "pkgdown"))
devtools::load_all() # load the package from source
devtools::document() # regenerate man/ and NAMESPACE from roxygen comments
devtools::test() # run the tests
devtools::check() # full R CMD check, as CI and CRAN run it
lintr::lint_package() # style checks (also run by CI)
covr::report() # browse test coverage line by line
pkgdown::build_site() # preview the website locally (output in docs/, not committed)Coding conventions
Style
- Follow the tidyverse style guide, with lines of up to 120 characters. The
.lintrfile defines the exact rules, and CI runslintron every PR. - Use implicit returns; reserve
return()for early exits. - Use
seq_len(n)orseq_along(x)instead of1:nor1:length(x), which misbehave whennis 0. - Refer to columns that hold strategy names with
df[[name]]ordf[, name, drop = FALSE], neverdf$nameor a formula, because strategy names may contain spaces and other characters.
Naming objects inside the package (DARTH coding framework)
Internal objects follow the DARTH naming convention <data type>_<variable type>_<description>, from Alarid-Escudero et al. (2019), “A need for change! A coding framework for improving transparency in decision modeling”, PharmacoEconomics 37(11):1329-1339, doi:10.1007/s40273-019-00837-x.
| Data type prefix | Variable type prefix | ||
|---|---|---|---|
| (none) | scalar | n |
number |
v |
vector | p |
probability |
m |
matrix | r |
rate |
a |
array | u |
utility |
df |
data frame | c |
cost |
dtb |
data table | hr |
hazard ratio |
l |
list | q |
QALYs |
Examples: df_cea, v_wtp, m_nmb, l_psa, n_sim. Either prefix is left out when it does not apply. Note that n_ means “number”, not “scalar”: scalars carry no data type prefix.
A prefix must stay true: an object named m_ must still be a matrix after subsetting (use drop = FALSE).
Exported function names and arguments
Exported function and argument names are part of the public API that users’ scripts depend on. Do not rename them in a minor release. A rename goes through soft deprecation with the lifecycle package: keep the old name working, warn with lifecycle::deprecate_soft(), record it in NEWS.md, and remove it only in the next major version.
New exported functions start with a verb (calculate_, make_, plot_, …), and new arguments follow the names already used elsewhere in the package (psa, wtp, currency, effect_units, txtsize, col).
Files and tests
- Source files live in
R/, one family of functions per file. - Each source file has a matching test file in
tests/testthat/. Existing test files are namedtest_<source file>.R; follow that pattern until the test suite is migrated to thetest-<source file>.Rform thatusethis::use_test()creates. - Example datasets are documented in
R/data_<dataset name>.R.
