hong2p.viz module

Functions for visualizing movies / cells / extracted traces, some intended to provide context specfically useful for certain types of olfaction experiments.

hong2p.viz.add_colorbar(fig, im, match_axes_size=False, axes_index=- 1, location='right', size=None, pad=None, cax=None, label=None, fontsize=None, **kwargs)

Parameters

• fig (Figure) – figure to add colorbar to

• im – typically output of a ax.imshow/similar call see Figure.colorbar docs for more details: https://matplotlib.org/stable/api/figure_api.html#matplotlib.figure.Figure.colorbar

• match_axes_size (bool) – if True, colorbar will be made same size (for now, just height) as Axes. assumed that all Axes are same height and in one row (if multiple).

• axes_index (int) – if match_axes_size=True, use fig.axes[axes_index] to match

• location (str) – {‘left’, ‘right’, ‘bottom’, ‘top’}. where new colorbar axes is placed relative to axes it’s created from. if match_axes_size=True, passed as 1st arg to AxesDivider.append_axes, otherwise passed as location kwarg to fig.colorbar.

• size –

  passed to AxesDivider.append_axes (default: ‘7%’), if match_axes_size=True. unused otherwise. ‘<x>%’ means the size of the created colorbar axes will be x% of matched Axes size (width, if appending on right).

  see matplotlib docs and examples listed there: https://matplotlib.org/stable/api/_as_gen/mpl_toolkits.axes_grid1.axes_divider.AxesDivider.html https://matplotlib.org/stable/gallery/axes_grid1/demo_colorbar_with_axes_divider.html

• pad – passed to AxesDivider.append_axes (default: ‘2%’), if match_axes_size=True. passed to fig.colorbar otherwise. spacing between created colorbar (vs matched) Axes.

• cax (Optional[Axes]) – passed to fig.colorbar. use for more control of size/shape of colorbar, e.g. to make colorbar same height as Axes, as in https://stackoverflow.com/a/18195921

• label (Optional[str]) – label for colorbar

• fontsize – passed to Axes.set_ylabel

• **kwargs – passed to Figure.colorbar

Return type

Colorbar

hong2p.viz.add_group_labels_and_lines(ax, x=None, *, y=None, lines=True, labels=True, formatter=None, label_offset=None, label_name=None, label_name_offset=3, linewidth=0.5, linecolor='k', _debug=False, **kwargs)

Parameters

**kwargs – passed thru to ax.text calls for group text labels

Return type

None

hong2p.viz.add_norm_options(plot_fn)

Processes kwargs to allow passing non-instantiated Normalize subclasses.

Parameters

norm – matplotlib expects str (e.g. ‘linear’, ‘log’, ‘symlog’, ‘logit’) or an instantiated Normalize subclass (or None), but passing a normalize subclass like this conflicts with non-None vmin`|`vmax. this function adds the option to pass a non-instantiated Normalize class, which will receive vmin`|`vmax, removing those from kwargs. this will let plotting functions determine the range of data to plot, while still allowing use of norms not able to be passed a str.

Returns **kwargs, with vmin,vmax,norm modified when necessary.

kwargs[‘norm’] (if not str or None) will always be an instantiated Normalize subclass (unlike input, where it’s allowed to also be non-instantiated).

See https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.imshow.html for descriptions of vmin/vmax/norm kwargs.

hong2p.viz.add_scalebar(ax, pixelsize_um, *, color=None, **kwargs)

Return type

None

hong2p.viz.callable_ticklabels(plot_fn)

Allows [x/y]ticklabel functions evaluated on indices of df (plot_fn(df, …))

First parameter to plot_fn must be a pandas.DataFrame (or xarray.DataArray convertable to one) to compute the str ticklabels from. plot_fn must also accept the kwargs ‘[x|y]ticklabels’.

If the input to the decorated function is a xarray.DataArray, the decorated function will receive a DataFrame (created via arr.to_pandas()) as input instead. Note that only ‘dimension coordinates’ (see xarray terminology page) are preserved when converting from DataArray to DataFrame, so use <arr>.set_index(<dimension name>=…) appropriately before passing the array to a wrapped function.

hong2p.viz.clustermap(df, *, optimal_ordering=True, title=None, xlabel=None, ylabel=None, ylabel_rotation=None, ylabel_kws=None, cbar_label=None, cbar_kws=None, row_cluster=True, col_cluster=True, row_linkage=None, col_linkage=None, method='average', metric='euclidean', z_score=None, standard_scale=None, return_linkages=False, **kwargs)

Same as seaborn.clustermap but allows callable [x/y]ticklabels + adds opts.

Adds optimal_ordering kwarg to scipy.cluster.hierarchy.linkage that is not exposed by seaborn version.

