enclone provides several mechanisms for creating, displaying, and exporting a phylogenetic
tree for each
clonotype. These are initial mechanisms, which are likely to be expanded and/or improved over
time in response to feedback. The initial implementation is inspired by the Levenshtein-NJ method described by Yermanos et al. 2017. For all of these mechanisms, we recommend using the argument
COMPLETE to remove exact subclonotypes that are missing 1 or more chains.
Method 1.
This method is invoked using the argument TREE, or TREE=v1,...vn,
where the vi are parseable variables.
The method first defines defines the distance between any two exact subclonotypes to be their
Levenshtein distance. We then add a root "virtual" exact subclonotype which equals the donor
reference away from the recombination region and which is undefined within that region (i.e. a
germline-reverted exact clonotype without the junction). The distance from the root to any
actual exact subclonotype is the Levenshtein distance, away from the region of recombination.
Next a tree is creating from these data using the neighbor joining algorithm. This sometimes yields negative distances, which we change to zero. We have only observed such negative distances on the edge emanating from the root.
Note that for a given clonotype, the neighbor joining algorithm is
O(n4), where n is the number of exact subclonotypes in the clonotype. Thus
for sample types having highly complex clonotypes (e.g. with ~1000 subclonotypes), the
algorithm will be very slow. Of course for such cases, the tree would be so large that it would
be difficult to do anything with it. You could exclude such clonotypes e.g. with
MAX_CELLS=100.
Finally, the tree is visualized using plain text, as shown in the example below. The
added field dref shows the distance of each exact subclonotype from the
donor reference, away from the recombination region.
enclone BCR=123085 TREE COMPLETE CDR3=CARDQNFDESSGYDAFDIW LVARSP=dref
[1] GROUP = 1 CLONOTYPES = 42 CELLS
[1.1] CLONOTYPE = 42 CELLS
┌──────────────┬────────────────────────────────────────────────────────────┬───────────────────────────────────────┐
│ │ CHAIN 1 │ CHAIN 2 │
│ │ 159|IGHV3-7 ◆ 53|IGHJ3 │ 376|IGLV5-37 ◆ 313|IGLJ3 │
│ ├────────────────────────────────────────────────────────────┼───────────────────────────────────────┤
│ │ 11 1111111111111111111 │ 11 11111111111 │
│ │ 23344445667777788999901 1111112222222222333 │ 23556679911 11111122222 │
│ │ 22324893380156725357903 4567890123456789012 │ 17068902403 45678901234 │
│ │ ════════CDR3═══════ │ ════CDR3═══ │
│reference │ LPGAGSSSLNKQEKYVRANLLQ◦ ◦◦◦◦◦◦◦◦◦◦◦◦◦◦◦◦◦◦W │ VRSYLYYAAAY CMIW◦◦◦◦◦◦◦ │
│donor ref │ LPGAGSSSLNKQEKYVRANLLQ◦ ◦◦◦◦◦◦◦◦◦◦◦◦◦◦◦◦◦◦W │ VRSYLYYAAAY CMIW◦◦◦◦◦◦◦ │
├──────────────┼────────────────────────────────────────────────────────────┼───────────────────────────────────────┤
│# n dref │ xxxxxxxxxxxxxxxxxxxxxxx .x......x........x. u const │ xxxxxxxxxxx ........... u const│
│1 10 8 │ LPGAGSSSPNKEEKYVRANLLQY CARDQNFDESSGYDAFDIW 2323 IGHG1 │ VRGYLYYAAAY CMIWPSNAWVF 14585 IGLC2│
│2 8 9 │ LPGAGSSSLNKEEKYMRANLLQY CARDQNFDESSGYDAFDIW 3121 IGHG1 │ VRSYLYYAAAY CMIWPSNAWVF 11855 IGLC2│
│3 6 9 │ LPGAKSNSLNKEQKYVRANLLQY CARDQNFDESSGYDAFDIW 1171 IGHG1 │ VRSYLYYTAAY CMIWPSNAWVF 7613 IGLC2│
│4 5 4 │ LPGAGSSSLNKEEKYVRANLLQY CARDQNFDESSGYDAFDIW 11 IGHG1 │ VRSYLYYAGAY CMIWPSNAWVF 26 IGLC2│
│5 2 8 │ LPGAGSSSLNKEEKYMRANLLQY CARDQNFDESSGYDAFDIW 1005 IGHG1 │ VRSYLYYAAAY CMIWPSNAWVF 4779 IGLC2│
│6 1 8 │ LPGAKSNSLNKEQKYVRANLLQY CARDQNFDESSGYDAFDIW 5862 IGHG1 │ VRSYLYYAAAY CMIWPSNAWVF 14144 IGLC2│
│7 1 7 │ LPGAGSNSLNKEEIYVRANLLEY CTRDQNFDESSGYDAFDIW 4384 IGHG1 │ VRSYLYYAAAY CMIWPSNAWVF 14621 IGLC2│
│8 1 3 │ LPGAGSSSLNKEEKYVRANLLQY CARDQNFDDSSGYDAFDIW 3890 IGHG1 │ VRSYLYYAAAY CMIWPSNAWVF 15577 IGLC2│
│9 1 3 │ LPGAGSSSLNKEEKYVRANLLQY CARDQNFDESSGYDAFDIW 3302 IGHG1 │ VRSYLYYAAAY CMIWPSNAWVF 5256 IGLC2│
│10 1 9 │ LPGAGSSSPNKEEKYVRANLLQY CARDQNFDESSGYDAFDIW 3067 IGHG1 │ VRGYLYYAAAY CMIWPSNAWVF 6429 IGLC2│
│11 1 13 │ LPGAGRNSLNKEEKYVRGNLLQY CARDQNFDESSGYDAFDIW 2724 IGHG3 │ VRGYLYYAAAY CMIWPSNAWVF 5775 IGLC2│
│12 1 9 │ LPGAGSSSLNKEEKYMRANLLQY CARDQNFDESSGYDAFDIW 2578 IGHA1 │ VRSYLYYAAAY CMIWPSNAWVF 14497 IGLC2│
│13 1 7 │ LPGAGSSSPNKEEKYVRANLLQY CARDQNFDESSGYDAFDIW 839 IGHG1 │ VRGYLYYAAAY CMIWPSNAWVF 7816 IGLC2│
│14 1 7 │ LPGAGSSSLNKEEKYVRANLLQY CARDQNFDESSGYDAFDIW 404 IGHG1 │ VRGYLYYAAAY CMIWPSNAWVF 3456 IGLC2│
│15 1 1 │ LPGAGSSSLNKQEKYVRANLLQY CARDQNFDESSGYDAFDIW 136 IGHG1 │ VRSYLYYAAAY CMIWPSNAWVF 1023 IGLC2│
│16 1 9 │ LPGAGSNSLNKEEIYVRANLLEY CTRDQNFDESSGYDAFDIW 96 IGHG1 │ VRSYLYYAAAY CMIWPSNAWVF 1762 IGLC2│
└──────────────┴────────────────────────────────────────────────────────────┴───────────────────────────────────────┘
•
╚═ • [0.00]
╠════════ 15 [1.33]
╚═══ • [0.50]
╠════════════ • [2.00]
║ ╠══════ 4 [1.00]
║ ╚═ 9 [0.00]
╚══ • [0.34]
╠════════════════════════════════ • [5.53]
║ ╠══ • [0.34]
║ ║ ╠════ • [0.61]
║ ║ ║ ╠═══ 1 [0.50]
║ ║ ║ ╚═════════ 10 [1.50]
║ ║ ╚══ 13 [0.39]
║ ╚════ 14 [0.66]
╚═ • [0.10]
╠═══════════════ 8 [2.65]
╚═══ • [0.55]
╠═════════════════════ • [3.58]
║ ╠═══════════════════════ • [4.00]
║ ║ ╠═════ • [0.79]
║ ║ ║ ╠═ 2 [0.00]
║ ║ ║ ╚═ 12 [0.00]
║ ║ ╚═ 5 [0.21]
║ ╚══════════════════════════════════════════════ 11 [8.00]
╚═ • [0.17]
╠═══════════════════════════════════════ • [6.70]
║ ╠══════ 3 [1.00]
║ ╚═ 6 [0.00]
╚════════════════════════════════════ • [6.30]
╠═ 7 [0.00]
╚════════════ 16 [2.00]
Method 2.
This method is invoked using the argument NEWICK, and is exactly like
method 1, except that it outputs the resulting tree in
Newick format.
For example, running enclone BCR=123085 NEWICK COMPLETE CDR3=CARDSWYSSGRNTPNWFDPW
will generate the following Newick tree for the largest clonotype:
(((4:0.00,(11:0.00,19:4.00)I4:1.00)I7:0.66,(6:0.80,((12:0.04,14:6.96)I6:0.96,(((((2:0.00,18:0.00)I1:0.94,5:0.06)I2:0.50,17:0.50)I3:5.95,(3:0.04,(8:0.00,9:1.00)I5:0.96)I8:0.55)I11:0.47,(((7:0.02,16:0.98)I9:0.04,20:2.96)I10:0.97,(1:0.00,(10:2.00,(13:1.00,15:0.00)I19:0.00)I18:0.00)I17:0.03)I16:0.00)I15:0.03)I14:0.17)I13:0.20)I12:0.00)0;
This tree can be copied and pasted or otherwise exported to be viewed in tools such as iTOL.
Method 3.
This method is invoked using the argument CLUSTAL_DNA=filename or
CLUSTAL_AA=filename, where
filename can be stdout, and otherwise must have the extension
".tar". It does not generate a tree, but instead
generates a CLUSTALW alignment for each clonotype (using either bases or
amino acids), with one sequence for each exact subclonotype.
This sequence is the concatenation of the per-chain sequences, with the appropriate number
of gap (-) characters shown if a chain is missing. As above, we recommend using the
COMPLETE option to avoid this happening.
If filename is stdout, then the alignments are printed out
after each clonotype picture. Otherwise, a tar file is generated, which if untarred yields
one file per clonotype. To avoid confusion, it would be best for filename to have
the suffix .tar. We also recommend using MIN_CELLS=... or some other
argument to restrict the number of files that would be generated upon untarring.
This method can be used to provide input to another program that will generate a tree.
Method 4.
This method is invoked using the argument PHYLIP_DNA=filename or
PHYLIP_AA=filename, and is just like method 3, except for the output format.