alleleforge

## 개요 AlleleForge는 가이드 RNA가 아닌 손상된 대립유전자(allele)에서 시작하는 연구 중심의 CRISPR 게놈 편집 설계 프레임워크입니다. 사용자가 ClinVar 항목, rsID, HGVS, VCF 또는 원시 좌표와 같은 변이를 제공하면, 파이프라인이 이를 분석하여 적절한 편집 화학 방식으로 라우팅하고, 후보 가이드/pegRNA를 나열 및 점수화하여 순위가 매겨진 후보 편집 메뉴를 반환합니다. SpCas9 뉴클레아제, 염기 교정기(ABE/CBE), 그리고 프로젝트의 핵심 모달리티인 프라임 편집의 세 가지 화학 방식이 지원됩니다. 각 후보에는 예측된 편집 결과, 불확실성 구간 및 오프타겟 보고서가 포함됩니다. 모든 기능은 하나의 코어 위에 Python 라이브러리, `aforge` 명령줄 인터페이스(CLI), 웹 UI(FastAPI 백엔드 및 Next.js 프런트엔드)라는 세 가지 셸을 통해 제공됩니다. ## 불확실성 및 안전성 보고 예측값은 단순한 부동 소수점으로 제공되지 않습니다. 각 수치 결과에는 구간, 생성 방법, 그리고 해당 구간이 홀드아웃 커버리지(held-out coverage)에 대해 적합되었는지를 나타내는 `calibrated` 플래그가 함께 제공됩니다. 기본 설정인 가중치 없는 기본값은 휴리스틱이며 `calibrated=False`로 보고됩니다. 구간 재보정에는 split-conformal 방법이 사용되고 확률 보정에는 isotonic regression이 사용되며, 필요한 경우 `empirical_coverage`/ECE가 표시됩니다. 오프타겟 분석은 인구 집단 및 하플로타입(haplotype)을 인식하지만, 명시적인 선택 사항(opt-in)으로 제공됩니다. 프로젝트에서 gnomAD 데이터를 직접 제공하지 않으므로, 조상 계층화 스캔을 위해서는 사용자가 빈도 소스(`--gnomad`, `--haplotypes`, `--patient-vcf`)를 제공해야 합니다. 소스가 없는 경우 스캔은 참조 서열(reference-only)로만 수행되며 결과에 해당 내용이 명시됩니다. 조상 위험은 평균값이 아닌 가장 큰 영향을 받는 인구 집단으로 보고되며, 인구 집단 및 하플로타입 경로에 동일한 운반 임계값이 적용됩니다. 추천 과정에서는 두 가지 특이성 모델(CFD 및 MIT)이 결합되어 사이트당 두 점수가 모두 기록됩니다. 실행 간 오프타겟 캐시는 참조 서열 전용 및 기본 스코어러 검색으로 안전 게이트가 설정되어 있습니다. ## 재현성 및 엔지니어링 체계 README에 문서화된 설계 결정 사항은 재현성을 강조합니다. 콘텐츠 주소 지정 결과, 분할 및 캐시(무결성 재검증 포함), 고정된 환경, 결정론적 시드, 콘텐츠 해시 체크포인트 등이 적용되었습니다. 설계상 `null` 아티팩트 해시는 다운로드를 차단합니다. 모델은 동의/라이선스/체크섬 게이트를 통해 로드됩니다. 기본 백본(Nucleotide Transformer v2 500M)은 CC-BY-NC-SA-4.0 라이선스를 따르며, 로드 시 상업적 이용이 거부되고 실제 가중치는 제공되지 않습니다. 백본을 위한 ONNX 내보내기 경로가 존재합니다. Rust/PyO3 크레이트(`aforge_native`)는 FM-index BWT 검색, k-mer 시딩, 하플로타입 워킹 및 bulged alignment와 같은 선택적 가속 커널을 제공합니다. 각 커널은 바이트 단위로 동일한 순수 Python 대체 수단과 패리티 테스트를 갖추고 있어, 크레이트 없이도 라이브러리 설치 및 실행이 가능합니다. 특히 벤치마킹 결과, FM-index 및 k-mer 시드 프리필터가 전체 스캔 수준에서 비용 증가로 측정되었기에 기본값이 아닌 선택 사항으로 남겨두었습니다. ## 벤치마크 및 상태 공개 벤치마크인 CRISPR-Bench는 작업, 고정된 분할, 메트릭, 러너 및 리더보드를 제공합니다. 보정/일반화 연구 스크립트는 작업별 ECE, 세포 유형 간 일반화 격차 및 재보정 보고서를 재생성합니다. 재현 가능한 SVG 수치는 종속성 없는 렌더러에 의해 생성됩니다. v0.1.0 로드맵의 15개 단계(코어 타입, 게놈 액세스, 데이터 레지스트리, 변이 리졸버, 오프타겟 엔진, 스코어링/모델 주, 세 가지 화학 방식, 디자이너, 보고, CLI, 웹, 벤치마크, 문서)가 모두 완료되었습니다. v1.0을 향한 v0.1.0 이후 단계로는 실제 아티팩트 해시 고정 및 검증/보정 연구 등이 진행 중이거나 시작 전으로 나열되어 있습니다. ## 설치 구조 코어 설치는 의도적으로 가볍게 구성되었으며(타입 지정 모델, 설정, 모델 카드 파싱), `core`, `genome`, `variant`, `cli`, `web`, `ml`, `cas9-rs3`, `docs`, `dev`를 위한 선택적 추가 옵션을 제공합니다. Python 3.11 이상이 필요합니다. `variant` 옵션은 `hgvs`가 `psycopg2`에 의존하므로 PostgreSQL 클라이언트 헤더가 필요하며, README에는 이로 인해 이전에 문서화된 설치 명령어를 실행할 수 없었던 점이 명시되어 있습니다. 본 프로젝트는 의료 기기가 아닌 연구 도구이며, 오프타겟 추천은 계산적인 결과이므로 반드시 실험적으로 검증되어야 함을 분명히 밝힙니다.