OmicVerse Installation Guide¶

Prerequisites¶

OmicVerse can be installed via conda or pip, but you need to install PyTorch first.

Note

To avoid potential dependency conflicts, it is recommended to install within a conda environment. Use pip install -U omicverse to update.

Platform-Specific Instructions¶

Installation methods vary depending on the platform:

Windows-WSL: Install the WSL subsystem and conda within WSL to configure the OmicVerse environment.
Windows-Native: From version 1.6.2, OmicVerse supports native Windows, but you need to install torch, torch_geometric first.
Linux: Install Anaconda or Miniconda and use conda to configure the OmicVerse environment.
Mac OS: Use miniforge or mambaforge to configure the environment.

pip Prerequisites¶

If using conda/mamba, run conda install -c anaconda pip and skip this section.
Install Python, preferably using the pyenv version management system along with pyenv-virtualenv.

Apple Silicon Prerequisites¶

Installing OmicVerse on a Mac with Apple Silicon is only possible using a native version of Python. You can install a native version of Python with an Apple Silicon version of mambaforge (installable via a native version of Homebrew using brew install --cask mambaforge).

Detailed Installation Steps¶

Using Conda¶

Install conda: Typically, use the mambaforge distribution.
Create a new conda environment:
```
conda create -n omicverse python=3.10
```
Activate your environment:
```
conda activate omicverse
```

Install PyTorch and PyG:

First, determine your CUDA version (if applicable):
```
nvcc --version
```

Install the appropriate version of PyTorch:

conda install pytorch torchvision torchaudio pytorch-cuda=11.8 -c pytorch -c nvidia

If using CPU only:

conda install pytorch torchvision torchaudio cpuonly -c pytorch

Install PyG:
```
conda install pyg -c pyg
```

Install OmicVerse:

#conda install python-annoy -c conda-forge
conda install omicverse -c conda-forge

Verify the installation:
```
python -c "import omicverse"
```
If no errors appear, the installation was successful.

Using pip¶

Install PyTorch:

pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

If using CPU only:

pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu

Install PyG:
- First, check your local CUDA version and PyTorch version:
```
python -c "import torch; print(torch.__version__)"
python -c "import torch; print(torch.version.cuda)"
```
- Install the appropriate PyG
```
pip install torch_geometric
```
- (Optional)Install the PyG dependencies version based on your CUDA and PyTorch versions:
```
#For windows
pip install pyg_lib torch_scatter torch_sparse torch_cluster torch_spline_conv -f https://data.pyg.org/whl/torch-${TORCH}+cpu.html
```
  Install the relevant packages:
```
pip install pyg_lib torch_scatter torch_sparse torch_cluster torch_spline_conv -f https://data.pyg.org/whl/torch-${TORCH}+${CUDA}.html
```
  where ${TORCH} and ${CUDA} should be replaced by the specific PyTorch and CUDA versions, respectively:
  - PyTorch 2.3: ${TORCH}=2.3.0 and ${CUDA}=cpu|cu118|cu121
  - PyTorch 2.2: ${TORCH}=2.2.0 and ${CUDA}=cpu|cu118|cu121
  - PyTorch 2.1: ${TORCH}=2.1.0 and ${CUDA}=cpu|cu118|cu121
  - PyTorch 2.0: ${TORCH}=2.0.0 and ${CUDA}=cpu|cu117|cu118
  - PyTorch 1.13: ${TORCH}=1.13.0 and ${CUDA}=cpu|cu116|cu117
  For example, for PyTorch 2.3.* and CUDA 12.1, type:
```
pip install pyg_lib torch_scatter torch_sparse torch_cluster torch_spline_conv -f https://data.pyg.org/whl/torch-2.3.0+cu121.html
```
  For example, for PyTorch 2.2.* and CUDA 11.8, type:
```
pip install pyg_lib torch_scatter torch_sparse torch_cluster torch_spline_conv -f https://data.pyg.org/whl/torch-2.2.0+cu118.html
```
  More information could be found in documention of PyG
Configure Annoy (Windows Native only) (Removed):
```
conda install python-annoy -c conda-forge
```

Configure GCC (Linux only):

For Ubuntu:

sudo apt update
sudo apt install build-essential

For CentOS:

sudo yum group install "Development Tools"

Verify GCC installation:
```
gcc --version
```

Install OmicVerse and Numba:

pip install -U omicverse
pip install -U numba

Verify the installation:
```
python -c "import omicverse"
```
If no errors appear, the installation was successful.

Nightly Version¶

If you want to use the nightly version of OmicVerse:

Clone the repository:

git clone https://github.com/Starlitnightly/omicverse.git

Install OmicVerse:

pip install .

Alternatively, you can install directly from GitHub:

pip install git+https://github.com/Starlitnightly/omicverse.git

Additional Notes¶

If you encounter errors with pip, for packages that pip can't install (e.g., scikit-misc), use conda:

conda install scikit-misc -c conda-forge -c bioconda

For M1/M2 silicon users, the following commands may help:

# Python 3.9
conda install s_gd2 -c conda-forge
pip install -U omicverse
conda install pytorch::pytorch torchvision torchaudio -c pytorch

GPU-Accelerated Installation¶

To install rapids-singlecell and omicverse with GPU acceleration, use the provided yaml file:

conda env create -f conda/omicverse_gpu.yml
# or
mamba env create -f conda/omicverse_gpu.yml

Docker¶

If you plan on running omicverse in a containerized environment, we provide various Docker images hosted on Docker Hub.

Jupyter-lab¶

For the best interactive analysis experience, we highly recommend installing jupyter-lab so that you can interactively edit the code and get the analysis results and visualizations right away.

pip install jupyter-lab

After you have finished the installation, in your terminal (note that you must be in the omicverse environment, not the base environment), type jupyter-lab, a URL will appear, we can open this URL in the browser to start our analysis journey!

Development¶

For development - clone this repo and run:

pip install -e ".[dev,docs]"