Background
The Illustration Editor is where figures (also known as Illustrations) are dynamically designed, created, modified, and exported in a Cytobank experiment. Illustrations can be used throughout your analysis process after scaling and compensation has been done, to visualize and ultimately communicate your findings.
In the Cytobank platform, we have two types of plots available: Event-level plots and Summary plots. In this article, we mostly cover the Event-level plots that include Dot plots, Histograms, and Contour plots. Heatmap is mentioned briefly here and in more detail in this article How to create and configure a Heatmap
To view the details of plot settings for Summary plots, please check out Overview of statistical plots generation using the Illustration Editor.
The Illustration Editor works optimally with data after you have annotated files with Sample tags to designate experimental variables, such as individual, conditions, sample type or any custom variable, termed a “dimension”. Sample tags become variables for configuring an Illustration. These variables can be toggled on or off and rearranged dynamically to build and modify a plot layout. This allows one to work above the level of FCS file names and instead use the scientific variables that were present in the experiment, to build a layout.
Cytobank automatically generates several basic Sample tags, such as FCS file names, channels, and populations after an experiment is created. You can continue your analysis using those basic experimental variables if additional experimental variables aren’t available.
Cytobank Illustration Editor Video
Outline
The process of creating a plot layout with the Illustration Editor can be broken down into multiple steps. Click on the link below to jump to the explanation for that step.
- Create a new illustration
- Set up the illustration layout
- Select and customize plots
- Customize plot headers
- Dynamically update the illustration
- Manage and export illustrations
If you want to follow along, find the public experiment called “PBMC (fluorescence)” in the Experiment Manager on whichever Cytobank you are registered on and fully clone it. We will generate an illustration to visualize which PBMC populations are responsive to in vitro stimulation with cytokines and Toll-like receptor ligands.
1) Create a new illustration
There are multiple ways to create a new illustration, depending on which page you are on within your experiment:
- From the Experiment preview pane: Click New illustration, in the Illustrations section.
- From the Experiment summary: Click New, in the Illustrations section.
From anywhere within an experiment: Select Illustrations from the blue Navigation bar and click New Illustration.
Creating a new illustration by any of these methods will prompt you to enter a custom name for the illustration, which can be changed at any time, and direct you to the Illustration Editor.
2) Set up illustration layout
The illustration layout is the arrangement of plots by dimensions, or experimental variables. Each specific variable within a dimension is called a Sample tag. Dimensions can be positioned in the illustration by rows, columns, or tables. Within each dimension, Sample tags can be selected and arranged in desired order. There are multiple ways to configure the illustration layout to generate the desired plot layout:
- Layout Settings menu
- Layout Preview menu within the Layout Settings menu
- Within the illustration
For any or all possible positions in the illustration (Rows/Overlaid, Columns, Tables), select which dimension to populate that position. By clicking the Add dimension menu, a dropdown will appear with all the dimensions that you have annotated in your experiment. If you have not yet annotated a dimension you would like to use, click Add dimension, then Enable another dimension. The Add experiment dimensions menu will show the pre-defined dimensions available, or you can click Define a custom dimension, to define another dimension with any name and custom icon.
A table is a grid of selected rows and columns within the Sample tag for that individual table. In the illustration we will build, each row is a condition (Unstim, IL6, LPS, IL10), each column is a population (intact cells, CD33+ monocytes, CD20+ B cells, CD3+ T cells), and each table is a channel (pStat3, pp38).
For a simpler view of the illustration to focus on the layout without seeing all of the plot details, you can set plot size to Placeholder. This will show a small icon instead of your plot, allowing you to see a higher level, birds-eye view of the illustration.
(Illustration from PBMC experiment. The layout in this illustration is cows are conditions (Unstim, IL6, LPS, IL10), columns are populations (intact cells, CD33+ monocytes, CD20+ B cells, CD3+ T cells), and horizontal tables are channels (pStat3, pp38). )
To configure this layout from a new illustration using the Layout Settings menu:
1. Click Layout in the Illustration navigation bar
(Layout settings menu)
2. To display Conditions by Rows, select Conditions as the dimension from the middle dropdown. Specify which conditions to display by clicking “4 of 4,” on the right-hand side to open the Select Conditions menu.
(Left, Layout settings menu to select the rows dimension. Right, Select Conditions menu for selecting which Conditions Sample tags to include. )
3. To display Populations by Columns, select Populations as the dimension from the middle dropdown. Since by default in the new illustration, populations already occupy the Tables position, Populations is greyed out. Instead, click on the blue Table 1 Switch box to the right of Populations. This will move Populations from Table 1 into Columns. Specify which populations to display by clicking “3 of 8,” on the right-hand side to open the Select Populations menu. In the Select Populations menu, you can view populations as a hierarchy called, Tree mode, (the default display), or as a list by clicking Sort mode.
(Left, Layout settings menu to switch the populations dimension from Table 1 (the default position) to columns. Right, Select Populations menu for selecting which populations to include. In Tree mode, shown here, populations are displayed in the order of the gating hierarchy. To change the order in which populations are displayed in the illustration, click the Sort mode button. )
4. To display channels by Table 1, select channels as the dimension from the middle dropdown. If you followed the preceding steps, channels should currently be in the Table 1 position. Click “2 of 24,” to choose which channels to display. If channels appear in different panels, you can select only the channels that are in the same panel by clicking on that Panel on the right-hand side of any of the channels that appear in that panel. You can also search for the panel name in the search box.
(Top, Layout settings menu highlighted to indicate where to access the channel selection menu. Bottom, Channels selection menu to select X axis channels )
To configure this layout from a new illustration using the Layout Preview menu:
The Layout Preview menu is an interactive preview of the files in your illustration, labeled and colored by names of dimensions and Sample tags, offering a bird’s eye view of your illustration and a description of the sample assigned to each position. It can aid in visualizing the final design of the illustration, and ensuring that you have properly assigned a unique FCS file to each position in the layout. If multiple files are assigned to a position, it will show “X files,” within a cell representing a plot, and you may need to re-visit Sample tags or select different Sample tags for display. For some functions of the illustration, such as calculating a fold change in the statistics table, the illustration must have one unique FCS file per position. However, in many cases, having multiple (or no) FCS files assigned to a position will not interfere with the function of the illustration.
(Top, Layout preview showing configuration of files by colored descriptions “Dimension: Sample tag.” Bottom, Layout preview appearance when multiple files are assigned to the same position. )
The Layout Preview can also be used to configure the layout, described below.
1. Click Layout in the illustration navigation bar, then click Layout Preview. In this view, the rows/columns/table positions are laid out corresponding to their position, with rows and row-wise tables on the left side of the preview, and columns and column-wise tables above the preview.
(Layout Preview menu allows simultaneous configuration of the illustration layout while seeing which sample occupies each position. )
2. Follow steps 2-4 above. In addition to selecting Sample tags from the pop-out selection menus, you can directly check or uncheck Sample tags from within the displayed box corresponding to the Figure dimension.
3. When you are done configuring your illustration in the Layout Preview menu, click the green Apply Changes button.
To configure this layout from directly within the illustration:
1. Hover the cursor over any row heading or single-click until the Rows settings menu appears. Select Conditions.
2. Hover the cursor over any column heading or single-click until the Columns settings menu appears. Select Populations by switching it from the Table 1 position. Click “3 of 8 selected,” to choose which populations to show.
3. Hover the cursor over any table title or single-click until the Table settings menu appears. Select Channels. Click “2 of 24 selected,” to choose which channels to display.
4. Once the correct dimension is assigned to a position, you can directly select the Sample tags by double clicking the header name. To remove any enabled Sample tags, hover over the corresponding row, column, or table header and click the blue X that appears. Removing a row or column from within a table will remove the corresponding Sample tag from all tables.
3) Select and customize plots
There are many options available for plot type, coloring, sizing, and overlays to most effectively interpret and communicate your data. As you change any settings, plots are updated in real time to allow you to quickly identify which is the best plot type for your needs. Here are some ways you can customize plots:
- Plot type: dot plots, contour plots, histograms, and heatmaps. Heatmaps are accompanied by interactive viewthrough plots of one of the other plot types as you hover your mouse over a cell.
- Coloring: by density, intensity of a channel, overlaid dimension, any selected statistic, or black. Nine coloring palettes are available. Histograms can be customized by outline and/or fill color.
- Overlay: Dot plots and histograms can be overlaid by a dimension.
- Size: 64 (“Tiny”) to 512 (“Huge”) pixels, or Placeholder.
- Other customizable settings: Show gates, customize axis labels and titles, statistic for coloring histograms, heatmaps
This article will walk through setting up a dot plot colored by density using the Cytobank-curated PBMC experiment that you can find and clone a copy of from your Experiment Manager. As with setting up the illustration layout, plot types can be selected and customized in multiple ways:
- Basic plot settings can be accessed through Plot settings menu or directly from a plot in the illustration
- More plot settings menu can be accessed from within the Plot settings menu or directly from a plot within the illustration
Basic plot settings include Plot type, Color by, Overlay, Palette, Plotting method, Show gates, and Size. For heatmaps, settings for the viewthrough plot (an event-level histogram or biaxial plot that shows when you hover your cursor over a heatmap square) will also appear in plot settings. To change basic plot settings, either click on Plots in the illustration navigation bar, or hover or single-click on a plot in the illustration.
To choose the channels displayed on an axis if that channel is not specified by a dimension (see layout settings above), hover over or single-click on the channel name to open a dropdown menu with available channels. If you have a large number of plots and do not see the channel name header of the X or Y axis, scroll to the bottom- and left-most plot in your layout. Repeated X and Y axis labels can be configured to appear for every plot or just the bottom- or left-most plot.
More plot settings available vary by plot type:
- Dot: For density-colored dot plots, additional settings include kernel smoothing, percent per contour, and outlier settings can be customized.
- Histogram: Additional settings include outline color selection, aspect ratio, kernel smoothing, orientation, and curve smoothing. When coloring by statistic, statistics settings become available for selection.
- For all plot types, axis markings can be configured in more plot settings, including whether to show axis tickmarks and X- and Y- axis labels. If the same X- or Y- axis appears on every plot within that column or row in a table, you can choose whether to show the label on every plot or only on the bottom- or left-most plot.
To customize additional plot settings, click on More plot settings from the Plot settings menu, or double click on a plot. Plot settings selected on the left side of the menu will be previewed in the Preview plot on the right. On the Preview plot, you can change the displayed axes, FCS file, or Population, but these selections do not influence the plots in the illustration. Changing settings within the Preview plot view is especially helpful for assessing the impact of changing settings of a large layout in real time. To apply the changes to the plots in the illustration, click the green Apply changes button.
4) Customize plot headers
To make your illustration presentation- or publication-ready, you can decide how to display row, column and table headers. Customize row headers by hovering over or single-click the row, column, or table heading. Click Header settings to expand the menu to show customizable features.
- For rows and columns, the line border can be enabled or disabled.
- For columns, you can choose whether to wrap, truncate column names that are wider than the plots, or expand the space around the plot to accommodate the length of the header name.
- For the FCS files dimension, the header can appear as the Sample name, FCS Filename, or Sample name – FCS filename. You can also choose whether to display the panel membership of the file.
- For the Channels dimension, you can choose to show the Channel name, or the axis in combination with the channel name, e.g. “x: pStat3.”
5) Dynamically update the illustration
Rearrange position of enabled dimensions
In addition to revisiting the steps above, you can also rearrange the layout by dragging and dropping dimensions into new positions in the Layout settings menu or Layout Preview. From the Layout settings menu, hover over the dotted grid on the right side of the layout position, and click and drag that dimension into another position, e.g. drag columns into rows. From the Layout Preview, the horizontally-oriented dimensions (columns and horizontal tables) and row-oriented dimensions (rows and vertical tables) can be swapped be dragging the blue dimensions boxes by the dotted grids.
Tables can be oriented as rows or columns, by clicking the double-headed arrow to the right of the table selection of the Layout settings or Layout preview menus (shown below).
(Select orientation of Table 1 dimension as rows or columns from Layout settings menu (left) or Layout preview menu (right))
Rearrange order of Sample tags within dimensions
Within a dimension, Sample tags can be reordered. The order of Sample tags in column and column-wise table dimensions is reflected left-to-right, and the order of row and row-wise table dimensions is reflected top-to-bottom.
To re-order Sample tags, either access the corresponding Sample tags selection menu or click on the corresponding row/column/table header within your illustration. For example, to reorder the Conditions in this illustration, click “4 of 4,” in the Layout settings menu Rows/Conditions row. Hover your mouse on the left side of the condition you want to move and drag it to the desired position. You can also re-order sample tags alphabetically or inverse alphabetically by clicking the A-to-Z button. From the illustration itself, click on any condition header and drag it up or down. This will impact the order of this dimension in all tables.
6) Manage and export illustrations
When you finish making an illustration that you want to keep, you can save the illustration in your Cytobank experiment, and export a copy as PDF, PNG, or SVG. You can also separately export the table of statistics below the figure.
By default, every change to your layout will be automatically saved. You can turn this option off by clicking Save in the illustration navigation bar, and disabling auto-save. With auto-save enabled, if you load a saved illustration and make any changes, they will overwrite the original saved illustration. If you want to start building a new illustration by working off of your saved illustration, then clone a new copy and work from the clone. To do this, click Save in the illustration navigation bar, Clone new copy, choose a name for the clone, and then “Click to view,” in the green message indicating that your illustration was created.
To load a saved illustration, either click Illustrations in the blue navigation bar, then locate your illustration by name under Recent, or click View all saved. Alternatively, you can find saved illustrations directly from the experiment summary, or the experiment preview pane from your Experiment Manager.
To delete an illustration that you are working on, click the Save link in the Illustration navigation bar, then click Delete. To delete a different illustration, go to the Illustrations section of the Experiment summary, locate the illustration to delete and click the trash can icon to the right. To delete all illustrations where you are the author, click the “Delete all your illustrations,” button on the bottom right of the Illustrations section. Any illustrations on which you are not the Author will not be deleted.
To collaborate on an illustration, you need to share your experiment with another user and unlock the illustration for editing. In a shared experiment, by default, your collaborators can view your illustrations but not make any changes directly. Instead, they can clone a copy. To instead enable other users with access to your experiment to edit an illustration, you can unlock it for editing. Click the dark blue padlock symbol from within your open illustration or from the Illustrations section of the Experiment summary. If multiple users are simultaneously editing an illustration, conflicts may arise and a warning will appear.
To reset an illustration that you are working on back to the default layout and plot settings, click Save in the Illustration navigation bar, then click Reset. If auto-save is enabled, your saved illustration will be reset to defaults.