Recording/displaying metadata with EMMA

.Rbuildignore

@@ -7,3 +7,5 @@
 ^_pkgdown\.yml$
 ^docs$
 ^pkgdown$
+^\.positai$
+^\.claude$

.github/workflows/R-CMD-check.yaml

@@ -1,28 +1,146 @@
-# Workflow derived from https://github.com/r-lib/actions/tree/master/examples
-# Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help
 on:
   push:
-    branches: [main, master]
   pull_request:
-    branches: [main, master]
+    branches:
+      - devel
+  schedule:
+    - cron: '0 8 * * 5'
 
 name: R-CMD-check
 
 jobs:
   R-CMD-check:
-    runs-on: ubuntu-latest
+    runs-on: ${{ matrix.config.os }}
+    container: ${{ matrix.config.image }}
+
+    name: ${{ matrix.config.os }} (${{ matrix.config.bioc }} - ${{ matrix.config.image }})
+
+    strategy:
+      fail-fast: false
+      matrix:
+        config:
+        - { os: windows-latest, bioc: 'devel'}
+        - { os: macOS-latest, bioc: 'devel', curlConfigPath: '/usr/bin/'}
+        - { os: ubuntu-latest, bioc: 'devel'}
+        # - { os: ubuntu-latest, bioc: 'devel', cran: "https://demo.rstudiopm.com/all/__linux__/xenial/latest"}
+        - { os: ubuntu-latest, image: 'bioconductor/bioconductor_docker:devel'}
+
     env:
+      R_REMOTES_NO_ERRORS_FROM_WARNINGS: true
+      CRAN: ${{ matrix.config.cran }}
+      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
-      R_KEEP_PKG_SOURCE: yes
+      CURL_CONFIG: ${{ matrix.config.curlConfigPath }}curl-config
+
     steps:
-      - uses: actions/checkout@v2
+      - name: Check out repo
+        uses: actions/checkout@v2
 
-      - uses: r-lib/actions/setup-r@v1
+      - name: Set up R and install BiocManager
+        uses: grimbough/bioc-actions/setup-bioc@v1
+        if: matrix.config.image == null
         with:
-          use-public-rspm: true
+          bioc-version: ${{ matrix.config.bioc }}
+
+      - name: Set up pandoc
+        uses: r-lib/actions/setup-pandoc@v2
+        if: matrix.config.image == null
+
+      - name: Install remotes
+        run: |
+          install.packages('remotes')
+        shell: Rscript {0}
 
-      - uses: r-lib/actions/setup-r-dependencies@v1
+      - name: Query dependencies
+        run: |
+          saveRDS(remotes::dev_package_deps(dependencies = TRUE, repos = c(getOption('repos'), BiocManager::repositories())), 'depends.Rds', version = 2)
+        shell: Rscript {0}
+
+      - name: Cache R packages
+        if: runner.os != 'Windows' && matrix.config.image == null
+        uses: actions/cache@v4
+        with:
+          path: ${{ env.R_LIBS_USER }}
+          key: ${{ runner.os }}-bioc-${{ matrix.config.bioc }}-${{ hashFiles('depends.Rds') }}
+          restore-keys: ${{ runner.os }}-bioc-${{ matrix.config.bioc }}-
+
+      - name: Install system dependencies
+        if: runner.os == 'Linux'
+        env:
+          RHUB_PLATFORM: linux-x86_64-ubuntu-gcc
+        uses: r-lib/actions/setup-r-dependencies@v2
         with:
-          extra-packages: rcmdcheck
+          extra-packages: any::rcmdcheck
+          pak-version: devel
+
+      - name: Install system dependencies (macOS)
+        if: runner.os == 'macOS'
+        run: |
+          brew install cairo
+          brew install --cask xquartz
+          brew install harfbuzz
+          brew install fribidi
+          brew install fftw
+
+      # - name: Set up gfortran symlinks (macOS)
+      #   if: runner.os == 'macOS'
+      #   run: |
+      #     set -x
+      #     sudo ln -s /usr/local/Cellar/gcc@11/*/lib/gcc/11 /usr/local/gfortran/lib
+      #     gfortran --version
+
+      - name: Install dependencies
+        run: |
+          local_deps <- remotes::local_package_deps(dependencies = TRUE)
+          deps <- remotes::dev_package_deps(dependencies = TRUE, repos = BiocManager::repositories())
+          BiocManager::install(local_deps[local_deps %in% deps$package[deps$diff != 0]], Ncpu = 2L)
+          remotes::install_cran('rcmdcheck', Ncpu = 2L)
+        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: Build, Install, Check
+        uses: grimbough/bioc-actions/build-install-check@v1
+
+      - name: Run BiocCheck
+        uses: grimbough/bioc-actions/run-BiocCheck@v1
+        with:
+          arguments: '--no-check-bioc-views --no-check-bioc-help'
+          error-on: 'error'
+
+      # - name: Upload check results
+      #   if: failure()
+      #   uses: actions/upload-artifact@master
+      #   with:
+      #     name: ${{ runner.os }}-r${{ matrix.config.r }}-results
+      #     path: check
+
+      - name: Show testthat output
+        if: always()
+        run: find check -name 'testthat.Rout*' -exec cat '{}' \; || true
+        shell: bash
+
+      - name: Upload check results
+        if: failure()
+        uses: actions/upload-artifact@master
+        with:
+          name: ${{ runner.os }}-bioc-${{ matrix.config.bioc }}-results
+          path: check
+
+      - name: Test coverage
+        if: matrix.config.os == 'macOS-latest'
+        run: |
+          install.packages("covr")
+          covr::codecov(token = "${{secrets.CODECOV_TOKEN}}")
+        shell: Rscript {0}
 
