enclone variable inventory

This page provides an alphabetical catalog of enclone variables, along with some general information.

enclone variables are complicated because there are different types and different ways that they can be used. This pages specifies the system, but also provides an example, and for a first pass, you may wish to just read that.

General information

enclone allows variables to be used in the following ways:

in visual output (clonotype tables)
in parseable output
in linear constraints.

All variables are in one of two classes:

lvar: a lead variable; these are not associated to a particular chain, and when they appear in clonotype tables, they're at the beginning (leading), before the variables that are associated to a chain
cvar: a chain variable; these are associated to a particular chain. Except when used in CVARS or CVARSP, these need to be suffixed by the chain number.

All variables are specified at one of the following levels:

cell: defined for each cell
cell-exact: defined for each cell, and also has a value for an exact subclonotype
exact: defined for each exact subclonotype
clono: defined for each clonotype
group: defined for each group of clonotypes
dataset: defined for each dataset
global: defined for entirety of all clonotypes.

This table shows how the level is reflected in the output:

level	visual output		parseable output		notes
level	exact	cell	exact	cell	notes
cell	no	yes	no	yes
cell-exact	yes	yes	yes	yes
exact	yes	no	yes	yes
clono	yes	no	yes	yes
group	no	no	yes	yes	not available at all for visual output
dataset	no	no	no	no	currently only accessible via `DVARS`
global	no	no	no	no	currently only accessible via `GVARS`

Here are some rules about how this works (and please see the example below, which may be more instructive):

In visual output, the default behavior is to display at the exact level. Variables which are defined only at the cell level will show as null (blank).
If you provide the argument PER_CELL, then visual output is in a "split" mode, appearing both at the exact and cell levels.
In parseable output, the default behavior is to display at the exact level. Variables which are defined only at the cell level are not allowed.
If you provide the argument PCELL, then parseable output is instead displayed at the cell level. Moreover, every cell-exact variable has a special _cell version that can be used in this mode. This allows you to use both the exact version and the cell version.

Example

The following example illustrates how this applies to the cell-exact variable u:

enclone BCR=123085 CDR3=CALMGTYCSGDNCYSWFDPW POUT=stdouth PCOLS=barcodes,u1

[1] GROUP = 1 CLONOTYPES = 6 CELLS

[1.1] CLONOTYPE = 6 CELLS
┌───────────┬───────────────────────────────────────┬─────────────────────────────┐
│           │  CHAIN 1                              │  CHAIN 2                    │
│           │  98|IGHV2-5 ◆ 13|IGHD2-15 ◆ 57|IGHJ5  │  349|IGLV3-1 ◆ 311|IGLJ2    │
│           ├───────────────────────────────────────┼─────────────────────────────┤
│           │    11111111111111111111               │    11111111111              │
│           │  8 11111222222222233333               │  6 00000111111              │
│           │  5 56789012345678901234               │  2 56789012345              │
│           │    ════════CDR3════════               │    ════CDR3═══              │
│reference  │  S ◦◦◦◦◦◦◦◦◦◦◦◦◦◦◦◦◦◦◦W               │  V CQAWD◦◦◦◦◦◦              │
│donor ref  │  S ◦◦◦◦◦◦◦◦◦◦◦◦◦◦◦◦◦◦◦W               │  V CQAWD◦◦◦◦◦◦              │
├───────────┼───────────────────────────────────────┼─────────────────────────────┤
│#  n       │  x ..x.......xx........     u  const  │  x ...........      u  const│
│1  3       │  S CALMGTYCSGDNCYSWFDPW   592  IGHM   │  V CQAWDSSVVVF   2995  IGLC2│
│2  1       │  S CALMGTYCSGDNCYSWFDPW  6218  IGHG1  │  V CQAWDSSVVVF  15182  IGLC2│
│3  1       │  T CALMGTYCSGDNCYSWFDPW  4033  IGHG1  │  V CQAWDSSVVVF   6777  IGLC2│
│4  1       │  S CAHMGTYCSGGSCYSWFDPW    18  IGHG1  │  V CQAWDSSVVVF    592  IGLC2│
└───────────┴───────────────────────────────────────┴─────────────────────────────┘
barcodes                                                    u1
CGTTCTGGTAGCCTCG-1,GCGCCAAGTATTACCG-1,TGGCCAGGTTACGCGC-1   592
GACCTGGAGCGTGAAC-1                                        6218
CTCCTAGCAAGGACAC-1                                        4033
AGCTTGACAATGGAGC-1                                          18

