FlowCal.plot module¶

Functions for visualizing flow cytometry data.

Functions in this module are divided in two categories:

Simple Plot Functions, with a signature similar to the following:
```
plot_fxn(data_list, channels, parameters, savefig)
```
where data_list is a NxD FCSData object or numpy array, or a list of such, channels spcecifies the channel or channels to use for the plot, parameters are function-specific parameters, and savefig indicates whether to save the figure to an image file. Note that hist1d uses channel instead of channels, since it uses a single channel, and density2d only accepts one FCSData object or numpy array as its first argument.

Simple Plot Functions do not create a new figure or axis, so they can be called directly to plot in a previously created axis if desired. If savefig is not specified, the plot is maintained in the current axis when the function returns. This allows for further modifications to the axis by direct calls to, for example, plt.xlabel, plt.title, etc. However, if savefig is specified, the figure is closed after being saved. In this case, the function may include keyword parameters xlabel, ylabel, xlim, ylim, title, and others related to legend or color, which allow the user to modify the axis prior to saving.

The following functions in this module are Simple Plot Functions:
- hist1d
- density2d
- scatter2d
- scatter3d
Complex Plot Functions, which create a figure with several axes, and use one or more Simple Plot functions to populate the axes. They always include a savefig argument, which indicates whether to save the figure to a file. If savefig is not specified, the plot is maintained in the newly created figure when the function returns. However, if savefig is specified, the figure is closed after being saved.

The following functions in this module are Complex Plot Functions:
- density_and_hist
- scatter3d_and_projections

FlowCal.plot.density2d(data, channels=[0, 1], bins=1024, mode='mesh', normed=False, smooth=True, sigma=10.0, colorbar=False, xscale='logicle', yscale='logicle', xlabel=None, ylabel=None, xlim=None, ylim=None, title=None, savefig=None, **kwargs)¶

Plot a 2D density plot from two channels of a flow cytometry data set.

density2d has two plotting modes which are selected using the mode argument. With mode=='mesh', this function plots the data as a true 2D histogram, in which a plane is divided into bins and the color of each bin is directly related to the number of elements therein. With mode=='scatter', this function also calculates a 2D histogram, but it plots a 2D scatter plot in which each dot corresponds to a bin, colored according to the number elements therein. The most important difference is that the scatter mode does not color regions corresponding to empty bins. This allows for easy identification of regions with low number of events. For both modes, the calculated histogram can be smoothed using a Gaussian kernel by specifying smooth=True. The width of the kernel is, in this case, given by sigma.

Parameters:

data : FCSData or numpy array

Flow cytometry data to plot.

channels : list of int, list of str, optional

Two channels to use for the plot.

bins : int or array_like or [int, int] or [array, array], optional

Bins used for plotting:

If None, use data.hist_bins to obtain bin edges for both axes. None is not allowed if data.hist_bins is not available.

If int, bins specifies the number of bins to use for both axes. If data.hist_bins exists, it will be used to generate a number bins of bins.

If array_like, bins directly specifies the bin edges to use for both axes.

If [int, int], each element of bins specifies the number of bins for each axis. If data.hist_bins exists, use it to generate bins[0] and bins[1] bin edges, respectively.

If [array, array], each element of bins directly specifies the bin edges to use for each axis.

Any combination of the above, such as [int, array], [None, int], or [array, int]. In this case, None indicates to generate bin edges using data.hist_bins as above, int indicates the number of bins to generate, and an array directly indicates the bin edges. Note that None is not allowed if data.hist_bins does not exist.

mode : {‘mesh’, ‘scatter’}, str, optional

Plotting mode. ‘mesh’ produces a 2D-histogram whereas ‘scatter’ produces a scatterplot colored by histogram bin value.

normed : bool, optional

Flag indicating whether to plot a normed histogram (probability mass function instead of a counts-based histogram).

smooth : bool, optional

Flag indicating whether to apply Gaussian smoothing to the histogram.

colorbar : bool, optional

Flag indicating whether to add a colorbar to the plot.

