Plotting

class celltk.utils.plot_utils.PlotHelper

Helper class for making plots. Most functions are simple wrappers around Plotly functions.

bar_plot(arrays, keys=[], estimator=None, err_estimator=None, ax_labels=None, colors=None, alpha=1.0, orientation='v', barmode='group', add_cell_numbers=True, legend=True, figure=None, figsize=(None, None), margin='auto', title=None, x_label=None, y_label=None, x_limit=None, y_limit=None, tick_size=None, axis_label_size=None, widget=False, row=None, col=None, **kwargs)

Builds a Plotly Figure object plotting bars from the given arrays. Each array is interpreted as a separate condition and is plotted in a different color.

Parameters

arrays (Collection[ndarray]) – List of arrays to plot. Assumed structure is n_cells x n_features. Each feature is plotted as a separate bar group. Arrays must be two-dimensional, so if only one sample, use np.newaxis or np.expand_dims.
keys (Collection[str], default: []) – Names corresponding to the data arrays. If not provided, the keys will be integers.
estimator (Union[Callable, str, partial, None], default: None) – Function for aggregating observations from multiple cells. For example, if estimator is np.mean, the mean of all of the cells will be plotted instead of a bar for each cell. Can be a function, name of numpy function, name of function in estimator_utils, or a functools.partial object. If a function or functools.partial object, should input a 2D array and return a 1D array.
err_estimator (Union[Callable, str, partial, None], default: None) – Function for estimating error bars. Can be a function, name of numpy function, name of function in estimator_utils, or a functools.partial object. If a function or functools.partial object, should input a 2D array and return a 1D or 2D array. If output is 1D, errors will be symmetric If output is 2D, the first dimension is used for the high error and second dimension is used for the low error.
colors (Union[str, Collection[str], None], default: None) – Name of a color palette or map to use. Searches first in seaborn/matplotlib, then in Plotly to find the color map. If not provided, the color map will be glasbey. Can also be list of named CSS colors or hexadecimal or RGBA strings.
alpha (float, default: 1.0) – Opacity of the marker fill colors.
ax_labels (Optional[Collection[str]], default: None) – Labels for the categorical axis.
orientation (str, default: 'v') – Orientation of the bar plot.
barmode (str, default: 'group') – Keyword argument describing how to group the bars. Options are ‘group’, ‘overlay’, ‘relative’, and ‘stack’.
add_cell_numbers (bool, default: True) – If True, adds the number of cells to each key in keys.
legend (bool, default: True) – If False, no legend is made on the plot.
figure (Union[Figure, FigureWidget, None], default: None) – If a go.Figure object is given, will be used to make the plot instead of a blank figure.
figsize (Tuple[int], default: (None, None)) – Height and width of the plot in pixels. Must be a tuple of length two. To leave height or width unchanged, set as None.
margin (str, default: 'auto') – Set the size of the margins. If ‘auto’, all margins are set to defualt values. If ‘zero’ or ‘tight’, margins are removed. If a number is given, sets all margins to that number.
title (Optional[str], default: None) – Title to add to the plot
x_label (Optional[str], default: None) – Label of the x-axis
y_label (Optional[str], default: None) – Label of the y-axis
x_limit (Optional[Tuple[float]], default: None) – Initial limits for the x-axis. Can be changed if the plot is saved as an HTML object. Only applies if orientation is horizontal.
y_limit (Optional[Tuple[float]], default: None) – Initial limits for the y-axis. Can be changed if the plot is saved as an HTML object. Only applies if orientation is vertical.
tick_size (Optional[float], default: None) – Size of the font of the axis tick labels.
axis_label_size (Optional[float], default: None) – Size of the font of the axis label.
widget (bool, default: False) – If True, returns a go.FigureWidget object instead of a go.Figure object.
row (Optional[int], default: None) – If Figure has multiple subplots, specifies which row to use for the plot. Indexing starts at 1. Note that some formatting args (such as figsize) may still be applied to all subplots. Both row and col must be provided together.
col (Optional[int], default: None) – If Figure has multiple subplots, specifies which col to use for the plot. Indexing starts at 1. Note that some formatting args (such as figsize) may still be applied to all subplots. Both row and col must be provided together.
kwargs – Depending on name, passed to go.Bar or to go.Figure.update_traces(). The following kwargs are passed to go.Bar: ‘hoverinfo’, ‘marker’, ‘width’.

Return type

Union[Figure, FigureWidget]

Returns

Figure object

Raises

AssertionError – If not all items in arrays are np.ndarray.
AssertionError – If orientation is a disallowed value.
AssertionError – If figsize is not a tuple of length two.

box_plot(arrays, keys=[], colors=None, line_colors=None, alpha=1.0, orientation='v', show_points=False, jitter=None, show_mean=False, width=0, add_cell_numbers=True, legend=True, figure=None, figsize=(None, None), margin='auto', title=None, x_label=None, y_label=None, x_limit=None, y_limit=None, tick_size=None, axis_label_size=None, widget=False, row=None, col=None, **kwargs)

Builds a Plotly go.Figure object with box and whisker distributions for each of the arrays given.

Parameters

