moseq2_viz.scalars package

Scalars - Utilities Module

Utility functions for handling all scalar data-related operations.

moseq2_viz.scalars.util.compute_all_pdf_data(scalar_df, normalize=False, centroid_vars=['centroid_x_mm', 'centroid_y_mm'], key='SubjectName', bins=20)

Compute a position PDF for all sessions and return the pdfs with corresponding lists of groups, session uuids, and subjectNames.

Args: scalar_df (pandas.DataFrame): DataFrame containing all scalar data + uuid columns for all stacked sessions normalize (bool): boolean flag that ndicates whether normalize the pdfs. centroid_vars (list): list of strings for column values to use when computing mouse position. key (str): metadata column to return info from.

Returns: pdfs (list): list of 2d np.arrays of PDFs for each session. groups (list): list of strings of groups corresponding to pdfs index. sessions (list): list of strings of session uuids corresponding to pdfs index. subjectNames (list): list of strings of subjectNames corresponding to pdfs index.

moseq2_viz.scalars.util.compute_mean_syll_scalar(scalar_df, scalar='velocity_3d_mm', max_sylls=40, syllable_key='labels (usage sort)')

Computes the mean syllable scalar-value based on the time-series scalar dataframe and the selected scalar.

Args: scalar_df (pandas.DataFrame): DataFrame containing all scalar data + uuid and syllable columns for all stacked sessions (moseq_df) scalar (str or list): Selected scalar column(s) to compute mean value for syllables max_sylls (int): the index of the maximum syllable to include. syllable_key (str): column in scalar_df that points to the syllable labels to use.

Returns: mean_df (pandas.DataFrame): updated input DataFrame with a speed value for each syllable merge in as a new column.

moseq2_viz.scalars.util.compute_mouse_dist_to_center(roi, centroid_x_px, centroid_y_px)

Compute the distance between the mouse and arena centroid.

Args: roi (tuple): Tuple of session’s arena dimensions. centroid_x_px (np.array): x-coordinate of the mouse centroid throughout the recording centroid_y_px (np.array): y-coordinate of the mouse centroid throughout the recording

Returns: dist_to_center (np.array): array of distance to the arena center in pixels.

moseq2_viz.scalars.util.compute_syllable_position_heatmaps(scalar_df, syllable_key='labels (usage sort)', syllables=range(0, 40), centroid_keys=['centroid_x_mm', 'centroid_y_mm'], normalize=False, bins=20)

Compute position heatmaps for each syllable on a session-by-session basis

Args: scalar_df (pandas.DataFrame): dataframe containing scalar data & labels for all sessions syllable_key (str): dataframe column to access syllable labels syllables (list): List of syllables to compute heatmaps for. centroid_keys (list): list of column names containing the centroid values used to compute mouse position. normalize (bool): boolean flag for whether normalizes the histogram to be a probability density bins (int): number of bins to cut the position data into

Returns: complete_df (pandas.DataFrame): model results dataframe with a new PDF column corresponding to each session-syllable pair.

moseq2_viz.scalars.util.convert_legacy_scalars(old_features, force: bool = False, true_depth: float = 673.1) → dict

Convert scalars in the legacy format to the new format, with explicit units.

Args: old_features (str, h5 group, or dictionary of scalars): filename, h5 group, or dictionary of scalar values. force (bool): boolean flag that forces the conversion of centroid_[xy]_px into mm. true_depth (float): true depth of the floor relative to the camera (673.1 mm by default)

Returns: features (dict): dictionary of scalar values

moseq2_viz.scalars.util.convert_pxs_to_mm(coords, resolution=(512, 424), field_of_view=(70.6, 60), true_depth=673.1)

Convert x, y coordinates in pixel space to mm

Args: coords (list): list of [x,y] pixel coordinate lists. resolution (tuple): video frame size. field_of_view (tuple): camera focal lengths. true_depth (float): detected distance between depth camera and bucket floor.

Returns: new_coords (list): list of same [x,y] coordinates in millimeters.

moseq2_viz.scalars.util.generate_empty_feature_dict(nframes) → dict

