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 shortcut 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 a 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 and you can go to the next step. 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. You can skip to the "remember" username and password step if git is already installed.

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 and you can go to the next step. Otherwise, you will see git not found and will need to install git by running the following commands:

sudo apt update
sudo apt upgrade
sudo apt install git

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

❗ Important ❗: you must run the following git command to "remember" the username and password to avoid installation failure due to GitHub authentication.

Later in the installation, you will be asked to provide your GitHub username and password to download all the packages in the MoSeq2 package suite.

Since each package is private, they all require a username and password for authentication. Many beta testers have reported issues when installing MoSeq2 this way because it is easy to mistype passwords.

To avoid this failure mode, run the following command 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

Find more information here if you want to learn more about what this command is doing.

Step 3: Install Anaconda/Miniconda

Anaconda is a distribution of python and Miniconda is a minimal version of Anaconda. Conda is the package and virtual environment management component of Anaconda/Miniconda. It allows users to install python packages and set up virtual environments more reproducibly.

Miniconda is sufficient for the MoSeq2 package suite because we don't need all the extra packages Anaconda provides. You can skip this step if Anaconda/Miniconda is already installed.

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

conda info

If you have conda, it should print out information about your environment and you can go to the next step. Otherwise, you will see conda not found and will need to download and install conda by running the following commands:

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. You can skip this step if gcc and g++ (version at least 6) are already installed.

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

which gcc
which g++

If you have gcc and g++, it should print out paths like /usr/bin/gcc and /usr/bin/g++, and you can go to the next step. Otherwise, you will see gcc/g++ not found or no command output, and you will need to install gcc and g++ by running the following commands:

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

Run the following commands again to ensure that you have installed gcc and g++ correctly in the environment:

which gcc
which g++

Like above, you should see something similar to /usr/bin/gcc and /usr/bin/g++ if they were installed correctly.

Make sure your gcc version is at least 6 or higher and you can check the version by running:

gcc --version

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

# 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.

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

Clone moseq2-app repository from GitHub by running:

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

Navigate to the moseq2-app directory by running:

cd moseq2-app

❗ STOP: ❗ read this section carefully to avoid authentication failure

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 if 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 the MoSeq2 package suite. This creates a new conda environment with the name moseq2-app where all MoSeq2 related packages will be installed.

Navigate to the moseq2-app folder (if you have 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

Step 7: Activate the Conda environment and install moseq2-app and the related packages

This is the actual installation step that 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 all the MoSeq2 related packages are installed by checking the version number of each package. You can print the version number of each package by running the following commands:

moseq2-extract --version
# moseq2-extract, version 1.0.1b0
moseq2-pca --version
# moseq2-pca, version 1.0.1b0
moseq2-model --version
# moseq2-model, version 1.0.1b0
moseq2-viz --version
# 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.

Step 9: (Optional) starting a Jupyter notebook

Using Jupyter notebooks is optional if you prefer to use the command-line interface (CLI), but is highly recommended because we provide interactive tools to aid in extraction or analysis.

First, make sure you are in the MoSeq2 Conda environment: conda activate moseq2-app

Next, copy the Jupyter notebooks provided in the moseq2-app repository to the project folder that contains data you would like to extract. For more information about how data should be organized for MoSeq, please see this page.

Navigate to your project folder in the terminal, and run jupyter notebook. You should see a window pop up in your browser that lists the MoSeq notebooks and the folders that contain your data.

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.