| name | flex-artifact-skill |
| description | Assesses probe barcode-associated technical variation in 10x Genomics Flex (Fixed RNA Profiling) scRNA-seq data. Use when user has Flex data with multiple probe barcodes and wants to check whether DE results are inflated by technical artifacts, or asks about probe barcode effects, sample barcoding variation, Flex v1 vs v2 technical differences, or spurious differential expression between barcodes. Based on Weir, Krebs, Chen 2026 (github.com/jacksonweir/flex-technical-variation). |
| metadata | {"author":"Jackson Weir","version":"1.0.0"} |
Probe Barcode Variation Assessment
Overview
In 10x Genomics Flex v1, probe barcode identity drives substantial spurious differential expression (DE) between biologically identical cells — hundreds of genes, reproducible across lanes and datasets. This creates a high false discovery rate when probe barcodes are confounded with biological sample identity. Flex v2 significantly reduces this artifact, but the magnitude depends on whether probe hybridization was performed in bulk or independently per sample.
Reference paper: "Sample barcoding-associated technical variation in probe-based single-cell RNA sequencing" (Weir, Krebs, Chen 2026)
Repository with analysis code and supplementary tables: https://github.com/jacksonweir/flex-technical-variation
Not all steps are necessary for every dataset. Start with the highest-yield steps:
identify the experimental design (Step 1), check QC metrics (Step 2), and run the VCC
reference comparison (Steps 3–3b). These three steps together will usually give a clear
answer about whether the artifact is present and how severe it is. Ask the user whether
to proceed to eta-squared computation (Step 4), visualization (Step 5), or FDP analysis
(Step 6) based on what the initial steps reveal and what level of characterization is needed.
Step 0 — Assign Probe Barcode Identity to Cells
Before any analysis, confirm that each cell in your Seurat object has a probe_barcode
metadata column (values like BC001–BC016 for Flex v1). This column is required for
all downstream steps.
If the column is already present (e.g., loaded from per-sample cellranger multi outputs
and labeled during object construction), proceed to Step 1.
If the column is absent (e.g., you loaded a combined or aggregated matrix without
per-sample metadata), extract probe barcode identity directly from the cell barcode sequences.
In Flex v1, the last 8 bp of the 16 bp cell barcode encode the probe barcode identity. Match
these 8 bp sequences against the BC001–BC016 whitelist to annotate each cell.
Full code and the sequence whitelist are in: references/extract-probe-barcodes.md
This approach is implemented in scripts/figure1/01_setup_vcc_seurat.R in this repository.
Step 1 — Identify Assay Version and Experimental Design
Flex v1: Probe barcode identity is embedded in the probe hybridization chemistry. Barcodes appear as values like BC001–BC016 in cell metadata. Technical variation between barcodes is inherent. Any DE comparing conditions assigned to different barcodes will be confounded.
Flex v2: Probe hybridization is barcode-free; barcoding happens in a separate oligo step. Barcodes follow a plate-well format (e.g. A-A01, B-C04) with the plate prefix varying depending on the plate used. The degree of technical variation depends on whether probe hybridization was bulk or per-sample.
Confounded Designs — Very Common and High Risk
A critical and common situation: in many Flex v1 experiments, each biological
condition is placed on a separate probe barcode. For example, treated cells on BC002 and
control cells on BC011, or patient A on BC001 and patient B on BC002. In this case,
probe barcode identity is perfectly confounded with sample identity. Any DE analysis
between your biological conditions will produce a mix of two signals:
- Genuine biological differences between the conditions
- Technical artifact genes introduced by the probe barcode itself
These two sources of DE are completely inseparable without an orthogonal label (e.g.,
CRISPR guide assignments or HTOs — see Step 6). The paper benchmarks this directly: at
|log2FC| ≥ 0.3, the median false discovery proportion is 67–91% depending on which
barcode pair is used. This means the majority of "significant" DE genes in a confounded
comparison may not reflect biology at all.
For confounded designs, the immediate priority is the VCC reference comparison (Step 3b):
run FindAllMarkers on your data with probe barcode as the identity, then compare each
barcode's one-vs-all DE to the VCC reference. This directly tests whether the same artifact
genes are inflating your results.
Check the barcode naming in cell metadata to identify which assay was used. For detailed scenarios (Flex v1, Flex v2 bulk hyb, Flex v2 independent hyb) and how to identify which applies to your data, read:
references/experimental-design.md
Step 2 — QC Metrics Per Probe Barcode
Before any DE analysis, verify QC metrics (cell count, median UMI, median genes detected, mitochondrial fraction) are comparable across barcodes. Systematically lower UMI counts or higher mitochondrial reads in specific barcodes are red flags. In the paper's VCC dataset, QC metrics per barcode were similar (Supp. Fig. 1), confirming the DE signal is not a QC artifact.
Step 3 — Differential Expression Between Probe Barcodes
Run FindAllMarkers (one-vs-all, Wilcoxon, min.pct = 0.1, logfc.threshold = 0) with probe barcode as the identity. Count significant DE genes per barcode at p_val_adj < 0.05 and |log2FC| ≥ 0.3.
Cross-reference your significant DE genes against the paper's supplementary tables to assess overlap with known probe barcode artifacts. Substantial overlap with the VCC (Table 1) or PBMC (Table 2) reference tables is strong evidence of probe barcode confounding.
Recurrently probe barcode-affected genes (high η², reproducible across independent datasets): SRP9, SPCS1, ISCU, RRM2, SLC2A3, ITSN1, PHF6, ADCY2
For code, read: references/analysis-code.md → Sections: FindAllMarkers, Pairwise DE
Step 3b — VCC Reference Comparison and Confounded Design Check
This step is especially important when probe barcode is perfectly confounded with sample
identity (e.g., all treated cells on BC002, all control cells on BC011). In that design,
probe barcode technical artifacts are indistinguishable from biological DE.
Primary approach — one-vs-all per barcode: Run FindAllMarkers on your data with probe
barcode as the identity. For each barcode, scatter-plot your avg_log2FC (barcode vs all
others) against the VCC reference avg_log2FC for the same barcode from Supplementary Table
- Since both use the same one-vs-all design, the fold-changes are directly comparable. A
positive Spearman ρ for any barcode means that barcode's artifact profile is present in
your data. This is the most direct and interpretable diagnostic for confounded designs.
Advanced — pairwise comparison: For a specific barcode pair of interest (e.g., the two
barcodes that correspond to your treatment vs control), run pairwise DE and compare to an
approximated VCC pairwise log2FC derived from Table 1.
Supplementary Table 1 (VCC) is the primary reference because VCC NTC cells are
biologically identical across all 16 barcodes — any DE between barcodes is unambiguously
technical. Table 2 (PBMC) provides a second independent confirmation.
Both tables are in references/ in this skill directory for direct access.
For full code (one-vs-all scatter plots, pairwise comparison, overlap statistics), read:
references/vcc-comparison.md
Step 4 — Quantify Variance Explained (Eta-Squared)
Eta-squared (η²) measures the fraction of total expression variance attributable to probe barcode identity via one-way ANOVA: η² = SS_between / SS_total. Computed on NTC cells only (biologically equivalent cells, so any variance explained is purely technical). Run separately for probe barcode and lane to compare their magnitudes.
Threshold from paper: η² ≥ 1% = probe barcode-affected gene
Paper benchmarks (VCC NTC cells, all 3 lanes, all 16 probe barcodes):
- 519 genes with η²_bc ≥ 1%
- 27 genes with η²_lane ≥ 1%
For the full η² computation code (sparse matrix algebra, no densification required), read:
references/analysis-code.md → Section: Eta-Squared Computation
Step 5 — Visualize the Effect
Key visualizations from the paper:
- Volcano plots (Fig. 1B, 1C): lane effect vs probe barcode effect side-by-side with shared axes
- Violin plots (Fig. 1D): per-cell expression of top η² genes across barcodes, split by lane — subtle, systematic shifts (no discrete on/off) are characteristic
- Stacked barplot (Fig. 1E): DE gene counts (up/down) per barcode from FindAllMarkers
If any of the recurrently probe barcode-affected genes (SRP9, SPCS1, ISCU, etc.) appear in your DE results, plotting their expression as violins across barcodes is a quick visual confirmation of the artifact.
For full plotting code, read: references/analysis-code.md → Section: Visualization
Step 6 — FDP Analysis (Requires Orthogonal Barcoding)
If your cells have an independent identity label beyond probe barcode — such as CRISPR guide assignments or hashtag oligonucleotides (HTOs) from cell hashing — you can directly measure the false discovery proportion (FDP): the fraction of DE genes that are probe barcode artifacts.
The paper's approach (script 05_compute_fdp_sweep.R): for each CRISPR target gene, run ground truth DE (NTC vs target cells, both within TRUTH_BC) and confounded DE (target cells in CONFOUNDED_BC vs NTC cells in TRUTH_BC). FDP = false positives / (false positives + true positives) at each |log2FC| threshold.
Paper benchmarks (BC005 vs BC008, average-effect pair):
- |log2FC| ≥ 0.3: median FDP = 67%
- |log2FC| ≥ 1.0: median FDP = 34%
- |log2FC| ≥ 1.7: FDP → 0%
Worst-case pair (BC002 vs BC011): median FDP = 91% at |log2FC| ≥ 0.3.
For code, read: references/analysis-code.md → Section: FDP Analysis
Step 7 — Interpret and Recommend
For the full interpretation table (risk by experimental design), mitigation strategies, and Flex v1 vs Flex v2 comparison, read:
references/interpretation.md
Quick risk assessment:
| Situation | Risk |
|---|
| Flex v1, each biological condition on a separate barcode | HIGH |
| Flex v1, balanced across barcodes | MEDIUM |
| Flex v2, independent probe hyb per sample | REDUCED but non-zero |
| Flex v2, bulk probe hyb then split and barcoded | MINIMAL |
Minimal mitigation if confounded:
- Use
latent.vars = "probe_barcode" with test.use = "LR" in FindMarkers
- Apply |log2FC| ≥ 1.7 threshold (FDP approaches 0% in paper benchmarks)
- Redesign: use Flex v2 with bulk probe hybridization, or distribute conditions across barcodes
Reference Files
| File | When to read |
|---|
references/extract-probe-barcodes.md | If your Seurat object lacks a probe barcode metadata column — extract BC001–BC016 identity from cell barcode sequences |
references/experimental-design.md | To understand Flex v1 vs v2 chemistry, the three experimental scenarios, and how to identify which applies to your data |
references/analysis-code.md | For complete R code: η² computation, FDP analysis, pairwise DE, all visualizations; Python code for probe-level h5 analysis |
references/interpretation.md | For detailed risk table, paper benchmark numbers, problematic gene lists, mitigation strategies, cross-dataset reproducibility |
references/vcc-comparison.md | For scatter plot code comparing your DE results to the VCC reference, and the confounded design check |
Supplementary Tables
The paper's FindAllMarkers results for three datasets are in supplementary_tables/:
| File | Dataset | Cells used |
|---|
Supplementary_Table_1_VCC_Flexv1_FindAllMarkers.csv | VCC Flex v1, Lane 1 | All Lane 1 cells (all CRISPR perturbations, no guide filter); 16 barcodes |
Supplementary_Table_2_PBMC_Flexv1_FindAllMarkers.csv | 10x PBMC 320k Flex v1 | All PBMC cells; 16 barcodes; FindAllMarkers one-vs-all |
Supplementary_Table_3_A375_Flexv2_FindAllMarkers.csv | A375 Flex v2 | All cells across all conditions (8 ligands + PBS); 16 barcodes (2 per condition) |
Columns: p_val, avg_log2FC, pct.1, pct.2, p_val_adj, cluster (probe barcode), gene
Table 1 (VCC) is the primary reference for the confounded design check. VCC NTC cells
are biologically identical across all 16 barcodes, making this the gold-standard artifact
gene list. Tables 1 and 2 are also available in references/ within this skill directory
for direct use without navigating to supplementary_tables/.
Table 2 (PBMC) carries no CRISPR perturbations, so any DE between barcodes is
unambiguously technical. Use it as a second independent confirmation when a gene appears
in Table 1 — genes significant in both VCC and PBMC are highly reliable artifact indicators.
Note on Table 1 and CRISPR guide effects: Table 1 includes all CRISPR guide populations.
A gene appearing in Table 1 could in principle reflect a genuine CRISPR perturbation rather
than a barcode artifact. Cross-check against Table 2 or the recurrently affected gene list
(SRP9, SPCS1, ISCU, RRM2, SLC2A3, ITSN1, PHF6, ADCY2) to confirm technical origin.