enclone BCR=123085 CDR3=CALMGTYCSGDNCYSWFDPW PER_CELL POUT=stdouth PCELL PCOLS=barcode,u1,u_cell1

[1] GROUP = 1 CLONOTYPES = 6 CELLS

[1.1] CLONOTYPE = 6 CELLS
┌──────────────────────────┬───────────────────────────────────────┬─────────────────────────────┐
│                          │  CHAIN 1                              │  CHAIN 2                    │
│                          │  98|IGHV2-5 ◆ 13|IGHD2-15 ◆ 57|IGHJ5  │  349|IGLV3-1 ◆ 311|IGLJ2    │
│                          ├───────────────────────────────────────┼─────────────────────────────┤
│                          │    11111111111111111111               │    11111111111              │
│                          │  8 11111222222222233333               │  6 00000111111              │
│                          │  5 56789012345678901234               │  2 56789012345              │
│                          │    ════════CDR3════════               │    ════CDR3═══              │
│reference                 │  S ◦◦◦◦◦◦◦◦◦◦◦◦◦◦◦◦◦◦◦W               │  V CQAWD◦◦◦◦◦◦              │
│donor ref                 │  S ◦◦◦◦◦◦◦◦◦◦◦◦◦◦◦◦◦◦◦W               │  V CQAWD◦◦◦◦◦◦              │
├──────────────────────────┼───────────────────────────────────────┼─────────────────────────────┤
│#  barcode             n  │  x ..x.......xx........     u  const  │  x ...........      u  const│
│1                      3  │  S CALMGTYCSGDNCYSWFDPW   592  IGHM   │  V CQAWDSSVVVF   2995  IGLC2│
│   CGTTCTGGTAGCCTCG-1     │                           592         │                  2995       │
│   GCGCCAAGTATTACCG-1     │                           104         │                   172       │
│   TGGCCAGGTTACGCGC-1     │                          6617         │                 12097       │
│2                      1  │  S CALMGTYCSGDNCYSWFDPW  6218  IGHG1  │  V CQAWDSSVVVF  15182  IGLC2│
│   GACCTGGAGCGTGAAC-1     │                          6218         │                 15182       │
│3                      1  │  T CALMGTYCSGDNCYSWFDPW  4033  IGHG1  │  V CQAWDSSVVVF   6777  IGLC2│
│   CTCCTAGCAAGGACAC-1     │                          4033         │                  6777       │
│4                      1  │  S CAHMGTYCSGGSCYSWFDPW    18  IGHG1  │  V CQAWDSSVVVF    592  IGLC2│
│   AGCTTGACAATGGAGC-1     │                            18         │                   592       │
└──────────────────────────┴───────────────────────────────────────┴─────────────────────────────┘
barcode               u1  u_cell1
CGTTCTGGTAGCCTCG-1   592      592
GCGCCAAGTATTACCG-1   592      104
TGGCCAGGTTACGCGC-1   592     6617
GACCTGGAGCGTGAAC-1  6218     6218
CTCCTAGCAAGGACAC-1  4033     4033
AGCTTGACAATGGAGC-1    18       18

Defining new variables as expressions

enclone allows new variables to be defined as expressions using VAR_DEF=..., like this:

enclone BCR=86237 GEX=85679 VAR_DEF="sum:CD19_ab + CD25_ab" LVARSP=CD19_ab,CD25_ab,sum 
CDR3=CARSFFGDTAMVMFQAFDPW PER_CELL FOLD_HEADERS

[1] GROUP = 1 CLONOTYPES = 3 CELLS

