Installation Guide#
System Requirements#
CEBRA is written in Python (3.9+) and PyTorch. CEBRA is most effective when used with a GPU, but CPU-only support is provided. We provide instructions to run CEBRA on your system directly. The instructions below were tested on different compute setups with Ubuntu 18.04 or 20.04, using Nvidia GTX 2080, A4000, and V100 cards. Other setups are possible (including Windows), as long as CUDA 10.2+ support is guaranteed.
- Software dependencies and operating systems:
Linux or MacOS
- Versions software has been tested on:
Linux (Ubuntu 20.04, 18.04, MacOS 12.1-5)
- Required non-standard hardware
GPU (optional)
Installation Guide#
We outline installation instructions for different systems.
CEBRA will be installed via pip install cebra.
CEBRA’s dependencies can be installed using pip or conda and
we outline different options below.
CEBRA can also be installed and run on Google Colaboratory.
Please see the open in colab button at the top of each demo notebook for examples.
If you are starting with a new notebook, simply run
! pip install cebra
In the first cell.
A conda environment for running CEBRA is provided in the conda sub-directory.
To built the env, please run from the CEBRA repo root directory:
$ conda env create -f conda/cebra.yml
Conda users should currently use pip for installation. The missing dependencies will be installed in the install process. A fresh conda environment can be created using
$ conda create -n cebra python==3.12
$ conda activate cebra
$ conda install -c conda-forge pytables==3.8.0
Install PyTorch separately
It is recommended to install PyTorch manually given your system setup. To select the right version, head to
the “Install PyTorch” instructions in the official PyTorch Docs. Select your desired PyTorch build, operating system,
select conda as your package manager and Python as the language. Select your compute platform (either a CUDA version or
CPU only). Then, use the command to install the PyTorch package. Below are a few possible examples (as of 23/8/22):
# CPU only version of pytorch, using the latest version
$ conda install pytorch cpuonly -c pytorch
# GPU version of pytorch for CUDA 11.3
$ conda install pytorch cudatoolkit=11.3 -c pytorch
# CPU only version of pytorch, using the pytorch LTS version
$ conda install pytorch cpuonly -c pytorch-lts
Install CEBRA using pip
Once PyTorch is set up, the remaining dependencies can be installed via pip. Select the correct feature
set based on your usecase:
Regular usage
$ pip install cebra
🚀 For more advanced users, CEBRA has different extra install options that you can select based on your usecase:
[integrations]: This will install (experimental) support for integrations, such as plotly.[docs]: This will install additional dependencies for building the package documentation.[dev]: This will install additional dependencies for development, unit and integration testing, code formatting, etc. Install this extension if you want to work on a pull request.[demos]: This will install additional dependencies for running our demo notebooks in Jupyter.[datasets]: This extension will install additional dependencies to use the pre-installed datasets incebra.datasets.
Inference and development tools only
$ pip install '.[dev]'
Full feature set
$ pip install '.[dev,docs,integrations,demos,datasets]'
Note that, similarly to that last command, you can select the specific install options of interest based on their description above and on your usecase.
Note
On windows systems, you will need to drop the quotation marks and install via pip install .[dev].
Note
Consider using a virtual environment when installing the package via pip.
(Optional) Create the virtual environment by running
$ virtualenv .env && source .env/bin/activate
We recommend that you install PyTorch before CEBRA by selecting the correct version in the PyTorch Docs. Select your desired PyTorch build, operating
system, select pip as your package manager and Python as the language. Select your compute platform (either a
CUDA version or CPU only). Then, use the command to install the PyTorch package. See the conda tab for examples.
Then you can install CEBRA, by running one of these lines, depending on your usage, in the root directory.
For regular usage, the PyPi package can be installed using
$ pip install cebra
For a full install, run
$ pip install 'cebra[dev,integrations,datasets]'
Note that, similarly to that last command, you can select the specific install options of interest based on their description above and on your usecase.
$ docker pull mmathislab/cebra-cuda12.4-cudnn9
You can pull our container from DockerHub: https://hub.docker.com/u/mmathislab
Installation Troubleshooting#
If yopu have issues installing CEBRA, we recommend carefully checking the traceback which can help you look on stackoverflow or the popular-in-life-sciences, Image Forum for similar issues. If you cannot find a solution, please do post an issue on GitHub!
Advanced Installation for Schneider, Lee, Mathis 2023 paper experiments#
If you want to install the additional dependencies required to run comparisons with other algorithms, please see the following:
We provide a conda environment with the full requirements needed to reproduce the first CEBRA paper (although we
recommend using Docker). Namely, you can run CEBRA, piVAE, tSNE and UMAP within this conda env. It is NOT needed if you only want to use CEBRA.
For all platforms except MacOS with M1/2 chipsets, create the full environment using
cebra_paper.yml, by running the following from the CEBRA repo root directory:$ conda env create -f conda/cebra_paper.yml
If you are a MacOS M1 or M2 user and want to reproduce the paper, use the
cebra_paper_m1.ymlinstead. You’ll need to install tensorflow. For that, use miniconda3 and follow the setup instructions for tensorflow listed in the Apple developer docs. In the Terminal, run the following commands:wget https://repo.anaconda.com/miniconda/Miniconda3-py39_4.12.0-MacOSX-arm64.sh -O ~/miniconda.sh bash ~/miniconda.sh -b -p $HOME/miniconda source ~/miniconda/bin/activate conda init zsh
Then, you can build the full environment from the root directory:
$ conda env create -f conda/cebra_paper_m1.yml