scvi-tools

scvi-tools 스킬 개요

scvi-tools는 무엇에 쓰는가

scvi-tools 스킬은 일반적인 분석 프롬프트로는 너무 모호할 때, 단일세포 omics에 scVI 계열의 확률적 모델을 적용하도록 돕습니다. 배치 보정, 잠재 표현 학습, 여러 런이나 donor 간 통합, 불확실성을 반영한 차등 발현 분석에 특히 유용합니다. 목표가 일상적인 전처리보다 고급 단일세포 모델링에 가깝다면, 이 scvi-tools 스킬은 매우 잘 맞습니다.

누가 설치해야 하는가

단일세포 RNA-seq, multiome, CITE-seq, ATAC, 또는 spatial 데이터를 다루며 모델 기반 워크플로를 원한다면 scvi-tools를 설치하세요. 정적인 방법 요약이 아니라 PyTorch 기반 프레임워크가 필요한 Machine Learning 사용자에게 특히 적합합니다. 기본적인 QC, 클러스터링, 시각화만 필요하다면, 보통은 Scanpy 중심의 표준 워크플로만으로도 충분합니다.

도입 전에 무엇을 따져봐야 하는가

핵심 가치는 단순히 scvi-tools가 존재한다는 데 있지 않고, 원시 count에서 명시적인 트레이드오프가 있는 학습된 잠재 모델까지 실무적으로 이어지는 경로를 제공한다는 데 있습니다. 중요한 판단 기준은 확률적 모델링, transfer learning, multimodal 통합이 추가 설정과 모델 선택의 수고를 감수할 만큼 필요한가 하는 점입니다. 배치 효과를 제대로 다루거나 이질적인 데이터셋을 신중하게 비교해야 출력 품질이 좌우된다면, 이 스킬을 설치할 가치가 있습니다.

scvi-tools 스킬 사용법

스킬 설치하기

scvi-tools 스킬은 디렉터리 설치 흐름을 사용하세요:
npx skills add K-Dense-AI/claude-scientific-skills --skill scvi-tools

설치 후에는 scientific-skills/scvi-tools 아래의 스킬 경로를 확인하고 소스 파일을 직접 여세요. 이 저장소에서는 SKILL.md가 기본 진입점이며, 의존할 수 있는 rules/, resources/, scripts/ 폴더는 없습니다.

먼저 읽어야 할 파일

먼저 SKILL.md를 읽어 범위, 모델 계열, 권장 판단 지점을 파악하세요. 그다음 프롬프트를 시도하기 전에 스킬을 언제 써야 하는지, 핵심 기능, 단일세포 RNA-seq 워크플로 섹션을 훑어보는 것이 좋습니다. 저장소가 작기 때문에, 모델 이름만 골라 읽기보다 파일 전체를 한 번 쭉 읽는 편이 추측을 줄이는 가장 빠른 방법입니다.

대충 잡은 목표를 쓸 수 있는 프롬프트로 바꾸기

“scRNA-seq 데이터를 분석해줘” 같은 약한 요청만으로는 부족합니다. 더 나은 scvi-tools 사용 프롬프트는 assay, 데이터 형태, 필요한 판단을 분명히 적습니다.

• “scVI로 6개의 scRNA-seq 배치를 통합하고 donor 효과를 비교한 뒤, latent space와 batch-mixing 진단 결과를 반환해줘.”
• “paired RNA + ATAC 데이터에 MULTIVI 스타일 워크플로를 적용하고, 세포가 biology 기준으로 더 잘 분리되는지 batch 기준으로 더 잘 분리되는지 설명해줘.”
• “두 세포 집단의 차등 발현을 불확실성까지 반영해 수행하고, p-value만이 아니라 effect size도 보고해줘.”

출력 품질을 바꾸는 워크플로 팁

이 스킬이 올바른 model family를 고를 수 있도록 필요한 입력을 주세요: modality, 배치 수, paired 데이터 여부, 통합인지 annotation인지 DE인지 같은 작업 유형입니다. sparse counts, 작은 샘플 수, 기존 scanpy 객체와의 호환성 유지 같은 제약도 처음부터 밝혀야 합니다. 가장 좋은 scvi-tools 가이드 결과를 원한다면, model choice, setup 단계, 예상 출력, 흔한 실패 모드를 한 번에 요청하세요.

scvi-tools 스킬 FAQ

scvi-tools는 scRNA-seq에만 쓰는가?

아닙니다. scvi-tools 스킬은 RNA-seq, ATAC, multimodal assay, spatial use case를 포함한 여러 단일세포 모달리티를 다룹니다. 다만 RNA 통합이 가장 흔한 출발점이므로, 더 복잡한 데이터로 확장하기 전에 적합성을 검증하기 가장 쉬운 지점이기도 합니다.

이미 Scanpy를 쓰고 있어도 필요한가?

둘 다 쓰되, 역할은 다릅니다. Scanpy는 표준 전처리와 탐색적 워크플로에 더 적합하고, scvi-tools는 확률적 모델링, latent embedding, 배치 효과 하의 통합이 필요할 때 더 강합니다. 분석 질문에 학습된 generative model이 꼭 필요하지 않다면, scvi-tools는 과한 선택일 수 있습니다.

초보자도 쓰기 쉬운가?

기본적인 single-cell 개념, 예를 들면 counts matrix, batch, annotation을 이미 이해하고 있다면 초보자도 접근할 수 있습니다. 이 스킬은 데이터와 목표를 명확히 말할 수 있을 때 가장 큰 도움이 됩니다. 아직 통합, transfer learning, differential expression 중 무엇이 필요한지 말할 수 없다면, 먼저 더 단순한 분석 경로부터 시작하세요.

언제 scvi-tools를 쓰지 말아야 하는가?

간단한 정규화, 빠른 그림 확인, 일회성 탐색 점검에는 scvi-tools를 굳이 꺼내지 마세요. 모델 선택 판단이 들어가지 않는 순수한 statistical cookbook을 원할 때도 잘 맞지 않습니다. 아주 작은 데이터셋이나 지나치게 커스텀된 파이프라인에서는 오버헤드가 이점보다 클 수 있습니다.

scvi-tools 스킬 개선하기

model-selection 맥락을 제공하기

가장 큰 품질 향상은 지금 겪고 있는 scvi-tools 문제의 종류를 정확히 알려주는 데서 나옵니다. 데이터 설명을 먼저 하고, 그다음에 scVI, TOTALVI, MultiVI, 또는 다른 계열이 필요한지 말하세요. 예를 들어 “강한 donor 효과가 있는 paired CITE-seq”가 “MultiVI를 써줘”보다 훨씬 유용합니다.

데이터 구조와 제약을 공유하기

좋은 입력은 가장 흔한 실패 모드, 즉 assay에 맞지 않는 모델을 고르는 문제를 줄여줍니다. matrix 타입, cell 수, batch 수, covariate, count가 raw인지 normalized인지 포함하세요. Machine Learning용 scvi-tools 워크플로를 쓰는 경우라면, 재사용 가능한 latent space가 필요한지, downstream classifier feature가 필요한지, 아니면 다른 모델과의 해석 가능한 비교가 필요한지도 함께 적어야 합니다.

바로 쓸 수 있는 출력물을 요청하기

“분석해줘”라고만 하지 마세요. training plan, model choice의 근거, integration diagnostics, notebook 스타일 워크플로처럼 구체적인 산출물을 요청해야 합니다. 첫 결과가 너무 일반적이라면, 빠진 정보를 보강하며 반복하세요. cell type label, batch 정의, 또는 scanpy나 다른 baseline과 무엇을 비교해야 하는지 추가하면 됩니다.