[1.1] CLONOTYPE = 3 CELLS
┌────────────────────────────────────────────────────┬──────────────────────────────────┬───────────────────────┐
│                                                    │  CHAIN 1                         │  CHAIN 2              │
│                                                    │  194|IGHV4-59                    │  349|IGLV3-1          │
│                                                    │  ◆ 29|IGHD5-18                   │  ◆ 311|IGLJ2          │
│                                                    │  ◆ 57|IGHJ5                      │                       │
│                                                    ├──────────────────────────────────┼───────────────────────┤
│                                                    │  11111111111111111111            │  11111111111          │
│                                                    │  11111112222222222333            │  00000111111          │
│                                                    │  34567890123456789012            │  56789012345          │
│                                                    │  ════════CDR3════════            │  ════CDR3═══          │
│reference                                           │  ◦◦◦◦◦◦◦◦◦◦◦◦◦◦◦◦◦◦◦W            │  CQAWD◦◦◦◦◦◦          │
│donor ref                                           │  ◦◦◦◦◦◦◦◦◦◦◦◦◦◦◦◦◦◦◦W            │  CQAWD◦◦◦◦◦◦          │
├────────────────────────────────────────────────────┼──────────────────────────────────┼───────────────────────┤
│#  barcode             n  CD19_ab  CD25_ab     sum  │  ....................  u  const  │  ...........  u  const│
│1                      1     1210      102  1312.0  │  CARSFFGDTAMVMFQAFDPW  2  IGHD   │  CQAWDSSTVVF  8  IGLC2│
│   GCTGGGTTCAACCAAC-1        1210      102  1312.0  │                        2         │               8       │
│2                      2      952       53  1004.5  │                                  │  CQAWDSSTVVF  4  IGLC2│
│   ACGTCAAAGTGGTAGC-1         850       80   930.0  │                                  │               6       │
│   ATGTGTGAGAGTACCG-1        1054       25  1079.0  │                                  │               2       │
└────────────────────────────────────────────────────┴──────────────────────────────────┴───────────────────────┘

Note that spaces need to be placed around operators! We require this because some variable names can have operators in them, for example because gene names can include -.

Multiple invocations of VAR_DEF are allowed.

We could easily add the ability to include calls to standard functions, if we had a list of such. Please let us know if this would be useful to you.

Column key

variable	name of the variable
limits	footnote to things missing from the implementation (which in general are deliberate)
class	lvar or cvar
level	cell or exact or clono or group or global
numeric	does the variable have numeric values*
help page	page where variable is documented (both a link and an enclone command)
brief description	summary, see help page for details

*We allow for the null value (the empty string). For example, this would be used if a chain is not present for an exact subclonotype.

user defined, A-B

variable	limits	class	level	numeric	help page	brief description
(from BC or META/bc)		lvar	cell	sometimes	`enclone help input`	user defined variable
(from INFO)		lvar	exact	sometimes	`enclone help input`	user defined variable
`<feature>`		lvar	cell-exact	yes	`enclone help lvars`	count for a gene expression or antibody feature
`<feature>_%`		lvar	cell-exact	yes	`enclone help lvars`	percent of total expression for a particular gene
`<feature>_cellular_r`		lvar	dataset	yes	`enclone help display`	percent of feature reads in cells, for a given dataset
`<feature>_cellular_u`		lvar	dataset	yes	`enclone help display`	percent of feature UMIs in cells, for a given dataset
`<feature>_max`		lvar	exact	yes	`enclone help lvars`	maximum count for a feature
`<feature>_mean`		lvar	exact	yes	`enclone help lvars`	mean count for a feature (same with `μ` for `mean`)
`<feature>_min`		lvar	exact	yes	`enclone help lvars`	minimum count for a feature
`<feature>_sum`		lvar	exact	yes	`enclone help lvars`	sum of counts for a feature (same with `Σ` for `sum`)
`<feature>_Σ`		lvar	exact	yes	`enclone help lvars`	sum of counts for a feature (same with `sum` for `Σ`)
`<feature>_μ`		lvar	exact	yes	`enclone help lvars`	mean count for a feature (same with `mean` for `μ`)
`<dataset>_barcode`	1	lvar	cell	no	`enclone help parseable`	barcode from the given dataset (or null)
`<dataset>_barcodes`	1	lvar	exact	no	`enclone help parseable`	barcodes from the given dataset
`aa%`		cvar	exact	yes	`enclone help cvars`	amino acid identity with donor reference
`barcode`	2	lvar	cell	no	`enclone help parseable`	barcode of the cell
`barcodes`	1	lvar	exact	no	`enclone help parseable`	barcodes for the exact subclonotype

