Pseudobulk counts

Preserve sample boundaries and inspect cell coverage before comparing expression. This count-evidence step performs no differential-expression test.

Choose the biological observations

1. Open the receptor dataset and each sample's raw expression matrix and supplied cell annotations in Cells. Use raw counts, not normalized, integrated or log-transformed values. Integer validation cannot prove a matrix is biologically raw.
2. Assign each sample its subject and literal timepoint. Save Clonotype phenotypes for each sample with receptor-population sizes and the same definition, QC and inclusive category breakpoints.
3. In Pseudobulk counts, select one saved phenotype result per sample, enter the supplied cell-type column and a minimum cell count (default 10), then Aggregate pseudobulk counts.

Sample names, expression inputs and subject/timepoint combinations must be unique within the selection. Repeated timepoints are kept separate; they are not independent subjects. Technical libraries, tissues and samples are never automatically pooled. Select a justified observation before aggregation if a subject/timepoint has multiple libraries. The result applies only to the explicitly selected samples.

The same Gene Expression feature IDs, names, modalities and ordering must be present in every input. A missing gene is not silently converted to zero, and duplicate gene names do not merge distinct IDs. Antibody Capture and other modalities are excluded. AnnData layer and MuData modality selections remain recorded with their source fingerprints.

Read cell coverage

Each bar counts contributing cells for one sample, supplied type and receptor-size category. All bars share a zero-based linear scale. Purple means the group meets the count-evidence rule; gray means too few cells or a zero count library. Absent groups have no bar and unavailable expression counts. The dashed minimum-cell line is not a significance threshold. Raw library totals are not comparable normalized expression levels.

Clone size counts uniquely assigned receptor cells in the original sample, before splitting by supplied type. It is not recomputed within a type or across samples. A size category describes observed sampling, not antigen specificity, proliferation rate or a causal exposure. Expression-dependent cell annotation and clone-size selection can affect a later comparison.

Distinguish missingness from zero

Missing cell-type annotations and unavailable unique clonotype sizes are excluded with separate reasons; missing type takes precedence when both are missing. Each expression barcode contributes at most once. Unmapped cells are still included when eligible; coordinates and visualization selection do not restrict aggregation. Expression QC is the upstream matrix selection; this step does not silently reuse the computed-map cell filter.

Every selected sample receives the union of observed nonempty types crossed with all declared size categories. A group with no eligible cells has null counts. A measured group retains every feature, including zeros. Groups below the minimum keep their exact raw sums but are not eligible; zero count libraries are likewise ineligible. Raising the threshold never changes the sums. Ten cells is a configurable evidence policy, not a power guarantee or a universal recommendation.

Try the artificial study

Open Pseudobulk count study. It provides eight sample-specific MEX directories under expression/, each with cells.tsv. Save phenotypes with annotation state, receptor sizes and breakpoints 1,5,10. Select the eight parents for aggregation with minimum 10 cells.

The reproducible model uses four subjects, visits at days 0 and 14, 420 expression cells per sample, 48 possible paired clones per subject and 24 artificial genes. Counts are negative-binomial with state-specific means, and clone probabilities proportional to inverse rank produce uneven realized sizes. Missing annotations, a receptor-unmatched cell and a zero-expression cell exercise bookkeeping. Full assignments and source hashes are in truth/. This is a small controlled demonstration, not a fitted biological cohort or a differential-expression benchmark.

Keep complete evidence

The saved result reopens and replays without the original sources or parent files. A new capture verifies the parent checksums and expression fingerprints. The ZIP contains the complete result, manifest, captured cell evidence, every group × feature count and provider NOTICE. Missing counts are blank in CSV; measured zeros are literal zero. Subject IDs remain present. Figure exports carry methods, source credits and citations. Remote clients use aggregate_pseudobulk.

The bounded implementation accepts 1–32 samples, up to 200,000 total captured cells (100,000 per sample), 50,000 Gene Expression features, 128 supplied types, two million sparse entries and two million output count slots. Each contributing cell/library total must be at most 9 × 10¹⁵. Larger requests are refused, not sampled or truncated.

Scientific basis and limits

Summing raw counts within sample and supplied cell type follows OSCA Multi-Sample, chapter 4 and Crowell et al., Nature Communications (2020). ClonoLoom adds a declared receptor-size partition and explicit missingness rules. Cells are not independent biological replicates. The separate paired differential-expression step declares its subject design, offsets, filtering, dispersion, multiplicity and uncertainty. The count-evidence result itself supplies none of those inferential claims.