12강 / 20강

HDF5 — 같은 행렬을 한 파일로

왜 형식이 두 벌인가, 그리고 CSC 라는 접는 법

Cell Ranger 는 같은 행렬을 두 가지 모양으로 내놓습니다.

폴더 세 파일

filtered_feature_bc_matrix/
사람이 열어 볼 수 있다
글자로 되어 있다
느리다

.h5 한 파일

filtered_feature_bc_matrix.h5
사람은 못 읽는다
이진 파일이다
훨씬 빠르다

알맹이는 완전히 같습니다. 편한 쪽을 쓰면 돼요. Scanpy 도 Seurat 도 둘 다 읽습니다.

고등학생같은 행렬을 한 파일로

HDF5는 여러 자료를 한 파일에 담는 형식입니다.

	MTX (세 파일)	HDF5 (한 파일)
파일 수	3	1
사람이 읽기	가능 (텍스트)	불가 (이진)
크기	큼	작음 — 압축
읽기 속도	느림	빠름
부분 읽기	불가	가능

.h5 안의 구조

matrix/
  barcodes        (2700,)          <- barcodes.tsv 와 같은 것
  data            (2286884,)       <- 0 이 아닌 값들
  indices         (2286884,)       <- 그 값들의 행 번호
  indptr          (2701,)          <- 열이 어디서 시작하나
  shape           (2,)             <- [32738, 2700]
  features/
    id            (32738,)         <- Ensembl ID
    name          (32738,)         <- 유전자 기호
    feature_type  (32738,)         <- Gene Expression
    genome        (32738,)         <- GRCh38
    

barcodes 와 features/ 는 아까 본 두 파일 그대로입니다. 새로운 것은 가운데 셋 — data · indices · indptr 입니다.

고등학생왜 형식이 두 벌인가

MTX가 좋은 때	HDF5가 좋은 때
사람이 열어 보고 싶을 때	큰 자료
간단한 도구로 처리	빠른 접근이 필요
호환성	메타데이터도 함께 담고 싶을 때

Cell Ranger는 둘 다 만들어 줍니다 — 목적에 따라 고르세요.

indptr 은 '이 열은 몇 번째 칸부터인가' 를 적은 목차입니다.

Python 브라우저에서 실행

# CSC 를 손으로 만들어 본다
import numpy as np

M = np.array([
    [3, 0, 0, 0],
    [0, 5, 0, 0],
    [12, 0, 8, 0],
    [0, 0, 0, 2],
    [0, 1, 0, 9],
])
print("원래 표 (유전자 5 × 세포 4):")
print(M)
print()

data, indices, indptr = [], [], [0]
for c in range(M.shape[1]):            # 열(세포) 하나씩
    for r in range(M.shape[0]):        # 행(유전자) 하나씩
        if M[r, c] != 0:
            data.append(int(M[r, c]))
            indices.append(r)
    indptr.append(len(data))

print("data    =", data,    "  <- 값")
print("indices =", indices, "  <- 그 값의 행 번호")
print("indptr  =", indptr,  "  <- 열의 경계")
print()
print("2번 세포(0부터 세면 1)를 꺼내려면:")
s, e = indptr[1], indptr[2]
print("  indptr[1]=%d 부터 indptr[2]=%d 까지" % (s, e))
for k in range(s, e):
    print("    유전자 %d번 -> %d" % (indices[k], data[k]))

고등학생CSC — 접는 법

희소 행렬을 저장하는 방식 중 하나입니다. 열 단위로 접어요.

배열	담는 것
data	0이 아닌 값들
indices	각 값의 행 번호
indptr	각 열이 data의 어디서 시작하나

indptr 덕분에 특정 세포만 골라 읽을 수 있습니다 — 전체를 안 읽고요.

indptr 의 길이는 늘 '열 수 + 1' 입니다.

Python 브라우저에서 실행

# 다시 표로 펴 본다 — 접기와 펴기가 맞물리는지 확인
import numpy as np

data    = [3, 12, 5, 1, 8, 2, 9]
indices = [0, 2, 1, 4, 2, 3, 4]
indptr  = [0, 2, 4, 5, 7]
shape   = (5, 4)

M = np.zeros(shape, dtype=int)
for c in range(shape[1]):
    for k in range(indptr[c], indptr[c + 1]):
        M[indices[k], c] = data[k]

print("펴낸 표:")
print(M)
print()
print("열 개수 확인: len(indptr) - 1 =", len(indptr) - 1)
print("칸 개수 확인: indptr[-1] =", indptr[-1], "= len(data) =", len(data))
print()
print("이 두 확인이 안 맞으면 파일이 깨진 것입니다.")

세 번째 파일 — molecule_info.h5

같은 폴더에 이것도 있습니다. 행렬이 아니라 UMI 하나하나의 기록이에요.

칸	무엇
`barcode_idx`	어느 세포
`feature_idx`	어느 유전자
`umi`	어느 분자
`count`	그 분자를 몇 번 읽었나

행렬은 이 표를 세어서 만든 것입니다. 그래서 이 파일이 있으면 읽기 깊이를 인위로 낮춰 여러 시료를 같은 깊이로 맞출 수 있어요 (cellranger aggr).

고등학생CSC와 CSR

	CSC (열 압축)	CSR (행 압축)
빠른 접근	열 = 세포	행 = 유전자
10x 기본	이것	—
세포별 작업	빠름	느림
유전자별 작업	느림	빠름

단일세포 분석은 대개 세포 단위로 하니 CSC가 유리합니다.

유전자별 계산을 많이 하면 CSR로 바꾸는 것이 빠릅니다. 변환에 시간이 걸리지만 여러 번 쓰면 이득이에요.

🤔 확인 문제

indptr 배열의 길이는?

🤔 확인 문제

.h5 와 세 파일 폴더의 관계는?