Also turns off constrained layout for the duration of the seaborn function, to prevent warnings + disabling that would otherwise happen.

Parameters

• method – default ‘average’ is same as sns.clustermap

• metric – default ‘euclidean’ is same as sns.clustermap

hong2p.viz.col_labels(df, label_fn)

hong2p.viz.constrained_layout(plot_fn)

Parameters

plot_fn – must make figure from start to finish inside, so changing constrained layout setting works

hong2p.viz.contour_bbox(contour)

hong2p.viz.contour_center_of_mass(contour)

hong2p.viz.fix_facetgrid_axis_labels(facet_grid, shared_in_center=False, x=True, y=True)

Modifies a FacetGrid to not duplicate X and Y axis text labels.

Return type

None

hong2p.viz.format_index_row(row, *, delim=' / ', float_format=None, _debug=False)

Takes Series to a str with the concatenated values, separated by delim.

hong2p.viz.get_default_overlay_color(ax)

Returns ‘w’ or ‘k’ (white/black), depending on current image colors.

Aims to provide the color that would be higher contrast with respect to the background.

Return type

str

hong2p.viz.image_grid(image_list, *, nrows=None, ncols=None, figsize=None, width=None, height=None, extra_figsize=None, inches_per_pixel=0.014, imagegrid_rect=None, dpi=None, scale_per_plane=False, minmax_clip_frac=0.0, vmin=None, vmax=None, cbar=True, cmap='gray', cbar_label=None, cbar_kws=None, **kwargs)

Parameters

• image_list – list/array of images, whose length is equal to the number of images (i.e. number of planes, for typical input of single-fly volumetric data, where input has been reduced across timepoints)

• ncols (Optional[int]) – how many columns for grid showing the background of each plane (one panel per plane)

• figsize (Optional[Tuple[float, float]]) – passed to plt.subplots. if passed, none of width, height, extra_figsize should be, and inches_per_pixel will be ignored. (width, height)

• width (Optional[float]) – figure width in inches. only pass either this or height. if you want to specify both, use figsize instead. this is to specify one and have the other calculated (from nrows, ncols, and extra_figsize). will ignore and recalulate inches_per_pixel to fit figure in this width.

• height (Optional[float]) – figure height in inches. see width documentation.

• extra_figsize (Optional[Tuple[float, float]]) – if calculating figsize, this can be used to add space for other elements besides the images (colorbars, titles, etc). (width, height)

• inches_per_pixel – used to calculate figsize, if figsize not passed

• imagegrid_rect –

  passed to ImageGrid, to determine size / position it will occupy in figure. defaults to something automatically determined. colorbar(s) and any labels/titles should (i think) extent past this.

  (left, bottom, width, height) tuple, where (0, 0) is bottom left, and everything should be in [0, 1]. width and height are fractions of figure sizes.

• scale_per_plane (bool) – if False, min/max of colorscale will be picked from min/max of all data (after excluding minmax_clip_frac, if it’s greater than 0).

• minmax_clip_frac (float) – clip this fraction of data from BOTH the lower/upper end, when deciding the limits of the colormap for the background images. v[min|max] must not be set if this is, and vice versa.

• cbar (bool) – set to False to disable colorbar(s)

• cbar_label (Optional[str]) – label for colorbar

• cbar_kws (Optional[Dict[str, Any]]) – passed to add_colorbar

• **kwargs – passed to imshow

hong2p.viz.imshow(img, ax=None, title=None, cmap='gray', **kwargs)

hong2p.viz.is_cmap_diverging(cmap)

Returns guess as to whether input colormap is a diverging colormap.

Parameters

cmap – anything that could be passed to plt.get_cmap, such as str colormap name

Return type

bool

hong2p.viz.matlabels(df, rowlabel_fn, axis='index')

Takes DataFrame and function that takes one row of index to a label.

rowlabel_fn should take a DataFrame row (w/ columns from index) to a str.

hong2p.viz.matshow(df, title=None, ticklabels=None, xticklabels=None, yticklabels=None, xtickrotation=None, xlabel=None, ylabel=None, ylabel_rotation=None, ylabel_kws=None, cbar_label=None, group_ticklabels=False, vline_level_fn=None, hline_level_fn=None, vline_group_text=False, hline_group_text=False, vgroup_formatter=None, hgroup_formatter=None, vgroup_label_offset=0.08, hgroup_label_offset=0.12, vgroup_label_rotation='horizontal', hgroup_label_rotation='horizontal', group_fontsize=None, group_fontweight=None, linewidth=0.5, linecolor='w', ax=None, fontsize=None, bigtext_fontsize_scaler=1.5, fontweight=None, figsize=None, dpi=None, inches_per_cell=None, extra_figsize=None, transpose_sort_key=None, colorbar=True, cbar_shrink=1.0, cbar_kws=None, levels_from_labels=True, allow_duplicate_labels=False, xticks_also_on_bottom=False, overlay_values=False, overlay_fmt='.2f', overlay_kws=None, _debug=False, **kwargs)

