Install MoSeq on MacOS using Conda

Follow this step-by-step guide to install MoSeq via Anaconda on MacOS.

At the end of this tutorial, you will have a working version of MoSeq2 installed in a virtual environment managed by Conda.

❗ Note: Installing Conda on MacBook with M1 chip (You can find what chip your MacBook has by going to About This Mac - Overview) is not supported. We recommend that you use a MacBook with an Intel chip or install MoSeq on Linux in a remote computing environment using Conda.

Step 0: Open your Terminal application

The following steps all take place within the terminal.

macOS comes with the Terminal app and you can find it by searching for "Terminal" in the search box in your Launchpad. If you can't figure out how to open up Terminal, you can check out this documentation or 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. macOS should come with curl so if the command is not found, you may need additional resources such as Google search, IT support, Apple Support, etc.

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 this 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 please follow the Installing on macOS section in the official documentation to install git.

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.anaconda.com/miniconda/Miniconda3-latest-MacOSX-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-7 and g++-7 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-7 and g++-7 compilers installed. You can skip this step if gcc-7 and g++-7 are already installed and the environment variables are set.

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

which gcc-7
which g++-7

If you have gcc-7 and g++-7, it should print out paths like /usr/bin/gcc-7 and /usr/bin/g++-7, and you can go to the set environment variable step. Otherwise, you will see gcc/g++ not found or no command output, and we recommend using homebrew to install the gcc-7 and g++-7. Please check out the official documentation for homebrew if you don't have homebrew in your environment.

After you install homebrew, you can run the following to install gcc-7 and g++-7:

brew install gcc@7

❗ Important ❗: you must run the following commands to set the environment variables to point to gcc-7 and g++-7 to ensure the code is compiled correctly.

If you have gcc-7 and g++-7 in the environment, you should see something similar to /usr/local/bin/gcc-7 and /usr/local/bin/g++-7, and you are ready to set the environment variables. To set the environment variables, run:

export CC="$(which gcc-7)"
export CXX="$(which g++-7)"

The two export commands have no outputs. If you like to see if the environment variables are correctly set, run the following commands and you should see the same paths as which gcc-7 and which g++-7:

echo $CC
echo $CXX

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

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:

# set conda channel configuration
conda config --set channel_priority strict
# 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.1.2
moseq2-pca --version
# moseq2-pca, version 1.1.3
moseq2-model --version
# moseq2-model, version 1.1.2
moseq2-viz --version
# moseq2-viz, version 1.2.0

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.

Common failure modes

I am not able to install autoregressive and pyshmm

Repeat step 4 and make sure you have gcc-7 and g++-7 in your environment and the paths should be exported using the following command:

export CC="$(which gcc-7)"
export CXX="$(which g++-7)"

Run the following commands to check if the environment variables are correctly set:

echo $CC
echo $CXX

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.