유전체 변이 분석 (AlphaGenome 기반)

AlphaGenome을 사용한 변이 분석

전제 조건

1. uv: uv 스킬을 읽고 설정 지침을 따라 uv가 설치되고 PATH에 등록되었는지 확인하세요.

2. 사용자 알림: 작업 디렉토리 루트에 .licenses/alphagenome_single_variant_analysis_LICENSE.txt 파일이 존재하지 않는 경우 (1) 사용자에게 https://deepmind.google.com/science/alphagenome/ 의 이용 약관을 확인하도록 명확히 알린 후 (2) 알림 텍스트와 타임스탬프를 기록한 파일을 생성하세요.

3. .env 파일: 홈 디렉토리에 .env 파일이 있는지 확인하세요. 없으면 생성합니다.

4. ALPHAGENOME_API_KEY: 이 스킬이 작동하려면 API 키가 필요합니다.

   https://deepmind.google.com/science/alphagenome/ 에서 키를 등록할 수 있습니다. credentials 스킬의 안전한 자격 증명 프로토콜을 반드시 사용하여 이 키를 확인하고 요청하세요. (이 스킬이 사용자 요청과 관련 있을 경우)

5. ALPHAGENOME_GTF_PATH (선택 사항): GCS에서 다운로드하는 대신 로컬 GTF Feather 파일 경로를 지정하여 유전자/전사체 조회를 가속화합니다:

   echo "ALPHAGENOME_GTF_PATH=/path/to/local/gencode.v46.annotation.gtf.gz.feather" >> ~/.env
   

핵심 규칙

• 절대로 python3 또는 python3 -c를 직접 실행하지 마십시오. 시스템 Python에 pandas, numpy 및 기타 주요 종속성이 반드시 있는 것은 아닙니다. 모든 Python 코드(스크립트, 임시 분석 파일, 한 줄 명령 포함)를 실행하려면 항상 uv run을 사용하십시오. pip install을 시도하거나 새 venv를 생성하지 마십시오. uv가 자동으로 격리된 환경을 관리합니다.
• 오프라인 전용: 유전자/전사체 조회에 외부 API(예: MyGene.info, Ensembl REST)를 절대 사용하지 마십시오. 로컬 GTF와 함께 lookup_gene_info.py를 사용하세요. 실패하면 환경/경로를 수정하고 외부 API로 전환하지 마십시오.
• API 키 필수: 스크립트를 실행하기 전에 ALPHAGENOME_API_KEY가 설정되어 있어야 합니다.
• 알림: 이 스킬을 사용하는 경우 출력에 언급되어 있는지 확인하세요.
• 보고서 형식: 분석 보고서 생성 시 항상 docs/report-templates.md의 템플릿을 사용하고, 발견 검색의 상위 결과 표를 포함해야 합니다.

환경 설정 및 문제 해결

Python 환경

모든 스크립트는 uv run을 사용하여 실행해야 합니다. uv는 이를 통해 올바른 종속성이 포함된 격리된 가상 환경을 관리합니다.

uv run <script_name> [args...]

임시 스크립트(예: 임시 파일로 저장된 인라인 분석 코드)의 경우 짧은 이름 대신 전체 경로를 전달하세요:

uv run --project $SKILL_DIR /tmp/my_analysis.py --arg1 val1

[!NOTE] 첫 번째 호출은 종속성을 확인하고 설치합니다(~10초). 이후 실행은 캐시된 환경을 사용하여 즉시 시작됩니다. 캐시는 ~/.cache/uv/에 있습니다.

일반적인 문제

