The MoSeq2 Analysis Visualization Notebook offers a series of interactive widgets for you to explore model results. Besides the Juypter notebook, MoSeq also offers a series of Command Line Interface (CLI) tools to visualize model results. You can access a short description of the tool by running moseq2-viz --help in the Terminal. You can use --help to access the available options for a specific command, eg. moseq2-viz make-crowd-movie --help.

You can use the MoSeq2 Analysis Visualization Notebook to explore model results and generate model results interactively. You can find the documentation for the notebook here.

If you are using Conda, and the environment name is moseq2-app, please run conda activate moseq2-app to activate the environment. If you are using the Docker container, please make sure your Docker is up and running, and you should see moseq next to your terminal prompt.

You can verify that all MoSeq modules by running

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

Note: if you are modeling more than one experimental group, you should first assign group labels in the moseq2-index.yaml file before creating any visualizations. You can find more information on using CLI to assign group labels here.

At this stage, you should have a folder for the PCA output, such as _pca, and a folder for trained AR-HMM model(s), such as model_dir. To better organize the output, we recommend that you set your working directory to be <base_dir>.

.                       ** current working directory
├── moseq2-index.yaml  
├── aggregate_results/  ** the folder that contains aggregated extraction results
├── _pca/               ** the folder that contains pca and changepoint outputs
├── model_dir/          ** the folder that contains trained AR-HMM model(s)
│   └── model.p   ** a trained AR-HMM model
├── session_1/          ** the folder containing all of a single session's data
...
└── session_n/

This command will save a plot model_pca_changepoints.png/pdf showing the comparative changepoint distribution curves between the trained model and the PCA scores changepoints.

The command supports comparison concerning two objectives: duration and jsd. duration finds the model where the median syllable duration best matches that of the principal components' changepoints. jsd finds the model where the distribution of syllable durations best match that of the principal components' changepoints.

If there are multiple models in the inputted folder, then the outputted figure will plot multiple dashed distribution curves representing distributions of unselected models and 2 solid distribution curves that show the "Best"/chosen model and the principal compoments' changepoint durations.

moseq2-viz get-best-model model_dir/ _pca/changepoints.h5 model_pca_changepoints

Syllable crowd movies are movies that show the mice's behavior within the syllable. They act as a tool to understand what behavior the syllables represent. The following commands generate crowd movies for the syllables. You can use the crowd movies to understand the mouse's behavior during the syllables, and you can use the method of your choice to record descriptions and behavior labels for the syllables. you can access information about the CLI flags associated with the command by running moseq2-viz make-crowd-movies --help.

The following command generates crowd movies for the top 40 syllables with a maximum of 20 different examples of the syllable. The generated crowd movies will be in crowd_movies folder.

# Assuming your working directory is base_dir
moseq2-viz make-crowd-movies moseq2-index.yaml model_dir/my_model.p --max-syllable 40 --max-examples 20

The following command generates a crowd movie of syllable "1" with 40 examples, which is the default value for --max-examples.

# Assuming your working directory is base_dir
moseq2-viz make-crowd-movies moseq2-index.yaml model_dir/my_model.p --specific-syllable 1 

The following command generates separate group crowd movies of syllable "1". If there are 2 groups in the experiment, 2 crowd movies will be generated.

# Assuming your working directory is base_dir
moseq2-viz make-crowd-movies moseq2-index.yaml model_dir/my_model.p -separate-by groups --specific-syllable 1

The following command generates separate session crowd movies of syllable "1". If there are 20 sessions in the experiment, 20 crowd movies will be generated.

# Assuming your working directory is base_dir
moseq2-viz make-crowd-movies moseq2-index.yaml model_dir/my_model.p -separate-by sessions -s session1 -s session2 --specific-syllable 1

The extraction step in MoSeq extracts kinematics-related scalar values. Using the following visualization tool to visualize the scalar values and position heatmaps can help you identify possible outliers.

Run the following command to visualize the mean and standard deviation of velocity 2d, velocity 3d, average height, width, and length.

# Assuming your working directory is base_dir
moseq2-viz plot-scalar-summary moseq2-index.yaml

Run the following command to visualize the position heatmaps by groups.

# Assuming your working directory is base_dir
moseq2-viz plot-group-position-heatmaps moseq2-index.yaml

Run the following command to visualize position heatmap by sessions.

# Assuming your working directory is base_dir
moseq2-viz plot-verbose-position-heatmaps moseq2-index.yaml

The following commands generate plots for syllable statistics. You can use the plots to see syllable usage distribution and understand behavior differences among experimental groups. You can access information about the CLI flags associated with the command by running moseq2-viz plot-stats --help.

Run the following command to plot usages for syllables.

# Assuming your working directory is base_dir
moseq2-viz plot-stats moseq2-index.yaml model_dir/my_model.p --stat usage --group group1 --group group2

Run the following command to plot the average velocity for syllables.

# Assuming your working directory is base_dir
moseq2-viz plot-stats moseq2-index.yaml model_dir/my_model.p --stat velocity_2d_mm --group group1 --group group2

Run the following command to plot syllable usages sorted by usage difference between two groups, eg. group1 and group2 in the following command.

# Assuming your working directory is base_dir
moseq2-viz plot-stats moseq2-index.yaml model_dir/my_model.p --stat usage -o diff --ctrl-group group1 --exp-group group2

Run the following command to plot the syllable transition graphs and their differences. The transition plot for each group will be plotted separately.

# Assuming your working directory is base_dir
moseq2-viz plot-transition-graph moseq2-index.yaml model_dir/my_model.p

If you are interested in plotting specific group(s), you could use -- group to specify the group(s) to plot.

# Assuming your working directory is base_dir
moseq2-viz plot-transition-graph --group drugA --group drugB moseq2-index.yaml model_dir/my_model.p

moseq2-extract [Repository][Documentation]

moseq2-pca [Repository][Documentation]

moseq2-model [Repository][Documentation]

moseq2-viz [Repository][Documentation]