A Worked Example From Barcoded Reads to Matrix

From Read Records to a Count Matrix

A count matrix is the end of a sequence of bookkeeping steps, not a direct transcription of a read table. A read is an observed sequencing record; in a UMI-based assay, multiple reads can represent the same tagged molecule. The practical task is to preserve the information that identifies a molecule, deduplicate at the appropriate level, and then aggregate counts for each cell and gene.

This tutorial works through that sequence using a small hypothetical data set. Gene assignments are treated as already supplied: the purpose here is to turn assigned, barcoded reads into counts, not to determine which gene a sequence belongs to. The earlier material on UMI deduplication establishes the molecule-counting rationale; here the key is applying it consistently across a complete table.

Definition: Under an exact-tag UMI rule, a read contributes to the same deduplicated count as another read when both have the same cell barcode, the same assigned gene, and the same UMI. A cell-by-gene count matrix has one row per cell and one column per gene; its entry for a cell and gene is the number of distinct cell–gene–UMI identities assigned to that pair.

This definition specifies the unit being counted. Two reads with the same UMI but different cell barcodes are not grouped together. Nor are reads with the same cell barcode and UMI but different assigned genes. Within the exact-tag rule, the full identity is the triple \((\text{cell barcode},\text{gene},\text{UMI})\).

Assumptions for the Worked Conversion

The example uses a deliberately simple processing rule. Before deduplication, assume that each read has a valid cell barcode, a usable UMI, and one unambiguous gene assignment. Assume that the cell barcodes and gene labels have already been checked against the intended cell and feature lists. No barcode or UMI correction is performed: tags are compared exactly as written. These conditions let us focus on the aggregation arithmetic.

The result is a count of distinct observed tags, not a guarantee that every tag corresponds to a different physical RNA molecule. For example, two molecules can in principle receive the same UMI within a cell and gene, a phenomenon called a UMI collision. Conversely, sequencing or barcode errors can make reads from one molecule appear to carry different tags. Those possibilities qualify the biological interpretation; they do not change the exact-tag calculation shown here.

Worked Example: Deduplicate 12 Reads and Build the Matrix

Suppose the following 12 hypothetical reads have already been assigned to genes. The sequence snippets are illustrative; the barcode, UMI, and gene columns are the fields used in the count calculation.

Read	Sequence snippet	Cell barcode	UMI	Assigned gene
r01	AACCT	A	U01	G1
r02	CAGGT	A	U01	G1
r03	TTACA	A	U02	G1
r04	GGCTA	A	U03	G2
r05	ATGCC	A	U03	G2
r06	CCTAG	A	U04	G3
r07	GATCA	B	U01	G1
r08	TCCGA	B	U02	G2
r09	AAGTC	B	U02	G2
r10	CGTTA	B	U05	G2
r11	TACCG	B	U06	G3
r12	GACAT	B	U07	G3

Step 1: Group reads by the full identity. For cell A and gene G1, r01 and r02 both have UMI U01, so they form one identity, \((A,G1,U01)\). Read r03 has U02 and forms a second identity, \((A,G1,U02)\). Applying the same rule to every row gives:

Cell A, G1: U01 and U02, or 2 identities.
Cell A, G2: U03, or 1 identity.
Cell A, G3: U04, or 1 identity.
Cell B, G1: U01, or 1 identity.
Cell B, G2: U02 and U05, or 2 identities.
Cell B, G3: U06 and U07, or 2 identities.

There are \(2+1+1+1+2+2=9\) distinct cell–gene–UMI identities. The three groups with repeated reads are \((A,G1,U01)\), \((A,G2,U03)\), and \((B,G2,U02)\). Each group has two reads and contributes one read beyond its first read, so there are \(12-9=3\) extra reads under this exact-tag rule.

Step 2: Aggregate identities by cell and gene. Count the distinct UMIs within each cell–gene pair. Thus cell A has 2 counts for G1, 1 for G2, and 1 for G3; cell B has 1 for G1, 2 for G2, and 2 for G3.

Step 3: Put those values into the declared orientation. With cells in rows and genes in columns, the cell-by-gene matrix is:

\begin{array}{c|ccc|c} & G1 & G2 & G3 & \text{Cell total}\\ \hline A & 2 & 1 & 1 & 4\\ B & 1 & 2 & 2 & 5\\ \hline \text{Gene total} & 3 & 3 & 3 & 9 \end{array}

The row totals are \(2+1+1=4\) for A and \(1+2+2=5\) for B. The column totals are \(2+1=3\) for G1, \(1+2=3\) for G2, and \(1+2=3\) for G3. Both ways of summing the matrix give \(4+5=3+3+3=9\), matching the number of distinct identities.

Why the Counting Formula Works

The aggregation rule can be written using an indicator, which equals 1 when a condition is true and 0 otherwise. Let \(R\) be the set of reads, and let \(C\) and \(G\) be the chosen cell and gene sets. For cell \(c\), gene \(g\), and UMI \(u\), define an identity as represented if at least one read has that combination. The matrix entry is the sum of these indicators over UMIs:

M_{cg}=\sum_{u} \mathbf{1}\{\text{at least one read in }R\text{ has cell }c,\text{ gene }g,\text{ and UMI }u\}.

To justify the rule, partition the reads for a fixed cell–gene pair into groups indexed by UMI. If UMI \(u\) occurs on \(k_{cgu}\) reads, those \(k_{cgu}\) records represent one distinct exact-tag identity whenever \(k_{cgu}>0\). The indicator contributes exactly 1 for that group, regardless of whether it has one read or many. Summing over the represented UMI groups therefore counts identities, not read records.