arrays (Collection[ndarray]) – List of arrays to plot. Arrays are assumed to be one dimensional.
keys (Collection[str], default: []) – Names corresponding to the data arrays. If not provided, the keys will be integers.
colors (Union[str, Collection[str], None], default: None) – Name of a color palette or map to use to fill boxes. Searches first in seaborn/matplotlib, then in Plotly to find the color map. If not provided, the color map will be glasbey. Can also be list of named CSS colors or hexadecimal or RGBA strings.
line_colors (Union[str, Collection[str], None], default: None) – Name of a color palette or map to use for outlines of boxes. Searches first in seaborn/matplotlib, then in Plotly to find the color map. If not provided, will use same colormap as colors. Can also be list of named CSS colors or hexadecimal or RGBA strings.
alpha (float, default: 1.0) – Opacity of the fill color of the box plots as a float in the range [0, 1].
orientation (str, default: 'v') – Orientation of the box plot.
show_points (Union[str, bool], default: False) – If True, individual data points are overlaid over the box plot. If ‘outliers’ or ‘suspectedoutliers’, only points that lie outside a certain distance from the interquartile range are shown.
jitter (Optional[float], default: None) – Sets the jitter in the sample points drawn. Ranges from 0-1. If 0, points are aligned on distribution axis, if 1, points are drawn in random jitter the width of the boxes.
show_mean (bool, default: False) – If True, dashed line is plotted at the mean value.
width (float, default: 0) – Sets the width of the boxes. If 0, width is automatically set.
add_cell_numbers (bool, default: True) – If True, adds the number of cells to each key in keys.
legend (bool, default: True) – If False, no legend is made on the plot.
figure (Union[Figure, FigureWidget, None], default: None) – If a go.Figure object is given, will be used to make the plot instead of a blank figure.
figsize (Tuple[int], default: (None, None)) – Height and width of the plot in pixels. Must be a tuple of length two. To leave height or width unchanged, set as None.
margin (str, default: 'auto') – Set the size of the margins. If ‘auto’, all margins are set to defualt values. If ‘zero’ or ‘tight’, margins are removed. If a number is given, sets all margins to that number.
title (Optional[str], default: None) – Title to add to the plot
x_label (Optional[str], default: None) – Label of the x-axis
y_label (Optional[str], default: None) – Label of the y-axis
x_limit (Optional[Tuple[float]], default: None) – Initial limits for the x-axis. Can be changed if the plot is saved as an HTML object. Only applies if orientation is horizontal.
y_limit (Optional[Tuple[float]], default: None) – Initial limits for the y-axis. Can be changed if the plot is saved as an HTML object. Only applies if orientation is veritcal.
tick_size (Optional[float], default: None) – Size of the font of the axis tick labels.
axis_label_size (Optional[float], default: None) – Size of the font of the axis label.
widget (bool, default: False) – If True, returns a go.FigureWidget object instead of a go.Figure object.
row (Optional[int], default: None) – If Figure has multiple subplots, specifies which row to use for the plot. Indexing starts at 1. Note that some formatting args (such as figsize) may still be applied to all subplots. Both row and col must be provided together.
col (Optional[int], default: None) – If Figure has multiple subplots, specifies which col to use for the plot. Indexing starts at 1. Note that some formatting args (such as figsize) may still be applied to all subplots. Both row and col must be provided together.
kwargs – Depending on name, passed to go.Box or to go.Figure.update_traces(). The following kwargs are passed to go.Box: ‘mean’, ‘lowerfence’, ‘upperfence’, ‘notched’, ‘notchspan’, ‘notchwidth’, ‘q1’, ‘q3’, ‘quartilemethod’, ‘sd’, ‘whiskerwidth’.

Return type

Union[Figure, FigureWidget]

Returns

Figure object

Raises

AssertionError – If not all entries in arrays or neg_arrays are np.ndarray
AssertionError – If any entry in arrays or neg_arrays have more than one dimension.
AssertionError – If neg_arrays is given, and len(arrays) != len(neg_arrays)
AssertionError – If figsize is not a tuple of length two.

contour2d_plot(x_array, y_array, colorscale='viridis', fill=True, zmin=None, zmid=None, zmax=None, robust_z=False, width=0.5, xbinsize=None, ybinsize=None, histfunc='count', histnorm='', figure=None, figsize=(None, None), margin='auto', title=None, x_label=None, y_label=None, x_limit=None, y_limit=None, tick_size=None, axis_label_size=None, widget=False, row=None, col=None, **kwargs)

Builds a Plotly go.Figure object with a two dimensional density contour heatmap of the provided arrays. This function is just a very thin wrapper around go.Heatmap2dContour.

Parameters

x_array (ndarray) – Array containing observations for the data on the x-axis. Expected to be one dimensional.
y_array (ndarray) – Array containing observations for the data on the y-axis. Expected to be one dimensional.
colorscale (str, default: 'viridis') – The colorscale to make the heatmap in. Options are more limited than the options for colors. Options include: “Blackbody”, “Bluered”, “Blues”, “Cividis”, “Earth”, “Electric”, “Greens”, “Greys”, “Hot”, “Jet”, “Picnic”, “Portland”, “Rainbow”, “RdBu”, “Reds”, “Viridis”, “YlGnBu”, and “YlOrRd”.
fill (bool, default: True) – If True, space between contour lines is filled with color, otherwise, only the lines are colored.
zmin (Optional[float], default: None) – Sets the lower bound of the color domain. If given, zmax must also be given.
zmid (Optional[float], default: None) – Sets the midpoint of the color domain by setting zmin and zmax to be equidistant from this point.
zmax (Optional[float], default: None) – Sets the upper bound of the color domain. If given, zmin must also be given.
robust_z (bool, default: False) – If True, uses percentiles to set zmin and zmax instead of extremes of the dataset.
width (float, default: 0.5) – Width of the contour lines.
xbinsize (Optional[float], default: None) – Size of the bins along the x-axis.
ybinsize (Optional[float], default: None) – Size of the bins along the y-axis.
histfunc (str, default: 'count') – Specifies the binning function used for this histogram trace. If “count”, the histogram values are computed by counting the number of values lying inside each bin. Can also be “sum”, “avg”, “min”, “max”.
histnorm (str, default: '') – Specifies the type of normalization used for this histogram trace. If “”, the span of each bar corresponds to the number of occurrences If “percent” / “probability”, the span of each bar corresponds to the percentage / fraction of occurrences with respect to the total number of sample points (here, the sum of all bin HEIGHTS equals 100% / 1). If “density”, the span of each bar corresponds to the number of occurrences in a bin divided by the size of the bin interval. If probability density, the area of each bar corresponds to the probability that an event will fall into the corresponding bin (here, the sum of all bin AREAS equals 1).
figure (Union[Figure, FigureWidget, None], default: None) – If a go.Figure object is given, will be used to make the plot instead of a blank figure.
figsize (Tuple[int], default: (None, None)) – Height and width of the plot in pixels. Must be a tuple of length two. To leave height or width unchanged, set as None.
margin (str, default: 'auto') – Set the size of the margins. If ‘auto’, all margins are set to defualt values. If ‘zero’ or ‘tight’, margins are removed. If a number is given, sets all margins to that number.
title (Optional[str], default: None) – Title to add to the plot
x_label (Optional[str], default: None) – Label of the x-axis
y_label (Optional[str], default: None) – Label of the y-axis
x_limit (Optional[Tuple[float]], default: None) – Initial limits for the x-axis. Can be changed if the plot is saved as an HTML object. Only applies if orientation is horizontal.
y_limit (Optional[Tuple[float]], default: None) – Initial limits for the y-axis. Can be changed if the plot is saved as an HTML object. Only applies if orientation is veritcal.
tick_size (Optional[float], default: None) – Size of the font of the axis tick labels.
axis_label_size (Optional[float], default: None) – Size of the font of the axis label.
widget (bool, default: False) – If True, returns a go.FigureWidget object instead of a go.Figure object.
row (Optional[int], default: None) – If Figure has multiple subplots, specifies which row to use for the plot. Indexing starts at 1. Note that some formatting args (such as figsize) may still be applied to all subplots. Both row and col must be provided together.
col (Optional[int], default: None) – If Figure has multiple subplots, specifies which col to use for the plot. Indexing starts at 1. Note that some formatting args (such as figsize) may still be applied to all subplots. Both row and col must be provided together.
kwargs – Passed to go.Heatmap2dContour

