Skip to contents

Developing scdrake

Document generated: 2025-08-27 15:59:17 UTC+0000

Source: vignettes/scdrake_development.Rmd
scdrake_development.Rmd

The purpose of this vignette is to easier the process of development of the scdrake pipeline and package. There are two main differences in developing scdrake package - whether the change is only in function and package constitution, with some additional changes in packages versions, or if there is major package function change. Basically, all the scdrake package development runs through devtools package.

Please, firstly check the principles of contributing described in CONTRIBUTING.md.

Smaller changes

  • bug fixing, minor function changes, adding new function/module

Preparation

Firstly, from Github download the scdrake package.

git clone https://github.com/bioinfocz/scdrake

If the focus is primary on changing function, or package arrangement, the easiest way is to pull and run the docker image, in same way as is described in vignette("scdrake_docker"), see details there. Pwd is in the scdrake folder.

docker run -d \
  -v $(pwd):/home/rstudio/scdrake_projects \
  -p 8787:8787 \
  -e USERID=$(id -u) \
  -e GROUPID=$(id -g) \
  -e PASSWORD=1234 \
  DOCKER_IMAGE_STABLE

In command line, create new Github branch and switch there, and also push the new branch on Github. Then in the Docker Rstudio create a new directory with a new scdrake project and switch there.

git checkout -b your_branch
git push -u origin your_branch

Changes in functions

In such prepared Docker Rstudio, make a changes in the specific function and run

devtools::load_all(path = "")

(path where the core scdrake package functions are located). And then you can just easily run,

scdrake::run_single_sample() 
scdrake::run_integration()

as they are normally used (the pipeline depends where the changes where made).

If running in real reproducible mode

, which is running though _drake_single_sample.R or _drake_integration.R file, then need to set SCDRAKE_PKG_DIR=“/home/rstudio/scdrake_source” (path to source of scdrake, usually this path)

New functions: creating new function need additional tweaking before load_all and scdrake::run.

(New) Functions in R/ folder need to be documented using roxygen2 standards, documentation .Rd files are generating using devtools::document() into man/ folder. More info about Roxygen2. The new functions need to be added to _pkgdown.yml file. Beware, it must be done where the core scdrake functions are located, not there where is the testing project with data

If for the new function were used new packages, All installed packages need to be exported into renv lockfile (but dont use renv to install packages).

Major docker changes

For developing scdrake, meaning increasing R version, the easiest way is to create your own Docker image. Scdrake is build on Bioconductor Docker images. Again, firstly download the package from GitHub, and create new branch and switch there. The main file here we are interested at is called deps.Dockerfile In the deps.Dockerfile file set BIOCONDUCTOR_VERSION variable on the requested value (check with the Bioconductor Docker that the requested version is available. Check that the packages version in deps.Dockerfile are complementary with the Bioconductor version (especially important for yq,renv, …). If needed, change the recorded versions. Create the Docker image, script showing how to create Docker for scdrake is in commented lines in the beginning of the deps.Dockerfile:

docker buildx build --progress plain --platform linux/amd64 --build-arg R_PKG_INSTALL_NCPUS=8 --build-arg R_PKG_INSTALL_MAKE_NCPUS=4 
-t your_docker_name/scdrake:tag -f deps.Dockerfile .

This will create Docker image and install all packages mentioned in DESCRIPTION file. Then you can use Rstudio Server classically by docker run -d -e USERID=$(id -u) -e GROUPID=$(id -g) -e PASSWORD=1234 -p <host port>:8787 -v $(pwd):/home/$(whoami)/scdrake scdrake:<tag> fo scdrake development.

If new function are created, check the ###Function changes part of this manual.

Save all package changes to lockfile. Then you need to create new Docker image - now with Dockerfile, where you set for scdrake build_vignettes = FALSE. Else you can not create documents - it supposed that scdrake is already in the Docker.

Merging branches with main scdrake branch

Its useful and highly recommended to test the pipeline and the changes scdrake test function, similar as:

docker exec -it -u rstudio -w /home/rstudio/scdrake <container name> \
  r --interactive -L /usr/local/lib/R/site-library -t dev/run_tests.R \
  --no-test-single_sample-full-sct \
  --output-dir /home/rstudio/shared/scdrake_run_tests_20230425-1.4.1_dev-bioc3.15-docker \
  --output-dir-pipeline-tests /home/rstudio/shared/scdrake_run_tests_20230425-1.4.1_dev-bioc3.15-docker/pipeline_outputs

*in bash. You can also run the run_tests.R in Docker Rstudio.

Please, check the structure of added code, reindent/reformat the code or code selection for better clarity and readability for other scdrake users.

All changes, even typos and minor bugs, need to be documented. As the first step before creating documentation and deploying version, always do devtools::document() (to make sure all the function are documented). Vignettes are best made using pkgdown::build_articles() into docs/articles. The whole documentation site is made by pkgdown::build_site(), into docs/, in docs/index.html is then the main page. If new vignette is created, firstly incorporate the vignette into vignettes/_vignette_signpost.Rmd.

Use renv::snapshot() to create new lock.file.

Change the version in DESCRIPTION. Also if new major packages were added, write them into DESCRIPTION too.

Then write changes into README.Rmd and render into README.md rmarkdown::render("README.Rmd")

Write news into NEWS.md

If there was changes in creating new Rmd files or config files, its important to update files in in /tests/_snaps. Here is an illustration how to do it for one test:

testthat::test_file("tests/testthat/test-project.R")
testthat::snapshot_review()
testthat::snapshot_accept()

With all this, create issue on Github and link the branch there. Upload changes in branch into Github.

git add.
git commit -m "message"
git push -u origin your_branch

Assign people from scdrake development/author team for checking the changes.

If all went well, you are prepared for PR of the branch!

Merging of version is allowed when all the checks and test will pass.

After passing wait for approval. Then you can merge. The vignettes will be automatically prepared in gh-pages/dev. To apply the changes in vignettes for pages, you must prepare release and release tag. Release and release tags are done manually. Fill the information and apply, then Github pages will be updated too.