Data Preparation Issues#

Use this page when cellucid_prepare() fails or produces exports that look wrong.

Important

The exhaustive prepare/export troubleshooting guide is: Troubleshooting: Prepare/Export.

Most common root causes (in priority order)#

1) Cell order mismatch#

Symptoms:

export “succeeds” but clusters/metadata do not match the embedding
gene expression appears on the wrong cells

Fix:

choose a canonical cells vector and reorder every input to match it
see Input Requirements (Global)

2) Expression orientation mismatch#

Symptoms:

var has X rows, but gene_expression has Y genes
or export is slow/huge unexpectedly because you exported the wrong dimension

Fix:

ensure gene_expression is cells × genes
Seurat/SCE usually need Matrix::t(...)
see Gene Expression Matrix

3) Too many genes exported#

Symptoms:

exports are enormous
export time is “forever”

Fix:

export a gene panel (gene_identifiers)
use quantization (var_quantization=8) and compression (compression=6)
see Performance Tuning (Prepare/Export)

4) Metadata column types are wrong#

Symptoms:

numeric-looking columns become categorical
legends explode into thousands of categories

Fix:

coerce columns intentionally (factor vs numeric)
export fewer columns (obs_keys)
see obs: Cell Metadata

Quick “what do I do next?” links#

Seurat export recipe: Seurat Recipe
SCE export recipe: SingleCellExperiment Recipe
Format/validation issues: Export Format and Validation Issues