moseq2_viz package

CLI Module

moseq2-viz

moseq2-viz [OPTIONS] COMMAND [ARGS]...

Options

--version

Show the version and exit.

Default:

False

add-group

Change group name for the sessions in index file (moseq2-index.yaml)

moseq2-viz add-group [OPTIONS] INDEX_FILE

Options

-k, --key <key>

metadata field to search for value to match

Default:

SubjectName

-v, --value <value>

Value to match for

Default:

Mouse

-g, --group <group>

Group name to set

Default:

Group1

-e, --exact

Exact match only

Default:

False

--lowercase

Set metadata info to lower case for matching

Default:

False

-n, --negative

Negative match (everything that does not match is included)

Default:

False

Arguments

INDEX_FILE

Required argument

copy-h5-metadata-to-yaml

Copy metadata within an h5 file to a yaml file.

moseq2-viz copy-h5-metadata-to-yaml [OPTIONS]

Options

-i, --input-dir <input_dir>

Directory to find h5 files

Default:

/home/wingillis/dev/moseq/moseq2-viz/docs

get-best-model

Get the model closest to model-free Changepoints, given the objective

moseq2-viz get-best-model [OPTIONS] MODEL_DIR CP_PATH OUTPUT_FILE

Options

--plot-all

Plot all included model results

Default:

False

--ext <ext>

Model extensions to look for in input directory

Default:

p

--fps <fps>

Frames per second

Default:

30

--objective <objective>

The objective finds the best model when comparing with model-free changepoints

Default:

duration (mean match)

Arguments

MODEL_DIR

Required argument

CP_PATH

Required argument

OUTPUT_FILE

Required argument

make-crowd-movies

write movies of overlaid examples of the rodent perform a given syllable

moseq2-viz make-crowd-movies [OPTIONS] INDEX_FILE MODEL_PATH

Options

--max-syllable <max_syllable>

index of the max syllable to include

Default:

40

-m, --max-examples <max_examples>

number of examples to show

Default:

40

--processes <processes>

number of processes to use for rendering crowd movies. Default None uses every process

--separate-by <separate_by>

generate crowd movies by specified grouping

Default:

default

Options:

default | groups | sessions | subjects

--specific-syllable <specific_syllable>

index of the specific syllable to render

-s, --session-names <session_names>

specific sessions to create crowd movies from

Default:

--sort <sort>

sort syllables by usage

Default:

True

--count <count>

How to quantify syllable usage

Default:

usage

Options:

usage | frames

-o, --output-dir <output_dir>

Path to store files

Default:

/home/wingillis/dev/moseq/moseq2-viz/docs/crowd_movies

--gaussfilter-space <gaussfilter_space>

x sigma and y sigma for Gaussian spatial filter to apply to data

Default:

0, 0

--medfilter-space <medfilter_space>

kernel size for median spatial filter

Default:

0

--min-height <min_height>

Minimum height for scaling videos

Default:

5

--max-height <max_height>

Maximum height for scaling videos

Default:

80

--raw-size <raw_size>

frame dimension of original videos

Default:

512, 424

--scale <scale>

Scaling from pixel units to mm

Default:

1

--cmap <cmap>

Name of valid Matplotlib colormap for false-coloring images

Default:

jet

--max-dur <max_dur>

Exclude syllables longer than this number of frames (None for no limit)

Default:

60

--min-dur <min_dur>

Exclude syllables shorter than this number of frames

Default:

0

--legacy-jitter-fix <legacy_jitter_fix>

Set to true if you notice jitter in your crowd movies

Default:

False

--frame-path <frame_path>

Path to depth frames in h5 file

Default:

frames

-p, --progress-bar

Show verbose progress bars.

Default:

False

--pad <pad>

Pad crowd movie videos with this many frames.

Default:

30

--seed <seed>

Defines random seed for selecting syllable instances to plot

Default:

0

Arguments

INDEX_FILE

Required argument

MODEL_PATH

Required argument

plot-group-position-heatmaps

Plots position heatmaps for each group

moseq2-viz plot-group-position-heatmaps [OPTIONS] INDEX_FILE

Options

--output-file <output_file>
Default:

/home/wingillis/dev/moseq/moseq2-viz/docs/group_heat_map