M_{cg}=\sum_{u:\,k_{cgu}>0}1 \qquad\text{and}\qquad \text{number of extra reads}=\sum_{c,g,u:\,k_{cgu}>0}(k_{cgu}-1).

In the worked table, the first expression sums to 9 across all cell–gene pairs. For the second expression, three identity groups have \(k_{cgu}=2\), and the other six have \(k_{cgu}=1\). Thus the extra-read count is \(3(2-1)+6(1-1)=3\), consistent with 12 total reads minus 9 identities.

Worked Example: Same UMI, Different Gene Assignment

Consider three hypothetical reads: two have cell C, UMI U7, and gene H1; the third has cell C, UMI U7, and gene H2. Under the stated rule, the first two reads form identity \((C,H1,U7)\), while the third forms \((C,H2,U7)\). The resulting counts are 1 for H1 and 1 for H2, not 1 total for the cell.

The calculation follows directly from the identity definition: gene is part of the grouping key. Deduplicating only on cell barcode and UMI would merge the two assignments and lose one gene-level count. In a real pipeline, conflicting gene assignments may call for upstream review; this small example merely illustrates what the specified grouping rule does when assignments are supplied.

Orientation, Zero Counts, and Basic Checks

Matrix orientation is a matter of declared layout, not a change in the counts. Here rows are cells and columns are genes, as required for a cell-by-gene matrix. A gene-by-cell representation contains the same values transposed: the entry for A and G1 remains 2, but it appears in the row for G1 and the column for A. State the orientation explicitly so that downstream interpretation of rows and columns is unambiguous.

The chosen cell and gene lists also determine which zeroes appear. If a cell–gene combination has no represented identity, its matrix entry is 0. Likewise, a gene included in the feature list but absent from all assigned reads has an all-zero column in a cell-by-gene layout. Do not infer a nonzero count merely because a cell or gene is present in the matrix labels.

Several simple checks catch many bookkeeping mistakes before analysis. Count the number of distinct triples independently of the matrix aggregation; sum all matrix entries and confirm that the total agrees. Check that row and column labels are the intended cell and gene lists, and confirm whether cells or genes occupy rows. If a matrix total exceeds the number of reads, or the calculated number of distinct identities, the counting or aggregation has been applied inconsistently.

Worked Example: Verify Totals After Aggregation

Using the matrix from the 12-read example, suppose a summary reports 10 total counts. That result fails the independent identity check: the six cell–gene groups contain \(2+1+1+1+2+2=9\) distinct UMIs. It also fails the row-total check, because the displayed row totals are 4 and 5, which sum to 9, not 10.

The correction is not to adjust a matrix entry to force agreement. Revisit the grouping keys and the cell–gene aggregation. In this data, the correct total is 9; the read total is 12, and the three-read difference is accounted for by the three repeated identity groups. These checks verify arithmetic and bookkeeping, although they cannot establish that all upstream assignments or barcodes are biologically correct.

Common Mistakes and Limitations

Using read counts as molecule counts. A repeated read with the same cell, gene, and UMI does not add another count under exact-tag deduplication. In the main table, 12 reads yield 9 deduplicated counts.
Deduplicating on an incomplete key. Grouping by UMI alone, or by cell and UMI but not gene, can merge distinct identities under the stated rule. Use the full cell–gene–UMI triple.
Reversing the matrix labels without noticing. A gene-by-cell matrix is the transpose of a cell-by-gene matrix. The values may be identical, but the row and column meanings differ.
Treating the result as a perfect census of molecules. Exact-tag counting can be affected by UMI collisions and sequencing errors. The matrix records deduplicated assigned tags, whose relationship to physical molecules depends on assay and processing quality.

Exact-tag deduplication is transparent and reproducible, but it is not the only possible UMI-processing approach. A method that corrects likely UMI errors may combine tags that differ slightly, while exact matching leaves them separate. Such correction requires an explicit rule and can change the counts; it should not be silently mixed into an example or pipeline described as exact-tag deduplication. The appropriate method depends on assay design, error patterns, and the stated processing workflow.

Key takeaway: Deduplicate by the full cell–gene–UMI identity, count distinct identities within each cell–gene pair, and declare matrix orientation. For the hypothetical table, 12 reads produce 9 distinct identities and a cell-by-gene matrix whose entries sum to 9.

Check Your Understanding

Answer each question from the definitions and worked calculations above. Solutions are included for checking.

A cell–gene–UMI triple occurs on four reads. How many counts does it contribute under exact-tag deduplication, and how many extra reads does it represent beyond the first?
In the main table, how many distinct identities occur for cell B and gene G2? Show which UMIs determine the count.
Why are reads with the same cell barcode and UMI but different assigned genes not one identity under the rule used here?
For the main example, what are the total counts for cell A and gene G3, respectively?
If the main matrix is transposed, what becomes the row unit and the column unit?

Solutions. (1) It contributes 1 count, representing \(4-1=3\) extra reads. (2) There are 2 identities: U02 and U05, so the B–G2 entry is 2. (3) Gene is part of the full grouping key, so the two triples are distinct. (4) Cell A totals \(2+1+1=4\); the G3 column total is \(1+2=3\). (5) Rows become genes and columns become cells, giving a gene-by-cell matrix with the same values transposed.