Return type

Union[Figure, FigureWidget]

Returns

Figure object

Raises

AssertionError – If x_array or y_array are more than one dimensional.
AssertionError – If figsize is not a tuple of length two.

heatmap2d_plot(x_array, y_array, colorscale='viridis', zmin=None, zmid=None, zmax=None, robust_z=False, xbinsize=None, ybinsize=None, histfunc='count', histnorm='', figure=None, figsize=(None, None), margin='auto', title=None, x_label=None, y_label=None, x_limit=None, y_limit=None, tick_size=None, axis_label_size=None, widget=False, row=None, col=None, **kwargs)

Builds a Plotly go.Figure object with a two dimensional density heatmap of the provided arrays. This function is just a very thin wrapper around go.Heatmap2d.

Parameters

x_array (ndarray) – Array containing observations for the data on the x-axis. Expected to be one dimensional.
y_array (ndarray) – Array containing observations for the data on the y-axis. Expected to be one dimensional.
colorscale (str, default: 'viridis') – The colorscale to make the heatmap in. Options are more limited than the options for colors. Options include: “Blackbody”, “Bluered”, “Blues”, “Cividis”, “Earth”, “Electric”, “Greens”, “Greys”, “Hot”, “Jet”, “Picnic”, “Portland”, “Rainbow”, “RdBu”, “Reds”, “Viridis”, “YlGnBu”, and “YlOrRd”.
zmin (Optional[float], default: None) – Sets the lower bound of the color domain. If given, zmax must also be given.
zmid (Optional[float], default: None) – Sets the midpoint of the color domain by setting zmin and zmax to be equidistant from this point.
zmax (Optional[float], default: None) – Sets the upper bound of the color domain. If given, zmin must also be given.
robust_z (bool, default: False) – If True, uses percentiles to set zmin and zmax instead of extremes of the dataset.
xbinsize (Optional[float], default: None) – Size of the bins along the x-axis.
ybinsize (Optional[float], default: None) – Size of the bins along the y-axis.
histfunc (str, default: 'count') – Specifies the binning function used for this histogram trace. If “count”, the histogram values are computed by counting the number of values lying inside each bin. Can also be “sum”, “avg”, “min”, “max”.
histnorm (str, default: '') – Specifies the type of normalization used for this histogram trace. If “”, the span of each bar corresponds to the number of occurrences If “percent” / “probability”, the span of each bar corresponds to the percentage / fraction of occurrences with respect to the total number of sample points (here, the sum of all bin HEIGHTS equals 100% / 1). If “density”, the span of each bar corresponds to the number of occurrences in a bin divided by the size of the bin interval. If probability density, the area of each bar corresponds to the probability that an event will fall into the corresponding bin (here, the sum of all bin AREAS equals 1).
figure (Union[Figure, FigureWidget, None], default: None) – If a go.Figure object is given, will be used to make the plot instead of a blank figure.
figsize (Tuple[int], default: (None, None)) – Height and width of the plot in pixels. Must be a tuple of length two. To leave height or width unchanged, set as None.
margin (str, default: 'auto') – Set the size of the margins. If ‘auto’, all margins are set to defualt values. If ‘zero’ or ‘tight’, margins are removed. If a number is given, sets all margins to that number.
title (Optional[str], default: None) – Title to add to the plot.
x_label (Optional[str], default: None) – Label of the x-axis
y_label (Optional[str], default: None) – Label of the y-axis
x_limit (Optional[Tuple[float]], default: None) – Initial limits for the x-axis. Can be changed if the plot is saved as an HTML object. Only applies if orientation is horizontal.
y_limit (Optional[Tuple[float]], default: None) – Initial limits for the y-axis. Can be changed if the plot is saved as an HTML object. Only applies if orientation is veritcal.
tick_size (Optional[float], default: None) – Size of the font of the axis tick labels.
axis_label_size (Optional[float], default: None) – Size of the font of the axis label.
widget (bool, default: False) – If True, returns a go.FigureWidget object instead of a go.Figure object.
row (Optional[int], default: None) – If Figure has multiple subplots, specifies which row to use for the plot. Indexing starts at 1. Note that some formatting args (such as figsize) may still be applied to all subplots. Both row and col must be provided together.
col (Optional[int], default: None) – If Figure has multiple subplots, specifies which col to use for the plot. Indexing starts at 1. Note that some formatting args (such as figsize) may still be applied to all subplots. Both row and col must be provided together.
kwargs – Passed to go.Histogram2d.

Return type

Union[Figure, FigureWidget]

Returns

Figure object

Raises

AssertionError – If x_array or y_array are more than one dimensional.
AssertionError – If figsize is not a tuple of length two.

heatmap_plot(array, colorscale='viridis', zmin=None, zmid=None, zmax=None, robust_z=False, reverse=False, sort=None, figure=None, figsize=(None, None), margin='auto', title=None, x_label=None, y_label=None, x_limit=None, y_limit=None, tick_size=None, axis_label_size=None, widget=False, row=None, col=None, **kwargs)

Builds a Plotly go.Figure object with a heatmap of the provided array. This function is just a very thin wrapper around go.Heatmap.