--normalize

normalize the PDF so that min and max values range from 0-1

Default:

False

Arguments

INDEX_FILE

Required argument

plot-scalar-summary

Plot a scalar summary scatter plot for each group.

moseq2-viz plot-scalar-summary [OPTIONS] INDEX_FILE

Options

--output-file <output_file>
Default:

/home/wingillis/dev/moseq/moseq2-viz/docs/scalars

-c, --colors <colors>

Colors to plot groups with.

Arguments

INDEX_FILE

Required argument

plot-stats

Plot syllable usages with different sorting,coloring and grouping capabilities

moseq2-viz plot-stats [OPTIONS] INDEX_FILE MODEL_FIT

Options

--stat <stat>

Statistic to plot

Default:

usage

--output-file <output_file>

Filename to store plot

Default:

/home/wingillis/dev/moseq/moseq2-viz/docs/syll_stat

--sort <sort>

Sort syllables by usage

Default:

True

--figsize <figsize>

Figure size of the plotted figure.

Default:

10, 5

--count <count>

How to relabel syllables

Default:

usage

Options:

usage | frames

--max-syllable <max_syllable>

Index of max syllable to render

Default:

40

-g, --group <group>

Name of group(s) to show

-o, --ordering <ordering>

How to order syllables in plot

Default:

stat

--ctrl-group <ctrl_group>

Name of control group

--exp-group <exp_group>

Name of experimental group

-c, --colors <colors>

Colors to plot groups with

Arguments

INDEX_FILE

Required argument

MODEL_FIT

Required argument

plot-transition-graph

Plot the transition graph depicting the transition probabilities between syllables.

moseq2-viz plot-transition-graph [OPTIONS] INDEX_FILE MODEL_FIT

Options

--max-syllable <max_syllable>

Index of max syllable to render

Default:

40

-g, --group <group>

the groups to include in the transition graph

--output-file <output_file>

Filename to store plot

Default:

/home/wingillis/dev/moseq/moseq2-viz/docs/transitions

--normalize <normalize>

How to normalize transition probabilities

Default:

bigram

Options:

bigram | rows | columns

--edge-threshold <edge_threshold>

Threshold for edges to show

Default:

0.001

--usage-threshold <usage_threshold>

Threshold for nodes to show

Default:

0

--layout <layout>

networkx layout algorithm

Default:

spring

-k, --keep-orphans

Show orphaned nodes

Default:

False

--orphan-weight <orphan_weight>

Weight for non-existent connections

Default:

0

--arrows

Show arrows

Default:

False

--sort <sort>

Sort syllables by usage

Default:

True

--count <count>

How to quantify syllable usage

Default:

usage

Options:

usage | frames

--edge-scaling <edge_scaling>

Scale factor from transition probabilities to edge width

Default:

250

--node-scaling <node_scaling>

Scale factor for nodes by usage

Default:

100000.0

--scale-node-by-usage <scale_node_by_usage>

Scale node sizes by usages probabilities

Default:

True

--width-per-group <width_per_group>

Width for figure canvas per group

Default:

8

Arguments

INDEX_FILE

Required argument

MODEL_FIT

Required argument

plot-verbose-position-heatmaps

Plots a position heatmap for each session in the index file.

moseq2-viz plot-verbose-position-heatmaps [OPTIONS] INDEX_FILE

Options

--output-file <output_file>
Default:

/home/wingillis/dev/moseq/moseq2-viz/docs/session_heat_map

--normalize

normalize the PDF so that min and max values range from 0-1

Default:

False

Arguments

INDEX_FILE

Required argument

GUI Module

GUI functions for visualizing model results.

moseq2_viz.gui.add_group(index_file, by='SessionName', value='default', group='default', exact=False, lowercase=False, negative=False)

Update the index file (moseq2-index.yaml) group names with user defined group names.

Args: index_file (str): path to index file by (str): session metadata field to find the match for the value value (str or list): value(s) to search for in the by field group (str or list): Respective group name(s) to set corresponding sessions as. exact (bool): indicate whether to search for exact match. lowercase (bool): indicate whether to convert all searched for names to lowercase. negative (bool): whether to update the inverse of the found selection.

