Install MoSeq on Linux using Conda

Follow this step-by-step guide to install MoSeq via Anaconda on a Linux computer (i.e., Ubuntu, Debian, or CentOS). At the end of this tutorial, you will have a working version of MoSeq2 installed in a virtual environment managed by Conda.

Step 0: Open your terminal application

The following steps all take place within the terminal. Most Linux distributions support pressing the shorcut ctrl+alt+T to open a terminal. Otherwise, open up the dashboard and search for the terminal application. If you can't figure out how to open up terminal, a quick Google search will have the information you're looking for.

Step 1: Install curl

curl is used to download Anaconda and (optionally) the test data. You can skip this step if curl is already installed.

Check if you have curl installed in the environment by running the following commands:

which curl

If you have curl, it should print out a path like /usr/bin/curl. Otherwise, you will see curl not found, and will need to install curl by running the following commands:

sudo apt update
sudo apt upgrade
sudo apt install curl

Step 2: Install and configure git

git is used to download the moseq2-app repository and the other MoSeq related repositories from GitHub.

Check if you have git installed in the environment by running the following commands:

which git

If you have git, it should print out a path like /usr/bin/git. Otherwise, you will see git not found and will need to install git You can install it by running

sudo apt update
sudo apt upgrade
sudo apt install git

If the installation code block above fails, visit the official documentation for alternative ways of installing git.

❗ Important ❗: you must run the following git command to ensure MoSeq2 will install without error

Later on in the install guide, you will be asked to provide your github username and password to download and install the MoSeq2 package suite. Since each package is private, they all need this information. Many beta testers have reported issues when installing MoSeq2 this way because it is easy to mistype passwords. To solve this problem, run following code snippet to make sure you only have to type in your github username and password once during the installation process.

git config --global credential.helper cache

Read this if you want to learn more about what this command is doing.

Step 3: Install Anaconda/Miniconda

Anaconda is a python environment manager that sees standard use among python developers. It allows users to install python packages more reproducibly. Miniconda is a stripped down version of Anaconda that takes up less storage space. We're going to install Miniconda because we don't need all the extra packages Anaconda provides.

Check if you have conda (the package manage in Anaconda/Miniconda program) installed in the environment by running the following commands:

which conda

If the command is not found, conda not found will be printed. Otherwise, skip to step 4.

Run the following to install conda:

curl -L https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh -o "$HOME/miniconda3_latest.sh"
chmod +x $HOME/miniconda3_latest.sh
$HOME/miniconda3_latest.sh

We recommend that you say yes when the installation prompt asks if you want to initialize Miniconda3. If you decide to say no (not recommended) you can manually initialize conda by running conda init.

❗ ❕ STOP! ❗ ❕ You must restart the terminal before continuing. Close the window, open a new one and move on to step 4. Restarting the terminal allows the new conda and python packages to be accessible by the terminal. This is important for step 6 and beyond.

Step 4: Check if gcc and g++ are installed and set necessary environment variables

One of the MoSeq2 packages (moseq2-model) uses compiled code to fit the AR-HMM models quickly. To compile the code, you need to have gcc and g++ compilers installed.

Check if you have gcc and g++ installed in the environment by running the following commands:

which gcc
# or
which g++

If either command is not found, there will be a message that says gcc/g++ not found, you can run the following to install gcc and g++:

sudo apt update
sudo apt upgrade
sudo apt install build-essential

To ensure that you have gcc and g++ installed in the environment by running the following commands:

which gcc
which g++

Like above, you should see something similar to /usr/bin/gcc and /usr/bin/g++ if they were installed correctly. Finally, make sure your gcc version is at least 6 or higher.

gcc --version
# gcc (Debian 10.2.1-6) 10.2.1 20210110
# Copyright (C) 2020 Free Software Foundation, Inc.
# This is free software; see the source for copying conditions.  There is NO
# warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

In this example gcc is version 10.2.1.

If your gcc version is lower than 6, proceed with the following installation steps at your own risk.

Step 5: Clone (download) the moseq2-app repository

Clone moseq2-app repository from GitHub:

git clone -b release https://github.com/dattalab/moseq2-app.git
cd moseq2-app

❗ STOP: ❗ read this section carefully

moseq2-app is a private repository so you will be prompted to input your username and password running the code block above. Importantly, if you have 2-Factor Authentication (2FA) enabled, you must generate a personal token and use that as your password in place of your log-in password. Learn more about generating this password here.

To determine of you have 2FA enabled, go to your profile and navigate to the account security tab in settings. Next to the "Two-factor authentication" header, you should see a button that says "Enabled" or "Disabled". We recommend that you enable 2FA as it provides more security.

Step 6: Create a conda Environment using moseq2-env.yaml

Create a conda environment to install MoSeq2. Navigate to the moseq2-app folder (if you followed step 5 exactly, you should already be in the folder) and run:

# assuming you're in the moseq2-app directory
conda env create -n moseq2-app --file scripts/moseq2-env.yaml

This creates a new conda environment with the name "moseq2-app" where all MoSeq2 related packages will be installed.

Step 7: Activate the Conda Environment and install moseq2-app and the Related Packages

This is the actual installation step and installs moseq2-app and all the python packages that it depends on.

# activate the new conda environment
conda activate moseq2-app
# assuming you're in the moseq2-app directory
./scripts/install_moseq2_app.sh

Notes: If you get any errors running that script, open the script in a text file and run each line of the script independently. This will help you (and us) figure out where the error is occurring.

Step 8: Check If All the Related Packages are Successfully Installed

Finally, verify that the MoSeq2 packages were installed by printing the version number of each package. To print the version numbers, run

moseq2-extract --version
# > prints moseq2-extract, version 1.0.1b0
moseq2-pca --version
# > prints moseq2-pca, version 1.0.1b0
moseq2-model --version
# > prints moseq2-model, version 1.0.1b0
moseq2-viz --version
# > prints moseq2-viz, version 1.0.2b0

If you get an error and the commands do not print something similar as shown above, you may have to restart the installation process.

Additionally, refer to the troubleshooting section to see if we have a solution.

Try out MoSeq with some test data

Now you should have MoSeq installed in your environment. If you want to explore MoSeq functionalities, check out the guide for downloading test data.