deepof.visuals.plot_embeddings

deepof.visuals.plot_embeddings(coordinates: deepof_coordinates, embeddings: deepof_table_dict | None = None, soft_counts: deepof_table_dict | None = None, supervised_annotations: deepof_table_dict | None = None, bin_size: int | str | None = None, bin_index: int | str | None = None, precomputed_bins: ndarray | None = None, samples_max=20000, roi_number: int | None = None, animals_in_roi: str | list | None = None, roi_mode: str = 'mousewise', in_roi_criterion: str = 'Center', min_confidence: float = 0.0, normative_model: str | None = None, add_stats: str = 'Mann-Whitney', verbose: bool = False, exp_condition: str | None = None, aggregate_experiments: str | None = None, samples: int = 500, show_aggregated_density: bool = True, colour_by: str = 'cluster', ax: Any | None = None, save: bool = False)

Return a scatter plot of the passed projection. Allows for temporal and quality filtering, animal aggregation, and changepoint detection size visualization.

Parameters:

  • coordinates (coordinates) – deepOF project where the data is stored.

  • embeddings (table_dict) – table dict with neural embeddings per animal experiment across time.

  • soft_counts (table_dict) – table dict with soft cluster assignments per animal experiment across time.

  • supervised_annotations (table_dict) – table dict with supervised annotations per experiment.

  • bin_size (Union[int,str]) – bin size for time filtering.

  • bin_index (Union[int,str]) – index of the bin of size bin_size to select along the time dimension. Denotes exact start position in the time domain if given as string.

  • precomputed_bins (np.ndarray) – precomputed time bins. If provided, bin_size and bin_index are ignored.

  • samples_max (int) – Maximum number of samples taken for plotting to avoid excessive computation times. If the number of rows in a data set exceeds this number the data is downsampled accordingly.

  • roi_number (int) – Number of the ROI that should be used for the plot (all behavior that occurs outside of the ROI gets excluded)

  • animals_in_roi (list) – List of ids of the animals that need to be inside of the active ROI. All frames in which any of the given animals are not inside of the ROI get excluded

  • roi_mode (str) – Determines how the rois should be applied to different behaviors. Options are “mousewise” (default, selected mice needs to be inside the ROI) and “behaviorwise” (only mice involved in a behavior need to be inside of the ROI, only for supervised behaviors)

  • in_roi_criterion (str) – Criterion for in roi check, can be a single bodypart, a list of bodyparts or “all” bodyparts of a mouse

  • min_confidence (float) – minimum confidence in cluster assignments used for quality control filtering.

  • normative_model (str) – Name of the cohort to use as controls. If provided, fits a Gaussian density to the control global animal embeddings, and reports the difference in likelihood across all instances of the provided experimental condition. Statistical parameters can be controlled via **kwargs (see full documentation for details).

  • add_stats (str) – test to use. Mann-Whitney (non-parametric) by default. See statsannotations documentation for details.

  • verbose (bool) – if True, prints test results and p-value cutoffs. False by default.

  • exp_condition (str) – Name of the experimental condition to use when plotting. If None (default) the first one available is used.

  • aggregate_experiments (str) – Whether to aggregate embeddings by experiment (by time on cluster, mean, or median) or not (default).

  • samples (int) – Number of samples to take from the time embeddings. None leads to plotting all time-points, which may hurt performance.

  • show_aggregated_density (bool) – if True, a density plot is added to the aggregated embeddings.

  • colour_by (str) – hue by which to colour the embeddings. Can be one of ‘cluster’ (default), ‘exp_condition’, ‘exp_id’ or, if supervised behaviors are given, also any supervised behavior.

  • ax (plt.AxesSubplot) – axes where to plot the current figure. If not provided, new figure will be created.

  • save (bool) – Saves a time-stamped vectorized version of the figure if True.