Installation

Installation#

There are multiple ways to install GRouNdGAN, depending on your preferences and requirements. Choose the installation method that best suits your needs:

1. Docker Setup:

If you want a quick and hassle-free installation with GPU support, you can use Docker. This method is recommended if you prefer a pre-configured environment.

  • Option A: Using Pre-built Docker Image (Recommended): We provide a pre-built Docker image for GRouNdGAN that is already configured with CUDA support for GPU acceleration. This option is the most convenient and straightforward way to get started.

  • Option B: Building Docker Image from Dockerfile: Building the Docker image from the Dockerfile allows you to further finetune our provided environment to your specific requirements. It also provides the advantage of knowing exactly which dependencies and configurations are being used in your experiments. This option is ideal if you want fine-grained control or if you need to make modifications to GRouNdGAN’s default setup.

2. Local Installation:

If you prefer greater control over your environment, you can opt for a local installation of GRouNdGAN. This option is particularly recommended if you plan to use GRouNdGAN as a foundation for new projects.

3. Singularity:

Most HPC clusters restrict the use of docker, as it can be used to gain root access to the host system. Singularity is a secure and compatible alternative for containerization.

Docker Setup#

Prerequisite: Before you begin, make sure you have Docker installed on your machine. You can download and install Docker from the official website: Get Started | Docker

Option B: Building Docker Image from Dockerfile#

  1. Clone the GRouNdGAN repository:

    $ git clone https://github.com/Emad-COMBINE-lab/GRouNdGAN.git

  2. Navigate to the project directory:

    $ cd GRouNdGAN

  3. Build the Docker image using the provided Dockerfile:

    $ docker build -t yourusername/groundgan:custom -f docker/Dockerfile .

    This command will build a Docker image with the tag yourusername/groundgan:custom.

    Note

    Building the image using this method may take approximately 15-30 minutes, depending on your system’s performance.

  4. Run the Docker container and pass GPU devices:

    $ docker run -itd --name yourusername/groundgan:custom --gpus all groundgan /bin/bash

Verifying GPU Acceleration#

Inside the Docker container, you can verify if the GPU is recognized using:

$ nvidia-smi

You should see detailed information about your GPU, including its name, memory usage, etc. This confirms that GPU acceleration is enabled inside the container.

+-----------------------------------------------------------------------------+
| NVIDIA-SMI 470.63.01    Driver Version: 470.63.01    CUDA Version: 11.4     |
|-------------------------------+----------------------+----------------------+
| GPU  Name        Persistence-M| Bus-Id        Disp.A | Volatile Uncorr. ECC |
| Fan  Temp  Perf  Pwr:Usage/Cap|         Memory-Usage | GPU-Util  Compute M. |
|                               |                      |               MIG M. |
|===============================+======================+======================|
|   0  Tesla V100-SXM2...  Off  | 00000000:00:1E.0 Off |                    0 |
| N/A   33C    P0    41W / 300W |      0MiB / 32480MiB |      0%      Default |
|                               |                      |                  N/A |
+-------------------------------+----------------------+----------------------+

+-----------------------------------------------------------------------------+
| Processes:                                                                  |
|  GPU   GI   CI        PID   Type   Process name                  GPU Memory |
|        ID   ID                                                   Usage      |
|=============================================================================|
|  No running processes found                                                 |
+-----------------------------------------------------------------------------+

Local Installation#

Prerequisites: Before setting up GRouNdGAN locally, ensure you have Python 3.9.6 installed. If you do not have Python 3.9.6, you can use pyenv to manage multiple Python versions. Detailed installation instructions for various platforms can be found in the pyenv documentation: pyenv/pyenv. In the case you are using pyenv, please use pyenv-virtualenv to manage and activate your virtual environment.

  1. Clone the GRouNdGAN repository to a directory of your choice:

    $ git clone https://github.com/Emad-COMBINE-lab/GRouNdGAN.git

    Tip

    You can optionally clone the scGAN, BEELINE, scDESIGN2, and SPARSim submodules to also get the specific version of repositories that we used in our study.

    git clone --recurse-submodules https://github.com/Emad-COMBINE-lab/GRouNdGAN.git

  2. Navigate to the project directory:

    $ cd GRouNdGAN

  3. Create a virtual environment for your project:

    $ python -m venv venv

In the case you are using pyenv, please use pyenv-virtualenv to manage and activate your virtual environment.

  1. Activate the virtual environment

    • Linux/macOS:

      $ source venv/bin/activate

    • Windows:

      $ venv\Scripts\activate

  2. Install the required dependencies from the requirements.txt file:

    (venv)$ pip install -r requirements.txt

    If you’re a fellow Canadian using ComputeCanada, consider using requirements_computecanada.txt instead.

You’re now ready to use GRouNdGAN locally!

Troubleshooting

Known Installation Issues

If you’re encountering issues with installation to ubuntu, it might be because you are missing one or more of the following packages:

sudo apt install build-essential libffi-dev     zlib1g-dev     libncurses5-dev     libgdbm-dev     libnss3-dev     libssl-dev     libreadline-dev     libsqlite3-dev     libpng-dev     libjpeg-dev     libbz2-dev  liblzma-dev tk-dev

Singularity Setup#

Converting Docker Image to Singularity#

  1. Install Singularity on your system if it’s not already installed (Installation Guide).

  2. Use the singularity pull command to convert the Docker image to a Singularity image:

$ singularity pull groundgan.sif docker://yazdanz/groundgan:4b98686

This command will create a Singularity image named groundgan.sif by pulling yazdanz/groundgan:4b98686 from Docker Hub.

Running a Singularity Container#

After converting the Docker image to a Singularity image, you can run a Singularity container interactively:

  1. Start an interactive shell session within the Singularity container:

$ singularity shell --nv groundgan.sif

  • The --nv flag enables running CUDA application inside the container.

Warning

There might be differences in directory structures and permissions between Singularity and Docker containers due to Singularity’s bind-mounted approach.

Contents