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 have 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.
To view the details of plot settings for Summary plots, please check out the 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 you 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.
The Cytobank platform 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 links 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).
(Illustration from PBMC experiment. The layout in this illustration is rows 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).)
For a simpler view of the illustration to focus on the layout without seeing all 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.
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.
HYPERLINK "https://support.cytobank.org/hc/article_attachments/360069815212/blobid2.png"
(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.
HYPERLINK "https://support.cytobank.org/hc/article_attachments/360070034591/blobid3.png"(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 Table 1 position. Click 2 of 24 to choose which channels to display. If channels appear in different panels, you can filter out the channels belonging to the same panel. To do so, click on the panel name on the right-hand side of the channel list. You can also search for the panel name in the search box.
(Left, Layout settings menu highlighted to indicate where to access the channel selection menu. Right, 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 showing 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:
- 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, Contour, and Histograms as event-level plots and Heatmap, Box, Violin, Bar, Line, and Summary dots as Summary charts. This article describes only the event-level plots. Please check out also these articles of the summary charts and the heatmap.
Overlaid: Dot plots and Histograms can be overlaid by a dimension.
- Concatenate: Dot plots, Histograms and Contour can be concatenated. None, Rows, columns, or All multi-files positions are available. If the dimension located on the position does not have multiple files, that position is greyed out and not selectable.
- Color by: Density, X-axis channel, overlaid dimension, or black.
- Palette: Nine coloring palettes are available. Histograms can be customized by outline and/or fill color.
- Show gates: Gates are shown on the plots. When using overlaid or concatenate with tailored gating, gates on the first FCS file are shown.
- Size: 64 (Tiny) to 512 (Huge) pixels, or Placeholder.
- Other customizable settings: More plot settings button opens a window for customizing detailed settings such as black background, axis markings, statistics and more.
This article will walk through setting up a dot plot colored by density or colored by Z-axis channel 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, Overlaid, Concatenate, Palette, Show gates, and Size. To change basic plot settings, either click on Plots in the illustration navigation bar, or hover over 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 in More plot settings > Axis markings section > open Axis labels menu.
More plot settings available vary by plot type:
- Dot: For color by density, density dot settings include kernel smoothing, percent per contour, and outlier settings can be customized. For color by Z-axis channels, Z channel settings include Z-axis range and dot plotting method can be customized.
- Histogram: Additional settings include outline and fill color selection, aspect ratio, kernel smoothing, orientation, and smooth curves.
- For all plot types, axis markings can be configured in more plot settings, including whether to show axis tickmarks, scale numbers 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 open Axis labels menu and choose whether to show the label on every plot in every row/column 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 show 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 Channels dimension, you can choose to show the Channel name, or the axis in combination with the channel name, e.g. x: pStat3.
- 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.
5) Dynamically update the illustration
After setting up your layout and plots, you can continue to modify any of the layout or plot settings. Any changes made to illustrations with up to 150 new plots will automatically update whenever a change is made. If your changes add more than 150 new plots, a green Update illustration button will appear to click to 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 by 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.
Displaying file-concatenated plots
If you need to display file-concatenated plots to compare the groups of experimental variables which include multiple files or to view a comprehensive distribution of populations within all files, please check out How to combine events from different files into one plot (Virtual Concatenation).
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 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 select Click to view in the green message that indicates 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 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.
*For Research Use Only. Not for use in diagnostic procedures.