moseq2_viz.gui.get_best_fit_model(progress_paths, output_file=None, plot_all=False, fps=30, ext='p', objective='duration (mean match)')

Return the best model in the model foder that is closest to model free changepoint in the given objective.

Args: progress_paths (dict): Dictionary containing paths the to model directory and pc scores file output_file (str): fiename for the comparison plot plot_all (bool): flag that Indicates whether to plot all the models. fps (int): Frames per second. ext (str): File extension to search for models with objective (str): The objective to compare the results between the models and the model free changepoint.

Returns: best_fit_model (str): Path tp best fit model

moseq2_viz.gui.get_groups_command(index_file)

Return the group names and print the number of groups, sessions and group names.

Args: index_file (str): path to index file

Returns: (int): number of unique groups

Utilities Module

General utility functions fors loading and organizing data.

moseq2_viz.util.assert_model_and_index_uuids_match(model, index)

Assert that both the model and index file contain the same set of UUIDs.

Args: model (str or dict): str path to the model or dictionary of model. index (str or dict): str path to index file (moseq2-index.yaml) or dictionary of index data.

moseq2_viz.util.camel_to_snake(s)

Convert CamelCase to snake_case

Args: s (str): string to convert to snake case

Returns: (str): snake_case string

moseq2_viz.util.clean_dict(dct)

Cast numpy.array into lists and np.generic data into scalar values.

Args: dct (dict): dictionary with values to clean.

Returns: (dict): dictionary with standardized value types.

moseq2_viz.util.get_index_hits(config_data, metadata, key, v)

Search for matching keys in given index file metadata dict and return a list of booleans indicating that a session was found.

Args: config_data (dict): dictionary containing boolean search filters [lowercase, negative] metadata (list): list of session metadata dict objects key (str): metadata key being searched for v (str): value of the corresponding key to be found

Returns: hits (list): list of booleans indicating the found sessions to be updated in add_group_wrapper()

moseq2_viz.util.get_metadata_path(h5file)

Return path within h5 file that contains the kinect extraction metadata.

Args: h5file (str): path to h5 file.

Returns: (str): path to acquistion metadata within h5 file.

moseq2_viz.util.get_sorted_index(index_file: str) → dict

Return the sorted index from an index_file path.

Args: index_file (str): path to index file.

Returns: sorted_ind (dict): dictionary of loaded sorted index file contents

moseq2_viz.util.get_timestamps_from_h5(h5file: str) → ndarray

Return a dict of timestamps from h5file.

Args: h5file (str): path to h5 file.

Returns: (np.ndarray): timestamps from extraction within the h5file.

moseq2_viz.util.h5_filepath_from_sorted(sorted_index_entry: dict) → str

Get the h5 extraction file path from a sorted index entry

Args: sorted_index_entry (dict): get filepath from sorted index.

Returns: (str): a str containing the extraction filepath

moseq2_viz.util.h5_to_dict(h5file, path: str = '/') → dict

Load h5 dict contents to a dict variable.

Args: h5file (str or h5py.File): file path to the given h5 file or the h5 file handle path (str): path to the base dataset within the h5 file. Default: /

Returns: out (dict): dictionary of all h5 contents

moseq2_viz.util.load_changepoint_distribution(cpfile)

Load changepoint durations from given model free changepoints file.

Args: cpfile (str): Path to changepoints h5 file.

Returns: (numpy.array): Array of changepoint durations.

moseq2_viz.util.load_timestamps(timestamp_file, col=0)

Read timestamps from space delimited text file.

Args: timestamp_file (str): path to timestamp file col (int): column to load.

Returns: ts (np.ndarray): loaded array of timestamps

moseq2_viz.util.parse_index(index: Union[str, dict]) → tuple

Load an index file, and use extraction UUIDs to sort index.

Args: index (str or dict): if str, must be a path to the index file. If dict, must be the unsorted index.

Returns: index (dict): loaded index file contents in a dictionary sorted_index (dict): index where the files have been sorted by UUID and pca_score path.

moseq2_viz.util.read_yaml(yaml_path: str)

Read a given yaml file path into a dictionary object.

Args: yaml_path (str): path to yaml file to read.

