Merge pull request #12 from artur-sannikov/docker

Add Docker image

.github/workflows/docker.yml

@@ -0,0 +1,96 @@
+name: docker
+
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  build-push:
+    runs-on: ubuntu-latest
+    name: build-book (${{ github.ref_name }})
+    permissions:
+      contents: write
+      packages: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Collect Workflow Telemetry
+        uses: runforesight/workflow-telemetry-action@v1
+
+      - name: Clean up Docker environment
+        run: |
+          docker system prune --all --force --volumes
+
+      - name: Additional disk space cleanup
+        run: |
+          sudo rm -rf /usr/share/dotnet
+          sudo rm -rf /opt/ghc
+          sudo rm -rf /usr/local/lib/android/sdk
+          sudo apt-get clean
+          sudo rm -rf /var/lib/apt/lists/*
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Cache Docker layers
+        uses: actions/cache@v4
+        with:
+          path: /tmp/.buildx-cache
+          key: ${{ runner.os }}-buildx-${{ github.sha }}
+          restore-keys: |
+            ${{ runner.os }}-buildx-
+
+      - name: Get package metadata
+        id: info
+        env:
+          OWNER: ${{ github.repository_owner }}
+        run: |
+          Pkgname=$(grep -m1 -E '^Package: +' DESCRIPTION | sed -E 's/.*: +//')
+          echo Pkgname=${Pkgname} >> "${GITHUB_ENV}"
+          pkgname=${Pkgname,,}
+          echo pkgname=${pkgname} >> "${GITHUB_ENV}"
+          owner=${OWNER,,}
+          echo owner=${owner} >> "${GITHUB_ENV}"
+          echo pkgversion=$(grep -m1 -E '^Version: +' DESCRIPTION | sed -E 's/.*: +//') >> "${GITHUB_ENV}"
+
+      - name: Log in to the Github Container registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ env.owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Get metadata for Docker
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ env.owner }}/${{ env.pkgname }}
+          tags: |
+            ${{ github.ref_name }}
+            ${{ env.pkgversion }}
+            type=raw,value=latest,enable=${{ github.ref == format('refs/heads/{0}', 'devel') }}
+
+      - name: Install, build and check package in local Docker image
+        id: docker
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          load: true
+          cache-from: type=local,src=/tmp/.buildx-cache
+          cache-to: type=local,dest=/tmp/.buildx-cache
+          tags: ${{ steps.meta.outputs.tags }}
+
+      - name: Push local Docker image to ghcr.io
+        uses: docker/build-push-action@v4
+        with:
+          context: .
+          push: true
+          cache-from: type=local,src=/tmp/.buildx-cache
+          cache-to: type=local,dest=/tmp/.buildx-cache
+          tags: ${{ steps.meta.outputs.tags }}

.gitignore

@@ -20,6 +20,9 @@
 # RStudio files
 .Rproj.user/
 
+# R environment variables
+.Renviron
+
 # produced vignettes
 # vignettes/*.html
 # vignettes/*.pdf
@@ -34,3 +37,5 @@
 # Temporary files created by R markdown
 *.utf8.md
 *.knit.md
+
+/.quarto/

DESCRIPTION

@@ -5,7 +5,17 @@ Date: 2023-08-02
 Authors: Himel Mallick (Cornell University) <[email protected]>, Anupreet Porwal (Google) <[email protected]>
 Description: IntegratedLearner provides an integrated machine learning framework to 1) consolidate predictions by borrowing information across several longitudinal and cross-sectional omics data layers, 2) decipher the mechanistic role of individual omics features that can potentially lead to new sets of testable hypotheses, and 3) quantify uncertainty of the integration process. Three types of integration paradigms are supported: early, late, and intermediate. The software includes multiple ML models based on the SuperLearner R package as well as several data exploration capabilities and visualization modules in a unified estimation framework.
 Depends: R (>= 3.6)
-Imports: SuperLearner, tidyverse, caret, mcmcplots, glmnetUtils, ROCR, quadprog, nloptr
+Imports:
+    bartMachine,
+    caret,
+    cowplot,
+    glmnetUtils,
+    mcmcplots,
+    nloptr,
+    quadprog,
+    ROCR,
+    SuperLearner,
+    tidyverse
 Suggests: data.table, knitr
 License: MIT + file LICENSE
 LazyData: TRUE

Dockerfile

@@ -0,0 +1,24 @@
+
+
+wget -qO - https://gitlab.com/paulcarroty/vscodium-deb-rpm-repo/raw/master/pub.gpg \
+    | gpg --dearmor \
+    | sudo dd of=/usr/share/keyrings/vscodium-archive-keyring.gpg
+# Fetch base image for R version 4.4.1
+FROM rocker/rstudio:4.4.1
+
+# Copy repository into the container image
+COPY --chown=rstudio:rstudio . /opt/pkg
+
+# Install Java
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+    openjdk-21-jdk
+
+# Let R automatically find Java files
+RUN R CMD javareconf
+
+# Install devtools
+RUN Rscript -e 'install.packages("devtools")'
+
+# Install IntegratedLearner
+RUN R -e 'devtools::install(pkg = "/opt/pkg", dependencies = TRUE, upgrade = "always")'

README.md

@@ -1,10 +1,11 @@
 # IntegratedLearner - Integrated machine learning for multi-omics prediction and classification
 
-The repository houses the **`IntegratedLearner`** R package for multi-omics prediction and classification. Both binary and continuous outcomes are supported. 
+The repository houses the **`IntegratedLearner`** R package for multi-omics prediction and classification. Both binary and continuous outcomes are supported.
 
 ## Dependencies
 
 `IntegratedLearner` requires the following `R` package: `devtools` (for installation only). Please install it before installing `IntegratedLearner `, which can be done as follows (execute from within a fresh R session):
+
 ```r
 install.packages("devtools")
 library(devtools)
@@ -13,63 +14,93 @@ library(devtools)
 ## Installation
 
 Once the dependencies are installed, `IntegratedLearner` can be loaded using the following command:
+
 ```r
 devtools::install_github("himelmallick/IntegratedLearner")
 library(IntegratedLearner)
 ```
 
+### Run IntegratedLearner in a container
+
+IntegratedLearner can be run in a containerized environment using either Docker or Podman. It significantly simplifies the installation by ensuring that all the necessary packages are installed to run the provided vignette.
+
+Refer to the installation instructions for your operating system for [Docker](https://docs.docker.com/engine/install/) or [Podman](https://podman.io/docs/installation). Then, in the terminal, run
+
+```
+# Pull the container image from the registry
+docker pull ghcr.io/himelmallick/integratedlearner:master
+
+# Start the container named IntegratedLearner on port 8787
+docker run --port 8787:8787 --name IntegratedLearner integratedlearner:master
+```
+
+In the browser, navigate to `localhost:8787` and log in with `rstudio` username and the password output in the terminal.
+
+In the R console, write `setwd("/opt/pkg")`. You can now open any file in the IntegratedLearner repository.
+
+Podman is compatible with Docker commands, therefore `docker` command can be substituted with `podman`. **NOTE**: if
+running rootless Podman, the correct username *might be* `root` instead of `rstudio`.
+
+#### Map local directory to container directory
+
+If you would like to make any of the code, you need to *map* the local directory to a directory inside the container.
+Otherwise, the modifications will be discarded when the container is stopped. To do so, we need to specify a volume option:
+
+docker run -p 8787:8787 -v .:/IntegratedLearner --name IntegratedLearner integratedlearner:master
+In this command, we *map* the current directory (container, for example, IntegratedLearner repository) to the `/IntegratedLearner`
+directory inside the container. In the RStudio console, write `setwd("/IntegratedLearner")` and modify the files.
+The modifications made *inside* the container will be persistently saved in the current directory of the host system.
+
+**NOTE**: if you are using SELinux (often enabled by default on Fedora), and you received *Permission denied* errors when
+accessing files inside the container, add a `:Z` flag to the volume option: `.:/IntegratedLearner:Z`.
+
 ## Features
 * Supports early, late, and intermediate fusion with one line of code
 * Dozens of algorithms: Random Forest, LASSO, Elastic Net, SVM, BART, and more
 * Integrates with [SuperLearner](https://cran.r-project.org/web/packages/SuperLearner/index.html) to support even more options to quickly add custom algorithms to the ensemble
 * Visualization using built-in plotting
 * Hyperparameter tuning
-* Screening algorithms 
+* Screening algorithms
 * Options to add new algorithms or change the default parameters for existing ones
-* Nested cross-validation to estimate the performance of the integrated machine learner 
+* Nested cross-validation to estimate the performance of the integrated machine learner
 * Multicore and multinode parallelization for scalability (**Not yet available**)
 
 ## Quickstart Guide
-The package vignette demonstrates how to use the **IntegratedLearner** workflow to perform a multi-omics prediction and classification task. This vignette can be viewed online [here](http://htmlpreview.github.io/?https://github.com/himelmallick/IntegratedLearner/blob/master/vignettes/IntegratedLearner.html).
 
+The package vignette demonstrates how to use the **IntegratedLearner** workflow to perform a multi-omics prediction and classification task. This vignette can be viewed online [here](http://htmlpreview.github.io/?https://github.com/himelmallick/IntegratedLearner/blob/master/vignettes/IntegratedLearner.html).
 
 ## Background
 
-
-
 **`IntegratedLearner`** provides an integrated machine learning framework to 1) consolidate predictions by borrowing information across several longitudinal and cross-sectional omics data layers, 2) decipher the mechanistic role of individual omics features that can potentially lead to new sets of testable hypotheses, and 3) quantify uncertainty of the integration process. Three types of integration paradigms are supported: early, late, and intermediate. The software includes multiple ML models based on the [SuperLearner R package](https://cran.r-project.org/web/packages/SuperLearner/index.html) as well as several data exploration capabilities and visualization modules in a unified estimation framework.
 
 At the core, the **`IntegratedLearner`** late fusion algorithm proceeds by 1) fitting a machine learning algorithm (```base_learner```) per-layer to predict outcome  and 2) combining the layer-wise cross-validated predictions using a meta model (```meta_learner```) to generate final predictions based on all available data points. As a default choice, we recommend [Bayesian additive regression trees (BART)](https://arxiv.org/abs/0806.3286) as the base learner (```base_learner = 'SL.BART'```) and non-negative least squares/ rank loss minimization as the meta model algorithm (```meta_learner = 'SL.nnls.auc'```). ```'SL.nnls.auc'``` fits a non-negative least squares (in case of a continuous outcome) and rank loss minimization (in case of binary outcome) on layer-wise cross-validated predictions to generate the final predictions and quantify per-layer contributions.
 
 In addition, >50 ML algorithms are supported. Note that, all the learners must be named such that they are preceeded by the prefix `SL.` followed by the name of the learner or the associated package (e.g.,  `SL.randomForest`, `SL.BART`, `SL.glmnet`, etc.). Please check out the [SuperLearner user manual](https://cran.r-project.org/web/packages/SuperLearner/vignettes/Guide-to-SuperLearner.html) for all available options.
 
-
-
-
-
 ## Basic Usage
+
 ```
 IntegratedLearner(feature_table, sample_metadata, feature_metadata, ...)
 ```
-
 ### Arguments
 
 * ```feature_table ```: Data frame representing concatenated multi-omics features with features in rows (```rownames```) and samples in columns (```colnames```).
 * ```sample_metadata ```: Data frame of sample-specific metadata. Must have a column named ```subjectID``` describing per-subject unique identifiers. For longitudinal designs, this variable is expected to have non-unique values. Additionally, a column named ```Y``` must be present which is the outcome of interest (can be binary or continuous). Row names of ```sample_metadata``` must match the column names of ```feature_table```.
 * ```feature_metadata ```: Data frame containing feature-specific metadata. Must have a column named ```featureID``` describing per-feature unique identifiers. Additionally, if multiple omics layers are present, a column named ```featureType``` should describe the corresponding source layer (e.g. metagenomics, metabolomics, etc.). Row names must match that of ```feature_table```.
-* ```feature_table_valid ```: Optional feature table from validation set. Must have the exact same structure as `feature_table`. 
-* ```sample_metadata_valid```: Optional sample-specific metadata table from independent validation set. Must have the exact same structure as `sample_metadata`. 
+* ```feature_table_valid ```: Optional feature table from validation set. Must have the exact same structure as `feature_table`.
+* ```sample_metadata_valid```: Optional sample-specific metadata table from independent validation set. Must have the exact same structure as `sample_metadata`.
 * ```family```: A character string representing one of the built-in families. Currently, ```gaussian()``` and ```binomial()``` are supported.
 * ```folds```: Integer. Number of folds for cross-validation. Default is 5.
 * ```base_learner ```: Character string representing the name of the ```SL``` base-learner in stacked generalization and optionally for joint learner (see example). Check out the [SL user manual](https://cran.r-project.org/web/packages/SuperLearner/vignettes/Guide-to-SuperLearner.html) for all available options. Default is ```'SL.BART'```
 * ```meta_learner```: Character string representing the name of the ```SL``` meta-learner in stacked generalization (see example). Check out the [SL user manual](https://cran.r-project.org/web/packages/SuperLearner/vignettes/Guide-to-SuperLearner.html) for all available options. Default is ```'SL.nnls.auc'```
 * ```run_concat```: Logical value representing whether a joint (concatenated) model should also be run (see tutorial). Default is TRUE.
 * ```run_stacked```: Logical value representing whether a stacked model should also be run (see tutorial). Default is TRUE.
 * ```print_learner```: Logical value representing whether a summary of fit should be printed. Default is TRUE.
-* ```verbose```: Logical value for printing progress during the computation (helpful for debugging). Default is FALSE. 
+* ```verbose```: Logical value for printing progress during the computation (helpful for debugging). Default is FALSE.
 * ```...```: Additional arguments for `SL` tuning parameters.
 
 #### The IntegratedLearner workflow
+
 ![Flow Chart](/images/Flowchart.png)
 
 #### Value
@@ -79,14 +110,12 @@ IntegratedLearner(feature_table, sample_metadata, feature_metadata, ...)
 * ```X_train_layers```: Input feature matrices for individual layers for training data.
 * ```Y_train```: Input response vector for training data.
 * ```yhat.train```: Predictions for training data from all individual base learners, the meta learner, and optionally the joint (concatenation) learner.
-* ```X_test_layers```: Input feature matrices for individual layers for test data. Available if ```feature_table_valid``` is provided. 
+* ```X_test_layers```: Input feature matrices for individual layers for test data. Available if ```feature_table_valid``` is provided.
 * ```Y_test```: Input response vector for test data.
 * ```weights```: Estimated layer weights in the meta model. Available if ```run_stacked=TRUE``` and ```meta_learner='SL.nnls.auc'```.
 * ```AUC.train```/```R2.train```: AUC/ R2 metrics calculated on training data using ```yhat.train``` and ```Y_train```.
 * ```AUC.test```/```R2.test```: AUC/ R2 metrics calculated on test data using ```yhat.test``` and ```Y_test```.
-* ```...```: Additional arguments containing information about inputs. 
-
-
+* ```...```: Additional arguments containing information about inputs.
 
 Citation
 --------
@@ -98,11 +127,10 @@ Mallick H et al. (2024). [An Integrated Bayesian Framework for Multi-omics Predi
 Issues
 ------
 
-We are happy to troubleshoot any issues with the package. Please contact the maintainer via email or [open an issue](https://github.com/himelmallick/IntegratedLearner/issues) in the GitHub repository. 
+We are happy to troubleshoot any issues with the package. Please contact the maintainer via email or [open an issue](https://github.com/himelmallick/IntegratedLearner/issues) in the GitHub repository.
 
 Future Release
-------
+--------------
 
-We are currently in the process of submitting 
+We are currently in the process of submitting
 **`IntegratedLearner`** to [Bioconductor](https://www.bioconductor.org/). Likewise, please keep an eye out for a future release of **`IntegratedLearner`** as an R/Bioconductor package while this repository remains the development version of the package.
-