deepspot-m은(는) 무엇을 하나요?
개요
DeepSpot-M은 224x224 H&E 조직학 타일을 log1p-CPM 공간 유전자 발현으로 매핑하는 다중 모달 기초 모델입니다. 출력은 가상 공간 전사체학 데이터로, 질의된 유전자당 타일별 하나의 값이 타일이 추출된 그리드에 배치됩니다.
LoRA로 미세 조정된 병리학 기초 백본(Midnight)이 타일을 토큰화합니다. 교차 주의 유전자 디코더를 통해 각 유전자 질의가 패치 토큰에 집중할 수 있으며, 유전자 라우터 하이퍼네트워크는 사전 학습된 생물학적 임베딩(Evo 2, Orthrus, ProtT5, scGPT, Apertus)으로부터 유전자별 투영을 구축합니다. 유전자는 고정된 출력 슬롯이 아닌 질의 가능한 임베딩으로 모델에 입력되므로, 출시된 모델은 학습 중 보지 못한 유전자를 포함하여 약 19,000개의 단백질 코딩 유전자 패널을 지원합니다. 이 패널은 가중치와 함께 tokens.csv로 제공되며 model.gene_names로 노출됩니다. 이번 릴리스에서는 이 패널 외부의 유전자는 질의할 수 없습니다.
TCGA에 적용된 이 모델은 32개 암 유형에 걸쳐 28,664개 슬라이드의 가상 공간 전사체학 지도를 생성했습니다.
라이선스
코드는 PolyForm 비상업적 1.0.0, 가중치는 CC-BY-NC-SA-4.0 라이선스입니다. 비상업적 연구 용도로 사용하고, 출력물을 재배포하기 전에 두 라이선스를 모두 확인하십시오.
설치
uv pip install deepspotm==1.0.0
버전 1.0.0은 Python 3.10부터 3.13까지 지원하며 PyTorch를 포함합니다. GPU 추론을 사용하려면 먼저 CUDA 버전에 맞는 PyTorch 빌드를 설치하십시오.
모델 접근
가중치는 게이트(gated) 방식으로 제공됩니다:
- https://huggingface.co/ratschlab/DeepSpotM을 열고 접근 권한을 요청하십시오.
- 접근이 승인되면 다운로드를 실행할 머신에서 인증하십시오:
huggingface-cli login
from_pretrained는 캐시된 토큰을 읽으므로, 머신당 한 번 로그인이 필요합니다.
빠른 시작
from deepspotm import DeepSpotM
model, image_processor = DeepSpotM.from_pretrained("ratschlab/DeepSpotM", source="scgpt")
vals = model.predict_genes(image_processor(pil_tile).unsqueeze(0), ["EPCAM", "CD3D"])
pil_tile은 정확히 224x224 픽셀의 PIL 이미지입니다. image_processor가 이를 텐서로 변환하고, unsqueeze(0)이 배치 차원을 추가하며, predict_genes는 배치와 HGNC 유전자 기호 목록을 받습니다. 값은 log1p-CPM으로 반환되며 전달한 유전자 목록 순서와 일치하므로, 출력 옆에 이 목록을 유지하여 열 레이블을 유지하십시오. 유전자 기호는 출시된 약 19,000개 유전자 패널(model.gene_names)에 포함되어야 하며, 알 수 없는 기호는 오류 유전자를 명시하는 KeyError를 발생시킵니다.
타일 요구 사항
타일은 약 20배율(픽셀당 약 0.5 마이크론)에서 224x224 RGB여야 합니다. 확인되지 않은 자르기를 전달하지 말고 파이프라인 경계에서 크기를 확인하십시오:
TILE_PX = 224
def require_tile(tile):
"""RGB 224x224 타일을 반환하거나, 자르기 크기가 올바르지 않으면 오류를 발생시킵니다."""
if tile.size != (TILE_PX, TILE_PX):
raise ValueError(
f"DeepSpot-M은 약 20배율(~픽셀당 약 0.5 마이크론)에서 {TILE_PX}x{TILE_PX} 타일을 필요로 합니다; "
f"{tile.size[0]}x{tile.size[1]}이(가) 제공되었습니다. "
"일치하는 레벨에서 다시 타일링하거나 자르기를 리샘플링하십시오."
)
return tile.convert("RGB")
슬라이드 레벨에서 픽셀당 0.5 마이크론에 가장 가까운 해상도로 타일을 추출한 다음, 해당 위치에서 224x224로 자릅니다. 더 낮은 해상도에서 리샘플링하면 백본이 읽는 텍스처가 변경됩니다.
종속성을 선택 사항으로 유지
deepspotm과 그 가중치는 무겁고 게이트된 종속성입니다. 이 종속성이 있는 함수 내부에서 임포트하여 주변 프로젝트가 설치, 임포트 및 테스트될 수 있도록 하고, ImportError를 각 단계를 명시하는 메시지로 변환하십시오:
DEEPSPOTM_HELP = (
"DeepSpot-M을 사용할 수 없습니다. `uv pip install deepspotm==1.0.0`로 설치하고, "
"https://huggingface.co/ratschlab/DeepSpotM에서 게이트된 가중치에 대한 접근을 요청한 다음, "
"`huggingface-cli login`으로 인증하십시오."
)
def load_deepspotm(source="scgpt"):
try:
from deepspotm import DeepSpotM
except ImportError as exc:
raise RuntimeError(DEEPSPOTM_HELP) from exc
return DeepSpotM.from_pretrained("ratschlab/DeepSpotM", source=source)
임베딩 소스
source는 라우터가 투영을 구축할 사전 학습된 유전자 임베딩을 선택합니다. 다음 다섯 가지 값 중 하나입니다:
source | 유전자 임베딩 |
|---|---|
evo2 | 게놈 서열 |
orthrus | RNA |
prott5 | 단백질 서열 |
scgpt | 단일 세포 발현 |
apertus | 언어 모델 |
각 소스는 유전자 식별에 대한 다른 관점을 제공합니다. 실행당 하나를 선택하고, 선택이 분석에 중요한 경우 동일한 타일을 여러 소스로 실행하십시오. 전체 호출 표면, 배치 처리 및 장치 배치, 유전자 기호 처리 및 출력 단위에 대한 자세한 내용은 references/api.md를 참조하십시오.
전체 슬라이드 워크플로우
예측은 타일별로 이루어지므로, 슬라이드 규모 실행은 타일링 단계 후 배치 추론으로 진행됩니다:
histolab기술을 사용하여 그리드에서 224x224 타일을 추출하고 각 타일의 좌표를 유지합니다.torch.stack으로 타일을 처리하고 배치로 쌓습니다.- 동일한 유전자 목록으로 배치당 한 번씩
predict_genes를 호출합니다. - 배치를 연결하여 타일-유전자 행렬을 만들고 좌표를 첨부합니다.
이 행렬이 슬라이드의 가상 공간 전사체학 맵이며, 다운스트림 공간 분석을 위해 AnnData에 직접 통합할 수 있습니다. references/whole_slide.md에는 구체적인 루프, 배치 크기 조정 및 AnnData 조립 단계가 포함되어 있습니다.
일반적인 사용 사례
- 종양 절편 전반에 걸친 마커 유전자의 공간 발현 맵
- 일치하는 분석 실행 없이 슬라이드 코호트에 대한 전사체 전반 예측
- 학습 중 보지 못한 유전자를 포함하여 약 19,000개 패널 유전자를 기호로 질의 (일반적인 공간 분석 패널의 수백 개 유전자를 훨씬 초과)
- 형태학 전용 조직학 파이프라인에 발현 채널 추가
- TCGA에서 수행된 것과 같은 슬라이드 수준 코호트 지도 구축
상세 참조
references/api.md:from_pretrained및predict_genes전체 설명, 다섯 가지 임베딩 소스 및 선택 방법, 배치 처리, 장치 배치, 유전자 기호 처리, log1p-CPM 출력 변환references/whole_slide.md: histolab을 사용한 타일링, 슬라이드 규모 예측 루프, 타일-유전자 행렬 조립 및 저장, 코호트 규모 실행
주요 출처
- 논문: https://doi.org/10.64898/2026.06.19.26356060 (medRxiv, 2026년 6월 22일 게재)
- 코드: https://github.com/ratschlab/DeepSpotM
- 가중치: https://huggingface.co/ratschlab/DeepSpotM
- PyPI: https://pypi.org/project/deepspotm/