diff --git a/.github/workflows/check-bioc.yml b/.github/workflows/check-bioc.yml new file mode 100644 index 0000000..b02c9e8 --- /dev/null +++ b/.github/workflows/check-bioc.yml @@ -0,0 +1,338 @@ +## Read more about GitHub actions the features of this GitHub Actions workflow +## at https://lcolladotor.github.io/biocthis/articles/biocthis.html#use_bioc_github_action +## +## For more details, check the biocthis developer notes vignette at +## https://lcolladotor.github.io/biocthis/articles/biocthis_dev_notes.html +## +## You can add this workflow to other packages using: +## > biocthis::use_bioc_github_action() +## +## Using GitHub Actions exposes you to many details about how R packages are +## compiled and installed in several operating system.s +### If you need help, please follow the steps listed at +## https://github.com/r-lib/actions#where-to-find-help +## +## If you found an issue specific to biocthis's GHA workflow, please report it +## with the information that will make it easier for others to help you. +## Thank you! + +## Acronyms: +## * GHA: GitHub Action +## * OS: operating system + +on: + push: + pull_request: + +name: R-CMD-check-bioc + +## These environment variables control whether to run GHA code later on that is +## specific to testthat, covr, and pkgdown. +## +## If you need to clear the cache of packages, update the number inside +## cache-version as discussed at https://github.com/r-lib/actions/issues/86. +## Note that you can always run a GHA test without the cache by using the word +## "/nocache" in the commit message. +env: + has_testthat: 'false' + run_covr: 'false' + run_pkgdown: 'false' + has_RUnit: 'false' + cache-version: 'cache-v1' + run_docker: 'false' + +jobs: + build-check: + runs-on: ${{ matrix.config.os }} + name: ${{ matrix.config.os }} (${{ matrix.config.r }}) + container: ${{ matrix.config.cont }} + ## Environment variables unique to this job. + + strategy: + fail-fast: false + matrix: + config: + - { os: ubuntu-latest, r: '4.3', bioc: '3.17', cont: "bioconductor/bioconductor_docker:RELEASE_3_17", rspm: "https://packagemanager.rstudio.com/cran/__linux__/jammy/latest" } + - { os: macOS-latest, r: '4.3', bioc: '3.17'} + - { os: windows-latest, r: '4.3', bioc: '3.17'} + ## Check https://github.com/r-lib/actions/tree/master/examples + ## for examples using the http-user-agent + env: + R_REMOTES_NO_ERRORS_FROM_WARNINGS: true + RSPM: ${{ matrix.config.rspm }} + NOT_CRAN: true + TZ: UTC + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} + + steps: + + ## Set the R library to the directory matching the + ## R packages cache step further below when running on Docker (Linux). + - name: Set R Library home on Linux + if: runner.os == 'Linux' + run: | + mkdir /__w/_temp/Library + echo ".libPaths('/__w/_temp/Library')" > ~/.Rprofile + + ## Most of these steps are the same as the ones in + ## https://github.com/r-lib/actions/blob/master/examples/check-standard.yaml + ## If they update their steps, we will also need to update ours. + - name: Checkout Repository + uses: actions/checkout@v3 + + ## R is already included in the Bioconductor docker images + - name: Setup R from r-lib + if: runner.os != 'Linux' + uses: r-lib/actions/setup-r@v2 + with: + r-version: ${{ matrix.config.r }} + http-user-agent: ${{ matrix.config.http-user-agent }} + + ## pandoc is already included in the Bioconductor docker images + - name: Setup pandoc from r-lib + if: runner.os != 'Linux' + uses: r-lib/actions/setup-pandoc@v2 + + - name: Query dependencies + run: | + install.packages('remotes') + saveRDS(remotes::dev_package_deps(dependencies = TRUE), ".github/depends.Rds", version = 2) + shell: Rscript {0} + + - name: Restore R package cache + if: "!contains(github.event.head_commit.message, '/nocache') && runner.os != 'Linux'" + uses: actions/cache@v3 + with: + path: ${{ env.R_LIBS_USER }} + key: ${{ env.cache-version }}-${{ runner.os }}-biocversion-RELEASE_3_17-r-4.3-${{ hashFiles('.github/depends.Rds') }} + restore-keys: ${{ env.cache-version }}-${{ runner.os }}-biocversion-RELEASE_3_17-r-4.3- + + - name: Cache R packages on Linux + if: "!contains(github.event.head_commit.message, '/nocache') && runner.os == 'Linux' " + uses: actions/cache@v3 + with: + path: /home/runner/work/_temp/Library + key: ${{ env.cache-version }}-${{ runner.os }}-biocversion-RELEASE_3_17-r-4.3-${{ hashFiles('.github/depends.Rds') }} + restore-keys: ${{ env.cache-version }}-${{ runner.os }}-biocversion-RELEASE_3_17-r-4.3- + + # - name: Install Linux system dependencies + # if: runner.os == 'Linux' + # run: | + # sysreqs=$(Rscript -e 'cat("apt-get update -y && apt-get install -y", paste(gsub("apt-get install -y ", "", remotes::system_requirements("ubuntu", "20.04")), collapse = " "))') + # echo $sysreqs + # sudo -s eval "$sysreqs" + + - name: Install macOS system dependencies + if: matrix.config.os == 'macOS-latest' + run: | + ## Enable installing XML from source if needed + brew install libxml2 + echo "XML_CONFIG=/usr/local/opt/libxml2/bin/xml2-config" >> $GITHUB_ENV + + ## Required to install magick as noted at + ## https://github.com/r-lib/usethis/commit/f1f1e0d10c1ebc75fd4c18fa7e2de4551fd9978f#diff-9bfee71065492f63457918efcd912cf2 + brew install imagemagick@6 + + ## For textshaping, required by ragg, and required by pkgdown + brew install harfbuzz fribidi + + ## For installing usethis's dependency gert + brew install libgit2 + + ## Required for tcltk + brew install xquartz --cask + + - name: Install Windows system dependencies + if: runner.os == 'Windows' + run: | + ## Edit below if you have any Windows system dependencies + shell: Rscript {0} + + - name: Install BiocManager + run: | + message(paste('****', Sys.time(), 'installing BiocManager ****')) + remotes::install_cran("BiocManager") + shell: Rscript {0} + + - name: Set BiocVersion + run: | + BiocManager::install(version = "${{ matrix.config.bioc }}", ask = FALSE, force = TRUE) + shell: Rscript {0} + + - name: Install dependencies pass 1 + run: | + ## Try installing the package dependencies in steps. First the local + ## dependencies, then any remaining dependencies to avoid the + ## issues described at + ## https://stat.ethz.ch/pipermail/bioc-devel/2020-April/016675.html + ## https://github.com/r-lib/remotes/issues/296 + ## Ideally, all dependencies should get installed in the first pass. + + ## For running the checks + message(paste('****', Sys.time(), 'installing rcmdcheck and BiocCheck ****')) + install.packages(c("rcmdcheck", "BiocCheck"), repos = BiocManager::repositories()) + + ## Pass #1 at installing dependencies + message(paste('****', Sys.time(), 'pass number 1 at installing dependencies: local dependencies ****')) + remotes::install_local(dependencies = TRUE, repos = BiocManager::repositories(), build_vignettes = FALSE, upgrade = TRUE) + continue-on-error: true + shell: Rscript {0} + + - name: Install dependencies pass 2 + run: | + ## Pass #2 at installing dependencies + message(paste('****', Sys.time(), 'pass number 2 at installing dependencies: any remaining dependencies ****')) + remotes::install_local(dependencies = TRUE, repos = BiocManager::repositories(), build_vignettes = TRUE, upgrade = TRUE, force = TRUE) + shell: Rscript {0} + + - name: Install BiocGenerics + if: env.has_RUnit == 'true' + run: | + ## Install BiocGenerics + BiocManager::install("BiocGenerics") + shell: Rscript {0} + + - name: Install covr + if: github.ref == 'refs/heads/devel' && env.run_covr == 'true' && runner.os == 'Linux' + run: | + remotes::install_cran("covr") + shell: Rscript {0} + + - name: Install pkgdown + if: github.ref == 'refs/heads/devel' && env.run_pkgdown == 'true' && runner.os == 'Linux' + run: | + remotes::install_cran("pkgdown") + shell: Rscript {0} + + - name: Session info + run: | + options(width = 100) + pkgs <- installed.packages()[, "Package"] + sessioninfo::session_info(pkgs, include_base = TRUE) + shell: Rscript {0} + + - name: Run CMD check + env: + _R_CHECK_CRAN_INCOMING_: false + DISPLAY: 99.0 + run: | + options(crayon.enabled = TRUE) + rcmdcheck::rcmdcheck( + args = c("--no-manual", "--no-vignettes", "--timings"), + build_args = c("--no-manual", "--keep-empty-dirs", "--no-resave-data"), + error_on = "warning", + check_dir = "check" + ) + shell: Rscript {0} + + ## Might need an to add this to the if: && runner.os == 'Linux' + - name: Reveal testthat details + if: env.has_testthat == 'true' + run: find . -name testthat.Rout -exec cat '{}' ';' + + - name: Run RUnit tests + if: env.has_RUnit == 'true' + run: | + BiocGenerics:::testPackage() + shell: Rscript {0} + + - name: Run BiocCheck + env: + DISPLAY: 99.0 + run: | + BiocCheck::BiocCheck( + dir('check', 'tar.gz$', full.names = TRUE), + `quit-with-status` = TRUE, + `no-check-R-ver` = TRUE, + `no-check-bioc-help` = TRUE + ) + shell: Rscript {0} + + - name: Test coverage + if: github.ref == 'refs/heads/devel' && env.run_covr == 'true' && runner.os == 'Linux' + run: | + covr::codecov(coverage = covr::package_coverage(type = "all")) + shell: Rscript {0} + + - name: Install package + if: github.ref == 'refs/heads/devel' && env.run_pkgdown == 'true' && runner.os == 'Linux' + run: R CMD INSTALL . + + - name: Build pkgdown site + if: github.ref == 'refs/heads/devel' && env.run_pkgdown == 'true' && runner.os == 'Linux' + run: pkgdown::build_site_github_pages(new_process = FALSE, install = FALSE) + shell: Rscript {0} + ## Note that you need to run pkgdown::deploy_to_branch(new_process = FALSE) + ## at least one locally before this will work. This creates the gh-pages + ## branch (erasing anything you haven't version controlled!) and + ## makes the git history recognizable by pkgdown. + + - name: Install deploy dependencies + if: github.ref == 'refs/heads/devel' && env.run_pkgdown == 'true' && runner.os == 'Linux' + run: | + apt-get update && apt-get -y install rsync + + - name: Deploy pkgdown site to GitHub pages 🚀 + if: github.ref == 'refs/heads/devel' && env.run_pkgdown == 'true' && runner.os == 'Linux' + uses: JamesIves/github-pages-deploy-action@releases/v4 + with: + clean: false + branch: gh-pages + folder: docs + + - name: Upload check results + if: failure() + uses: actions/upload-artifact@master + with: + name: ${{ runner.os }}-biocversion-RELEASE_3_17-r-4.3-results + path: check + + + ## Code adapted from + ## https://github.com/waldronlab/cBioPortalData/blob/e0440a4445f0cc731e426363a76faa22ee5e0f9d/.github/workflows/devel_check_dock.yml#L65-L92 + docker-build-and-push: + runs-on: ubuntu-latest + needs: build-check + steps: + - name: Checkout Repository + if: "!contains(github.event.head_commit.message, '/nodocker') && env.run_docker == 'true' && github.ref == 'refs/heads/devel'" + uses: actions/checkout@v3 + + - name: Register repo name + if: "!contains(github.event.head_commit.message, '/nodocker') && env.run_docker == 'true' && github.ref == 'refs/heads/devel'" + id: reg_repo_name + run: | + echo CONT_IMG_NAME=$(echo ${{ github.event.repository.name }} | tr '[:upper:]' '[:lower:]') >> $GITHUB_ENV + + - name: Set up QEMU + if: "!contains(github.event.head_commit.message, '/nodocker') && env.run_docker == 'true' && github.ref == 'refs/heads/devel'" + uses: docker/setup-qemu-action@v2 + + - name: Set up Docker Buildx + if: "!contains(github.event.head_commit.message, '/nodocker') && env.run_docker == 'true' && github.ref == 'refs/heads/devel'" + uses: docker/setup-buildx-action@v2 + + - name: Login to Docker Hub + if: "!contains(github.event.head_commit.message, '/nodocker') && env.run_docker == 'true' && github.ref == 'refs/heads/devel'" + uses: docker/login-action@v2 + with: + username: ${{ secrets.DOCKERHUB_USERNAME }} + password: ${{ secrets.DOCKERHUB_TOKEN }} + ## Note that DOCKERHUB_TOKEN is really a token for your dockerhub + ## account, not your actual dockerhub account password. You can get it + ## from https://hub.docker.com/settings/security. + ## Check https://github.com/docker/build-push-action/tree/v4.0.0 + ## for more details. + ## Alternatively, try checking + ## https://seandavi.github.io/BuildABiocWorkshop/articles/HOWTO_BUILD_WORKSHOP.html. + + - name: Build and Push Docker + if: "!contains(github.event.head_commit.message, '/nodocker') && env.run_docker == 'true' && github.ref == 'refs/heads/devel' && success()" + uses: docker/build-push-action@v4 + with: + context: . + push: true + tags: > + ${{ secrets.DOCKERHUB_USERNAME }}/${{ env.CONT_IMG_NAME }}:latest, + ${{ secrets.DOCKERHUB_USERNAME }}/${{ env.CONT_IMG_NAME }}:devel diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..c066a39 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +inst/doc diff --git a/DESCRIPTION b/DESCRIPTION index 054da7f..554daf0 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -17,5 +17,11 @@ Encoding: UTF-8 Roxygen: list(markdown = TRUE) RoxygenNote: 7.2.3 Suggests: + BiocStyle, + knitr, + RefManageR, + rmarkdown, + sessioninfo, testthat (>= 3.0.0) Config/testthat/edition: 3 +VignetteBuilder: knitr diff --git a/vignettes/.gitignore b/vignettes/.gitignore new file mode 100644 index 0000000..097b241 --- /dev/null +++ b/vignettes/.gitignore @@ -0,0 +1,2 @@ +*.html +*.R diff --git a/vignettes/slurmjobs.Rmd b/vignettes/slurmjobs.Rmd new file mode 100644 index 0000000..d0753d5 --- /dev/null +++ b/vignettes/slurmjobs.Rmd @@ -0,0 +1,165 @@ +--- +title: "Introduction to slurmjobs" +author: + - name: Your name + affiliation: + - Your institution + email: your.email@somewhere.com +output: + BiocStyle::html_document: + self_contained: yes + toc: true + toc_float: true + toc_depth: 2 + code_folding: show +date: "`r doc_date()`" +package: "`r pkg_ver('slurmjobs')`" +vignette: > + %\VignetteIndexEntry{Introduction to slurmjobs} + %\VignetteEngine{knitr::rmarkdown} + %\VignetteEncoding{UTF-8} +--- + +```{r setup, include = FALSE} +knitr::opts_chunk$set( + collapse = TRUE, + comment = "#>", + crop = NULL ## Related to https://stat.ethz.ch/pipermail/bioc-devel/2020-April/016656.html +) +``` + + +```{r vignetteSetup, echo=FALSE, message=FALSE, warning = FALSE} +## Track time spent on making the vignette +startTime <- Sys.time() + +## Bib setup +library("RefManageR") + +## Write bibliography information +bib <- c( + R = citation(), + BiocStyle = citation("BiocStyle")[1], + knitr = citation("knitr")[1], + RefManageR = citation("RefManageR")[1], + rmarkdown = citation("rmarkdown")[1], + sessioninfo = citation("sessioninfo")[1], + testthat = citation("testthat")[1], + slurmjobs = citation("slurmjobs")[1] +) +``` + +# Basics + +## Install `slurmjobs` + +`R` is an open-source statistical environment which can be easily modified to enhance its functionality via packages. `r Biocpkg("slurmjobs")` is a `R` package available via the [Bioconductor](http://bioconductor.org) repository for packages. `R` can be installed on any operating system from [CRAN](https://cran.r-project.org/) after which you can install `r Biocpkg("slurmjobs")` by using the following commands in your `R` session: + +```{r "install", eval = FALSE} +if (!requireNamespace("BiocManager", quietly = TRUE)) { + install.packages("BiocManager") + } + +BiocManager::install("slurmjobs") + +## Check that you have a valid Bioconductor installation +BiocManager::valid() +``` + +## Required knowledge + +`r Biocpkg("slurmjobs")` is based on many other packages and in particular in those that have implemented the infrastructure needed for dealing with RNA-seq data (EDIT!). That is, packages like `r Biocpkg("SummarizedExperiment")` (EDIT!). + +If you are asking yourself the question "Where do I start using Bioconductor?" you might be interested in [this blog post](http://lcolladotor.github.io/2014/10/16/startbioc/#.VkOKbq6rRuU). + +## Asking for help + +As package developers, we try to explain clearly how to use our packages and in which order to use the functions. But `R` and `Bioconductor` have a steep learning curve so it is critical to learn where to ask for help. The blog post quoted above mentions some but we would like to highlight the [Bioconductor support site](https://support.bioconductor.org/) as the main resource for getting help: remember to use the `slurmjobs` tag and check [the older posts](https://support.bioconductor.org/tag/slurmjobs/). Other alternatives are available such as creating GitHub issues and tweeting. However, please note that if you want to receive help you should adhere to the [posting guidelines](http://www.bioconductor.org/help/support/posting-guide/). It is particularly critical that you provide a small reproducible example and your session information so package developers can track down the source of the error. + +## Citing `slurmjobs` + +We hope that `r Biocpkg("slurmjobs")` will be useful for your research. Please use the following information to cite the package and the overall approach. Thank you! + +```{r "citation"} +## Citation info +citation("slurmjobs") +``` + +# Quick start to using `slurmjobs` + +```{r "start", message=FALSE} +library("slurmjobs") +``` + +Edit this as you see fit =) + +Here is an example of you can cite your package inside the vignette: + +* `r Biocpkg("slurmjobs")` `r Citep(bib[["slurmjobs"]])` + + + +# Reproducibility + +The `r Biocpkg("slurmjobs")` package `r Citep(bib[["slurmjobs"]])` was made possible thanks to: + +* R `r Citep(bib[["R"]])` +* `r Biocpkg("BiocStyle")` `r Citep(bib[["BiocStyle"]])` +* `r CRANpkg("knitr")` `r Citep(bib[["knitr"]])` +* `r CRANpkg("RefManageR")` `r Citep(bib[["RefManageR"]])` +* `r CRANpkg("rmarkdown")` `r Citep(bib[["rmarkdown"]])` +* `r CRANpkg("sessioninfo")` `r Citep(bib[["sessioninfo"]])` +* `r CRANpkg("testthat")` `r Citep(bib[["testthat"]])` + +This package was developed using `r BiocStyle::Biocpkg("biocthis")`. + + +Code for creating the vignette + +```{r createVignette, eval=FALSE} +## Create the vignette +library("rmarkdown") +system.time(render("slurmjobs.Rmd", "BiocStyle::html_document")) + +## Extract the R code +library("knitr") +knit("slurmjobs.Rmd", tangle = TRUE) +``` + +Date the vignette was generated. + +```{r reproduce1, echo=FALSE} +## Date the vignette was generated +Sys.time() +``` + +Wallclock time spent generating the vignette. + +```{r reproduce2, echo=FALSE} +## Processing time in seconds +totalTime <- diff(c(startTime, Sys.time())) +round(totalTime, digits = 3) +``` + +`R` session information. + +```{r reproduce3, echo=FALSE} +## Session info +library("sessioninfo") +options(width = 120) +session_info() +``` + + + +# Bibliography + +This vignette was generated using `r Biocpkg("BiocStyle")` `r Citep(bib[["BiocStyle"]])` +with `r CRANpkg("knitr")` `r Citep(bib[["knitr"]])` and `r CRANpkg("rmarkdown")` `r Citep(bib[["rmarkdown"]])` running behind the scenes. + +Citations made with `r CRANpkg("RefManageR")` `r Citep(bib[["RefManageR"]])`. + +```{r vignetteBiblio, results = "asis", echo = FALSE, warning = FALSE, message = FALSE} +## Print bibliography +PrintBibliography(bib, .opts = list(hyperlink = "to.doc", style = "html")) +```