savefig : str, optional

The name of the file to save the figure to. If None, do not save.

Other Parameters:

sigma : float, optional: The sigma parameter for the Gaussian kernel to use when smoothing.
xscale : str, optional: Scale of the x axis, either linear, log, or logicle.
yscale : str, optional: Scale of the y axis, either linear, log, or logicle
xlabel : str, optional: Label to use on the x axis. If None, attempts to extract channel name from data.
ylabel : str, optional: Label to use on the y axis. If None, attempts to extract channel name from data.
xlim : tuple, optional: Limits for the x axis. If not specified and bins exists, use the lowest and highest values of bins.
ylim : tuple, optional: Limits for the y axis. If not specified and bins exists, use the lowest and highest values of bins.
title : str, optional: Plot title.
kwargs : dict, optional: Additional parameters passed directly to the underlying matplotlib functions: plt.scatter if mode==scatter, and plt.pcolormesh if mode==mesh.

FlowCal.plot.density_and_hist(data, gated_data=None, gate_contour=None, density_channels=None, density_params={}, hist_channels=None, hist_params={}, figsize=None, savefig=None)¶

Make a combined density/histogram plot of a FCSData object.

This function calls hist1d and density2d to plot a density diagram and a number of histograms in different subplots of the same plot using one single function call. Setting density_channels to None will not produce a density diagram, and setting hist_channels to None will not produce any histograms. Setting both to None will raise an error. Additional parameters can be provided to density2d and hist1d by using density_params and hist_params.

If gated_data is provided, this function will plot the histograms corresponding to gated_data on top of data‘s histograms, with some transparency on data. In addition, a legend will be added with the labels ‘Ungated’ and ‘Gated’. If gate_contour is provided and it contains a valid list of 2D curves, these will be plotted on top of the density plot.

Other Parameters:
Parameters:	data : FCSData object Flow cytometry data object to plot. gated_data : FCSData object, optional Flow cytometry data object. If gated_data is specified, the histograms of data are plotted with an alpha value of 0.5, and the histograms of gated_data are plotted on top of those with an alpha value of 1.0. gate_contour : list, optional List of Nx2 curves, representing a gate contour to be plotted in the density diagram. density_channels : list Two channels to use for the density plot. If density_channels is None, do not plot a density plot. density_params : dict, optional Parameters to pass to density2d. hist_channels : list Channels to use for each histogram. If hist_channels is None, do not plot histograms. hist_params : list, optional List of dictionaries with the parameters to pass to each call of hist1d. savefig : str, optional The name of the file to save the figure to. If None, do not save.
	figsize : tuple, optional Figure size. If None, calculate a default based on the number of subplots.
Raises:	ValueError If both density_channels and hist_channels are None.

FlowCal.plot.hist1d(data_list, channel=0, xscale='logicle', bins=256, histtype='stepfilled', normed_area=False, normed_height=False, xlabel=None, ylabel=None, xlim=None, ylim=None, title=None, legend=False, legend_loc='best', legend_fontsize='medium', legend_labels=None, facecolor=None, edgecolor=None, savefig=None, **kwargs)¶

Plot one 1D histogram from one or more flow cytometry data sets.

Parameters:

data_list : FCSData or numpy array or list of FCSData or numpy array: Flow cytometry data to plot.
channel : int or str, optional: Channel from where to take the events to plot. If ndim == 1, channel is ignored. String channel specifications are only supported for data types which support string-based indexing (e.g. FCSData).
xscale : str, optional: Scale of the x axis, either linear, log, or logicle.
bins : int or array_like, optional: If bins is an integer, it specifies the number of bins to use. If bins is an array, it specifies the bin edges to use. If bins is None or an integer, hist1d will attempt to use data.hist_bins to generate the bins automatically.
histtype : {‘bar’, ‘barstacked’, ‘step’, ‘stepfilled’}, str, optional: Histogram type. Directly passed to plt.hist.
normed_area : bool, optional: Flag indicating whether to normalize the histogram such that the area under the curve is equal to one. The resulting plot is equivalent to a probability density function.
normed_height : bool, optional: Flag indicating whether to normalize the histogram such that the sum of all bins’ heights is equal to one. The resulting plot is equivalent to a probability mass function. normed_height is ignored if normed_area is True.
savefig : str, optional: The name of the file to save the figure to. If None, do not save.

