Scanpy: 단일 세포 분석
개요
Scanpy는 AnnData를 기반으로 구축된, 단일 세포 RNA-seq 데이터 분석을 위한 확장 가능한 Python 툴킷입니다. 이 스킬을 사용하여 품질 관리, 정규화, 차원 축소, 클러스터링, 마커 유전자 식별, 시각화 및 궤적 분석을 포함한 완전한 단일 세포 워크플로를 적용하세요. 현재 안정적인 릴리스: scanpy 1.12.x (2026년 1월)
설치
Python 3.12+ (scanpy 1.12는 Python ≤3.11 지원 중단) 및 anndata ≥0.10이 필요합니다.
uv pip install "scanpy[leiden]"
[leiden] 옵션은 Leiden 클러스터링에 필요한 python-igraph와 leidenalg를 설치합니다. 재현 가능한 환경을 위해 버전을 고정하세요: uv pip install "scanpy[leiden]==1.12.1".
대규모 또는 out-of-core 데이터셋의 경우, 많은 함수가 Dask 배열을 지원합니다(실험적):
uv pip install "scanpy[leiden]" dask
Dask와 함께 Scanpy 사용하기 튜토리얼을 참조하세요. GPU 가속 scanpy 유사 연산을 위해서는 별도 패키지인 rapids-singlecell을 사용하세요.
입력이 R 네이티브 단일 세포 객체(.rds, .RData, Seurat 또는 SingleCellExperiment)인 경우, 먼저 R 도구를 사용하여 .h5ad로 변환한 후 Scanpy로 로드하세요. macOS, Linux 및 Windows에서 에이전트 실행 설치 및 변환 지침은 references/r_interop.md를 읽으세요.
AnnData 구조 및 I/O 세부 정보는 anndata 스킬을 사용하세요. 확률적 모델 및 배치 보정은 scvi-tools를 사용하세요.
이 스킬을 사용해야 하는 경우
이 스킬은 다음과 같은 경우에 사용해야 합니다:
- 단일 세포 RNA-seq 데이터(.h5ad, 10X, CSV 형식) 분석
.h5ad로 변환이 필요한 R 기반 단일 세포 데이터셋(.rds,.RData, Seurat, SingleCellExperiment) 작업- scRNA-seq 데이터셋에 대한 품질 관리 수행
- UMAP, t-SEN 또는 PCA 시각화 생성
- 세포 클러스터 식별 및 마커 유전자 찾기
- 유전자 발현 기반 세포 유형 주석
- 궤적 추론 또는 유사시간 분석 수행
- 출판 수준의 단일 세포 플롯 생성
스크립트 툴킷 (처음부터 코드를 작성하는 것보다 선호)
이 스킬은 모든 일반적인 단계에 대해 scripts/ 디렉토리에 즉시 실행 가능한 CLI 스크립트를 제공합니다. scanpy 코드를 직접 작성하는 대신 이 스크립트를 실행하세요. 이 스크립트는 확장자별 파일 로드, 그림 설정, 적절한 기본값, 원시 카운트 보존 및 진행 로깅을 처리합니다. 각 스크립트는 .h5ad를 읽고 쓰므로 체인으로 연결할 수 있으며, 각각 --help가 있습니다. 스크립트로 다루지 않거나 특별한 사용자 정의가 필요한 작업에 대해서만 scanpy 코드 작성을 고려하세요.
모든 스크립트는 공유 scripts/_common.py 헬퍼(로딩, 저장, 그림 설정)를 사용합니다. 다른 스크립트와 함께 보관하세요. 스킬 디렉토리에서 실행하거나 전체 경로를 전달하세요; 그림은 기본적으로 ./figures/에 저장됩니다.
| 스크립트 | 목적 | 일반적인 호출 |
|---|---|---|
run_pipeline.py | 하나의 명령으로 전체 워크플로: 로드 → QC → 정규화 → HVG → PCA → (배치) → UMAP → Leiden → 마커 | python scripts/run_pipeline.py raw.h5ad -o processed.h5ad |
inspect_data.py | 알 수 없는 데이터셋 요약 (형태, obs/var, 레이어, 이미 계산된 것, raw vs 정규화) | python scripts/inspect_data.py data.h5ad |
convert.py | 모든 형식 로드(10x 디렉토리/.h5, csv, loom, mtx) 및 .h5ad 쓰기 | python scripts/convert.py 10x_dir/ -o data.h5ad |
qc_analysis.py | QC 메트릭, 전/후 플롯, 필터링, 선택적 Scrublet 더블릿 | python scripts/qc_analysis.py raw.h5ad -o qc.h5ad --scrublet |
preprocess.py | 정규화, log1p, HVG, 선택적 스케일/회귀 (counts 레이어 + raw 유지) | python scripts/preprocess.py qc.h5ad -o norm.h5ad |
reduce_dimensions.py | PCA + 분산 플롯, 이웃, UMAP, 선택적 t-SNE | python scripts/reduce_dimensions.py norm.h5ad -o red.h5ad |
batch_correct.py | 통합: harmony / bbknn / combat | python scripts/batch_correct.py red.h5ad -o int.h5ad --method harmony --batch-key sample |
cluster.py | 하나 또는 여러 해상도에서 Leiden (또는 louvain) | python scripts/cluster.py red.h5ad -o clu.h5ad --resolution 0.3 0.6 1.0 |
find_markers.py | rank_genes_groups + 그룹별 CSV + 마커 플롯 | python scripts/find_markers.py clu.h5ad --groupby leiden -o clu.h5ad |
annotate.py | JSON/CSV에서 클러스터 → 세포 유형 매핑; 선택적 마커 참조 닷플롯 | python scripts/annotate.py clu.h5ad -o ann.h5ad --mapping map.json |
score_genes.py | 유전자 시그니처(JSON) 및/또는 세포 주기 점수 계산 | python scripts/score_genes.py ann.h5ad -o scored.h5ad --gene-sets sigs.json |
pseudobulk.py | 샘플 × 세포 유형별 카운트 집계 → pydeseq2용 행렬 | python scripts/pseudobulk.py ann.h5ad --by sample cell_type --out-prefix pb |
subset.py | obs 값 또는 유전자 목록으로 하위 집합 (선택적으로 오래된 임베딩 제거) | python scripts/subset.py ann.h5ad -o tcells.h5ad --obs cell_type --keep "T cells" |
plot.py | 처리된 객체에서 umap/tsne/pca/violin/dotplot/heatmap 등 생성 | python scripts/plot.py ann.h5ad --kind dotplot --genes CD3D CD14 --groupby cell_type |
원샷 종단간 실행
# 카운트 → 클러스터링 및 마커 주석된 객체 + 그림 + 마커 CSV
python scripts/run_pipeline.py raw.h5ad -o processed.h5ad \
--resolution 0.5 --n-top-genes 2000 --scrublet
# 다중 샘플 통합:
python scripts/run_pipeline.py raw.h5ad -o processed.h5ad --batch-key sample --batch-method harmony
# JSON을 통한 재현 가능한 매개변수 (키는 플래그 이름과 언더스코어 일치):
python scripts/run_pipeline.py raw.h5ad -o processed.h5ad --config params.json
단계별 체인 (단계 사이를 검사/반복해야 할 때)
python scripts/qc_analysis.py raw.h5ad -o qc.h5ad --scrublet
python scripts/preprocess.py qc.h5ad -o norm.h5ad --n-top-genes 2000
python scripts/reduce_dimensions.py norm.h5ad -o red.h5ad --n-pcs 40
python scripts/cluster.py red.h5ad -o clu.h5ad --resolution 0.3 0.5 0.8
python scripts/find_markers.py clu.h5ad -o clu.h5ad --groupby leiden --use-raw
# 결과/마커/*.csv 검사, 레이블 결정, 매핑 JSON 작성, 그런 다음:
python scripts/annotate.py clu.h5ad -o ann.h5ad --mapping celltypes.json
아래 섹션에서는 각 스크립트가 수행하는 기본 scanpy 호출을 문서화합니다. 스크립트 플래그 이상으로 사용자 정의가 필요할 때 읽어보세요.
빠른 시작
기본 임포트 및 설정
import scanpy as sc
import pandas as pd
import numpy as np
# 설정 구성
sc.settings.verbosity = 3
sc.settings.set_figure_params(dpi=80, facecolor='white')
sc.settings.figdir = './figures/'
sc.settings.autosave = True # scanpy 1.12에서 더 이상 사용되지 않는 per-plot save=보다 선호
데이터 로딩
# 10X Genomics에서
adata = sc.read_10x_mtx('path/to/data/')
adata = sc.read_10x_h5('path/to/data.h5')
# h5ad (AnnData 형식)에서
adata = sc.read_h5ad('path/to/data.h5ad')
# CSV에서
adata = sc.read_csv('path/to/data.csv')
R 네이티브 파일의 경우 Python에서 직접 Seurat .rds를 구문 분석하려고 시도하지 마세요. 먼저 변환하세요:
# R 설치 및 변환 패키지 설치에 대한 자세한 내용은 references/r_interop.md를 참조하세요.
Rscript convert_rds_to_h5ad.R input.rds output.h5ad
adata = sc.read_h5ad('output.h5ad')
AnnData 구조 이해
AnnData 객체는 scanpy의 핵심 데이터 구조입니다:
adata.X # 발현 행렬 (세포 × 유전자)
adata.obs # 세포 메타데이터 (DataFrame)
adata.var # 유전자 메타데이터 (DataFrame)
adata.uns # 구조화되지 않은 주석 (dict)
adata.obsm # 다차원 세포 데이터 (PCA, UMAP)
adata.raw # 원시 데이터 백업
# 세포 및 유전자 이름 접근
adata.obs_names # 세포 바코드
adata.var_names # 유전자 이름
표준 분석 워크플로
일곱 단계와 각 단계에서 중요한 매개변수에 대한 코드는 references/analysis_workflow.md에 있습니다:
- 품질 관리 — 세포와 유전자를 필터링합니다. 기본값을 복사하는 대신 임계값을 선택하기 전에 미토콘드리아 분율과 카운트를 검사합니다.
- 정규화 및 전처리 — 정규화, 로그 변환, 고도로 가변적인 유전자 선택, 나중에 플롯팅을 위해
.raw를 유지합니다. - 차원 축소 — PCA, 그 다음 이웃 그래프, 그 다음 UMAP입니다.
- 클러스터링 — 질문에 맞게 선택된 해상도로 Leiden을 사용합니다. 기본값을 사용하지 마세요.
- 마커 유전자 식별 — 클러스터당 유전자 순위.
- 세포 유형 주석 — 마커에서 클러스터를 유형으로 매핑합니다.
- 결과 저장 — 주석이 달린
AnnData를 씁니다.
일반적인 후속 작업(출판 플롯, 궤적 추론, 조건 간 유사벌크 차별 발현, 유전자 세트 점수, 배치 보정)은 동일한 파일에 있습니다. references/standard_workflow.md 및 references/plotting_guide.md도 참조하세요.
조정할 주요 매개변수
품질 관리
min_genes: 세포당 최소 유전자 수 (일반적으로 200-500)min_cells: 유전자당 최소 세포 수 (일반적으로 3-10)pct_counts_mt: 미토콘드리아 임계값 (일반적으로 5-20%)
정규화
target_sum: 세포당 목표 카운트 (기본값 1e4)
특징 선택
n_top_genes: HVG 수 (일반적으로 2000-3000)min_mean,max_mean,min_disp: HVG 선택 매개변수
차원 축소
n_pcs: 주성분 수 (분산 비율 플롯 확인)n_neighbors: 이웃 수 (일반적으로 10-30)
클러스터링
resolution: 클러스터링 세분성 (0.4-1.2, 높을수록 더 많은 클러스터)
일반적인 함정 및 모범 사례
- 항상 원시 카운트 저장: 유전자 필터링 전에
adata.raw = adata - QC 플롯 주의 깊게 확인: 데이터셋 품질에 따라 임계값 조정
- Leiden 클러스터링 사용:
sc.tl.louvain은 scanpy 1.12에서 더 이상 사용되지 않음 - 여러 클러스터링 해상도 시도: 최적의 세분성 찾기
- 세포 유형 주석 검증: 여러 마커 유전자 사용
- 유전자 발현 플롯에
use_raw=True사용:.raw의 정규화된 카운트 표시 - PCA 분산 비율 확인: 최적 PC 수 결정
- 중간 결과 저장: 긴 워크플로는 중간에 실패할 수 있음
- DE를 위한 유사벌크:
rank_genes_groupsp-값을 조건 간 엄격한 DE로 취급하지 마세요 - 설정을 통해 플롯 저장: 플롯 함수에서 더 이상 사용되지 않는
save=대신sc.settings.autosave사용 - Scanpy 전에 R 객체 변환: R 패키지를 사용하여 Seurat 또는 SingleCellExperiment
.rds파일을.h5ad로 변환하고 카운트, 메타데이터 및 유전자 식별자 보존
번들 리소스
scripts/ (CLI 툴킷)
전체 워크플로를 포괄하고 하나의 명령으로 종단간 파이프라인을 제공하는 구성 가능한 .h5ad-입력/.h5ad-출력 스크립트 세트입니다. 전체 표 및 체인 예제는 위의 스크립트 툴킷 섹션을 참조하세요. 각 스크립트에는 --help가 있습니다. 파일:
_common.py— 다른 스크립트에서 가져오는 공유 로딩/저장/그림 헬퍼 (CLI 아님)run_pipeline.py— 하나의 명령으로 전체 파이프라인 (플래그 또는--configJSON)inspect_data.py,convert.py— 모든 입력 형식 탐색 및 로드/변환qc_analysis.py,preprocess.py,reduce_dimensions.py,batch_correct.py,cluster.py— 파이프라인 단계find_markers.py,annotate.py,score_genes.py,pseudobulk.py— 마커, 주석, 점수 계산, DE 준비subset.py,plot.py— 메타데이터/유전자로 하위 집합; 모든 표준 플롯 생성
처음부터 scanpy 코드를 작성하기 전에 이 스크립트를 기본으로 사용하세요.
references/standard_workflow.md
상세한 설명과 코드 예제가 포함된 완전한 단계별 워크플로:
- 데이터 로딩 및 설정
- 시각화를 포함한 품질 관리
- 정규화 및 스케일링
- 특징 선택
- 차원 축소 (PCA, UMAP, t-SNE)
- 클러스터링 (Leiden)
- 더블릿 탐지 (scrublet) 및 유사벌크 집계
- 마커 유전자 식별
- 세포 유형 주석
- 궤적 추론
- 차별 발현
처음부터 완전한 분석을 수행할 때 이 참조를 읽으세요.
references/api_reference.md
모듈별로 구성된 scanpy 함수 빠른 참조 가이드:
- 데이터 읽기/쓰기 (
sc.read_*,adata.write_*) - 전처리 (
sc.pp.*) - 도구 (
sc.tl.*) - 플롯팅 (
sc.pl.*) - AnnData 구조 및 조작
- 설정 및 유틸리티
함수 시그니처 및 일반적인 매개변수를 빠르게 찾을 때 사용하세요.
references/plotting_guide.md
포괄적인 시각화 가이드:
- 품질 관리 플롯
- 차원 축소 시각화
- 클러스터링 시각화
- 마커 유전자 플롯 (히트맵, 닷 플롯, 바이올린 플롯)
- 궤적 및 유사시간 플롯
- 출판 품질 사용자 정의
- 다중 패널 그림
- 색상 팔레트 및 스타일링
출판 준비가 된 그림을 만들 때 참고하세요.
references/r_interop.md
macOS, Linux 및 Windows에 R을 설치하고, CRAN/Bioconductor 변환 패키지를 설치하고, .rds/.RData 입력을 검사하고, Seurat 또는 SingleCellExperiment 객체를 .h5ad로 변환하고, Scanpy에서 결과를 검증하기 위한 에이전트 실행 설명서입니다.
assets/analysis_template.py
데이터 로딩부터 세포 유형 주석까지 전체 워크플로를 제공하는 완전한 분석 템플릿입니다. 새 분석을 위해 이 템플릿을 복사하여 사용자 정의하세요:
cp assets/analysis_template.py my_analysis.py
# 매개변수 편집 및 실행
python my_analysis.py
템플릿은 구성 가능한 매개변수와 유용한 주석이 포함된 모든 표준 단계를 포함합니다.
assets/ JSON 템플릿
처음부터 구성/매핑을 작성하지 않도록 편집 및 전달 가능한 템플릿:
assets/pipeline_config.json—run_pipeline.py --config용 매개변수 세트assets/celltype_mapping.json—annotate.py --mapping용 클러스터 → 세포 유형 맵assets/gene_signatures.json—score_genes.py --gene-sets용 유전자 세트 시그니처
추가 리소스
- 공식 scanpy 문서: https://scanpy.scverse.org/en/stable/
- Scanpy 튜토리얼: https://scanpy.scverse.org/en/stable/tutorials/
- scverse 생태계: https://scverse.org/
- AnnData 사양: https://anndata.readthedocs.io/
- 문제 보고: https://github.com/scverse/scanpy/issues