Parameters

array (ndarray) – Array from which to make the heatmap.
colorscale (str, default: 'viridis') – The colorscale to make the heatmap in. Options are more limited than the options for colors. Options include: “Blackbody”, “Bluered”, “Blues”, “Cividis”, “Earth”, “Electric”, “Greens”, “Greys”, “Hot”, “Jet”, “Picnic”, “Portland”, “Rainbow”, “RdBu”, “Reds”, “Viridis”, “YlGnBu”, and “YlOrRd”.
zmin (Optional[float], default: None) – Sets the lower bound of the color domain. If given, zmax must also be given.
zmid (Optional[float], default: None) – Sets the midpoint of the color domain by setting zmin and zmax to be equidistant from this point.
zmax (Optional[float], default: None) – Sets the upper bound of the color domain. If given, zmin must also be given.
robust_z (bool, default: False) – If True, uses percentiles to set zmin and zmax instead of extremes of the dataset.
reverse (bool, default: False) – If True, the color mapping is reversed.
sort (Optional[str], default: None) – If the name of a distance metric, will sort the array according to that metric before producing the heatmap. Valid values are ‘cityblock’, ‘cosine’, ‘euclidean’, ‘l1’, ‘l2’, ‘manhattan’, ‘braycurtis’, ‘canberra’, ‘chebyshev’, ‘correlation’, ‘dice’, ‘hamming’, ‘jaccard’, ‘kulsinski’, ‘mahalanobis’, ‘minkowski’, ‘rogerstanimoto’, ‘russellrao’, ‘seuclidean’, ‘sokalmichener’, ‘sokalsneath’, ‘sqeuclidean’, and ‘yule’.
figure (Union[Figure, FigureWidget, None], default: None) – If a go.Figure object is given, will be used to make the plot instead of a blank figure.
figsize (Tuple[int], default: (None, None)) – Height and width of the plot in pixels. Must be a tuple of length two. To leave height or width unchanged, set as None.
margin (str, default: 'auto') – Set the size of the margins. If ‘auto’, all margins are set to defualt values. If ‘zero’ or ‘tight’, margins are removed. If a number is given, sets all margins to that number.
title (Optional[str], default: None) – Title to add to the plot
x_label (Optional[str], default: None) – Label of the x-axis
y_label (Optional[str], default: None) – Label of the y-axis
x_limit (Optional[Tuple[float]], default: None) – Initial limits for the x-axis. Can be changed if the plot is saved as an HTML object. Only applies if orientation is horizontal.
y_limit (Optional[Tuple[float]], default: None) – Initial limits for the y-axis. Can be changed if the plot is saved as an HTML object. Only applies if orientation is veritcal.
tick_size (Optional[float], default: None) – Size of the font of the axis tick labels.
axis_label_size (Optional[float], default: None) – Size of the font of the axis label.
widget (bool, default: False) – If True, returns a go.FigureWidget object instead of a go.Figure object.
row (Optional[int], default: None) – If Figure has multiple subplots, specifies which row to use for the plot. Indexing starts at 1. Note that some formatting args (such as figsize) may still be applied to all subplots. Both row and col must be provided together.
col (Optional[int], default: None) – If Figure has multiple subplots, specifies which col to use for the plot. Indexing starts at 1. Note that some formatting args (such as figsize) may still be applied to all subplots. Both row and col must be provided together.
kwargs – Passed to go.Heatmap.

Return type

Union[Figure, FigureWidget]

Returns

Figure object.

Raises

AssertionError – If array dtype is object.
AssertionError – If array is not two-dimensional.
AssertionError – If figsize is not a tuple of length two.

histogram_plot(arrays, keys=[], histfunc='count', histnorm='', normalizer=None, nbins=None, binsize=None, bargap=None, bargroupgap=None, cumulative=False, include_histogram=True, include_kde=False, bandwidth=None, extend_kde=0, fill_kde=False, colors=None, alpha=1.0, orientation='v', barmode='group', add_cell_numbers=True, legend=True, figure=None, figsize=(None, None), margin='auto', title=None, x_label=None, y_label=None, x_limit=None, y_limit=None, tick_size=None, axis_label_size=None, widget=False, row=None, col=None, **kwargs)

Builds a Plotly Figure object plotting a histogram of each of the given arrays. Each array is interpreted as a separate condition and is plotted in a different color.

Parameters