Parameters

• transpose_sort_key (None | function) – takes df.index/df.columns and compares output to decide whether matrix should be transposed before plotting

• vline_level_fn – callable whose output varies along axis labels/index (see levels_from_labels for details). vertical lines will be drawn between changes in the output of this function.

• hline_level_fn – as vline_level_fn, but for horizontal lines.

• [h|v]group_formatter – optional function to map group values to str

• [h|v]group_label_offset – in axes (not data) coordinates. should probably be in [0, 1] and pretty close to 0. increase if constrained layout warning emitted when showing / saving plot.

• [h|v]group_label_rotation – passed to rotation of corresponding Axes.text call

• levels_from_labels (bool) – if True, [h|v]line_level_fn functions use formatted [x|y]ticklabels as input. Otherwise, a dict mapping index level names to values are used. Currently only support drawing labels for each group if this is False (still true?).

• xticks_also_on_bottom (bool) – if True, show same xticks on bottom as will be shown on top. for very tall plots where we can sometimes more easily reference the bottom than the top, when scrolling through.

• overlay_values (bool) – if True, overlays text with numerical value for each cell

• overlay_fmt (str) – float format str, used to format overlay_values text

• overlay_kws (Optional[Dict[str, Any]]) – optional dict of kwargs to pass to overlay ax.text calls

• **kwargs – passed thru to matplotlib.pyplot.matshow

hong2p.viz.micrometer_depth_title(ax, zstep_um, z_index, *, as_ylabel=False, as_overlay=False, fontsize=8, **kwargs)

Parameters

• as_ylabel (bool) – if True, use ax.set_ylabel instead of ax.title, to put this information on the left (may want to use if have a series of single column plots, rather than a series of rows). adds rotation=0 and labelpad=16 by default. mutually exclusive with as_overlay.

• as_overlay (bool) – draws on ax instead of labelling above / to the side. in top left corner by default. mutually exclusive with as_ylabel.

• fontsize – passed to ax.set_title (or ax.set_ylabel, if as_ylabel=True; ax.text if as_overlay=True)

• **kwargs – passed to ax.set_title (or ax.set_ylabel, if as_ylabel=True)

Return type

None

hong2p.viz.no_constrained_layout(plot_fn)

Parameters

plot_fn – must make figure from start to finish inside, so changing constrained layout setting works

hong2p.viz.plot_closed_contours(footprint, if_multiple='err', _pad=True, ax=None, label=None, label_over_contour=False, label_to_bbox_dy=0, text_kws=None, colors=None, color=None, linewidths=1.2, linestyles='dotted', label_outline=False, label_outline_linewidth=0.75, label_outline_color='black', smooth=False, **kwargs)

Plots line around the contiguous positive region(s) in footprint.

Parameters

• ax (Optional[Axes]) – Axes to plot onto. will use current Axes otherwise.

• if_multiple (str) – ‘take_largest’|’join’|’err’|’ignore’. what to do if there are multiple closed contours within footprint. contour will be plotted regardless, but error will happen before a contour is returned for use in other analysis.

• label (Optional[str]) – name of ROI. drawn in center of ROI contour by default.

• label_over_contour (bool) – if True, will draw label above ROI contour (rather than on center of mass). see also label_to_bbox_dy.

• label_to_bbox_dy (int) – how many pixels above ROI bounding box to draw ROI label. ignored if label_over_contour=False.

• label_outline (bool) – if True, adds a PathEffects to text_kws to add an outline around drawn label.

• label_outline_color – color for outline from label_outline=True

• label_outline_linewidth – linewidth for outline from label_outline=True

• **kwargs – passed through to matplotlib ax.contour call

hong2p.viz.plot_odor_corrs(corr_df, odor_order=False, odors_in_order=None, trial_stat='mean', title_suffix='', **kwargs)

Takes a symmetric DataFrame with odor x odor correlations and plots it.

hong2p.viz.plot_pair_n(df, *args)

Plots a matrix of odor1 X odor2 w/ counts of flies as entries.

Args: df (pd.DataFrame): DataFrame with columns:

• prep_date

• fly_num

• thorimage_id

• name1

• name2

Data already collected w/ odor pairs.

odor_panel (pd.DataFrame): (optional) DataFrame with columns:

• odor_1

• odor_2

• reason (maybe make this optional?)

The odor pairs experiments are supposed to collect data for.

