# Single-Cell Data Structures and File Formats

> How 10x feature-barcode matrices, MEX and HDF5, AnnData and h5ad, and Seurat objects store sparse counts, metadata, and derived embeddings.

Single-cell file formats store a **sparse feature-barcode count matrix with cell and gene metadata**. Their input is a UMI count for each barcode-feature pair, and analysis tools attach QC metrics, clusters, labels, and embeddings to the same cells.

## The same matrix may reverse its axes

A 10x Genomics MEX matrix has **features in rows and barcodes in columns**.

```text
             cell_A  cell_B  cell_C
Gene_A            3       0       1
Gene_B            0       4       0
Gene_C            1       0       2
```

AnnData usually exposes the same values as observations, cells, by variables, genes, or `n_obs × n_vars`.

```text
         Gene_A  Gene_B  Gene_C
cell_A        3       0       1
cell_B        0       4       0
cell_C        1       0       2
```

Always name both axes when reporting shape.

## A 10x MEX matrix is three files

```text
filtered_feature_bc_matrix/
  matrix.mtx.gz
  features.tsv.gz
  barcodes.tsv.gz
```

| file | role |
| --- | --- |
| `matrix.mtx.gz` | nonzero row, column, and UMI-count entries |
| `features.tsv.gz` | feature ID, name, and type for each row |
| `barcodes.tsv.gz` | barcode sequence for each column |

A feature may be a gene, antibody capture, or CRISPR guide. Check the `feature_type` field instead of assuming every row is gene expression.

## Raw and filtered mean before and after cell calling

| type | barcodes included | use |
| --- | --- | --- |
| raw matrix | background and cell-associated barcodes with signal | cell-calling review and ambient estimation |
| filtered matrix | barcodes called as cell-associated | common downstream starting point |

Filtered does not mean that all QC is complete. Damaged cells and doublets may remain.

## HDF5 stores the sparse matrix in binary form

The 10x `.h5` feature-barcode file stores the same kind of sparse count matrix in HDF5. `data`, `indices`, `indptr`, and `shape` encode a compressed sparse column matrix, while `barcodes` and the `features` group describe the axes.

MEX and H5 are two packages for the same analysis-stage output.

## AnnData and h5ad

AnnData is a Python **matrix plus metadata container**. `.h5ad` stores it in an HDF5-based format.

| slot | common contents |
| --- | --- |
| `.X` | current primary matrix, which must be identified |
| `.obs` | cell metadata: sample, QC, cluster, cell type |
| `.var` | gene or feature metadata |
| `.layers` | additional matrices such as raw counts and normalized values |
| `.obsm` | multi-coordinate arrays such as PCA and UMAP |
| `.uns` | parameters and unstructured derived metadata |

`.X` is not guaranteed to contain raw counts. Inspect layers, generation code, and history.

## Seurat objects and rds

Seurat is an R container for counts, normalized values, metadata, and reductions. `.rds` serializes one R object and is not a Seurat-only extension.

In a Seurat v5 object, check the active assay, the layer containing raw counts, preservation of sample IDs in cell names or metadata, parameters behind reductions, and separation of integrated from unintegrated representations.

## Dense CSV discards the sparse advantage

A 30,000 cell by 25,000 gene matrix contains 750 million positions, most of them zero. MEX, H5, and h5ad avoid writing every zero. A small CSV extract is useful for inspection, but the full dense table is a poor handoff format.

## Inspection order

1. Determine whether the matrix is raw or filtered.
2. Identify feature and barcode axes.
3. Determine whether values are raw UMI counts or transformed values.
4. Check that sample, donor, and condition metadata map to cells.
5. Record genome, GTF, pipeline, and chemistry versions.
6. Separate measured counts from derived clusters, labels, and UMAP coordinates.

### Official resources

- [10x Genomics MEX feature-barcode matrix](https://www.10xgenomics.com/support/software/cell-ranger/latest/analysis/outputs/cr-outputs-mex-matrices)
- [10x Genomics HDF5 feature-barcode matrix](https://www.10xgenomics.com/support/software/cell-ranger/latest/analysis/outputs/cr-outputs-h5-matrices)
- [AnnData documentation](https://anndata.readthedocs.io/en/stable/)
- [Seurat v5 getting started](https://satijalab.org/seurat/articles/get_started_v5_new)