Other Parameters:

xlabel : str, optional: Label to use on the x axis. If None, attempts to extract channel name from last data object.
ylabel : str, optional: Label to use on the y axis. If None and normed_area==True, use ‘Probability’. If None, normed_area==False, and normed_height==True, use ‘Counts (normalized)’. If None, normed_area==False, and normed_height==False, use ‘Counts’.
xlim : tuple, optional: Limits for the x axis. If not specified and bins exists, use the lowest and highest values of bins.
ylim : tuple, optional: Limits for the y axis.
title : str, optional: Plot title.
legend : bool, optional: Flag specifying whether to include a legend. If legend is True, the legend labels will be taken from legend_labels if present, else they will be taken from str(data_list[i]).
legend_loc : str, optional: Location of the legend.
legend_fontsize : int or str, optional: Font size for the legend.
legend_labels : list, optional: Labels to use for the legend.
facecolor : matplotlib color or list of matplotlib colors, optional: The histogram’s facecolor. It can be a list with the same length as data_list. If edgecolor and facecolor are not specified, and histtype == 'stepfilled', the facecolor will be taken from the module-level variable cmap_default.
edgecolor : matplotlib color or list of matplotlib colors, optional: The histogram’s edgecolor. It can be a list with the same length as data_list. If edgecolor and facecolor are not specified, and histtype == 'step', the edgecolor will be taken from the module-level variable cmap_default.
kwargs : dict, optional: Additional parameters passed directly to matploblib’s hist.

Notes

hist1d calls matplotlib’s hist function for each object in data_list. hist_type, the type of histogram to draw, is directly passed to plt.hist. Additional keyword arguments provided to hist1d are passed directly to plt.hist.

If normed_area is set to True, hist1d calls plt.hist with density (or normed, if matplotlib’s version is older than 2.2.0) set to True. There is a bug in matplotlib 2.1.0 that produces an incorrect plot in these conditions. We do not recommend using matplotlib 2.1.0 if normed_area is expected to be used.

FlowCal.plot.scatter2d(data_list, channels=[0, 1], xscale='logicle', yscale='logicle', xlabel=None, ylabel=None, xlim=None, ylim=None, title=None, color=None, savefig=None, **kwargs)¶

Plot 2D scatter plot from one or more FCSData objects or numpy arrays.

Parameters:

data_list : array or FCSData or list of array or list of FCSData: Flow cytometry data to plot.
channels : list of int, list of str: Two channels to use for the plot.
savefig : str, optional: The name of the file to save the figure to. If None, do not save.

Other Parameters:

xscale : str, optional: Scale of the x axis, either linear, log, or logicle.
yscale : str, optional: Scale of the y axis, either linear, log, or logicle.
xlabel : str, optional: Label to use on the x axis. If None, attempts to extract channel name from last data object.
ylabel : str, optional: Label to use on the y axis. If None, attempts to extract channel name from last data object.
xlim : tuple, optional: Limits for the x axis. If None, attempts to extract limits from the range of the last data object.
ylim : tuple, optional: Limits for the y axis. If None, attempts to extract limits from the range of the last data object.
title : str, optional: Plot title.
color : matplotlib color or list of matplotlib colors, optional: Color for the scatter plot. It can be a list with the same length as data_list. If color is not specified, elements from data_list are plotted with colors taken from the module-level variable cmap_default.
kwargs : dict, optional: Additional parameters passed directly to matploblib’s scatter.

Notes

scatter2d calls matplotlib’s scatter function for each object in data_list. Additional keyword arguments provided to scatter2d are passed directly to plt.scatter.

