Install MoSeq on MacOS using Docker

Follow this step-by-step guide to install and run MoSeq inside a Docker container. You can learn more about Docker from Docker's documentation. Learn more about the differences between a Docker images and containers here. If you run into any problems, refer to the troubleshooting section to see if we have a solution.

❗ Note: If your MacBook has M1 chip (you can find what chip you MacBook has by going to About This Mac - Overview), Docker performance may be poor. At the time of writing, Macs with Intel chips are better supported. If you need more performance, look into installing MoSeq on other platforms like linux or Windows.

Docker installation prerequisites

Before following this installation guide, you must create an account with Docker Hub to have access to the image.

If you would like to try out MoSeq2 but don't have any data, download one of our multiple datasets using the file download guide before installing Docker and MoSeq2.

At the end of this tutorial, you should have created a MoSeq2 Docker container to run the MoSeq2 package suite.

Step 1: Install and Launch Docker Desktop

Docker Desktop provides a graphical user interface (GUI) and more to interact with Docker images and containers. Follow the official documentation to install Docker Desktop.

After installing, launch Docker Desktop. It takes a while for it to finish launching - wait for the bottom left area of the GUI to turn green, as shown in the image below.

Step 2: Sign in to Docker Desktop

Sign in to Docker Desktop as shown in the image below.

Step 3: Configure Docker Resources

Extraction and modeling steps in the MoSeq analysis pipeline can be resource-intensive. We recommend you configure the resources available to the container to maximize performance. It is possible to go to the next step if you don't want to configure resources, but we highly recommend it.

Click on the "Settings" icon and then click on the "Resources" tab to configure Docker resources to achieve good MoSeq performance. If you have the available resources, we recommend the following settings:

However, if you don't have the available resources, use the maximum amount of RAM and CPU cores available to you. Don't worry about changing the disk image size — MoSeq does not use much extra disk space.

Step 4: Set up your base directory/data folder

The base directory/data folder is a folder on your local computer that should contain the depth data you want to analyze for a given experiment and the analysis results are stored in this folder.

If you downloaded one of our test datasets, you can use the downloaded folder as the base directory. If you want to download one of our datasets, refer to our download guide for more information, then come back here once you've downloaded and decompressed the data.

In step 6, the base directory/data folder will be mounted to the MoSeq2 Docker container so the data is available to the container. See the link on setting up directory structures to learn more about how data should be organized for MoSeq2 analysis.

Step 5: Pull (download) the MoSeq2 Docker image from the dattalab MoSeq2 repository

The MoSeq2 Docker image contains all the MoSeq2 packages pre-installed and configured for use. Here we will download the image, which will be used to create a container that can run MoSeq2 and process your data.

Click on the Images tab on the left, click on the REMOTE REPOSITORIES tab.

Select dattalab from the dropdown menu.

Hover over the MoSeq2 Docker image that with the most recent tag and click PULL to download the image. In this example, the most recent tag (version) is v1.2.3.

Note: If you have an existing MoSeq2 Docker image with the same tag, pulling a new image from dattalab will update the overwrite the existing image. Below we show an example of the message after pulling the new image from dattalab in REMOTE REPOSITORIES and the new image is the same as the existing image.

Two images can co-exist if the the tags are different. Below we show an example of two MoSeq2 Docker images with different tags (v1.0.1beta and v1.0.2beta) existing locally at the same time. You can also find all previous MoSeq2 Docker images in dattalab/moseq2 on dockerhub.

Step 6: Create a container using the MoSeq2 Docker image

A container is a runnable instance of a Docker image. Create a container from the Docker image to run the MoSeq2 package suite on your data.

Click on the LOCAL tab and you should see the dattalab/moseq2 image downloaded to your local environment. You might see more than one dattalab/moseq2 image if you have previously downloaded other versions. Hover over the Docker image you want to run and click RUN to set up a container.

A popup window will open after you click RUN and you MUST configure the container settings to use all of MoSeq2's functionalities.

Container settings:

• Container Name: sets the name of the container.

  • Name the container with any name of your choice, but spaces and special characters are not allowed. In the example below, we named the container "moseq".

• Ports: allows us to map network traffic from the container to the local computer. The MoSeq2 Docker image specifies 2 main ports to map: 8786 and 8787, as seen in the image below. When you open this dialog, you might notice that only one port is visible. Click the "+" button on the right to reveal the second port. The first port (8786) will connect you to the MoSeq jupyter notebooks within the Docker container. The second port (8787) will connect you to the dask dashboard instantiated during the PCA step. It is less important, but useful for debugging.

  • Type a port number in each text box on the left. You can use any port that's not already in use, but for simplicity, you can use 8786 and 8787 for each port, respectively. In the example below, we set the first port to be 12345 and the second port to 8787.

• Host Path: connects the data folder on your local machine to the container.

  • Click the ... in the text field to select the folder that contains your project data. In the example below, the path points to example_data on the Desktop.

• Container Path: specifies the folder within the container that the data folder connects to.

  • You MUST type "/data" into the input box like the example below, or the Docker container won't function correctly.

Note:

• You can create multiple containers from the same Docker image, as long as they have different names.
• You can also have multiple containers from different MoSeq2 Docker images.
• Since each container is mapped to a specific data folder, we recommend that you create a separate container for each MoSeq2 project.
• Multiple containers mapped to the same port cannot be running at the same time. If you create multiple containers, they must either:
  • map to different, unique ports on your local computer (which allows you to use the containers simultaneously)
  • be run individually, stopping one container to start the other

Step 7: Open the Jupyter notebooks

This step opens a browser to interact with the Jupyter notebooks and use the MoSeq2 package suite on your data.

Click on the Containers/Apps tab to locate the running container. Hover over the running container and click the OPEN IN BROWSWER button to open your browser and use the Jupyter notebooks.

Input moseq as the password when Jupyter prompts you for one.

After inputting the password moseq, you should see:

1. 3 MoSeq notebooks (files with the extension .ipynb) that were copied into your data folder
2. the contents of your local data folder. In the example shown below, the data folder contains 20 recording sessions from our "small dataset" example.

Open the extraction and modeling notebook to begin using the MoSeq2 package!

Step 8: [Optional] Using the command-line interface (CLI) from the container

The container includes the MoSeq2 CLI if you prefer that mode of working with MoSeq. Open a Terminal and run the following command to start a bash shell from a running container:

docker exec -it <container name> /bin/bash

We previously named our container "moseq" in the example above, so we run the following command to start a bash shell in the "moseq" container:

docker exec -it moseq /bin/bash

Alternatively, you can hover over the running container and click the CLI button to open a sh shell (sh has fewer convenient features so we recommend the approach above).

Although not necessary, you can verify that all the MoSeq2 related packages are in the container by printing the version number of each package in the CLI.

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

Step 9: Stopping the container

Exit/stop the container when you are done with your extraction or analysis session by clicking the STOP button.

You can restart the container and pick up where you left off by clicking the START button.

Removing containers and images

You can see all the running containers and images on Docker Dashboard.

If you need to delete your containers, go to the Containers/Apps tab and click the trash can to delete the container.

You can pull the latest version of the MoSeq container image or delete the image in the following window.

Try out MoSeq with some test data

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