• 열 이름: tidy_scores 및 메타데이터는 종종 gene_name(gene_symbol 아님) 및 output_type(modality 아님)을 사용합니다. 필터링하기 전에 항상 df.columns를 확인하세요.
• 큰 유전자: 500kb를 초과하는 유전자(예: USH2A)는 whole_gene 뷰에서 문제를 일으킵니다. 대신 --view detail 또는 수동 영역 윈도우를 사용하세요.
• Sashimi 가닥 오류: plot_components.Sashimi는 strand 인수를 직접 허용하지 않습니다. 대신 입력 트랙을 필터링하세요.
• KeyError: 'ontology_curie': 모든 트랙에 ontology_curie가 있는 것은 아닙니다. 필터링하기 전에 track.metadata.columns를 확인하세요.
• Python Path: exec: "python": executable file not found 오류가 발생하면 python/python3 대신 uv run을 사용하고 있는지 확인하세요.
• NotImplementedError (pandas): "iLocation based boolean indexing on an integer type is not available". 이는 최신 pandas 버전에서 정수 인덱스 DataFrame에 대해 .iloc과 함께 부울 마스크를 사용할 때 발생합니다. 수정 방법: np.flatnonzero(mask)를 사용하여 부울 마스크를 정수 인덱스로 변환하세요.
• GTF Feather 대소문자 구분: AlphaGenome GTF Feather 파일은 표준 GTF 파일과 달리 대문자 열 이름(Feature, Start, End, Strand)을 사용합니다. KeyError가 발생하면 항상 df.columns를 확인하세요.
• score_variant 온톨로지 필터링: score_variant는 ontology_terms를 인수로 허용하지 않습니다. 반환된 AnnData 객체를 adata.var 열을 검사하여 수동으로 필터링해야 합니다. 반면에 predict_variant는 ontology_terms를 직접 허용합니다.
• Sashimi 확대/축소 로직: "건너뛰기" 아크(arcs)가 보이도록 하려면 접합부 중복만 의존하지 말고 플랭킹 엑손(flanking exons) 을 포함하도록 확대/축소를 확장하세요.
• 접합부 점수: prediction의 원시 Junction 객체는 단순한 Interval일 수 있습니다. .k (풍부도/점수) 속성이 있는 객체를 검색하려면 junction_data.get_junctions_to_plot(predictions=..., name=...)를 사용하세요.
• uv를 찾을 수 없음: exec: uv: not found 오류가 발생하면 전제 조건의 설치 지침을 따르세요.
• 레지스트리 인증 오류 (401): 비공개 레지스트리에서 uv가 401 Unauthorized 오류로 실패하면 스크립트를 실행하기 전에 UV_INDEX_URL=https://pypi.org/simple을 설정하세요.

참고 자료

• alphagenome-api.md — API 참조 및 코드 패턴
• interpretation-guide.md — 해석 가이드, 점수 크기 규칙, ISM 및 체크리스트
• report-templates.md — 전체 보고서 템플릿
• scripts/visualize_variant_effects.py — 단일 변이 시각화 템플릿 (참조/대립유전자 비교, 스플라이싱)
  • 스플라이싱 확대/축소 전략: 최적의 가시성을 위해 하이브리드 접근 방식을 사용합니다:
    1. 기본 구간: 변이 +/- 1개의 다운스트림 및 업스트림 엑손 (구조적 컨텍스트).
    2. 접합부 확장: 유의미한 스플라이싱 접합부(예: 여러 엑손에 걸친 엑손 스키핑 이벤트)의 전체 범위를 포함하도록 확장합니다.
    3. 앵커 강제 적용: 이러한 긴 접합부를 앵커링하는 엑손이 완전히 보이도록 합니다. 교훈: 단순한 고정 윈도우(예: 2kb) 또는 가장 가까운 엑손 로직은 스키핑 이벤트에 대해 종종 실패합니다. 확대/축소 수준을 결정하려면 항상 관찰된 접합부 데이터를 사용하세요.
• examples/splicing/ — 스플라이싱 분석 예제
• examples/model_limitation_RNU4ATAC/ — ncRNA 구조 한계 사례 연구
• examples/polyadenylation_HBA2/ — 3' UTR / 폴리아데닐화 사례 연구
• examples/regulatory/ — 조절 변이 예제
• examples/negative_result_GATA4/ — 부정 결과 (수학적 아티팩트)
• examples/negative_result_TGFB3/ — 부정 결과 (대리 변수)
• scripts/lookup_gene_info.py — 유전자 및 전사체 조회
• scripts/resolve_ontology_terms.py — 온톨로지 용어 확인 (UBERON/CL ID)

---

코드 패턴

광범위한 발견 검색

예상치 못한 조직 효과를 발견하기 위해 차등 스코어러(differential scorers)에 한정하여 score_variant를 사용하세요.

