Frequently Asked Questions

We're sorry you're having difficulty! Please see the answers below or check out the other help
guides.

1. Why is my enclone output garbled?

We can think of two possibilities:

A. The escape characters that enclone emits for color and bolding are not getting
translated.  You have some options:
(a) Turn off escape character generation by adding PLAIN to your enclone commands.
This will work but you'll lose some information.
(b) If your terminal window is not translating escape characters, ask someone
with appropriate expertise to help you.  We have not observed this phenomenon,
but it should be fixable.
(c) If you're trying to view enclone output, with escape characters, using an editor,
that's probably not going to work well.

B. Perhaps enclone is emitting very wide lines.  Here are things you can do about this:
(a) Make your terminal window wider or reduce the font size.
(b) Identify the field that is very wide and use the column controls to remove that
field.  See the help for lvars and cvars.  For example,
AMINO=cdr3
may help, or even
AMINO=
These options may also help: CVARS=u FOLD_HEADERS.

2. Can I convert the enclone visual output into other forms?

Yes, there are choices:
A. On a Mac, you can screenshot from a terminal window.
B. Add the argument HTML to the enclone command line.  Then the output will be presented as html,
with title "enclone output".  If you want to set the title, use HTML="...".
C. You can then convert the html to pdf.  The best way on a Mac is to open Safari, which is the
best browser for this particular purpose, select the file where you've saved the html, and then
export as pdf.  Do not convert to pdf via printing, which produces a less readable file, and also
distorts colors.  (We do not know why the colors are distorted.)
D. If you want to put enclone output in a Google Doc, you can do it via approach A, although then
you won't be able to select text within the copied region.  Alternatively, if you open the html
file in a browser, you can then select text (including clonotype box text) and paste into a Google
Doc.  It will be pretty ugly, but will capture color and correctly render the box structure,
provided that you use an appropriate fixed-width font for that part of the Doc.  We found that
Courier New works, with line spacing set to 0.88.  You may have to reduce the font size.

3. Why is enclone slow for me?

On a single VDJ dataset, it typically runs for us in a few seconds, on a Mac or Linux server. 
Runs where we combine several hundred datasets execute in a couple minutes (on a server).  Your
mileage could vary, and we are interested in cases where it is underperforming.  Let us know.  We
are aware of several things that could be done to speed up enclone.

4. How does enclone fit into the 10x Genomics software ecosystem?

There are several parts to the answer:
• enclone is a standalone executable that by default produces human-readable output.
• You can also run enclone to produce parseable output (see enclone help parseable), and that
output can be digested using code that you write (for example, in R).
• When you run Cell Ranger to process 10x single cell immune profiling data, it in effect calls
enclone with a special option that yields only an output file for the 10x visualization tool
Loupe.
• Clonotypes may then be viewed using Loupe.  The view of a clonotype provided by Loupe is
different than the view provided by enclone.  Loupe shows a continuous expanse of bases across
each chain, which you can scroll across, rather than the compressed view of "important" bases or
amino acids that enclone shows.

5. What platforms does enclone run on?