FlowCal.plot.scatter3d(data_list, channels=[0, 1, 2], xscale='logicle', yscale='logicle', zscale='logicle', xlabel=None, ylabel=None, zlabel=None, xlim=None, ylim=None, zlim=None, title=None, color=None, savefig=None, **kwargs)¶

Plot 3D scatter plot from one or more FCSData objects or numpy arrays.

Parameters:

data_list : array or FCSData or list of array or list of FCSData: Flow cytometry data to plot.
channels : list of int, list of str: Three channels to use for the plot.
savefig : str, optional: The name of the file to save the figure to. If None, do not save.

Other Parameters:

xscale : str, optional: Scale of the x axis, either linear, log, or logicle.
yscale : str, optional: Scale of the y axis, either linear, log, or logicle.
zscale : str, optional: Scale of the z axis, either linear, log, or logicle.
xlabel : str, optional: Label to use on the x axis. If None, attempts to extract channel name from last data object.
ylabel : str, optional: Label to use on the y axis. If None, attempts to extract channel name from last data object.
zlabel : str, optional: Label to use on the z axis. If None, attempts to extract channel name from last data object.
xlim : tuple, optional: Limits for the x axis. If None, attempts to extract limits from the range of the last data object.
ylim : tuple, optional: Limits for the y axis. If None, attempts to extract limits from the range of the last data object.
zlim : tuple, optional: Limits for the z axis. If None, attempts to extract limits from the range of the last data object.
title : str, optional: Plot title.
color : matplotlib color or list of matplotlib colors, optional: Color for the scatter plot. It can be a list with the same length as data_list. If color is not specified, elements from data_list are plotted with colors taken from the module-level variable cmap_default.
kwargs : dict, optional: Additional parameters passed directly to matploblib’s scatter.

Notes

scatter3d uses matplotlib’s scatter with a 3D projection. Additional keyword arguments provided to scatter3d are passed directly to scatter.

FlowCal.plot.scatter3d_and_projections(data_list, channels=[0, 1, 2], xscale='logicle', yscale='logicle', zscale='logicle', xlabel=None, ylabel=None, zlabel=None, xlim=None, ylim=None, zlim=None, color=None, figsize=None, savefig=None, **kwargs)¶

Plot a 3D scatter plot and 2D projections from FCSData objects.

scatter3d_and_projections creates a 3D scatter plot and three 2D projected scatter plots in four different axes for each FCSData object in data_list, in the same figure.

Parameters:

data_list : FCSData object, or list of FCSData objects: Flow cytometry data to plot.
channels : list of int, list of str: Three channels to use for the plot.
savefig : str, optional: The name of the file to save the figure to. If None, do not save.

Other Parameters:

xscale : str, optional: Scale of the x axis, either linear, log, or logicle.
yscale : str, optional: Scale of the y axis, either linear, log, or logicle.
zscale : str, optional: Scale of the z axis, either linear, log, or logicle.
xlabel : str, optional: Label to use on the x axis. If None, attempts to extract channel name from last data object.
ylabel : str, optional: Label to use on the y axis. If None, attempts to extract channel name from last data object.
zlabel : str, optional: Label to use on the z axis. If None, attempts to extract channel name from last data object.
xlim : tuple, optional: Limits for the x axis. If None, attempts to extract limits from the range of the last data object.
ylim : tuple, optional: Limits for the y axis. If None, attempts to extract limits from the range of the last data object.
zlim : tuple, optional: Limits for the z axis. If None, attempts to extract limits from the range of the last data object.
color : matplotlib color or list of matplotlib colors, optional: Color for the scatter plot. It can be a list with the same length as data_list. If color is not specified, elements from data_list are plotted with colors taken from the module-level variable cmap_default.
figsize : tuple, optional: Figure size. If None, use matplotlib’s default.
kwargs : dict, optional: Additional parameters passed directly to matploblib’s scatter.

Notes

scatter3d_and_projections uses matplotlib’s scatter, with the 3D scatter plot using a 3D projection. Additional keyword arguments provided to scatter3d_and_projections are passed directly to scatter.