cytoflow.views.base_views#

Base classes for views.

I found, as I wrote a bunch of views, that I was also writing a bunch of shared boiler-plate code. This led to more bugs and a harder-to-maintain codebase. So, I extracted the copied code in a short hierarchy of reusable base classes:

BaseView – implements a view with row, column and hue facets. After setting up the facet grid, it calls the derived class’s _grid_plot to actually do the plotting. BaseView.plot also has parameters to set the plot style, legend, axis labels, etc.

BaseDataView – implements a view that plots an Experiment’s data (as opposed to a statistic.) Includes functionality for subsetting the data before plotting, and determining axis limits and scales.

Base1DView – implements a 1-dimensional data view. See HistogramView for an example.

Base2DView – implements a 2-dimensional data view. See ScatterplotView for an example.

BaseNDView – implements an N-dimensional data view. See RadvizView for an example.

BaseStatisticsView – implements a view that plots a statistic from an Experiment (as opposed to the underlying data.) These views have a “primary” BaseStatisticsView.statistic, and can be subset as well.

Base1DStatisticsView – implements a view that plots one dimension of a statistic. See BarChartView for an example.

Base2DStatisticsView – implements a view that plots two dimensions of a statistic. See Stats2DView for an example.

class cytoflow.views.base_views.BaseView[source]#

Bases: HasStrictTraits

The base class for facetted plotting.

xfacet#

Set to one of the Experiment.conditions in the Experiment, and a new column of subplots will be added for every unique value of that condition.

Type:

String

yfacet#

Set to one of the Experiment.conditions in the Experiment, and a new row of subplots will be added for every unique value of that condition.

Type:

String

huefacet#

Set to one of the Experiment.conditions in the in the Experiment, and a new color will be added to the plot for every unique value of that condition.

Type:

String

huescale#

How should the color scale for huefacet be scaled?

Type:

{‘linear’, ‘log’, ‘logicle’}

plot(experiment, data, **kwargs)[source]#

Base function for facetted plotting

Parameters:

  • experiment (Experiment) – The Experiment to plot using this view.

  • title (str) – Set the plot title

  • xlabel (str) – Set the X axis label

  • ylabel (str) – Set the Y axis label

  • huelabel (str) – Set the label for the hue facet (in the legend)

  • legend (bool) – Plot a legend for the color or hue facet? Defaults to True.

  • legend_out (bool) – Plot the legend outside of the plot or grid? Defaults to True.

  • sharex (bool) – If there are multiple subplots, should they share X axes? Defaults to True.

  • sharey (bool) – If there are multiple subplots, should they share Y axes? Defaults to True.

  • row_order (list) – Override the row facet value order with the given list. If a value is not given in the ordering, it is not plotted. Defaults to a “natural ordering” of all the values.

  • col_order (list) – Override the column facet value order with the given list. If a value is not given in the ordering, it is not plotted. Defaults to a “natural ordering” of all the values.

  • hue_order (list) – Override the hue facet value order with the given list. If a value is not given in the ordering, it is not plotted. Defaults to a “natural ordering” of all the values.

  • height (float) – The height of each row in inches. Default = 3.0

  • aspect (float) – The aspect ratio of each subplot. Default = 1.5

  • col_wrap (int) – If xfacet is set and yfacet is not set, you can “wrap” the subplots around so that they form a multi-row grid by setting this to the number of columns you want.

  • sns_style ({“darkgrid”, “whitegrid”, “dark”, “white”, “ticks”}) – Which seaborn style to apply to the plot? Default is whitegrid.

  • sns_context ({“notebook”, “paper”, “talk”, “poster”}) – Which seaborn context to use? Controls the scaling of plot elements such as tick labels and the legend. Default is notebook.

  • palette (palette name, list, or dict) – Colors to use for the different levels of the hue variable. Should be something that can be interpreted by seaborn.color_palette, or a dictionary mapping hue levels to matplotlib colors. See https://seaborn.pydata.org/tutorial/color_palettes.html for a good overview.

  • despine (Bool) – Remove the top and right axes from the plot? Default is True.

class cytoflow.views.base_views.BaseDataView[source]#

Bases: BaseView

The base class for data views (as opposed to statistics views).

subset#

An expression that specifies the subset of the statistic to plot. Passed unmodified to pandas.DataFrame.query.

Type:

str

plot(experiment, **kwargs)[source]#

Plot some data from an experiment. This function takes care of checking for facet name validity and subsetting, then passes the underlying dataframe to BaseView.plot

Parameters:

  • min_quantile (float (>0.0 and <1.0, default = 0.001)) – Clip data that is less than this quantile.

  • max_quantile (float (>0.0 and <1.0, default = 1.00)) – Clip data that is greater than this quantile.

Other Parameters:

  • lim (Dict(Str : (float, float))) – Set the range of each channel’s axis. If unspecified, assume that the limits are the minimum and maximum of the clipped data. Required.

  • scale (Dict(Str : IScale)) – Scale the data on each axis. Required.

class cytoflow.views.base_views.Base1DView[source]#

Bases: BaseDataView

A data view that plots data from a single channel.

channel#

The channel to view

Type:

Str

scale#

The scale applied to the data before plotting it.

Type:

{‘linear’, ‘log’, ‘logicle’}