from alphagenome.models import dna_client
from alphagenome.models import variant_scorers
from alphagenome.data import genome
import os
import pandas as pd
import dotenv

# ~/.env에서 환경 변수 로드
dotenv.load_dotenv(os.path.expanduser('~/.env'))

# API 키 및 클라이언트 설정
dna_model = dna_client.create(api_key=os.environ.get('ALPHAGENOME_API_KEY'),
                              address='dns:///gdmscience.googleapis.com:443')

# 변이 정의 (예시)
variant_str = "chr2:1234:A>C"
chrom, pos_str, ref_alt = variant_str.split(':')
ref, alt = ref_alt.split('>')
pos = int(pos_str)

# 지원되는 시퀀스 길이 사용 (최적 성능을 위해 2**20 권장)
SEQ_LENGTH = 2**20
interval = genome.Interval(chrom, pos - SEQ_LENGTH // 2, pos + SEQ_LENGTH // 2)
variant = genome.Variant(chrom, pos, ref, alt)

scorers = [
    variant_scorers.RECOMMENDED_VARIANT_SCORERS[m]
    for m in variant_scorers.RECOMMENDED_VARIANT_SCORERS
    if "ACTIVE" not in m and "CAGE" not in m and "PROCAP" not in m
]

print(f"Scoring variant {variant_str}...")
scores_list = dna_model.score_variant(interval=interval, variant=variant, variant_scorers=scorers)

# 결과 처리 및 표시
all_dfs = []
for score_adata in scores_list:
    df = variant_scorers.tidy_scores([score_adata], match_gene_strand=True)
    if df is not None:
        all_dfs.append(df)

if all_dfs:
    df = pd.concat(all_dfs)
    significant = df[df['quantile_score'].abs() > 0.995]
    ranked = significant.sort_values('raw_score', key=abs, ascending=False)
    print("Top Significant Hits:")
    print(ranked[['biosample_name', 'gene_name', 'output_type', 'quantile_score', 'raw_score']])

질병 관련 조직에 대한 확장 검색

# 질병 컨텍스트를 기반으로 키워드 정의
disease_keywords = ["liver", "hepatocyte"]

# 일치 항목 필터링
mask = df['biosample_name'].str.contains('|'.join(disease_keywords), case=False, na=False)

relevant_hits = df[mask].sort_values('raw_score', key=abs, ascending=False)
print(f"\n--- Extended Analysis (Keywords: {disease_keywords}) ---")
print(relevant_hits.head(20)[['biosample_name', 'output_type', 'raw_score', 'quantile_score']])

워크플로우 체크리스트

변이 분석 진행 상황:
- [ ] 단계 0: 모범 예제 검토 (필수)
- [ ] 단계 1: 출력 폴더 생성 및 설정
- [ ] 단계 2: 사용자 쿼리 구문 분석 및 연구
- [ ] 단계 3: 조직 및 모달리티 확인
- [ ] 단계 4: 시각화 및 플롯 저장
- [ ] 단계 5: 예측 분석 (플롯 확인, 코드 없음). 필수: 결과 해석 전 [interpretation-guide.md](docs/interpretation-guide.md) 읽기
- [ ] 단계 6: 보고서 작성, `report.md`로 저장 (필수)
- [ ] 단계 7: 자체 비평 (`report.md`를 보고 링크 및 주장 확인)
- [ ] 단계 8: `report.md`를 아티팩트로 만들기

---

다중 변이 워크플로우

여러 변이가 지정된 경우 하위 에이전트를 생성하여 각 변이 분석을 실행한 다음 각 report.md를 단일 보고서로 종합합니다.

스크립트 참조

스크립트	목적
lookup_gene_info	GTF 데이터를 사용한 종합적인 유전자 및 전사체 조회
: : :
resolve_ontology_terms	생물학적 용어 → UBERON/CL/EFO ID 변환
visualize_variant_effects	REF/ALT 시각화 (발현, 조절, 스플라이싱)
: : :
analyze_ism	인실리코 돌연변이 유발(In-Silico Mutagenesis) SeqLogo 생성
interpret_splicing	정량적 스플라이싱 분석 (델타 점수, 접합부)
: : :
visualize_genome_tracks	특정 영역의 유전체 트랙 시각화