# 싱글셀 데이터 구조와 파일 형식

> 10x feature-barcode matrix, MEX·HDF5, AnnData·h5ad와 Seurat 객체가 세포×유전자 count와 metadata·embedding을 어떻게 저장하는지 읽는 독립 레퍼런스.

싱글셀 데이터 파일은 **희소한 feature-barcode count matrix와 세포·유전자 metadata를 저장하는 형식**입니다. 입력은 barcode·feature별 UMI count이고, 분석 도구는 이를 세포 행과 유전자 열로 읽어 QC 값·cluster·UMAP 좌표를 같은 객체에 연결합니다.

## 같은 행렬도 축 방향이 다를 수 있다

10x Genomics의 원본 MEX 행렬은 **feature가 행, barcode가 열**입니다.

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

Scanpy의 AnnData는 보통 같은 값을 **observation(cell)이 행, variable(gene)이 열**인 `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
```

shape를 말할 때 `cells × genes`인지 `features × barcodes`인지 축 이름을 함께 적어야 합니다.

## 10x MEX는 세 파일이 한 행렬이다

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

| 파일 | 역할 |
| --- | --- |
| `matrix.mtx.gz` | 0이 아닌 칸의 행·열 번호와 UMI count |
| `features.tsv.gz` | 행 번호에 대응하는 feature ID·name·type |
| `barcodes.tsv.gz` | 열 번호에 대응하는 barcode 서열 |

`features.tsv.gz`의 feature는 gene만이 아닐 수 있습니다. Feature Barcode assay에서는 antibody capture나 CRISPR guide 같은 행도 함께 들어갈 수 있으므로 세 번째 `feature_type` 열을 확인합니다.

## raw와 filtered는 cell calling 전후다

| 종류 | 포함되는 barcode | 용도 |
| --- | --- | --- |
| raw matrix | 하나 이상의 read가 있는 background·cell-associated barcode | cell calling 재검토, ambient RNA 추정 |
| filtered matrix | cell-associated라고 판정된 barcode | 일반적인 downstream 분석 시작점 |

filtered는 QC까지 모두 끝났다는 뜻이 아닙니다. doublet과 손상 세포는 filtered matrix 안에 남을 수 있습니다.

## HDF5는 같은 희소 행렬을 바이너리로 저장한다

10x의 `.h5` feature-barcode matrix는 큰 희소 행렬을 효율적으로 읽도록 HDF5에 저장합니다. `data`, `indices`, `indptr`, `shape`가 CSC(compressed sparse column) 행렬을 구성하고 `barcodes`와 `features` group이 축 metadata를 제공합니다.

MEX와 H5는 분석 단계가 다른 파일이 아니라 같은 종류의 count matrix를 다른 포장으로 저장한 것입니다.

## AnnData와 h5ad

AnnData는 Python 단일세포 생태계에서 쓰는 **행렬 + metadata 컨테이너**이고, `.h5ad`는 그 객체를 HDF5 기반 파일로 저장한 형식입니다.

| slot | 일반적인 내용 |
| --- | --- |
| `.X` | 현재 주 분석 행렬, 무엇을 넣었는지 확인 필요 |
| `.obs` | cell metadata: sample, QC, cluster, cell type |
| `.var` | gene/feature metadata |
| `.layers` | raw counts, normalized values 같은 추가 행렬 |
| `.obsm` | PCA·UMAP처럼 cell마다 여러 좌표가 있는 배열 |
| `.uns` | 파라미터·색상·분석 결과의 비정형 metadata |

`.X`가 raw count라는 보장은 없습니다. 이미 log-normalized 값일 수 있으므로 `layers`, 생성 코드와 history를 함께 확인합니다.

## Seurat 객체와 rds

Seurat는 R에서 count·normalized data·metadata·차원축소 결과를 묶는 객체입니다. `.rds`는 R 객체 하나를 직렬화한 파일이며 Seurat 전용 확장자는 아닙니다.

Seurat v5의 assay는 여러 layer에 count와 변환값을 보관할 수 있습니다. 객체를 받았을 때 다음을 확인합니다.

- 어떤 assay가 active인지
- raw counts가 어느 layer에 있는지
- cell 이름에 sample ID가 보존됐는지
- reduction에 PCA·UMAP이 어떤 파라미터로 생성됐는지
- integration 전후 표현이 구분되는지

## CSV로 펴면 희소성의 이점을 잃는다

싱글셀 행렬은 대부분 0입니다. 30,000 cells × 25,000 genes를 CSV로 펼치면 7억 5천만 칸을 기록해야 합니다. MEX·H5·h5ad는 0이 아닌 값 중심으로 저장해 크기와 메모리 사용을 줄입니다.

Excel로 변환한 작은 일부는 확인용으로 쓸 수 있지만 전체 분석 전달 형식으로는 적합하지 않습니다.

## 파일을 받으면 확인할 순서

1. raw인지 filtered인지 확인한다.
2. 행과 열이 feature·barcode 중 무엇인지 확인한다.
3. 값이 raw UMI count인지 normalized value인지 확인한다.
4. sample·donor·condition metadata가 cell과 연결되는지 확인한다.
5. genome·GTF·pipeline·chemistry 버전을 기록한다.
6. cluster·cell type·UMAP이 원시 측정이 아니라 파생 결과임을 구분한다.

### 공식 자료

- [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 공식 문서](https://anndata.readthedocs.io/en/stable/)
- [Seurat v5 공식 시작 문서](https://satijalab.org/seurat/articles/get_started_v5_new)