arrays (Collection[ndarray]) – List of arrays to plot histograms.
keys (Collection[str], default: []) – Names corresponding to the data arrays. If not provided, the keys will be integers.
histfunc (str, default: 'count') – Specifies the binning function used for this histogram trace. If “count”, the histogram values are computed by counting the number of values lying inside each bin. Can also be “sum”, “avg”, “min”, “max”.
histnorm (str, default: '') – Specifies the type of normalization used for this histogram trace. If “”, the span of each bar corresponds to the number of occurrences If “percent” / “probability”, the span of each bar corresponds to the percentage / fraction of occurrences with respect to the total number of sample points (here, the sum of all bin HEIGHTS equals 100% / 1). If “density”, the span of each bar corresponds to the number of occurrences in a bin divided by the size of the bin interval. If “probability density”, the area of each bar corresponds to the probability that an event will fall into the corresponding bin (here, the sum of all bin AREAS equals 1).
normalizer (Union[Callable, str, None], default: None) – If given, used to normalize the data after applying the estimators. Normalizes the error as well. Can be ‘minmax’ or ‘maxabs’, or a callable that inputs an array and outputs an array of the same shape.
nbins (Optional[int], default: None) – Approximate number of bins to use. Ignored if binsize is set.
binsize (Optional[float], default: None) – Size of each bin.
bargap (Optional[float], default: None) – Gap between bars in adjacent locations.
bargroupgap (Optional[float], default: None) – Gap between bars in the same location.
cumulative (bool, default: False) – If True, the histogram will plot cumulative occurances.
include_histogram (bool, default: True) – If True, plot the histogram as a series of bars.
include_kde (bool, default: False) – If True, calculate and plot a Gaussian kernel density estimate of the data. NOTE: Not currently normalized, so only plots the probability density function.
bandwidth (Union[str, float, None], default: None) – Value of the bandwidth or name of method to estimate a good value of the bandwidth. Method options are ‘scott’ and ‘silverman’. If None, uses ‘scott’.
extend_kde (Union[float, bool], default: 0) – Boolean or number of bandwidth lengths to extend the plot of the kernel density estimate. False or value of 0 means the kernel density estimate will only be plotted for the values of the data provided. If True, the default value is 3.
fill_kde (Union[bool, str], default: False) – If True, fills in the area of the kernel density estimate. By default, fills to a value of 0 on the axis. Can also be a string to specify a different fill method. These options are from Plotly and include: ‘tozerox’, ‘tozeroy’, ‘tonextx’, ‘tonexty’, ‘tonext’, ‘toself’.
colors (Union[str, Collection[str], None], default: None) – Name of a color palette or map to use. Searches first in seaborn/matplotlib, then in Plotly to find the color map. If not provided, the color map will be glasbey. Can also be list of named CSS colors or hexadecimal or RGBA strings.
alpha (float, default: 1.0) – Opacity of the fill color of the histogram as a float in the range [0, 1].
orientation (str, default: 'v') – Orientation of the bar plot.
barmode (str, default: 'group') – Keyword argument describing how to group the bars. Options are ‘group’, ‘overlay’, ‘stack’, and ‘relative’.
add_cell_numbers (bool, default: True) – If True, adds the number of cells to each key in keys.
legend (bool, default: True) – If False, no legend is made on the plot.
figure (Union[Figure, FigureWidget, None], default: None) – If a go.Figure object is given, will be used to make the plot instead of a blank figure.
figsize (Tuple[int], default: (None, None)) – Height and width of the plot in pixels. Must be a tuple of length two. To leave height or width unchanged, set as None.
margin (str, default: 'auto') – Set the size of the margins. If ‘auto’, all margins are set to defualt values. If ‘zero’ or ‘tight’, margins are removed. If a number is given, sets all margins to that number.
title (Optional[str], default: None) – Title to add to the plot
x_label (Optional[str], default: None) – Label of the x-axis
y_label (Optional[str], default: None) – Label of the y-axis
x_limit (Optional[Tuple[float]], default: None) – Initial limits for the x-axis. Can be changed if the plot is saved as an HTML object. Only applies if orientation is horizontal.
y_limit (Optional[Tuple[float]], default: None) – Initial limits for the y-axis. Can be changed if the plot is saved as an HTML object. Only applies if orientation is vertical.
tick_size (Optional[float], default: None) – Size of the font of the axis tick labels.
axis_label_size (Optional[float], default: None) – Size of the font of the axis label.
widget (bool, default: False) – If True, returns a go.FigureWidget object instead of a go.Figure object.
row (Optional[int], default: None) – If Figure has multiple subplots, specifies which row to use for the plot. Indexing starts at 1. Note that some formatting args (such as figsize) may still be applied to all subplots. Both row and col must be provided together.
col (Optional[int], default: None) – If Figure has multiple subplots, specifies which col to use for the plot. Indexing starts at 1. Note that some formatting args (such as figsize) may still be applied to all subplots. Both row and col must be provided together.
kwargs – Depending on name, kwargs are passed to either go.Histogram or the line kwarg of go.Scatter if a kernel density estimate is included. The following kwargs are passed to “line”: ‘color’, ‘dash’, ‘shape’, ‘simplify’, ‘smoothing’, ‘width’, ‘hoverinfo’.

Return type

Union[Figure, FigureWidget]

Returns

Figure object

Raises

AssertionError – If not all items in arrays are np.ndarray.
AssertionError – If orientation is a disallowed value.
AssertionError – If figsize is not a tuple of length two.

line_plot(arrays, keys=[], estimator=None, err_estimator=None, normalizer=None, colors=None, alpha=1.0, time=None, add_cell_numbers=True, legend=True, figure=None, figsize=(None, None), margin='auto', title=None, x_label=None, y_label=None, x_limit=None, y_limit=None, tick_size=None, axis_label_size=None, widget=False, gl=False, row=None, col=None, **kwargs)

Builds a Plotly Figure object plotting lines of the given arrays. Each array is interpreted as a separate condition and is plotted in a different color.

Parameters

arrays (Collection[ndarray]) – List of arrays to plot. Assumed structure is n_cells x n_features. Arrays must be two-dimensional, so if only one sample, use np.newaxis or np.expand_dims.
keys (Collection[str], default: []) – Names corresponding to the data arrays. If not provided, the keys will be integers.
estimator (Union[Callable, str, partial, None], default: None) – Function for aggregating observations from multiple cells. For example, if estimator is np.mean, the mean of all of the cells will be plotted instead of a trace for each cell. Can be a function, name of numpy function, name of function in estimator_utils, or a functools.partial object. If a function or functools.partial object, should input a 2D array and return a 1D array.
err_estimator (Union[Callable, str, partial, None], default: None) – Function for estimating error bars from multiple cells. Can be a function, name of numpy function, name of function in estimator_utils, or a functools.partial object. If a function or functools.partial object, should input a 2D array and return a 1D or 2D array. If output is 1D, errors will be symmetric If output is 2D, the first dimension is used for the high error and second dimension is used for the low error.
normalizer (Union[Callable, str, None], default: None) – If given, used to normalize the data after applying the estimators. Normalizes the error as well. Can be ‘minmax’, ‘maxabs’, ‘standard’, ‘robust’, or a callable that inputs an array and outputs an array of the same shape.
colors (Union[str, Collection[str], None], default: None) – Name of a color palette or map to use. Searches first in seaborn/matplotlib, then in Plotly to find the color map. If not provided, the color map will be glasbey.
alpha (float, default: 1.0) – Opacity of the line colors.
time (Union[Collection[ndarray], ndarray, None], default: None) – Time axis for the plot. Must be the same size as the second dimension of arrays.
add_cell_numbers (bool, default: True) – If True, adds the number of cells to each key in keys.
legend (bool, default: True) – If False, no legend is made on the plot.
figure (Union[Figure, FigureWidget, None], default: None) – If a go.Figure object is given, will be used to make the plot instead of a blank figure.
figsize (Tuple[int], default: (None, None)) – Height and width of the plot in pixels. Must be a tuple of length two. To leave height or width unchanged, set as None.
margin (str, default: 'auto') – Set the size of the margins. If ‘auto’, all margins are set to defualt values. If ‘zero’ or ‘tight’, margins are removed. If a number is given, sets all margins to that number.
title (Optional[str], default: None) – Title to add to the plot
x_label (Optional[str], default: None) – Label of the x-axis
y_label (Optional[str], default: None) – Label of the y-axis
x_limit (Optional[Tuple[float]], default: None) – Initial limits for the x-axis. Can be changed if the plot is saved as an HTML object.
y_limit (Optional[Tuple[float]], default: None) – Initial limits for the y-axis. Can be changed if the plot is saved as an HTML object.
tick_size (Optional[float], default: None) – Size of the font of the axis tick labels.
axis_label_size (Optional[float], default: None) – Size of the font of the axis label.
widget (bool, default: False) – If True, returns a go.FigureWidget object instead of a go.Figure object.
gl (bool, default: False) – If True, switches to using a WebGL backend. Much faster for large datasets, but some features may not be available. May not work in all contexts.
row (Optional[int], default: None) – If Figure has multiple subplots, specifies which row to use for the plot. Indexing starts at 1. Note that some formatting args (such as figsize) may still be applied to all subplots. Both row and col must be provided together.
col (Optional[int], default: None) – If Figure has multiple subplots, specifies which col to use for the plot. Indexing starts at 1. Note that some formatting args (such as figsize) may still be applied to all subplots. Both row and col must be provided together.
kwargs – Depending on name, passed to the “line” keyword argument of go.Scatter or as keyword arguments for go.Scatter. The following kwargs are passed to “line”: ‘color’, ‘dash’, ‘shape’, ‘simplify’, ‘smoothing’, ‘width’, ‘hoverinfo’