1: only implemented for parseable output

2: only implemented for parseable output, and as an automatic field for clonotype tables in PER_CELL mode

C

variable	limits	class	level	numeric	help page	brief description
`cdiff`		cvar	exact	no	`enclone help cvars`	differences of const region with universal reference
`cdr*_aa`		cvar	exact	no	`enclone help cvars`	CDR* amino acid sequence
`cdr*_aa_L_R_ext`		cvar	exact	no	`enclone help cvars`	CDR* region with specified extension length
`cdr*_aa_north`		cvar	exact	no	`enclone help cvars`	North version of CDR* amino acid sequence
`cdr*_aa_ref`		cvar	clono	no	`enclone help cvars`	CDR* amino acid sequence for universal reference
`cdr*_dna`		cvar	exact	no	`enclone help cvars`	CDR* nucleotide sequence
`cdr*_dna_ref`		cvar	clono	no	`enclone help cvars`	CDR* nucleotide sequence for universal reference
`cdr*_len`		cvar	exact	yes	`enclone help cvars`	length of CDR* amino acid sequence
`cdr3_aa_conp`		cvar	clono	no	`enclone help cvars`	CDR3 amino acid consensus, symbols at variants
`cdr3_aa_conx`		cvar	clono	no	`enclone help cvars`	CDR3 amino acid clonotype consensus, Xs at variants
`cdr3_start`		cvar	exact	yes	`enclone help parseable`	nucleotide start of CDR3 sequence on full sequence
`clen`		cvar	exact	yes	`enclone help cvars`	length of observed constant region
`clonotype_id`	1	lvar	clono	yes	`enclone help parseable`	identifier of clonotype within clonotype group
`clonotype_ncells`		lvar	clono	yes	`enclone help parseable`	number of cells in the clonotype
`comp`		cvar	exact	yes	`enclone help cvars`	CDR3 complexity number
`const`		cvar	exact	no	`enclone help cvars`	constant region name
`const_id`		cvar	exact	yes	`enclone help parseable`	numerical identifier of constant region (or null)
`count_*`		lvar	exact	yes	`enclone help lvars`	count amino acid motifs
`cred`		lvar	cell-exact	yes	`enclone help lvars`	credibility assessed using GEX data

1: only implemented for parseable output

D

variable	class	level	numeric	help page	brief description
`d1_name`	cvar	exact	no	`enclone help cvars`	optimal D segment name
`d2_name`	cvar	exact	no	`enclone help cvars`	second best D segment name
`d1_score`	cvar	exact	yes	`enclone help cvars`	score of optimal D segment
`d2_score`	cvar	exact	yes	`enclone help cvars`	score of second best D segment
`datasets`	lvar	cell-exact	no	`enclone help lvars`	dataset names
`dna%`	cvar	exact	yes	`enclone help cvars`	nucleotide identity with donor reference
`donors`	lvar	cell-exact	no	`enclone help lvars`	donor names
`dref`	lvar	exact	yes	`enclone help lvars`	nucleotide distance to donor reference
`dref_aa`	lvar	exact	yes	`enclone help lvars`	amino acid distance to donor reference
`d_delta`	cvar	exact	yes	`enclone help cvars`	score delta between top two D gene assignments
`d_donor`	cvar	exact	yes	`enclone help cvars`	distance from donor reference
`d_frame`	cvar	exact	yes	`enclone help parseable`	reading frame of D segment (0, 1, 2 or null)
`d_id`	cvar	clono	yes	`enclone help parseable`	D region id
`d_inconsistent_%`	lvar	global	yes	`D genes`	inconsistency percent for D gene assignment
`d_inconsistent_n`	lvar	global	yes	`D genes`	sample size for computation of `d_inconsistent_%`
`d_name`	cvar	clono	no	`enclone help parseable`	D region name
`d_start`	cvar	exact	yes	`enclone help parseable`	start of D on full nucleotide sequence (or null)
`d_univ`	cvar	exact	yes	`enclone help cvars`	distance from universal reference
`d_Δ`	cvar	exact	yes	`enclone help cvars`	score delta between top two D gene assignments