1. Linux/x86-64 (that's most servers)
2. Mac.

However, we have not and cannot test every possible configuration of these platforms.  Please let
us know if you encounter problems!

6. How can I print out all the donor reference sequences?

Add the argument DONOR_REF_FILE=filename to your enclone command, and fasta for the donor
reference sequences will be dumped there.

7. How does enclone know what VDJ reference sequences I'm using?

If you used Cell Ranger version 4.0 or greater, then the VDJ reference file was included in the
outs directory, and so enclone knows the reference sequence from that.

For outs from older Cell Ranger versions, enclone has to guess which VDJ reference sequences were
used, and may or may not do so correctly.  As part of this, if you have mouse data from older Cell
Ranger versions, you need to supply the argument MOUSE on the command line.

It is also possible to set the reference sequence directly by adding by adding REF=f to your
command line, where f is the name of your VDJ reference fasta file, but if that is different than
the reference supplied to Cell Ranger, then you will have to add the additional argument RE to
recompute annotations, and that will slow down enclone somewhat.

8. Can I provide data from more than one donor?

Yes.  Type enclone help input for details.  The default behavior of enclone is to prevent cells
from different donors from being placed in the same clonotype.  The MIX_DONORS option may be used
to turn off this behavior.  If you employ this option, then clonotypes containing cells from more
than one donor will be flagged as errors, unless you use the NWARN option to turn off those
warnings.  The primary reason for allowing entry of data from multiple donors is to allow
estimation of enclone's error rate.

9. What are some command line argument values quoted?

Command line argument values that contain any of these characters ;|* need to be quoted like so
TCR="a;b"
to prevent the shell from interpreting them for a purpose completely unrelated to enclone.  This
is a trap, because forgetting to add the quotes can result in nonsensical and confusing behavior!

10. If enclone fails, does it return nonzero exit status?

Yes, unless output of enclone is going to a terminal.  In that case, you'll always get zero.

11. Could a cell be missing from an enclone clonotype?

Yes, some cells are deliberately deleted.  The cell might have been deleted by one of the filters
described in enclone help special, and which you can turn off.  We also delete cells for which
more than four chains were found.

12. Can enclone print summary stats?

Yes, if you add the option SUMMARY, then some summary stats will be printed.  If you wish to
suppress visual output, then also add the option NOPRINT.

13. What is the notes column?

The notes column appears if one of two relatively rare events occurs:

1. An insertion is detected in a chain sequence, relative to the reference.

2. The end of the J segment on a chain sequence does not exactly coincide with
   the beginning of the C segment.
The latter could correspond to one of several phenomena:
a. A transcript has an insertion between its J and C segments.
   This can happen.  See e.g. Behlke MA, Loh DY.
   Alternative splicing of murine T-cell receptor beta-chain transcripts.
   Nature 322(1986), 379-382.
b. There is an error in a reference sequence segment.
   We have tried to eliminate all such errors from the built-in references for
   human and mouse.
c. A cell produced a nonstandard transcript and also standard ones, and the
   Cell Ranger pipeline just happened to pick a nonstandard one.
d. There was a technical artifact and the sequence does not actually represent
   an mRNA molecule.

Overlaps of length exactly one between J and C segments are not shown unless you specify the
option JC1.  The reason for this is that certain reference sequences (notably those from IMGT and
those supplied with Cell Ranger 3.1) often have an extra base at the beginning of their C
segments, resulting in annoying overlap notes for a large fraction of clonotypes.

14. Can I cap the number of threads used by enclone?

You can use the command-line argument MAX_CORES=n to cap the number of cores used in parallel
loops.  The number of threads used is typically one higher.

15. Can I use enclone if I have only gene expression data?

Possibly.  In some cases this works very well, but in other cases it does not.  Success depends on
dataset characteristics that have not been carefully investigated.  To attempt this, you need to
invoke Cell Ranger on the GEX dataset as if it was a VDJ dataset, and you need to specify to Cell
Ranger that the run is to be treated as BCR or TCR.  Two separate invocations can be used to get
both.  Note also that Cell Ranger has been only minimally tested for this configuration and that
this is not an officially supported Cell Ranger configuration.

16. How can I cite enclone?

10x Genomics, https://github.com/10XGenomics/enclone,
(your enclone version information will be printed here).
You can cite the enclone preprint, which can be found on bioRxiv in the link below or by using the
DOI 10.1101/2022.04.21.489084. The latest version of the preprint can be found at:
https://www.biorxiv.org/content/10.1101/2022.04.21.489084v1.

17. Can I print the enclone version?

Yes, type "enclone version".

18. Can enclone ingest multiple datasets from the same library?

If enclone detects significant (≥ 25%) barcode reuse between datasets, it will exit.  This
behavior can be overridden using the argument ACCEPT_REUSE.

19. Can I turn off all the filters used in joining clonotypes?

Pretty much.  You can run with the following arguments:
MAX_CDR3_DIFFS=100
MAX_LOG_SCORE=100
EASY
MAX_DIFFS=200
MAX_DEGRADATION=150,
however this will in general be very slow and not produce useful results.  Depending on what your
goal is, you may find it helpful to use some of these arguments, and with lower values.  You can
see the meaning of the arguments and their default values by typing enclone help how.

20. How can I send the developers an example?

Use filters to select a clonotype or clonotypes of interest.  Then you can cut and paste enclone
output into an email.  If you want the example to be reproducible by us, add the argument
SUBSET_JSON=filename to the command line, which will create a json file containing only data for
the barcodes in the clonotype.  Then send us the file as an email attachment.  This only works for
VDJ data, and we do not have a parallel mechanism for gene expression and antibody data.  Please
note also that running enclone on the barcodes from a single clonotype will not necessarily
reproduce the results you observed, because the clonotyping algorithm uses all the data, even if
only some clonotypes are selected.