Return type

Union[Figure, FigureWidget]

Returns

Figure object

Raises

AssertionError – If any item in arrays is not two dimensional.
AssertionError – If figsize is not a tuple of length two.
TypeError – If time is not an np.ndarray or collection of np.ndarray.

ridgeline_plot(arrays, keys=[], colors=None, spanmode='hard', overlap=3, show_box=False, show_points=False, show_mean=True, add_cell_numbers=True, legend=True, figure=None, figsize=(None, None), margin='auto', title=None, x_label=None, y_label=None, x_limit=None, y_limit=None, tick_size=None, axis_label_size=None, widget=False, row=None, col=None, **kwargs)

Builds a Plotly go.Figure object with partially overlapping distributions for each of the arrays given. Similar to a violin plot. See the section on ridgeline plots here for more information.

Parameters

arrays (Collection[ndarray]) – List of arrays to create distributions from. Arrays are assumed to be one dimensional.
keys (Collection[str], default: []) – Names corresponding to the data arrays. If not provided, the keys will be integers.
colors (Union[str, Collection[str], None], default: None) – Name of a color palette or map to use. Searches first in seaborn/matplotlib, then in Plotly to find the color map. If not provided, the color map will be glasbey. Can also be list of named CSS colors or hexadecimal or RGBA strings.
spanmode (str, default: 'hard') – Determines how far the tails of the violin plot are extended. If ‘hard’, the plot spans as far as the data. If ‘soft’, the tails are extended.
overlap (float, default: 3) – Sets the amount of overlap between adjacent distributions. Larger values means more overlap.
show_box (bool, default: False) – If True, a box plot is made and overlaid over the distribution.
show_points (Union[str, bool], default: False) – If True, individual data points are overlaid over the distribution.
side – Side to plot the distribution. By default, the distribution is plotted on both sides, but can be ‘positive’ or ‘negative’ to plot on only one side.
add_cell_numbers (bool, default: True) – If True, adds the number of cells to each key in keys.
legend (bool, default: True) – If False, no legend is made on the plot.
figure (Union[Figure, FigureWidget, None], default: None) – If a go.Figure object is given, will be used to make the plot instead of a blank figure.
figsize (Tuple[int], default: (None, None)) – Height and width of the plot in pixels. Must be a tuple of length two. To leave height or width unchanged, set as None.
margin (str, default: 'auto') – Set the size of the margins. If ‘auto’, all margins are set to defualt values. If ‘zero’ or ‘tight’, margins are removed. If a number is given, sets all margins to that number.
title (Optional[str], default: None) – Title to add to the plot
x_label (Optional[str], default: None) – Label of the x-axis
y_label (Optional[str], default: None) – Label of the y-axis
x_limit (Optional[Tuple[float]], default: None) – Initial limits for the x-axis. Can be changed if the plot is saved as an HTML object. Only applies if orientation is horizontal.
y_limit (Optional[Tuple[float]], default: None) – Initial limits for the y-axis. Can be changed if the plot is saved as an HTML object. Only applies if orientation is veritcal.
tick_size (Optional[float], default: None) – Size of the font of the axis tick labels.
axis_label_size (Optional[float], default: None) – Size of the font of the axis label.
widget (bool, default: False) – If True, returns a go.FigureWidget object instead of a go.Figure object.
row (Optional[int], default: None) – If Figure has multiple subplots, specifies which row to use for the plot. Indexing starts at 1. Note that some formatting args (such as figsize) may still be applied to all subplots. Both row and col must be provided together.
col (Optional[int], default: None) – If Figure has multiple subplots, specifies which col to use for the plot. Indexing starts at 1. Note that some formatting args (such as figsize) may still be applied to all subplots. Both row and col must be provided together.
kwargs – Depending on name, passed to go.Violin or to go.Figure.update_traces(). The following kwargs are passed to go.Violin: ‘bandwidth’, ‘fillcolor’, ‘hoverinfo’, ‘jitter’, ‘line’, ‘marker’, ‘opacity’, ‘pointpos’, ‘points’, ‘span’, ‘width’, ‘hoverinfo’
show_mean (bool, default: True) –

Return type

Union[Figure, FigureWidget]

Returns

Figure object

scatter_plot(x_arrays=[], y_arrays=[], keys=[], estimator=None, err_estimator=None, normalizer=None, scatter_mode='markers', colors=None, alpha=1.0, symbols=None, add_cell_numbers=True, legend=True, figure=None, figsize=(None, None), margin='auto', title=None, x_label=None, y_label=None, x_limit=None, y_limit=None, tick_size=None, axis_label_size=None, widget=False, gl=False, row=None, col=None, **kwargs)