E-F

variable	class	level	numeric	help page	brief description
`edit`	cvar	exact	no	`enclone help cvars`	edit to get from reference CDR3
`exact_subclonotype_id`	lvar	exact	yes	`enclone help cvars`	identifier of exact subclonotype
`filter`	lvar	cell	no	`enclone help lvars`	name of filter that would be applied (if filters off)
`fwr*_aa`	cvar	exact	no	`enclone help cvars`	FWR* amino acid sequence
`fwr*_aa_ref`	cvar	clono	no	`enclone help cvars`	FWR* amino acid seq for universal reference
`fwr*_dna`	cvar	exact	no	`enclone help cvars`	FWR* nucleotide sequence
`fwr*_dna_ref`	cvar	clono	no	`enclone help cvars`	FWR* nucleotide seq for universal reference
`fwr*_len`	cvar	exact	yes	`enclone help cvars`	length of FWR* amino acid sequence

G-M

variable	limits	class	level	numeric	help page	brief description
`g<d>`		lvar	exact	yes	`enclone help lvars`	exact subclonotype group, by Hamming distance
`gex`		lvar	cell-exact	yes	`enclone help lvars`	number of GEX UMIs
`gex_max`		lvar	exact	yes	`enclone help lvars`	maximum number of GEX UMIs across exact subclonotype
`gex_mean`		lvar	exact	yes	`enclone help lvars`	mean of GEX UMIs across exact subclonotype (= `gex_μ`)
`gex_min`		lvar	exact	yes	`enclone help lvars`	minimum number of GEX UMIs across exact subclonotype
`gex_sum`		lvar	exact	yes	`enclone help lvars`	sum of GEX UMIs across exact subclonotype (= `gex_Σ`)
`gex_Σ`		lvar	exact	yes	`enclone help lvars`	sum of GEX UMIs across exact subclonotype (= `gex_sum`)
`gex_μ`		lvar	exact	yes	`enclone help lvars`	mean of GEX UMIs across exact subclonotype (= `gex_mean`)
`group_id`	1	lvar	group	yes	`enclone help parseable`	identifier of clonotype group
`group_ncells`	1	lvar	group	yes	`enclone help parseable`	number of cells in clonotype group
`inkt`		lvar	exact	no	`enclone help lvars`	evidence for iNKT cell
`j_id`		cvar	clono	yes	`enclone help parseable`	J region id
`j_name`		cvar	clono	no	`enclone help parseable`	J region name
`mait`		lvar	exact	no	`enclone help lvars`	evidence for MAIT cell

1: only implemented for parseable output

N-R

variable	limits	class	level	numeric	help page	brief description
`n`	3	lvar	cell-exact	yes	`enclone help lvars`	number of cells
`n_<name>`	3	lvar	cell-exact	yes	`enclone help lvars`	number of cells associated to the given name
`n_gex`		lvar	cell-exact	yes	`enclone help lvars`	number of cells seen by GEX pipeline
`nbc`		lvar	cell	yes	`enclone help lvars`	numerically encoded barcode
`nchains`		lvar	clono	yes	`enclone help lvars`	number of chains in the clonotype
`nchains_present`		lvar	exact	yes	`enclone help lvars`	number of chains present in an exact subclonotype
`ndiff<n>vj`		cvar	exact	yes	`enclone help cvars`	number of base differences with exact subclonotype n
`near`		lvar	exact	yes	`enclone help lvars`	Hamming distance to nearest neighbor
`notes`		cvar	exact	no	`enclone help cvars`	notes for exact subclonotype
`origins`		lvar	cell-exact	no	`enclone help lvars`	origin names
`q<n>_`		cvar	exact	no	`enclone help parseable`	read quality scores at position `n`
`r`		cvar	cell-exact	yes	`enclone help cvars`	number of reads supporting chain
`r_max`		cvar	exact	yes	`enclone help cvars`	maximum chain read count across exact subclonotype
`r_mean`		cvar	exact	yes	`enclone help cvars`	mean chain reads across exact subclonotype (= `r_mean`)
`r_min`		cvar	exact	yes	`enclone help cvars`	minimum chain read count across exact subclonotype
`r_sum`		cvar	exact	yes	`enclone help cvars`	sum of chain read counts across exact subclonotype (= `r_Σ`)
`r_Σ`		cvar	exact	yes	`enclone help cvars`	sum of chain reads across exact subclonotype (= `r_sum`)
`r_μ`		cvar	exact	yes	`enclone help cvars`	mean chain read count across exact subclonotype (= `r_μ`)

