Analysis: visualization

Finally we have some PC coefficients and scores and a model fit. Let's say your directory now looks like this,

.
├── _pca
│   ├── changepoints.h5
│   ├── changepoints_dist.pdf
│   ├── changepoints_dist.png
│   ├── pca.h5
│   ├── pca.yaml
│   ├── pca_components.pdf
│   ├── pca_components.png
│   ├── pca_scores.h5
│   ├── pca_scree.pdf
│   └── pca_scree.png
├── my_model.p
├── session_20180503101758
│   ├── depth.dat
│   ├── depth_ts.txt
│   ├── metadata.json
│   ├── proc
│   │   ├── bground.tiff
│   │   ├── first_frame.tiff
│   │   ├── results_00.h5
│   │   ├── results_00.mp4
│   │   ├── results_00.yaml
│   │   └── roi_00.tiff
│   ├── rgb.mp4
│   └── rgb_ts.txt
└── session_20180503112433
    ├── depth.dat
    ├── depth_ts.txt
    ├── metadata.json
    ├── proc
    │   ├── bground.tiff
    │   ├── first_frame.tiff
    │   ├── results_00.h5
    │   ├── results_00.mp4
    │   ├── results_00.yaml
    │   └── roi_00.tiff
    ├── rgb.mp4
    └── rgb_ts.txt

Let's make an index file which will tell MoSeq2 where to find the extractions and the PCA results,

moseq2-viz generate-index 

If you used a custom filename, you can pass this as an option to generate-index (use --help to figure out which options to use here). Now we can make some crowd movies,

moseq2-viz make-crowd-movies moseq2-index.yaml my_model.p

This will then generate crowd movies for your fit model. To look at the usages,

moseq2-viz plot-usages moseq2-index.yaml my_model.p

If you want to plot multiple groups, first you need to specify the groups in your index file. If you haven't specified any groups the contents might look like this,

files:
- path:
  - session_20180503101758/proc/results_00.h5
  - session_20180503101758/proc/results_00.yaml
  uuid: c89bbf91-b589-450f-b4b6-118310b1dc25
  group: default
  metadata:
    SubjectName: mouse1
    SessionName: test
    NidaqChannels: 0
    NidaqSamplingRate: 0.0
    DepthResolution:
    - 512
    - 424
    IsLittleEndian: true
    DepthDataType: UInt16[]
    ColorResolution:
    - 512
    - 424
    ColorDataType: Byte[]
    StartTime: '2018-05-03T10:20:15.5562372-04:00'
- path:
  - session_20180503112433/proc/results_00.h5
  - session_20180503112433/proc/results_00.yaml
  uuid: 2251ec08-91e9-4260-97f5-ee1e0aa15d6a
  group: default
  metadata:
    SubjectName: mouse2
    SessionName: test
    NidaqChannels: 0
    NidaqSamplingRate: 0.0
    DepthResolution:
    - 512
    - 424
    IsLittleEndian: true
    DepthDataType: UInt16[]
    ColorResolution:
    - 512
    - 424
    ColorDataType: Byte[]
    StartTime: '2018-05-03T11:25:41.4688248-05:00'
pca_path: _pca/pca_scores.h5

Here, the metadata for each session, stored in metadata.json, comes in handy, since this is loaded into the metadata field for each file, which is now assigned a unique key (so if you move your data around we can keep track of it). Say you have recorded two sessions from two mice, each from a separate treatment group, which we'll call group1 and group2. You can use moseq2-viz add-group` to specify groups in the index.

moseq2-viz add-group -k SubjectName -v "mouse1" -g group1 moseq2-index.yaml

MoSeq2-viz will search all of the sessions, and any sessions where the SubjectName is "mouse1" will be assigned to group1. If you made a mistake and you want to change the metadata for a particular session, you can modify the yaml file directory.

moseq2-viz add-group -k SubjectName -v "mouse2" -g group2 moseq2-index.yaml

If you have a list of values you want to add to a group, use the following syntax,

moseq2-viz add-group -k SubjectName -v "mouse3" -v "mouse4" -v "mouse8" -v "mouse100" -g "groupd" moseq2-index.yaml

With the groups specified we can visualize things a few different ways. First, we can plot the syllable usages for each group (average and bootstrap confidence interval shown on a per session basis, i.e. one sample is one session),

moseq2-viz plot-usages moseq2-index.yaml my_model.p --group group1 --group group2

Next we can visualize what we call scalars such as velocity and average height,

moseq2-viz plot-scalar-summary moseq2-index.yaml

You don't need to specify groups or a model here, by default each group is shown separately. Finally, we can visualize the transition graphs and their differences,

moseq2-viz plot-transition-graph moseq2-index.yaml my_model.p --group group1 --group group2

Beyond that, we have included convenience functions for packing the data into dataframes for custom plotting and analysis. See the notebook linked here.