Builds a Plotly Figure object containing a scatter plot of the given arrays. Each array is interpreted as a separate condition and is plotted in a different color or with a different marker.

Parameters

x_arrays (Collection[ndarray], default: []) – List of arrays that set the x-coordinates to plot. Each array is assumed to be a different condition.
y_arrays (Collection[ndarray], default: []) – List of arrays that set the y-coordinates to plot. Each array is assumed to be a different condition.
keys (Collection[str], default: []) – Names corresponding to the data arrays. If not provided, the keys will be integers.
estimator (Union[Callable, str, partial, None], default: None) – Function for aggregating observations from multiple cells. For example, if estimator is np.mean, the mean of all of the cells will be plotted instead of a point for each cell. Can be a function, name of numpy function, name of function in estimator_utils, or a functools.partial object. If a function or functools.partial object, should input a 2D array and return a 1D array.
err_estimator (Union[Callable, str, partial, None], default: None) – Function for estimating vertical error bars. Can be a function, name of numpy function, name of function in estimator_utils, or a functools.partial object. If a function or functools.partial object, should input a 2D array and return a 1D or 2D array. If output is 1D, errors will be symmetric. If output is 2D, the first dimension is used for the high error and second dimension is used for the low error. Only applies to the y-dimension. Horizontal error bars not currrently implemented.
normalizer (Union[Callable, str, None], default: None) – If given, used to normalize the data after applying the estimators. Normalizes the error as well. Can be ‘minmax’ or ‘maxabs’, or a callable that inputs an array and outputs an array of the same shape.
scatter_mode (str, default: 'markers') – Drawing mode for the traces. Can be ‘markers’, ‘lines’, or ‘lines+markers’.
colors (Union[str, Collection[str], None], default: None) – Name of a color palette or map to use. Searches first in seaborn/matplotlib, then in Plotly to find the color map. If not provided, the color map will be glasbey. Can also be list of named CSS colors or hexadecimal or RGBA strings.
alpha (float, default: 1.0) – Opacity of the marker fill colors.
add_cell_numbers (bool, default: True) – If True, adds the number of cells to each key in keys.
legend (bool, default: True) – If False, no legend is made on the plot.
figure (Union[Figure, FigureWidget, None], default: None) – If a go.Figure object is given, will be used to make the plot instead of a blank figure.
figsize (Tuple[int], default: (None, None)) – Height and width of the plot in pixels. Must be a tuple of length two. To leave height or width unchanged, set as None.
margin (str, default: 'auto') – Set the size of the margins. If ‘auto’, all margins are set to defualt values. If ‘zero’ or ‘tight’, margins are removed. If a number is given, sets all margins to that number.
title (Optional[str], default: None) – Title to add to the plot
x_label (Optional[str], default: None) – Label of the x-axis
y_label (Optional[str], default: None) – Label of the y-axis
x_limit (Optional[Tuple[float]], default: None) – Initial limits for the x-axis. Can be changed if the plot is saved as an HTML object.
y_limit (Optional[Tuple[float]], default: None) – Initial limits for the y-axis. Can be changed if the plot is saved as an HTML object.
tick_size (Optional[float], default: None) – Size of the font of the axis tick labels.
axis_label_size (Optional[float], default: None) – Size of the font of the axis label.
widget (bool, default: False) – If True, returns a go.FigureWidget object instead of a go.Figure object.
gl (bool, default: False) – If True, switches to using a WebGL backend. Much faster for large datasets, but some features may not be available. May not work in all contexts.
row (Optional[int], default: None) – If Figure has multiple subplots, specifies which row to use for the plot. Indexing starts at 1. Note that some formatting args (such as figsize) may still be applied to all subplots. Both row and col must be provided together.
col (Optional[int], default: None) – If Figure has multiple subplots, specifies which col to use for the plot. Indexing starts at 1. Note that some formatting args (such as figsize) may still be applied to all subplots. Both row and col must be provided together.
kwargs – Depending on name, passed to the “marker” keyword argument of go.Scatter or as keyword arguments for go.Scatter. The following kwargs are passed to “marker”: ‘color’, ‘line’, ‘opacity’, ‘size’, ‘symbol’.

Return type

Union[Figure, FigureWidget]

Returns

Figure object

Raises

AssertionError – If both x_arrays and y_arrays are given, but have different lengths.
AssertionError – If not all items in either array are np.ndarray.
AssertionError – If not all items in arrays have the same number of columns.
AssertionError – If any item in arrays has more than 3 columns.
AssertionError – If figsize is not a tuple of length two.

Parameters: symbols (Union[str, Collection[str], None], default: None) –

trace_color_plot(trace_array, color_arrays=[], color_thres=[], colors=None, rows=6, cols=4, max_figures=None, time=None, figsize=(None, None), title=None, x_label=None, y_label=None, x_limit=None, y_limit=None, **kwargs)

Generates Plotly go.Figure objects with subplots for each individual trace in trace_array. Traces can be colored with discrete colors based on arbitrary criteria in color_arrays. For example, this function can be used to evaluate the success of peak segmentation by passing the traces to trace_array, and the peak segmentation to color_arrays.

Parameters