Returns: loaded (dict): loaded yaml file contents.

moseq2_viz.util.recursive_find_h5s(root_dir=None, ext='.h5', yaml_string='{}.yaml')

Recursively find h5 files, along with yaml files with the same basename.

Args: root_dir (str): path to directory containing h5, if None, searches the current working directory ext (str): extension to search for. yaml_string (str): yaml file format name.

Returns: h5s (list): list of paths to h5 files dicts (list): list of paths to metadata files yamls (list): list of paths to yaml files

moseq2_viz.util.star(f='__no__default__', args='__no__default__')

Apply a function to a tuple of args, by expanding the tuple into each of the function’s parameters.

Args: f (function): a function that takes multiple arguments args (tuple): : a tuple to expand into f

Returns: the output of f

moseq2_viz.util.strided_app(a, L, S)

Slice a numpy.array into subarrays with a given stride

Args: a (numpy.array): array to get subarrays from. L (int): window length. S (int): stride size.

Returns: (np.ndarray): sliced subarrays

Visualization Module

Data pre-processing and visualization functions for model results.

moseq2_viz.viz.clean_frames(frames, medfilter_space=None, gaussfilter_space=None, tail_filter=None, tail_threshold=5)

Smooth frames using Median or Gaussian filters.

Args: frames (numpy.array): frames to filter. medfilter_space (list): Median space filter kernel size, list of length 1. gaussfilter_space (list): x sigma and y sigma for Gaussian space filter, list of length 2. tail_filter (cv2.getStructuringElement): structuringElement to filter out mouse tails. tail_threshold (int): filtering threshold value

Returns: out (numpy.array): filtered numpy array.

moseq2_viz.viz.make_crowd_matrix(slices, nexamples=50, pad=30, raw_size=(512, 424), outmovie_size=(300, 300), frame_path='frames', crop_size=(80, 80), max_dur=60, min_dur=0, scale=1, center=False, rotate=False, select_median_duration_instances=False, min_height=10, legacy_jitter_fix=False, seed=0, **kwargs)

Creates crowd movie video numpy array.

Args: slices (np.ndarray): video slices of specific syllable label nexamples (int): maximum number of mice to include in crowd_matrix video pad (int): number of frame padding in video raw_size (tuple): video dimensions. frame_path (str): variable to access frames in h5 file crop_size (tuple): mouse crop size max_dur (int or None): maximum syllable duration. min_dur (int): minimum syllable duration. scale (int): mouse size scaling factor. center (bool): boolean flag that indicates whether mice are centered. rotate (bool): boolean flag that indicates wehther to rotate mice and orient them. select_median_duration_instances (bool): flag that indicates wehther to select examples with syallable duration closer to median. min_height (int): minimum max height from floor to use. legacy_jitter_fix (bool): flag that indicates wehther to apply jitter fix for K1 camera. kwargs (dict): extra keyword arguments

Returns: crowd_matrix (np.ndarray): crowd movie for a specific syllable.

moseq2_viz.viz.plot_cp_comparison(model_results, pc_cps, plot_all=False, best_model=None, bw_adjust=0.4)

Plot the duration distributions for model labels and model free changepoints.

Args: model_cps (dict): Multiple parsed model results aggregated into a single dict. pc_cps (np.array): Computed PC changepoints plot_all (bool): Boolean flag that indicates whether to plot all model changepoints for all keys included in model_cps dict. best_model (str): key name to the model with the closest median syllable duration bw_adjust (float): fraction to modify bandwith of kernel density estimate. (lower = higher definition)

Returns: fig (pyplot.figure): syllable usage ordered by frequency, 90% usage marked ax (pyplot.axis): plotted scalar axis

moseq2_viz.viz.plot_mean_group_heatmap(pdfs, groups, normalize=True, norm_color=<matplotlib.colors.LogNorm object>)

Compute and plot the overall group mean of the computed PDFs.

Args: pdfs (list): list of 2d probability density functions (heatmaps) describing mouse position. groups (list): list of groups to compute means and plot normalize (bool): flag to normalize the pdfs between 0-1 norm_color (mpl.colors Color Scheme or None): indicates a color scheme to use when plotting heatmaps.

Returns: fig (pyplot figure): plotted scalar scatter plot