-      - uses: r-lib/actions/check-r-package@v1
+      - name: Deploy
+        if: github.event_name == 'push' && github.ref == 'refs/heads/devel' && matrix.config.os == 'macOS-latest'
+        run: |
+          R CMD INSTALL .
+          Rscript -e "remotes::install_dev('pkgdown'); pkgdown::deploy_to_branch(new_process = FALSE)"

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: EMMA
-Title: EMMA: Enrichment Methods Matter for enabeling fully reproducible and 
+Title: EMMA: Enrichment Methods Matter for enabling fully reproducible and 
     provenance-aware pathway analysis
-Version: 0.0.1
+Version: 0.99.0
 Authors@R: 
     c(
         person(
@@ -28,15 +28,27 @@ Description: EMMA is a package that provides a provenance-aware execution
 License: MIT + file LICENSE
 Encoding: UTF-8
 Roxygen: list(markdown = TRUE)
-RoxygenNote: 7.3.3
+RoxygenNote: 8.0.0
+Imports:
+    AnnotationDbi,
+    cli
 Suggests: 
     knitr,
     rmarkdown,
+    macrophage,
+    DESeq2,
+    clusterProfiler,
+    gprofiler2,
     org.Hs.eg.db,
+    GO.db,
+    mosdef,
+    topGO,
+    renv,
+    DeeDeeExperiment,
     testthat (>= 3.0.0)
 VignetteBuilder: knitr
 URL: https://github.com/imbeimainz/EMMA
 BugReports: https://github.com/imbeimainz/EMMA/issues
-biocViews:  Pathways, GO, KEGG, GeneSetEnrichment, Annotation, ImmunoOncology,
-    ReproducibleResearch, Transcriptomics, SingleCell, Software
+biocViews: Software, Pathways, GO, KEGG, GeneSetEnrichment, ImmunoOncology,
+    Transcriptomics, SingleCell, GeneExpression, DifferentialExpression
 Config/testthat/edition: 3

NAMESPACE

@@ -1,5 +1,12 @@
 # Generated by roxygen2: do not edit by hand
 
+export(EMMA_add_custom_metadata)
+export(EMMA_explain)
+export(EMMA_freeze)
+export(EMMA_get_record)
 export(EMMA_run)
 export(EMMA_show)
+importFrom(AnnotationDbi,metadata)
+importFrom(cli,cli_alert_info)
 importFrom(utils,packageVersion)
+importFrom(utils,sessionInfo)

NEWS.md

@@ -1,3 +1,39 @@
+# EMMA 0.99.0
+
+* Ready for Bioconductor submission!
+
+# EMMA 0.3.0
+
+* Added the initial implementation of `EMMA_freeze()`.
+* `EMMA_explain()` now returns also citations of the used packages.
+* Renamed `getEMMARecord()` to `EMMA_get_record()` for consistency.
+* Resizing toy data to speed up examples.
+* Updated the vignette.
+* Updating unit tests.
+
+# EMMA 0.2.0
+
+* `EMMA_run()` can accept custom functions and wrappers and collect metadata
+based on which function was used in the wrapper.
+* Added `EMMA_add_custom_metadata()` to give the user manual/easy access to modify
+`user_metdata` field in `EMMA_record`.
+* Added a fully runnable vignette.
+
+
+# EMMA 0.1.0
+
+* `EMMA_run()` captures a function call, executes the FEA analysis, and returns
+the results in their native format while attaching structured metadata to the
+result object as attribute.
+* `EMMA_run()` can now capture information from functions in `mosdef`,
+`gprofiler2`, and 5 commonly used functions from `clusterProfiler`.
+* `EMMA_show()` prints the captured metadata in a more user-friendly format.
+* Added `getEMMARecord()` to fetch all metadata stored in the attributes of an
+object returned by `EMMA_run()`.
+* Added toy data.
+* Added the initial implementation of `EMMA_explain`.
+
+
 # EMMA 0.0.1
 
 * Added the initial implementation of `EMMA_run()` and `EMMA_show()`.

R/EMMA-data.R

@@ -0,0 +1,70 @@
+#' A sample `data.frame` containing Differential Expression Analysis, generated
+#' with `DESeq2`
+#'
+#' @details This `data.frame` object contains the results of a Differential
+#' Expression Analysis performed on data from the `macrophage` package, more
+#' precisely contrasting the counts from naive macrophage to those associated
+#' with IFNg.
+#'
+#' The code to create said object can be found in the folder `/inst/scripts` in
+#' the EMMA package, the file is called `create_datasets_examples.R`.
+#'
+#' @return A sample `data.frame` object, extracted from `DESeq2` results
+#'
+#' @format A `data.frame` object
+#'
+#' @references Alasoo, et al. "Shared genetic effects on chromatin and gene
+#' expression indicate a role for enhancer priming in immune response",
+#' Nature Genetics, January 2018 doi: 10.1038/s41588-018-0046-7.
+#'
+#' @name de_res_IFNg_vs_naive
+#' @docType data
+NULL
+
+#' A sample `character vector` containing the background gene list used to
+#' perform FEA on the `macrophage` dataset
+#'
+#' @details This `character vector` object contains the assay's `rownames`
+#' of the `macrophage` data
+#'
+#' The code to create said object can be found in the folder `/inst/scripts` in
+#' the EMMA package, the file is called `create_datasets_examples.R`.
+#'
+#' @return A sample `character vector` containing the assay's `rownames`
+#' of the `macrophage` data
+#'
+#' @format A `character vector`
+#'
+#'
+#' @references Alasoo, et al. "Shared genetic effects on chromatin and gene
+#' expression indicate a role for enhancer priming in immune response",
+#' Nature Genetics, January 2018 doi: 10.1038/s41588-018-0046-7.
+#'
+#' @name gene_universe
+#' @docType data
+NULL
+
+#' A sample `list` containing Functional Enrichment Analysis results,
+#' generated with `gprofiler2`
+#'
+#' @details This `list` object contains the result table and metadata of the
+#' functional enrichment analysis (FEA) performed on the `macrophage` data,
+#' specifically using the `gost()` function from the `gprofiler2` package, and
+#' wrapped in `EMMA_run()`
+#'
+#' The code to create said object can be found in the folder `/inst/scripts` in
+#' the EMMA package, the file is called `create_datasets_examples.R`.
+#'
+#' @return A sample `list` containing the FEA results `result` and `metadata`.
+#' This results object has the `EMMA_record` attribute.
+#'
+#' @format A `list`
+#'
+#'
+#' @references Alasoo, et al. "Shared genetic effects on chromatin and gene
+#' expression indicate a role for enhancer priming in immune response",
+#' Nature Genetics, January 2018 doi: 10.1038/s41588-018-0046-7.
+#'
+#' @name fea_res
+#' @docType data
+NULL

R/EMMA-pkg.R

@@ -3,8 +3,9 @@
 #' EMMA stands for Enrichment Methods Matter.
 #' And EMMA stands to help you in realizing it.
 #'
-#'
-#' @importFrom utils packageVersion
+#' @importFrom AnnotationDbi metadata
+#' @importFrom utils packageVersion sessionInfo
+#' @importFrom cli cli_alert_info
 #' @name EMMA-pkg
 #' @docType package
 "_PACKAGE"

R/EMMA_add_custom_metadata.R

@@ -0,0 +1,39 @@
+#' EMMA_add_custom_metadata
+#'
+#' Append or replace the `extra` field in the `EMMA_record` attribute
+#' of a result object returned by `EMMA_run()`. This allows users to manually
+#' provide additional annotation or contextual information that could not be
+#' captured automatically
+#'
+#' @param res A functional enrichment analysis results object as returned by
+#' `EMMA_run()`
+#' @param extra A named list of user-defined metadata elements to store in
+#' the `extra` field
+#'
+#' @returns The input result object with updated `EMMA_record` attribute
+#' @export
+#'
+#' @examples
+#' data("fea_res", package = "EMMA")
+#' fea_res <- EMMA_add_custom_metadata(fea_res, extra =
+#'   list(note = "The background gene set list was all expressed genes in the assay"))
+EMMA_add_custom_metadata <- function(res,
+                                     extra = list()) {
+
+  if (!is.list(extra)) {
+    stop("`extra` must be a list!")
+  }
+
+  if (length(extra) > 0L && is.null(names(extra))) {
+    stop("`extra` must be a named list!")
+  }
+
+  emma_rec <- EMMA_get_record(res = res)
+
+  emma_rec$extra <- extra
+
+  # update
+  attr(res, "EMMA_record") <- emma_rec
+
+  return(res)
+}