trace_array (ndarray) – Array containing the values to be plotted. Assumed structure is two-dimensional of shape n_cells x n_features.
color_arrays (Collection[ndarray], default: []) – Collection of arrays of the same shape as trace_array. Used with color_thres to determine what sections of the trace should be colored. There is no limit on the number of arrays passed, but color_thres must be the same length.
color_thres (Collection[float], default: []) – Collection of thresholds associated with color_arrays. For each array and threshold, the trace will be colored wherever color_array >= color_thres.
colors (Union[str, Collection[str], None], default: None) – Name of a color palette or map to use. Will use the first color as the base color of trace, and subsequent colors for each color_array. Searches first in seaborn/matplotlib, then in Plotly to find the color map. If not provided, the color map will be glasbey. Can also be list of named CSS colors or hexadecimal or RGBA strings.
rows (int, default: 6) – Number of rows of subplots to make for each figure.
cols (int, default: 4) – Number of columns of subplots to make for each figure.
max_figures (Optional[int], default: None) – Maximum number of figures to produce. If None, makes enough figures to plot all of the traces.
time (Optional[ndarray], default: None) – Time axis for the plot. Must be the same size as the second dimension of arrays.
title (Optional[str], default: None) – Title to add to the plot
x_label (Optional[str], default: None) – Label of the x-axis
y_label (Optional[str], default: None) – Label of the y-axis
x_limit (Optional[Tuple[float]], default: None) – Initial limits for the x-axis. Can be changed if the plot is saved as an HTML object.
y_limit (Optional[Tuple[float]], default: None) – Initial limits for the y-axis. Can be changed if the plot is saved as an HTML object.
kwargs – Depending on name, passed to the “line” keyword argument of go.Scatter or as keyword arguments for go.Scatter. The following kwargs are passed to “line”: ‘color’, ‘dash’, ‘shape’, ‘simplify’, ‘smoothing’, ‘width’, ‘hoverinfo’
figsize (Tuple[float], default: (None, None)) –

Return type

Generator

Returns

Generator that produces go.Figure objects

Raises

AssertionError – If any array in color_arrays does not have the same shape as trace array.
AssertionError – If length of color_arrays does not equal length of color_thres.

violin_plot(arrays, neg_arrays=[], keys=[], neg_keys=[], colors=None, neg_colors=None, alpha=1.0, orientation='v', show_box=False, show_points=False, show_mean=False, spanmode='soft', side=None, add_cell_numbers=True, legend=True, figure=None, figsize=(None, None), margin='auto', title=None, x_label=None, y_label=None, x_limit=None, y_limit=None, tick_size=None, axis_label_size=None, widget=False, row=None, col=None, **kwargs)

Builds a Plotly go.Figure object with violin distributions for each of the arrays given. If negative arrays are given, matches them with arrays and plots two distributions side by side.

Parameters

arrays (Collection[ndarray]) – List of arrays to plot. Arrays are assumed to be one dimensional. If neg_arrays is given, arrays are plotted on the positive side.
keys (Collection[str], default: []) – Names corresponding to the data arrays. If not provided, the keys will be integers.
neg_arrays (Collection[ndarray], default: []) – List of arrays to plot. Arrays are assumed to be 1-dimensional. If neg_arrays is given, arrays are plotted on the positive side.
neg_keys (Collection[str], default: []) – Names corresponding to the neative data arrays. If not provided, the keys will be integers.
colors (Union[str, Collection[str], None], default: None) – Name of a color palette or map to use. Searches first in seaborn/matplotlib, then in Plotly to find the color map. If not provided, the color map will be glasbey. Can also be list of named CSS colors or hexadecimal or RGBA strings.
neg_colors (Union[str, Collection[str], None], default: None) – Name of a color palette or map to use. Searches in seaborn/matplotlib first, then in Plotly to find the color map. If not provided, the color map will be glasbey. Can also be list of named CSS colors or hexadecimal or RGBA strings.
alpha (float, default: 1.0) – Opacity of the fill color of the violin plots as a float in the range [0, 1].
orientation (str, default: 'v') – Orientation of the violin plot.
show_box (bool, default: False) – If True, a box plot is made and overlaid over the violin plot.
show_points (Union[str, bool], default: False) – If True, individual data points are overlaid over the violin plot.
show_mean (bool, default: False) – If True, dashed line is plotted at the mean value.
spanmode (str, default: 'soft') – Determines how far the tails of the violin plot are extended. If ‘hard’, the plot spans as far as the data. If ‘soft’, the tails are extended.
side (Optional[str], default: None) – Side to plot the distribution. By default, the distribution is plotted on both sides, but can be ‘positive’ or ‘negative’ to plot on only one side.
add_cell_numbers (bool, default: True) – If True, adds the number of cells to each key in keys.
legend (bool, default: True) – If False, no legend is made on the plot.
figure (Union[Figure, FigureWidget, None], default: None) – If a go.Figure object is given, will be used to make the plot instead of a blank figure.
figsize (Tuple[int], default: (None, None)) – Height and width of the plot in pixels. Must be a tuple of length two. To leave height or width unchanged, set as None.
margin (str, default: 'auto') – Set the size of the margins. If ‘auto’, all margins are set to defualt values. If ‘zero’ or ‘tight’, margins are removed. If a number is given, sets all margins to that number.
title (Optional[str], default: None) – Title to add to the plot
x_label (Optional[str], default: None) – Label of the x-axis
y_label (Optional[str], default: None) – Label of the y-axis
x_limit (Optional[Tuple[float]], default: None) – Initial limits for the x-axis. Can be changed if the plot is saved as an HTML object. Only applies if orientation is horizontal.
y_limit (Optional[Tuple[float]], default: None) – Initial limits for the y-axis. Can be changed if the plot is saved as an HTML object. Only applies if orientation is veritcal.
tick_size (Optional[float], default: None) – Size of the font of the axis tick labels.
axis_label_size (Optional[float], default: None) – Size of the font of the axis label.
widget (bool, default: False) – If True, returns a go.FigureWidget object instead of a go.Figure object.
row (Optional[int], default: None) – If Figure has multiple subplots, specifies which row to use for the plot. Indexing starts at 1. Note that some formatting args (such as figsize) may still be applied to all subplots. Both row and col must be provided together.
col (Optional[int], default: None) – If Figure has multiple subplots, specifies which col to use for the plot. Indexing starts at 1. Note that some formatting args (such as figsize) may still be applied to all subplots. Both row and col must be provided together.
kwargs – Depending on name, passed to go.Violin or to go.Figure.update_traces(). The following kwargs are passed to go.Violin: ‘bandwidth’, ‘fillcolor’, ‘hoverinfo’, ‘jitter’, ‘line’, ‘marker’, ‘opacity’, ‘pointpos’, ‘points’, ‘span’, ‘width’, ‘hoverinfo’

Return type

Union[Figure, FigureWidget]

Returns

Figure object

Raises

AssertionError – If not all entries in arrays or neg_arrays are np.ndarray
AssertionError – If any entry in arrays or neg_arrays have more than one dimension.
AssertionError – If neg_arrays is given, and len(arrays) != len(neg_arrays)
AssertionError – If figsize is not a tuple of length two.