Generates a dict of numpy.array of zeros of length nframes for each feature parameter.

Args: nframes (int): length of video

Returns: (dict): dictionary feature to numpy 0 arrays of length nframes key-value pairs.

moseq2_viz.scalars.util.get_scalar_map(index, fill_nans=True, force_conversion=False)

Return a dictionary of scalar values loaded from an index dictionary.

Args: index (dict): dictionary of index file contents. fill_nans (bool): boolean flag that indicates whether to replace NaN values with 0. force_conversion (bool): boolean flag that forces the conversion of centroid_[xy]_px into mm.

Returns: scalar_map (dict): dictionary of all the scalar values acquired after extraction.

moseq2_viz.scalars.util.get_scalar_triggered_average(scalar_map, model_labels, max_syllable=40, nlags=20, include_keys=['velocity_2d_mm', 'velocity_3d_mm', 'width_mm', 'length_mm', 'height_ave_mm', 'angle'], zscore=False)

Get the averages of selected scalar keys for each syllable.

Args: scalar_map (dict): dictionary of all the scalar values acquired after extraction. model_labels (dict): dictionary of uuid to syllable label array pairs. max_syllable (int): the index of the maximum syllable to use. nlags (int): the number of lags to use when averaging over a series of PCs. include_keys (list): list of scalar values to load averages of. zscore (bool): indicate whether to z-score loaded values.

Returns: syll_average (dict): dictionary of scalars for each syllable sequence.

moseq2_viz.scalars.util.get_syllable_pdfs(pdf_df, normalize=True, syllables=range(0, 40), groupby='group', syllable_key='labels (usage sort)')

Compute the mean syllable position PDF/Heatmap for the given groupings.

Args: pdf_df (pandas.DataFrame): model results dataframe including a position PDF column containing 2D numpy arrays. normalize (bool): boolean flag that indicates whether normalize the pdf scales. syllables (list): list of syllables to get a grouping of. groupby (str): column name to group the df keys by. (either group, or SessionName) syllable_key (str): name of the column that contains the requested syllable label sequences.

Returns: group_syll_pdfs (list): 2D list of computed pdfs of shape ngroups x nsyllables groups (list): list of corresponding names to each row in the group_syll_pdfs list

moseq2_viz.scalars.util.is_legacy(features: dict)

Check a dictionary of features to see if they correspond with an older version of moseq.

Args: features (dict): dict of scalar_df column names.

Returns: (bool): true if the dict is from an old dataset

moseq2_viz.scalars.util.nanzscore(data)

Apply Z-score numpy.array that may contain NaN values.

Args: data (np.ndarray): array of scalar values.

Returns: data (np.ndarray): z-scored data.

moseq2_viz.scalars.util.process_scalars(scalar_map: dict, include_keys: list, zscore: bool = False) → dict

Fill NaNs and possibly zscore scalar values.

Args: scalar_map (dict): dictionary of all the scalar values acquired after extraction. include_keys (list): scalar keys to process. zscore (bool): boolean flag that indicates whether to z-score loaded values.

Returns: scalar_map (dict): dict that contains the updated NaN-filled values.

moseq2_viz.scalars.util.scalars_to_dataframe(index: dict, include_keys: list = ['SessionName', 'SubjectName', 'StartTime'], disable_output=False, force_conversion=True, model_path=None)

Generate a dataframe containing scalar values for all sessions and the dataframe will include syllable information when model_path in not None.

Args: index (dict): a sorted_index dictionary generated by parse_index or get_sorted_index include_keys (list): a list of other moseq related keys to include in the dataframe disable_output (bool): boolean flag that indicates whether to show tqdm output. force_conversion (bool): boolean flag that forces the conversion of centroid_[xy]_px into mm. model_path (str): path to model object to pull labels from and include in the dataframe

Returns: scalar_df (pandas DataFrame): DataFrame of loaded scalar values with their selected metadata.

moseq2_viz.scalars.util.star_valmap(func, d)

map the function to itratables

Args: func (func): function to map onto the values in iterables d (dict): iterables

Returns: (dict): dictionary of key and function mapped to the values