moseq2_viz.viz.plot_syll_stats_with_sem(scalar_df, syll_info=None, sig_sylls=None, stat='usage', ordering='stat', max_sylls=40, groups=None, ctrl_group=None, exp_group=None, colors=None, join=False, figsize=(10, 5))

Plot a line and/or point-plot of a given pre-computed syllable statistic (usage, duration, or speed), with a SEM error bar with respect to the group.

Args: scalar_df (pandas.DataFrame): dataframe containing the summary statistics about scalars and syllable data (mean_df/stats_df) syll_info (dict): dictionary of syllable numbers mapped to dict containing the label, description and crowd movie path. sig_sylls (list): List of syllable numbers that are statistically significant to optionally mark in the graph. stat (str): choice of statistic to plot: either usage, duration, or speed ordering (str, list, None): statistics for sorting syllables on or the list of syllable orders. max_sylls (int): the index of the maximum number of syllables to include groups (list): list of groups to include in plot. If groups=None, all groups will be plotted. ctrl_group (str): Control group to graph. exp_group (str): Experimental group to compare with control group. colors (list): list of user-selected colors to represent the data join (bool): flag that indicate whether to connect points of pointplot figsize (tuple): tuple value of length of 2, representing (columns x rows) of the plotted figure dimensions

Returns: fig (pyplot.figure): plotted scalar scatter plot legend (pyplot.legend): figure legend

moseq2_viz.viz.plot_verbose_heatmap(pdfs, sessions, groups, subjectNames, normalize=False, norm_color=<matplotlib.colors.LogNorm object>)

Plot the PDF position heatmap for each session, titled with the group and subjectName.

Args: pdfs (list): list of 2d probability density functions (heatmaps) describing mouse position. sessions (list): list of sessions corresponding to the pdfs indices groups (list): list of groups corresponding to the pdfs indices subjectNames (list): list of subjectNames corresponding to the pdfs indices normalize (bool): flag to normalize the pdfs between 0-1 norm_color (mpl.colors object): indicates a color scheme to use when plotting heatmaps.

Returns: fig (pyplot.figure): plotted scalar scatter plot

moseq2_viz.viz.position_plot(scalar_df, centroid_vars=['centroid_x_mm', 'centroid_y_mm'], sort_vars=['SubjectName', 'uuid'], group_var='group', plt_kwargs={'linewidth': 1})

Create a position summary graph that shows all the mice’s centroid path throughout the respective sessions.

Args: scalar_df (pandas.DataFrame): dataframe containing all scalar data centroid_vars (list): list of scalar variables to track mouse position sort_vars (list): list of variables to sort the dataframe by. group_var (str): groups df column to graph position plots for. plt_kwargs (dict): extra keyword arguments for plt.plot

Returns: fig (pyplot.figure): matplotlib figure object ax (pyplot.axis): matplotlib axis object g (sns.FacetGrid): FacetGrid object the data was plotted with

moseq2_viz.viz.save_fig(fig, output_file, suffix=None, **kwargs)

Save matplotlib figures to PNG and PDF formats.

Args: fig (pyplot.Figure): open figure to save output_file (str): file name for the figure without the file extension suffix (str): string to append to the end of output_file kwargs (dict): dictionary containing additional figure saving parameters.

Returns:

moseq2_viz.viz.scalar_plot(scalar_df, sort_vars=['group', 'uuid'], group_var='group', show_scalars=['velocity_2d_mm', 'velocity_3d_mm', 'height_ave_mm', 'width_mm', 'length_mm'], headless=False, colors=None, plt_kwargs={'aspect': 0.8, 'height': 2})

Create scatter plot of given scalar variables representing extraction results.

Args: scalar_df (pandas.DataFrame): dataframe containing scalar data. sort_vars (list): list of variables to sort the dataframe by. group_var (str): groups scalar plots into separate distributions. show_scalars (list): list of scalar variables to plot. headless (bool): bool flag to run in headless environment colors (list): list of color strings to indicate groups plt_kwargs (dict): extra arguments for the swarmplot

Returns: fig (pyplot figure): plotted scalar scatter plot ax (pyplot axis): plotted scalar axis

Subpackages