plot(experiment, **kwargs)[source]#
Parameters:

  • lim ((float, float)) – Set the range of the plot’s data axis.

  • orientation ({‘vertical’, ‘horizontal’})

class cytoflow.views.base_views.Base2DView[source]#

Bases: BaseDataView

A data view that plots data from two channels.

xchannel#

The channel to view on the X axis

Type:

Str

ychannel#

The channel to view on the Y axis

Type:

Str

xscale#

The scales applied to the xchannel data before plotting it.

Type:

{‘linear’, ‘log’, ‘logicle’} (default = ‘linear’)

yscale#

The scales applied to the ychannel data before plotting it.

Type:

{‘linear’, ‘log’, ‘logicle’} (default = ‘linear’)

plot(experiment, **kwargs)[source]#
Parameters:

  • xlim ((float, float)) – Set the range of the plot’s X axis.

  • ylim ((float, float)) – Set the range of the plot’s Y axis.

class cytoflow.views.base_views.BaseNDView[source]#

Bases: BaseDataView

A data view that plots data from one or more channels.

channels#

The channels to view

Type:

List(Str)

scale#

Re-scale the data in the specified channels before plotting. If a channel isn’t specified, assume that the scale is linear.

Type:

Dict(Str : {“linear”, “logicle”, “log”})

plot(experiment, **kwargs)[source]#
Parameters:

lim (Dict(Str : (float, float))) – Set the range of each channel’s axis. If unspecified, assume that the limits are the minimum and maximum of the clipped data

class cytoflow.views.base_views.BaseStatisticsView[source]#

Bases: BaseView

The base class for statistics views (as opposed to data views).

statistic#

The statistic to plot. Must be a key in Experiment.statistics.

Type:

Str

xfacet#

Set to one of the index levels in the statistic being plotted, and a new column of subplots will be added for every unique value of that index level.

Type:

String

yfacet#

Set to one of the index levels in the statistic being plotted, and a new row of subplots will be added for every unique value of that index level.

Type:

String

huefacet#

Set to one of the index levels in the statistic being plotted, and a new colored artist (line, bar, etc) will be added for every unique value of that index level.

Type:

String

subset#

An expression that specifies the subset of the statistic to plot. Passed unmodified to pandas.DataFrame.query.

Type:

str

enum_plots(experiment)[source]#

Enumerate the named plots we can make from this set of statistics.

Returns:

An iterator across the possible plot names. The iterator ALSO has an instance attribute called by, which holds a list of the facets that are not yet set (and thus need to be specified in the plot name.)

Return type:

iterator

plot(experiment, plot_name=None, **kwargs)[source]#

Plot some data from a statistic.

This function takes care of checking for facet name validity and subsetting, then passes the dataframe to BaseView.plot

Parameters:

plot_name (str) – If this IView can make multiple plots, plot_name is the name of the plot to make. Must be one of the values retrieved from enum_plots.

class cytoflow.views.base_views.Base1DStatisticsView[source]#

Bases: BaseStatisticsView

The base class for 1-dimensional statistic views – ie, the variable attribute is on the x axis, and the statistic value is on the y axis.

variable#

The condition that varies when plotting this statistic: used for the x axis of line plots, the bar groups in bar plots, etc. Must be a level in the statistic’s index.

Type:

Str

feature#

The column in the statistic to plot (often a channel name.)

Type:

Str

error_low#

The name of the column used to plot low extent error bars. If error_low is set, error_high must be set as well.

Type:

Str

error_high#

The name of the column used to plot high extent error bars. If error_high is set, error_low must be set as well.

Type:

Str

scale#

The scale applied to the data before plotting it.

Type:

{‘linear’, ‘log’, ‘logicle’}

plot(experiment, plot_name=None, **kwargs)[source]#
Parameters:

  • orientation ({‘vertical’, ‘horizontal’})

  • lim ((float, float)) – Set the range of the plot’s axis.

class cytoflow.views.base_views.Base2DStatisticsView[source]#

Bases: BaseStatisticsView

The base class for 2-dimensional statistic views – ie, the variable attribute varies independently, and the corresponding values from the x and y statistics are plotted on the x and y axes.

variable#

The condition that varies when plotting this statistic: used for the x axis of line plots, the bar groups in bar plots, etc. Must be a level in the statistic’s index.

Type:

Str

xfeature#

The name of the column to plot on the X axis.

Type:

Str

xerror_low#

The name of the column containing the low values for the X error bars. If xerror_low is set, xerror_high must be set as well.

Type:

Str

xerror_high#

The name of the column containing the high values for the X error bars. If xerror_high is set, xerror_low must be set as well.

Type:

Str

yfeature#

The name of the column to plot on the Y axis.

Type:

Str

yerror_low#

The name of the column containing the low values for the Y error bars. If yerror_low is set, yerror_high must be set as well.

Type:

Str

yerror_high#

The name of the column containing the high values for the Y error bars. If yerror_high is set, yerror_low must be set as well.

Type:

Str

xscale#

The scale applied to X axis.

Type:

{‘linear’, ‘log’, ‘logicle’}

yscale#

The scale applied to Y axis.

Type:

{‘linear’, ‘log’, ‘logicle’}

plot(experiment, plot_name=None, **kwargs)[source]#
Parameters:

  • xlim ((float, float)) – Set the range of the plot’s X axis.

  • ylim ((float, float)) – Set the range of the plot’s Y axis.