3: PER_CELLvalues are not displayed because they are all 1, which would be distracting; also there is no _cell version

S-U

variable	limits	class	level	numeric	help page	brief description
`seq`	1	cvar	exact	no	`enclone help parseable`	full nucleotide sequence of exact subclonotype
`share_indices_aa`	1	cvar	clono	no	`enclone help parseable`	shared amino acid positions
`share_indices_dna`	1	cvar	clono	no	`enclone help parseable`	shared nucleotide positions
`u`		cvar	cell-exact	yes	`enclone help cvars`	number of UMIs supporting chain
`u_max`		cvar	exact	yes	`enclone help cvars`	maximum chain UMIs across exact subclonotype
`u_mean`		cvar	exact	yes	`enclone help cvars`	mean chain UMIs across exact subclonotype (= `u_μ`)
`u_min`		cvar	exact	yes	`enclone help cvars`	minimum chain UMIs across exact subclonotype
`u_sum`		cvar	exact	yes	`enclone help cvars`	sum of chain UMIs for exact subclonotype (= `u_Σ`)
`u_Σ`		cvar	exact	yes	`enclone help cvars`	sum of chain UMIs across exact subclonotype (= `u_sum`)
`u_μ`		cvar	exact	yes	`enclone help cvars`	mean chain UMIs for exact subclonotype (= `u_mean`)
`udiff`		cvar	exact	no	`enclone help cvars`	differences of 5'-UTR region with universal reference
`ulen`		cvar	exact	yes	`enclone help cvars`	length of observed 5'-UTR sequence
`utr_id`		cvar	exact	yes	`enclone help parseable`	numerical identifier of 5'-UTR region (or null)
`utr_name`		cvar	exact	yes	`enclone help parseable`	name 5'-UTR region (or null)

1: only implemented for parseable output

V-Z

variable	limits	class	level	numeric	help page	brief description
`v_id`		cvar	clono	yes	`enclone help parseable`	V region id
`v_name`		cvar	clono	no	`enclone help parseable`	V region name
`v_start`		cvar	exact	yes	`enclone help parseable`	start of V on full nucleotide sequence
`var`		cvar	clono	no	`enclone help cvars`	bases at position in chain that vary across the clonotype
`var_aa`	1	cvar	exact	no	`enclone help parseable`	variant residue indices in clonotype (including synonymous)
`var_indices_aa`	1	cvar	clono	no	`enclone help parseable`	variable amino acid positions
`var_indices_dna`	1	cvar	clono	no	`enclone help parseable`	variable nucleotide positions
`vj_aa`	1	cvar	exact	no	`enclone help parseable`	amino acid sequence of V..J
`vj_aa_nl`	1	cvar	exact	no	`enclone help parseable`	amino acid sequence of V..J, excluding leader
`vj_seq`	1	cvar	exact	no	`enclone help parseable`	nucleotide sequence of V..J
`vj_seq_nl`	1	cvar	exact	no	`enclone help parseable`	nucleotide sequence of V..J, excluding leader
`vjlen`		cvar	exact	yes	`enclone help cvars`	length in bases of V..J

1: only implemented for parseable output