FAQ

Does UniVI need paired data? Training needs cells with at least two modalities measured together; that is what teaches the model how modalities correspond. Once trained, single-modality data can be embedded with the matching encoder, so unimodal cohorts can be mapped onto a paired reference (tutorial).

How many paired cells do I need? In the paper’s overlap sweep on Multiome PBMCs (Fig. 9), correspondence collapsed when only a few percent of cells were paired and stabilized with modest overlap: with 10% of cells paired, bidirectional label-transfer macro-F1 was about 0.70 and clustering NMI about 0.72. The paired cells should cover the cell types you care about.

Raw counts or normalized data? Keep raw counts in layers["counts"] and give the model normalized inputs with a Gaussian likelihood for integration work (the paper’s default). Use count likelihoods (nb, poisson) on raw counts when you need decoders that output counts.

Can I use more than two modalities? Yes, any number: add one ModalityConfig per modality (tutorial).

How do I handle batches or donors? Train on data that spans them; the shared latent space is often robust to moderate batch effects. For stronger effects, preprocess with a batch-aware method, or add an adversarial head (ClassHeadConfig(..., adversarial=True)) for the batch variable.

Are predicted values real measurements? No. Cross-modal predictions and denoised values are model estimates. They are good for visualization, annotation, and hypothesis generation; statistical tests should use measured data.

Why does my joint UMAP look mixed but cell types are blurred? Mixing alone is easy to achieve by collapsing structure. Check label transfer and per-cell-type structure too; lower gamma if the embedding over-aligns.

Where are downloaded datasets stored? In ~/.cache/univi unless UNIVI_DATA_DIR is set. Files are verified by checksum and reused.

How do I cite UniVI? See Citation.