15  Loading BRC Modules

The Bioinformatics Research Center (BRC) administers and maintains a set of common bioinformatics software packages for the BRC community to use on Hazel. We prefer to have control over the software to reduce the burden on individual users, eliminate redundant software downloads, and control software versions for reproducibility. Software is downloaded and formatted using container-mod.

See the full list of currently active BRC Modules!

15.1 Accessing the BRC Software repository

The BRC software downloads are located in /usr/local/usrapps/brc/brc_modules/modules

brc_modules
  ├── images/    ← .sif container images
  ├── modules/   ← TCL module files
  └── tools/     ← Program executables 

These software containers can be loaded in two different ways:

Important

Do not copy this folder! Instead have your scripts/jobs point to software contained here.

15.1.1 Loading modules (recommended)

Much like how common modules can be loaded using module load <module_name>, the BRC software exists as modules in /usr/local/usrapps/brc/brc_modules/modules. The difference is that the module load command doesn’t know to search in this directory. To make these modules available, you must first run:

$ module use /usr/local/usrapps/brc/brc_modules/modules/

Now if you run module avail you should see a list of all the available BRC modules at the top.

$ module avail
------------------ /usr/local/usrapps/brc/brc_modules/modules ------------------
angsd/0.940             funannotate/1.8.17          paml/4.10.10
augustus/3.5.0          gatk4/4.6.2.0               picard/3.4.0
autodock-vina/1.1.2     gcta/1.94.1                 plink2/2.00a5.12
bbtools/39.84           gffread/0.12.9              prokka/1.15.6
bcftools/1.23.1         gtdbtk/2.7.2                raxml-ng/2.0.1
...

Now load any BRC module:

$ module load samtools/
Loading samtools/1.23.1
  Loading requirement: singularity/1.4.2-1

To use software modules in job that you submit to slurm, place the module load command into your job scripts – note that whatever modules that you’ve loaded interactively on the login node may not make it into your job submission.

Warning

The module use command must be run every time you log onto hazel for the BRC modules to be available. You can edit your .bashrc profile to automatically run module use upon start up. See chapter 13 bashrc for more details.

15.1.1.1 Containerized modules

Most BRC modules exist as containers, meaning the programs run inside isolated container environments. Since containers are isolated, data directories on hazel must be bound to the container. Some directories are bound by default, but not all. See the Bind paths and file visibility section below for more information.

15.1.2 Using apptainer

You may also run software without loading it as a module by using the apptainer tool. First load the apptainer module:

$ module load apptainer

Now, any software image (.sif) file in the /usr/local/usrapps/brc/brc_modules/images directory can be run using the command apptainer exec which will temporarily load the software while your command is running. The basic structure is:

apptainer exec <path_to_.sif> <command>

For example, if we want to run samtools to print the help message:

$ apptainer exec /usr/local/usrapps/brc/brc_modules/images/quay.io_biocontainers_samtools:1.23.1--ha83d96e_0.sif samtools --help

Program: samtools (Tools for alignments in the SAM format)
Version: 1.23.1 (using htslib 1.23.1)

Usage:  samtools <command> [options]
...

Important

Both options for loading and using BRC software are compatible with bash scripts and job submission. Never do computationally expensive work from the login nodes.

15.1.3 Bind paths and file visibility

Containers have their own isolated filesystem, so a program running inside one can only see host directories that have been “bound” (mounted) into it. A plain apptainer exec call adds no extra bind paths on its own — it relies entirely on Apptainer’s default bind behavior.

By default, without any --bind flags, Apptainer automatically makes the following visible inside the container:

• your home directory ($HOME)
• the directory you load a BRC module or the apptainer module from ($PWD)
• /tmp, /proc, /sys, /dev

If the files you’re working with live under one of those paths, everything works with no extra steps. If they live somewhere else — for example a scratch or RS1 path that isn’t part of your current working directory tree — you have a few options:

1. Load the module in the directory you want to work from, then refer to them with relative paths. Since $PWD is auto-bound when you load a module, this is the simplest fix for a one-off command.

2. Set the APPTAINER_BINDPATH environment variable. Apptainer reads this variable automatically and applies it to every exec/run/shell call — including the ones inside the BRC module load wrapper scripts. This is the recommended fix if you regularly work with data that spans multiple locations on hazel, because it’s a one-time setup that then applies to every BRC module:

   $ export APPTAINER_BINDPATH="/rs1,/share/$GROUP"

   This will recursively bind all directories within /rs1 and within your group’s scratch directory.

   Add this to ~/.bashrc.d/env.sh (see chapter 13) to make this a permanent fix. The value is a comma-separated list of directory entries, with the same syntax as --bind.

3. Bind the path explicitly for a single command if you’re calling apptainer exec yourself instead of going through a module load wrapper:

   SAMTOOLS_SIF="/usr/local/usrapps/brc/brc_modules/images/quay.io_biocontainers_samtools:1.24--h9dcdb79_1.sif"
   $ apptainer exec --bind /path/to/data/dir $SAMTOOLS_SIF samtools view /path/to/data/dir/input.sam

   This will bind whatever directory you pass to the --bind option, useful for when your data is in a separate filesystem.

Tip

If a tool reports that a file doesn’t exist even though you can see it fine on the host filesystem (e.g. [E::hts_open] fail to open file), this is almost always a missing bind mount, not a typo in the path.

15.2 Requesting software

If you want to use a software package that is missing from the BRC library, or need a package updated to a newer version fill out this google form: Request BRC Software Module