Analysis Troubleshooting

Analysis FAQ

Q: My ROI is not being detected at all, what parameters do I change to fix this?
A: Edit the following configuration parameters to control how the ROI is being computed:

Set the camera_type to 'manual'.
Increase the noise_tolerance for more depth values to be counted in the depth range (included in the ROI).
Edit the bg_roi_weights to accept larger depth value regions. The bg_roi_weights parameters is a 3-tuple describing (area, extent, dist).
- Increase the area value to be less restrictive.
- Set the dist value to equal the number of corners (1 for circular arenas), and
- Scan the extent values [0.1, 1, 2, 4, 10], sticking with the value that yields the best ROI.
To edit the parameters in the Jupyter Notebook, use the following example template (as seen in the Interactive ROI Tool Cell): config_data['camera_type'] = 'manual' config_data['noise_tolerance'] = 100 config_data['bg_roi_weights'] = (1, .1, 1)
To edit the parameters using the CLI, using the parameter flags --camera-type manual, etc.

Q: My crowd movies are empty and the movies are 0 bytes in size but I don't see any errors, why?
A: You likely are using the wrong version of FFmpeg, or don't have the proper movie encoders. Make sure you download FFmpeg like so: conda install -c conda-forge ffmpeg.

Q: How do I load the raw data in Python or MATLAB?
A: The depth frames are saved as binary data in 16-bit little Endian format. See this function to load in raw data in Python. In MATLAB use the following code:

width=512;
height=424;
start_point=1; % start frame
frames_to_read=100; % frames to read

fid=fopen(PATH_TO_DATA, 'rb');

bytes_per_frame = height * width * 2; %2 bytes per int16
offset = bytes_per_frame * (start_point - 1);
fseek(fid, offset, 'bof'); % seek to the correct point

% note that width and height are permuted here
raw_frames = reshape(fread(fid, (width * height) * frames_to_read, '*int16'), [width height frames_to_read]);

Q: The ROI detection isn't working, how do I fix this?
A: First, make sure that the floor of the arena is between the bounds set by --bg-roi-depth-range in moseq2-extract find-roi or moseq2-extract extract. If that doesn't work you will likely need to tweak --bg-roi-weights, which set weights for the area, extent, and distance from the center for the ROI, e.g. if you only want the largest ROI by area, set to --bg-roi-weights 1 0 0, which excludes extent and distance altogether. The ROI detector finds all planes within the specified depth range and ranks them according to their area (higher weight favors larger area), extent (using the OpenCV contour definition, higher weight favors larger extent), and distance from the center (higher weight favors closeness to the center). Note that only the relative magnitudes are used, the absolute magnitudes of the weights do not matter. If you find it hard to exclude walls, also turn on the gradient filter with --bg-roi-gradient-filter True.

Q: I have specified the group names for my experimental groups but I receive warning messages in the modeling step and in the compute moseq_df step in the MoSeq2 Anlaysis Visualiation Notebook. Example warnings are:

UserWarning: groups key not found in h5 file, assigning each session to unique group...
  warnings.warn('groups key not found in h5 file, assigning each session to unique group...')

 UserWarning: Group labels from index.yaml and model results do not match! Setting group labels to ones used in the model.
  warnings.warn('Group labels from index.yaml and model results do not match! Setting group labels ')

A: If you train the modeling using the CLI, double check if you have passed in the --index ./moseq2-index.yaml in the moseq2-model learn-model command.

Troubleshooting output from MoSeq Pipeline

Troubleshooting for Not Passing Sessions in Interactive ROI Detection Tool

ROI Not Detected Correctly

Adjust the Depth Range Selector to include the depth range of the detected bucket floor distance (which can be found by hovering over the Background image with your mouse). You can also manually enter slider values by clicking on the numbers. If the mouse seems to be cropped when at the bucket edge, increase the "dilate iterations" settings to enlarge the size of the included floor area.

Too Much Noise Around Mouse Body

Use the Rodent Height Threshold Slider to remove any noise/speckle from the bucket floor or walls. Ensure the min height parameter is small enough to only filter out floor reflections. Do not exclude too much of the mouse's body. Ensure the max height parameter is large enough to include the largest possible mouse height, (i.e., when the mouse is rearing). A reasonable value is around 100 mm for Kinect v2 recordings. Hover over the mouse in either of the bottom two plots to explore its height.

Flagged Session

If a session is flagged, click on the session and adjust the parameters until the session passes. Click Save Parameters to save the parameters. The Save ROI button can be used to manually accept a session's parameter set.

Note: if the cell seems to be running out of memory after the first use, set compute_all_bgs=False to reduce the memory pressure.

Possible PCA Problems

Good PCA Output Examples

Principal Components

Scree Plot

Bad Scree Plot Example

Problem description: Cannot achieve an explained variance of over 90% from less than 15 Principal Components (PCs).

Possible Solutions:

Check if the crop size is too large, if so, decrease it and re-extract your data.
Try (incrementally) adjusting the spatial and temporal filtering kernel sizes in the PCA step. Generally, increasing temporal smoothing will aid in increasing explained variance, but can potentially throw out data.
If there are cable occlusions, try setting missing_data=True. Using an iterative PCA to reconstruct the PCs can aid in increasing the explained variance ratio.
Increase the size of your dataset. If your dataset is too small, it may contribute to overfitting PCs.

Bad Principal Component Example

Problem description: PCs look noisy, or are not representative of realistic mouse body regions.

Possible Solutions:

Ensure that an appropriate amount of spatial and temporal filtering is applied.
If you set missing_data=True, adjust spatial and temporal filtering, and try adjusting the number of PCs used for reconstruction (the recon_pcs parameter).
Acquire and extract more data, then try again.

Possible Model-Free Changepoints Problems

Good changepoint

Bad changepoint

Problem description: Model-free syllable changepoint distances distribution is incorrectly skewed/too sparse and/or changepoint mode duration is less than 0.2s.

Possible Solutions: Try retraining the PCA with adjusted spatial and temporal filtering kernel sizes. Ensure your extracted data is correct with minimal flips. If the extraction version of the mouse is too noisy, then the PC trajectories cannot be accurately applied to the data. Get more data and try again.

Problem description: The videos don't show up in the interactive widgets.

Possible Solutions:

Here is an example of videos not displaying correctly in the Review Extraction Output widget. safari video