hong2p.viz.plot_rois(rois, background, *, certain_only=False, best_planes_only=False, show_names=True, color=None, palette=None, seed=0, focus_roi=None, focus_roi_color='red', focus_roi_linewidth=None, palette_desat=0.4, scalebar=False, cbar=True, cbar_label=None, cbar_kws=None, pixelsize_um=None, scalebar_kws=None, image_kws=None, zstep_um=None, depth_text_kws=None, title=None, title_kws=None, linewidth=1.2, _pad=False, zero_outside_plane_outlines=False, plane_outline_line_kws=None, **kwargs)

Parameters

• rois (DataArray) – with dims (‘roi’, ‘z’, ‘y’, ‘x’). coords must have at least (‘roi_z’, ‘roi_name’) on the ‘roi’ dimension.

• background (ndarray) – must have shape equal to the (<z>, <y>, <x>) lengths of the corresponding entries in rois.sizes

• certain_only (bool) – whether to only show ROIs whose names indicate certainty about their ID (see roi.is_ijroi_certain)

• best_planes_only (bool) – whether to only show best plane for each volumetric ROI. If True, requires input also has ‘is_best_plane’ on ‘roi’ dimension.

• show_names – whether to plot ROI names in the center of each ROI. True`|`False`|`focus.

• color – for coloring ROI labels/outlines. use either this or palette. this is never desaturated, like palette can be via palette_desat.

• palette – for coloring ROI labels/outlines. use either this or color.

• focus_roi_color – color to use when the ROI name matching focus_roi (if passed). set to None to color these ROIs no differently from others, where they will then also be desaturated by palette_desat (if set).

• palette_desat (Optional[float]) – desaturate each color in passed / generated palette color by this amount, except for any ROIs who name is that of focus_roi (if passed. see also focus_roi_color docs). if focus_roi not passed, still desaturate everything by this amount, for consistency. will not desaturate if color is specified via color kwarg instead of palette.

• scalebar (bool) – if True, will draw scalebar on first plane (must also pass pixelsize_um)

• pixelsize_um (Optional[float]) – for use drawing scalebar

• scalebar_kws (Optional[dict]) – passed to matplotlib_scalebar.scalebar.ScaleBar

• zstep_um (Optional[float]) – if passed, axes titles will be added to indicate depth of each plane. no depth titles will be drawn if this is None.

• depth_text_kws (Optional[dict]) – passed to micrometer_depth_title (if zstep_um is provided).

• title (Optional[str]) – will set as suptitle if passed

• title_kws (Optional[dict]) – passed to suptitle. ignored if title not passed.

• image_kws (Optional[Dict[str, Any]]) – passed to image_grid, for plotting background(s)

• linewidth – linewidth for ROI outline

• zero_outside_plane_outlines (bool) – if True, and will zero the background outside ROIs matching roi.is_ijroi_plane_outline (assumed there is at most one per plane).

• plane_outline_line_kws – passed to plot_closed_contours for each ROI matching roi.is_ijroi_plane_outline. defaults specified internally (different from for regular ROIs).

• **kwargs – passed thru to plot_closed_contours

Return type

Figure

hong2p.viz.plot_traces(*args, footprints=None, order_by='odors', scale_within='cell', n=20, random=False, title=None, response_calls=None, raw=False, smoothed=True, show_footprints=True, show_footprints_alone=False, show_cell_ids=True, show_footprint_with_mask=False, gridspec=None, linewidth=0.5, verbose=True)

n (int): (default=20) Number of cells to plot traces for if cell_ids not

passed as second positional argument.

random (bool): (default=False) Whether the n cell ids should be selected

randomly. If False, the first n cells are used.

order_by (str): ‘odors’ or ‘presentation_order’ scale_within (str): ‘none’, ‘cell’, or ‘trial’ gridspec (None or matplotlib.gridspec.*): region of a parent figure

to draw this plot on.

linewidth (float): 0.25 seemed ok on CNMF data, but too small w/ clean traces.

hong2p.viz.remove_axes_ticks(ax)

Return type

None

hong2p.viz.row_labels(df, label_fn)

hong2p.viz.set_facetgrid_legend(facet_grid, **kwargs)

In cases where different axes have different subsets of the hue levels, the legend may not contain the artists for the union of hue levels across all axes. This sets a legend from the hue artists across all axes.

Return type

None

hong2p.viz.set_panel2order(panel2order)

Sets module-level dict mapping panels to order for plotting odors.

Return type

None

hong2p.viz.showsync(thorsync_dir, verbose=False, **kwargs)

Shows ThorSync .h5 data interactively, using pyqtgraph.

Parameters

• thorsync_dir – path to a directory created by ThorSync

• kwargs – passed through to thor.load_thorsync_hdf5

hong2p.viz.with_panel_orders(plot_fn, panel2order=None, **fn_kwargs)