[GL_RefAnnotTable] switch from apptainer to singularity

torres-alexis · torres-alexis · commit 86814bd32e6b · 2024-10-10T12:49:34.000-07:00
diff --git a/GeneLab_Reference_Annotations/Workflow_Documentation/GL_RefAnnotTable-A/README.md b/GeneLab_Reference_Annotations/Workflow_Documentation/GL_RefAnnotTable-A/README.md
@@ -1,112 +1,96 @@
 # GL_RefAnnotTable-A Workflow Information and Usage Instructions <!-- omit in toc -->
 
 ## Table of Contents <!-- omit in toc -->
-- [General Workflow Info](#general-workflow-info)
+
+- [General Workflow Information](#general-workflow-information)
 - [Utilizing the Workflow](#utilizing-the-workflow)
-  - [Approach 1: Using Apptainer](#approach-1-using-apptainer)
-    - [1. Install Apptainer](#1-install-apptainer)
-    - [2. Download the Workflow Files](#2-download-the-workflow-files)
-    - [3. Fetch Apptainer Image](#3-fetch-apptainer-image)
-    - [4. Run the Workflow](#4-run-the-workflow)
-    - [5. Run the Annotations Database Creation Function as a Stand-Alone Script](#5-run-the-annotations-database-creation-function-as-a-stand-alone-script)
-  - [Approach 2: Using a Local R Environment](#approach-2-using-a-local-r-environment)
-    - [1. Install R and Required R Packages](#1-install-r-and-required-r-packages)
-    - [2. Download the Workflow Files](#2-download-the-workflow-files-1)
-    - [3. Set Execution Permissions for Workflow Scripts](#3-set-execution-permissions-for-workflow-scripts)
-    - [4. Run the Workflow](#4-run-the-workflow-1)
-    - [5. Run the Annotations Database Creation Function as a Stand-Alone Script](#5-run-the-annotations-database-creation-function-as-a-stand-alone-script-1)
-
-<br>
+  - [1. Download the Workflow Files](#1-download-the-workflow-files)
+  - [2. Run the Workflow](#2-run-the-workflow)
+    - [Approach 1: Using Singularity](#approach-1-using-singularity)
+      - [Step 1: Install Singularity](#step-1-install-singularity)
+      - [Step 2: Fetch the Singularity Image](#step-2-fetch-the-singularity-image)
+      - [Step 3: Run the Workflow](#step-3-run-the-workflow)
+      - [Step 4: Run the Annotations Database Creation Function as a Stand-Alone Script](#step-4-run-the-annotations-database-creation-function-as-a-stand-alone-script)
+    - [Approach 2: Using a Local R Environment](#approach-2-using-a-local-r-environment)
+      - [Step 1: Install R and Required R Packages](#step-1-install-r-and-required-r-packages)
+      - [Step 2: Run the Workflow](#step-2-run-the-workflow)
+      - [Step 3: Run the Annotations Database Creation Function as a Stand-Alone Script](#step-3-run-the-annotations-database-creation-function-as-a-stand-alone-script)
 
 ---
 
-## General Workflow Info
-
-The current GeneLab Reference Annotation Table (GL_RefAnnotTable-A) pipeline is implemented as an R workflow that can be run from a command line interface (CLI) using bash. The workflow can be executed using either a Apptainer (formerly Singularity) container or a local R environment. The workflow can be used even if you are unfamiliar with R, but if you want to learn more about R, visit the [R-project about page here](https://www.r-project.org/about.html). Additionally, an introduction to R along with installation help and information about using R for bioinformatics can be found [here at Happy Belly Bioinformatics](https://astrobiomike.github.io/R/basics).
+## General Workflow Information
 
-<br>
+The current GeneLab Reference Annotation Table (GL_RefAnnotTable-A) pipeline is implemented as an R workflow that can be run from a command line interface (CLI) using bash. The workflow can be executed using either a Singularity container or a local R environment. The workflow can be used even if you are unfamiliar with R, but if you want to learn more about R, visit the [R-project about page here](https://www.r-project.org/about.html). Additionally, an introduction to R along with installation help and information about using R for bioinformatics can be found [here at Happy Belly Bioinformatics](https://astrobiomike.github.io/R/basics).
 
 ---
 
 ## Utilizing the Workflow
 
-The GL_RefAnnotTable-A workflow can be run using two approaches:
-
-1. **[Using Apptainer](#approach-1-using-apptainer)**.  
+To utilize the GL_RefAnnotTable-A workflow, follow the instructions below to download the necessary workflow files. Once downloaded, the workflow can be executed using two approaches:
 
-2. **[Using a local R environment](#approach-2-using-a-local-r-environment)**.  
+1. **[Using Singularity](#approach-1-using-singularity)**
+2. **[Using a Local R Environment](#approach-2-using-a-local-r-environment)**
 
-Please follow the instructions for the approach that best matches your setup and preferences. Each method is explained in the sections below.
-
-<br>
+Please follow the instructions for the approach that best matches your setup and preferences. Each method is explained in detail below.
 
 ---
 
-### Approach 1: Using Apptainer
+### 1. Download the Workflow Files
 
-This approach allows you to run the workflow within a containerized environment, ensuring consistency and reproducibility.
+Download the latest version of the GL_RefAnnotTable-A workflow:
 
-<br>
+```bash
+curl -LO https://github.com/nasa/GeneLab_Data_Processing/releases/download/GL_RefAnnotTable-A_1.1.0/GL_RefAnnotTable-A_1.1.0.zip
+unzip GL_RefAnnotTable-A_1.1.0.zip
+```
 
 ---
 
-#### 1. Install Apptainer
-
-Apptainer can be installed either through [Anaconda](https://anaconda.org/conda-forge/singularity) or as documented on the [Apptainer documentation page](https://apptainer.org/docs/admin/main/installation.html).
+### 2. Run the Workflow
 
-> **Note**: If you prefer to use Anaconda, we recommend installing Miniconda for your system, as instructed by [Happy Belly Bioinformatics](https://astrobiomike.github.io/unix/conda-intro#getting-and-installing-conda).
->
-> Once conda is installed on your system, you can install Apptainer by running:
->
-> ```bash
-> conda install -c conda-forge apptainer
-> ```
+The GL_RefAnnotTable-A workflow can be run using two approaches:
 
-<br>
+- **[Approach 1: Using Singularity](#approach-1-using-singularity)**
+- **[Approach 2: Using a Local R Environment](#approach-2-using-a-local-r-environment)**
 
 ---
 
-#### 2. Download the Workflow Files
+#### Approach 1: Using Singularity
 
-Download the latest version of the GL_RefAnnotTable-A workflow:
+This approach allows you to run the workflow within a containerized environment, ensuring consistency and reproducibility.
 
-```bash
-curl -LO https://github.com/nasa/GeneLab_Data_Processing/releases/download/GL_RefAnnotTable-A_1.1.0/GL_RefAnnotTable-A_1.1.0.zip
-unzip GL_RefAnnotTable-A_1.1.0.zip
-cd GL_RefAnnotTable-A_1.1.0
-```
+##### Step 1: Install Singularity
 
-<br>
+Singularity is a containerization platform for running applications portably and reproducibly. We use container images hosted on Quay.io to encapsulate all the necessary software and dependencies required by the GL_RefAnnotTable-A workflow. This setup allows you to run the workflow without installing any software directly on your system. Other containerization tools like Docker or Apptainer can also be used to pull and run these images.
 
----
+We recommend installing Singularity system-wide as per the official [Singularity installation documentation](https://docs.sylabs.io/guides/3.10/admin-guide/admin_quickstart.html).
 
-#### 3. Fetch Apptainer Image
+> **Note**: While Singularity is also available through [Anaconda](https://anaconda.org/conda-forge/singularity), we recommend installing Singularity system-wide following the official installation documentation.
 
-To fetch the Apptainer image needed for the workflow, run:
+##### Step 2: Fetch the Singularity Image
 
-```bash
-bash bin/prepull_apptainer.sh config/software/by_docker_image.config
-```
-> Note: This command should be run in the directory containing the GL_RefAnnotTable-A_1.1.0 folder downloaded in [step 2](#2-download-the-workflow-files). Depending on your network speed, this may take approximately 20 minutes.
+To pull the Singularity image needed for the workflow, you can use the provided script as directed below or pull the image directly.
 
-Once complete, an apptainer folder containing the Apptainer image will be created. Export this folder as an Apptainer configuration environment variable:
+> **Note**: This command should be run in the location containing the `GL_RefAnnotTable-A_1.1.0` directory that was downloaded in [step 1](#1-download-the-workflow-files). Depending on your network speed, fetching the images will take approximately 20 minutes.
 
 ```bash
-export APPTAINER_CACHEDIR=$(pwd)/apptainer
+bash GL_RefAnnotTable-A_1.1.0/bin/prepull_singularity.sh GL_RefAnnotTable-A_1.1.0/config/software/by_docker_image.config
 ```
 
-<br>
+Once complete, a `singularity` folder containing the Singularity images will be created. Run the following command to export this folder as an environment variable:
 
----
+```bash
+export SINGULARITY_CACHEDIR=$(pwd)/singularity
+```
 
-#### 4. Run the Workflow
+##### Step 3: Run the Workflow
 
-While in the `GL_RefAnnotTable-A_1.1.0` directory, you can now run the workflow. Below is an example for generating an annotation table for Mus musculus (mouse):
+While in the directory containing the `GL_RefAnnotTable-A_1.1.0` folder, you can now run the workflow. Below is an example for generating the annotation table for *Mus musculus* (mouse):
 
 ```bash
-apptainer exec -B $(pwd):/work \
-$APPTAINER_CACHEDIR/quay.io-nasa_genelab-gl-refannottable-a-1.1.0.img \
-bash -c "cd /work && Rscript GL-DPPD-7110-A_build-genome-annots-tab.R 'Mus musculus'"
+singularity exec -B $(pwd)/GL_RefAnnotTable-A_1.1.0:/work \
+$SINGULARITY_CACHEDIR/quay.io-nasa_genelab-gl-refannottable-a-1.1.0.sif \
+Rscript /work/GL-DPPD-7110-A_build-genome-annots-tab.R 'Mus musculus'
 ```
 
 **Input data:**
@@ -119,18 +103,14 @@ bash -c "cd /work && Rscript GL-DPPD-7110-A_build-genome-annots-tab.R 'Mus muscu
 - *-GL-annotations.tsv (Tab delineated table of gene annotations)
 - *-GL-build-info.txt (Text file containing information used to create the annotation table, including tool and tool versions and date of creation)
 
-<br>
-
----
+##### Step 4: Run the Annotations Database Creation Function as a Stand-Alone Script
 
-#### 5. Run the Annotations Database Creation Function as a Stand-Alone Script
-
-If the reference table does not specify an annotations database for the target organism in the annotations column, the `install_annotations` function (defined in `install-org-db.R`) will be executed. This function can also be run as a stand-alone script:
+If the reference table does not specify an annotations database for the target organism in the 'annotations' column, the `install_annotations` function (defined in `install-org-db.R`) will be executed. This function can also be run as a stand-alone script:
 
 ```bash
-apptainer exec -B $(pwd):/work \
-  $APPTAINER_CACHEDIR/quay.io-nasa_genelab-gl-refannottable-a-1.1.0.img \
-  bash -c "cd /work && Rscript install-org-db.R 'Bacillus subtilis'"
+singularity exec -B $(pwd)/GL_RefAnnotTable-A_1.1.0:/work \
+$SINGULARITY_CACHEDIR/quay.io-nasa_genelab-gl-refannottable-a-1.1.0.sif \
+Rscript /work/install-org-db.R 'Bacillus subtilis'
 ```
 
 **Input data:**
@@ -142,39 +122,33 @@ apptainer exec -B $(pwd):/work \
 
 - org.*.eg.db/ (Species-specific annotation database, as a local R package)
 
-<br>
-
 ---
 
-### Approach 2: Using a Local R Environment  
+#### Approach 2: Using a Local R Environment
 
-This approach allows you to run the workflow directly in your local R environment without using Apptainer containers.
+This approach allows you to run the workflow directly in your local R environment without using containers.
 
-<br>
-
----
-
-#### 1. Install R and Required R Packages
+##### Step 1: Install R and Required R Packages
 
 We recommend installing R via the [Comprehensive R Archive Network (CRAN)](https://cran.r-project.org/):
 
-1. Select the [CRAN Mirror](https://cran.r-project.org/mirrors.html) closest to your location.  
-2. Navigate to the download page for your operating system.  
-3. Download and install R (e.g., R-4.4.0).  
+1. Select the [CRAN Mirror](https://cran.r-project.org/mirrors.html) closest to your location.
+2. Navigate to the download page for your operating system.
+3. Download and install R (e.g., R-4.4.0).
+
+Once R is installed, you need to install the required R packages.
 
-Once R is installed, open a terminal and start R:
+Open a terminal and start R:
 
 ```bash
 R
 ```
 
-Within an active R environment, run the following commands to install the required R packages:
+Within the R environment, run the following commands to install the required packages:
 
 ```R
 install.packages("tidyverse")
-
 install.packages("BiocManager")
-
 BiocManager::install("STRINGdb")
 BiocManager::install("PANTHER.db")
 BiocManager::install("rtracklayer")
@@ -183,42 +157,12 @@ BiocManager::install("biomaRt")
 BiocManager::install("GO.db")
 ```
 
-<br>
-
----
+##### Step 2: Run the Workflow
 
-#### 2. Download the Workflow Files
-
-All files required for utilizing the GL_RefAnnotTable-A workflow for generating reference annotation tables are in the [workflow_code](workflow_code) directory. To get a copy of latest GL_RefAnnotTable version on to your system, run the following command:
+While in the directory containing the `GL_RefAnnotTable-A_1.1.0` folder, you can now run the workflow. Below is an example of how to run the workflow to build an annotation table for *Mus musculus* (mouse):
 
 ```bash
-curl -LO https://github.com/nasa/GeneLab_Data_Processing/releases/download/GL_RefAnnotTable-A_1.1.0/GL_RefAnnotTable-A_1.1.0.zip
-``` 
-
-<br>
-
----
-
-#### 3. Set Execution Permissions for Workflow Scripts
-
-Once you've downloaded the GL_RefAnnotTable-A workflow directory as a zip file, unzip the workflow then `cd` into the GL_RefAnnotTable-A_1.1.0 directory on the CLI. Next, run the following command to set the execution permissions for the R script:
-
-```bash
-unzip GL_RefAnnotTable-A_1.1.0.zip
-cd GL_RefAnnotTable-A_1.1.0
-chmod -R u+x *R
-```
-
-<br>
-
----
-
-#### 4. Run the Workflow 
-
-While in the GL_RefAnnotTable workflow directory, you are now able to run the workflow. Below is an example of how to run the workflow to build an annotation table for Mus musculus (mouse):
-
-```bash
-Rscript GL-DPPD-7110-A_build-genome-annots-tab.R 'Mus musculus'
+Rscript GL_RefAnnotTable-A_1.1.0/GL-DPPD-7110-A_build-genome-annots-tab.R 'Mus musculus'
 ```
 
 **Input data:**
@@ -231,16 +175,12 @@ Rscript GL-DPPD-7110-A_build-genome-annots-tab.R 'Mus musculus'
 - *-GL-annotations.tsv (Tab delineated table of gene annotations)
 - *-GL-build-info.txt (Text file containing information used to create the annotation table, including tool and tool versions and date of creation)
 
-<br>
-
----
-
-#### 5. Run the Annotations Database Creation Function as a Stand-Alone Script
+##### Step 3: Run the Annotations Database Creation Function as a Stand-Alone Script
 
 If the reference table does not specify an annotations database for the target organism in the 'annotations' column, the `install_annotations` function (defined in `install-org-db.R`) will be executed. This function can also be run as a stand-alone script:
 
 ```bash
-Rscript install-org-db.R 'Bacillus subtilis'
+Rscript GL_RefAnnotTable-A_1.1.0/install-org-db.R 'Bacillus subtilis'
 ```
 
 **Input data:**
@@ -252,4 +192,4 @@ Rscript install-org-db.R 'Bacillus subtilis'
 
 - org.*.eg.db/ (species-specific annotation database, as a local R package)
 
-<br>
+---
diff --git a/GeneLab_Reference_Annotations/Workflow_Documentation/GL_RefAnnotTable-A/workflow_code/bin/prepull_singularity.sh b/GeneLab_Reference_Annotations/Workflow_Documentation/GL_RefAnnotTable-A/workflow_code/bin/prepull_singularity.sh
@@ -4,7 +4,7 @@
 # Addresses issue: https://github.com/nextflow-io/nextflow/issues/1210
 
 CONFILE=${1:-nextflow.config}
-OUTDIR=${2:-./apptainer}
+OUTDIR=${2:-./singularity}
 
 if [ ! -e $CONFILE ]; then
         echo "$CONFILE does not exist"
@@ -26,7 +26,7 @@ while IFS= read -r line; do
         name=${name/:/-}
         name=${name//\//-}
         echo $name
-        apptainer pull ${name}.img docker://$line
+        singulairty pull ${name}.img docker://$line
 done < $TMPFILE
 
 cd $CURDIR
