====== SAIGE ======

> SAIGE is an R package developed with Rcpp for genome-wide association tests in large-scale data sets and biobanks. 

   * For more information: https://saigegit.github.io/SAIGE-doc/
   * Source code: https://github.com/saigegit/SAIGE

----

===== Running SAIGE on Comet =====

We have installed SAIGE on Comet using the images published on [[https://hub.docker.com/r/wzhou88/saige/tags|Docker Hub]].

The **SAIGE** container is stored in the ''/nobackup/shared/containers'' directory and is accessible to __all__ users of Comet. You do //not// need to take a copy of the container file; it should be left in its original location.

You can find the container files here:

   * ''/nobackup/shared/containers/saige-1.5.1.sif''

We //normally// recommend using the latest version of the container, in the case of SAIGE, the version numbers represent the version of the SAIGE software itself.

<WRAP round box info>
**Container Image Versions**

We //may// reference a specific container file, such as **saige-1.5.1**, but you should always check whether this is the most recent version of the container available. Simply ''ls'' the ''/nobackup/shared/containers'' directory and you will be able to see if there are any newer versions listed.
</WRAP>

We have provided a convenience script that will automate **all** of steps needed to run applications inside the container, as well as access your ''$HOME'',  ''/scratch'' and ''/nobackup'' directories to just two simple commands.

   * ''/nobackup/shared/containers/saige-1.5.1.sh''

<WRAP round box info half>
There is a corresponding ''.sh'' script for //each version// of the container image we make available.
</WRAP>

Just ''source'' this file and it will take care of loading ''apptainer'', setting up your ''bind'' directories and calling the ''exec'' command for you - and give you a single command called ''container.run'' (instead of the really long //apptainer exec// command) to then //run// anything you want inside the container.

----

===== Simple use of SAIGE =====

All of the SAIGE commands are installed under ''/usr/local/bin'' //within// the container, but can be called by simply using the ''container.run'' command. You //do not// need to give their full path details and you //do not// need to prefix them with ''Rscript''.

Commands available:

   * ''createSparseGRM.R''
   * ''step1_fitNULLGLMM.R''
   * ''step2_SPAtests.R''
   * ''step3_LDmat.R''

For example, to see the help page for the ''step1_fitNULLGLMM.R'' command, run as follows:

<code lang=bash>
$ source /nobackup/shared/containers/saige-1.5.1.sh
$ container.run step1_fitNULLGLMM --help
R version 4.4.3 (2025-02-28)
Platform: x86_64-conda-linux-gnu
Running under: Ubuntu 20.04.6 LTS

Usage: /usr/local/bin/step1_fitNULLGLMM.R [options]

Options:
	--plinkFile=PLINKFILE
		Path to plink file for creating the genetic relationship matrix (GRM). minMAFforGRM can be used to specify the minimum MAF and maxMissingRate can be used to specify the maximum missing rates  of markers in the plink file to be used for constructing GRM. Genetic markers are also randomly selected from the plink file to estimate the variance ratios

	--bedFile=BEDFILE
		Path to bed file. If plinkFile is specified, 'plinkFile'.bed will be used

	--bimFile=BIMFILE
		Path to bim file. If plinkFile is specified, 'plinkFile'.bim will be used

	--famFile=FAMFILE
		Path to fam file. If plinkFile is specified, 'plinkFile'.fam will be used
...
$
</code>

   * Further documentation: https://saigegit.github.io/SAIGE-doc/

----

===== Running the SAIGE Examples =====

The [[https://saigegit.github.io/SAIGE-doc/docs/single_step1.html|Single-variant test example]] from the SAIGE website can be run with the container as follows:

<code lang=bash>
$ source /nobackup/shared/containers/saige-1.5.1.sh
$ container.run step1_fitNULLGLMM.R     \
        --plinkFile=/app/extdata/input/nfam_100_nindep_0_step1_includeMoreRareVariants_poly_22chr  \
        --phenoFile=/app/extdata/input/pheno_1000samples.txt_withdosages_withBothTraitTypes.txt \
        --phenoCol=y_binary \
        --covarColList=x1,x2 \
        --qCovarColList=x2  \
        --sampleIDColinphenoFile=IID \
        --traitType=binary        \
        --outputPrefix=./example_binary \
        --nThreads=4 \
        --IsOverwriteVarianceRatioFile=TRUE
$
</code>

<WRAP round box important>
**Note:**

   * **Sample data** - (//plinkFile// and //phenoFile//) The sample data noted in the [[https://saigegit.github.io/SAIGE-doc/docs/single_step1.html|example]] is available under ''/app/extdata'' //within// the container. Adjust any paths using this data in the online guide to use ''/app/extdata'' instead.
   * **Threads** - Set the //nThreads// value to the number of cores you have requested via Slurm.
</WRAP>

   * Single-variant example: https://saigegit.github.io/SAIGE-doc/docs/single_step1.html

----

===== Accessing Data =====

As long as you use the ''container.run'' method to launch the applications, you will automatically be able to read and write to files in the three main user areas of Comet: ''$HOME'', ''/scratch'' and ''/nobackup'' directories. 

If you run any of the applications inside the container manually, without using the ''container.run'' helper you will need to use the ''--bind'' argument to ''apptainer'' to ensure that all relevant directories are exposed within the container.

Do remember that the container filesystem itself cannot be changed - so you won't be able to write or update to ''/usr/local'', ''/opt'', ''/etc'', ''/app'' or any other internal folders - keep output directories restricted to the three areas listed above.

----
===== Installing SAIGE on Comet =====

<WRAP round box important>
**Important!**

This section is only intended for RSE HPC admin staff or users who are interested in how SAIGE is installed. If you just need to //use// SAIGE, then stop reading here.
</WRAP>

**Installing**

<code lang=bash title=saige.build.sh>
#!/bin/bash
module load apptainer
export APPTAINER_TMPDIR=/scratch
apptainer build saige-1.5.1.sif docker://wzhou88/saige:1.5.1
</code>

**Container definition**

This has //no// container definition, as we are simply translating the published Saige container from [[https://hub.docker.com/r/wzhou88/saige/tags|Docker hub]] to a local Apptainer format.

**Helper script**

<code lang=bash title=saige.sh>
#!/bin/bash
module load apptainer
IMAGE_NAME=/nobackup/shared/containers/saige-1.5.1.sif

container.run() {
    # Run a command inside the container...
    # automatically bind the /scratch and /nobackup dirs
    # pass through any additional parameters given on the command line
    apptainer exec --bind /scratch:/scratch --bind /nobackup:/nobackup ${IMAGE_NAME} $@
}
</code>

----

[[:advanced:software|Back to software]]