Container Execution Wrappers

To make local analysis and development easier, the lab maintains a collection of command-line wrappers. These wrappers allow you to run containerized tools (such as PLINK, BCFtools, and R) directly from your shell without needing to write complex Singularity/Apptainer commands.

---

Setting Up Your Environment

To use the wrappers, you need to add the wrappers directory to your shell's PATH environment variable.

Step 1: Edit Your Shell Configuration

Open your shell configuration file (usually ~/.bashrc for Bash or ~/.zshrc for Zsh) in a text editor:

nano ~/.bashrc

Step 2: Add the Wrappers Directory

Append the following line at the end of the file:

# Add SysMedBio container wrappers to PATH
export PATH="/labs/SysMedBio/Q/Containers/wrappers:$PATH"

Step 3: Reload Your Shell

Apply the changes to your current session:

source ~/.bashrc

Verify that the wrappers are accessible by running:

which plink2

This should output: /labs/SysMedBio/Q/Containers/wrappers/plink2.

---

Available Wrapper Tools

The directory /labs/SysMedBio/Q/Containers/wrappers contains wrappers for several key bioinformatics tools:

Wrapper Command	Underlying Tool	Container
plink	PLINK v1.90	coreygiles-gwas-suite-main.sif
plink2	PLINK v2.00	coreygiles-gwas-suite-main.sif
bcftools	BCFtools	coreygiles-gwas-suite-main.sif
regenie	REGENIE	coreygiles-gwas-suite-main.sif
gcta	GCTA (Genome-wide Complex Trait Analysis)	coreygiles-gwas-suite-main.sif
gctb	GCTB (Bayesian complex trait analysis)	coreygiles-gwas-suite-main.sif
gemma	GEMMA (Genome-wide Efficient Mixed Model Association)	coreygiles-gwas-suite-main.sif
smr	SMR (Summary-data-based Mendelian Randomization)	coreygiles-gwas-suite-main.sif
osca	OSCA (Omic Association Analysis)	coreygiles-gwas-suite-main.sif
vep	Variant Effect Predictor (VEP)	coreygiles-gwas-suite-main.sif
vep_GRCh37	VEP pre-configured for GRCh37	coreygiles-gwas-suite-main.sif
vep_GRCh38	VEP pre-configured for GRCh38	coreygiles-gwas-suite-main.sif
containeR	R Environment (passes custom container name)	coreygiles-<container>-main.sif
nf-modules	Shared Nextflow modules downloader	(Local Bash Script)
aria2c	aria2 (high-speed download utility)	coreygiles-gwas-suite-main.sif

---

How Wrappers Work Behind the Scenes

Every command wrapper is a lightweight shell script that executes a singularity exec command. For example, looking at the plink wrapper:

#!/bin/bash
set -euo pipefail

exec singularity exec \
  --bind /labs:/labs \
  /labs/SysMedBio/Q/Containers/cache/coreygiles-gwas-suite-main.sif \
  plink "$@"

This script:

1. Mounts the /labs directory from the host filesystem to /labs inside the container using the --bind /labs:/labs flag.
2. Locates the pre-built GWAS suite Singularity image (.sif) in the shared cache.
3. Passes all options and files you specified ("$@") directly to the plink binary inside the container.

---

Critical Gotchas & Troubleshooting

1. The File System Boundary (Bind Mounting)

Because the wrapper mounts only the /labs filesystem inside the container, the containerized tools cannot see files outside /labs.

Warning

If your input files are stored in your home directory (e.g., /home/username/data/) or a temporary folder (like /tmp/), running any wrapper will result in a "File not found" error.

Solution: Always work with files located under /labs/... (such as /labs/SysMedBio/Q/... or /labs/bioinformatics/...) when using these wrappers.

2. Multi-threading & Memory Usage

By default, some wrapper tools (like PLINK2 or REGENIE) will try to consume all CPU cores and RAM available on the machine they run on.

• On login nodes: Do not run heavy commands. Login nodes are shared. Running a command that uses all cores will slow down the system for everyone.
• In SLURM jobs: If you call a wrapper inside a SLURM batch job, specify resource limits to match your allocation:

# Example: limit thread usage inside SLURM
plink2 --threads $SLURM_CPUS_PER_TASK --pfile my_data --out my_results

3. Using containeR for R scripts

If you want to run R scripts using packages installed inside one of the lab's containers, use the containeR helper. It takes the target container suffix as its first argument:

# Runs R scripts using the gwas-suite container
containeR gwas-suite my_script.R

# Runs R interactively within the gwas-suite container
containeR gwas-suite