plots

enclone can create these types of plots:

• a "honeycomb" plot showing each clonotype as a cluster of dots, one per cell
• a dotplot of one variable versus another variable
• a matrix plot showing the cosine similarity across cells between variables in a list

honeycomb plots

Honeycomb plots display cells as dots, with each clonotype represented as a hexagonal cluster of cells. enclone provides various controls over the configuration of the plots, as described in the next sections.

Hint. You may wish to use the MIN_CELLS option (see enclone help filter) to exclude tiny clonotypes, which might otherwise crowd the image and slow down plotting.

coloring of cells in honeycomb plots

enclone provides a number of ways to assign colors in such a plot. We describe them in order of precedence, i.e. color data for the first will be used if provided, etc.

The syntax for this is under development and fragmented at present.

PLOT="filename,origin1->color1,...,originn->colorn"

Example: enclone BCR=123085:123089 MIN_CELLS=10 PLOT="plot.svg,s1->blue,s2->red" NOPRINT LEGEND=blue,123085,red,123089

Note the colon between 123085 and 123089. This tells enclone that the two datasets are different origins from the same donor. For example, they might represent cells collected at two time points. This is not actually true in this case, as these two datasets have the same origin, but is needed to plot in this way.

The NOPRINT argument tells enclone to not generate its usual output, so although the command itself will appear to do nothing, it will create a file plot.svg.

If you're using a Mac, then the file plot.svg in the command can be displayed by typing open plot.svg. In that case the application used to display the plot will be picked for you. You can specify a particular app e.g. with open -a "Google Chrome" plot.svg.

Here is a simpler example, which plots the clonotypes in a single dataset (plot not shown): enclone BCR=123085 MIN_CELLS=10 PLOT="plot.svg,s1->blue" NOPRINT.

PLOT=filename

Example: enclone BCR=123085,123089 MIN_CELLS=5 MIN_CHAINS_EXACT=2 NOPRINT PLOT_BY_ISOTYPE=plot.svg

If desired, an additional argument PLOT_BY_ISOTYPE_COLOR=color1,...,colorn maybe used to define an alternate color list. The first color is for the undetermined case, and the subsequent colors are in order by constant region name. enclone will fail if the list is not long enough.

The legend may be suppressed using the argument SUPPRESS_ISOTYPE_LEGEND.

Example: enclone BCR=123085 MIN_CELLS=10 HONEY=out=plot.svg,color=var,u_cell1 NOPRINT

In the given dataset, for cells in clonotypes having at least ten cells, the plot colors each by the value of the variable u_cell1, the number of UMIs in the first chain within the cell's clonotype. The variable is sometimes undefined because a clonotype can include cells which are missing the first chain. Note also that using the variable u1 would have instead colored cells by the median number of UMIs for their first chain, where the median is computed across the exact subclonotype containing the cell.

See merged syntax, below.

Example: enclone BCR=123085,123089,124547 MIN_CELLS=5 HONEY=out=gui,color=dataset

See merged syntax, below.

Example: enclone BCR=123085 HONEY=out=plot.svg,color=catvar,v_name1+v_name2,maxcat:10 NOPRINT CHAINS_EXACT=2

See merged syntax, below.

Merged syntax

Here we show the syntax for coloring by variable or dataset.

Red fields are to be filled in by you.

colors

The colors should be valid colors for use in an svg file. They can be named colors like red or blue (see here for a full list) or a hex specification like #00FFFF for aqua. The full color description for svg is here.

enclone also recognizes the color abbreviations @1, ..., @6, which refer to enclone's color blind friendly palette (see enclone help color).

Each cell is shown as a disk having the given color, and each clonotype is shown as a cluster of these disks, which are positioned at random. The filename argument may be "stdout".

layout

We describe here two options that can be used to modify the layout of honeycomb plots.

If desired, the honeycomb plots can be forced into the first quadrant using the QUAD_HIVE option.

enclone BCR=123085:123089 PLOT="plot.svg,s1->blue,s2->red" QUAD_HIVE NOPRINT

enclone can make side-by-side honeycomb plots to facilitate comparison between different cell origins. For example, these origins could be from different tissues, or the cells could be prepared differently.

In this example we have two datasets, specified using a colon as 123085:123089, which treats them as arising from two origins. These particular data are actually replicates.

Specification in this manner with SPLIT_PLOT_BY_ORIGIN causes all the 123085 cells to be shown in the left plot, and all the 123089 cells to be shown in the right plot. Thus a cluster in the picture may be a partial clonotype, relative to the entirety of the data.

In principle more than two origins can be specified.

enclone BCR=123085:123089 PLOT_BY_ISOTYPE=plot.svg SPLIT_PLOT_BY_ORIGIN NOPRINT

other controls

To add a legend to the graph, add the argument LEGEND to your command line. This will give you an auto-generated legend. You can also customize the legend by adding an argument of the form LEGEND=color1,"text1",...,colorn,"textn" to the command line.

When enclone creates a honeycomb plot, it tries to rearrange clonotypes so as to place identically colored clonotypes next to each other. If you want to create two plots of the same data, in which the positions of the cells are fixed by the first plot, you can do this by providing an argument HONEY_OUT=filename to a first enclone command, and then HONEY_IN=filename to a second enclone command, where both commands refer to the same file.

plots of one variable versus another

If xvar and yvar are the names of variables (see enclone variable inventory, enclone help lvars, enclone help cvars and enclone help parseable), and those variables have numeric values, then enclone can produce a plot of xvar versus yvar, showing a point for each exact subclonotype (after all filtering) for which both variables are defined and are numbers. The syntax is PLOTXY_EXACT="xvar,yvar,filename". The file is an SVG file. We allow xvar = log10(v) for some parseable variable v, and likewise for yvar. The quotes are only needed if the variables have "funny" characters in them.

Example.

An optional fourth argument sym may be added to force a square plot having identical tic marks on the axes. This makes sense, for example, when comparing data from replicates.

plots of cosine similarity between multiple variables

Given a list of numeric variables, enclone can display their pairwise correlation, where the correlation of two variables is the cosine similarity of their vectors (ranging across cells).

Example.