# 19-1 희귀질환 판독 연구

가상 VCF 주석, HPO 표현형 순위, ACMG 근거 검사를 한 흐름에 묶고, 감사기가 독자적으로 결과를 대조한다. 기준을 통과할 때의 결과는 가상 입출력 재현 검증이다. 실제 환자 진단, 질환 유발 변이 분류 또는 공고 이행 여부는 이 시험 범위에 포함하지 않는다.

## 실행

프로젝트 루트에서 Python 3.10 이상으로 실행한다. 외부 패키지는 필요 없다.

```sh
rare_work="$(mktemp -d)"
python3 -B -m rare19.orchestrate --output "$rare_work/run.json"
python3 -B -m rare19.audit --run "$rare_work/run.json" --output "$rare_work/audit.json"
python3 -B -m unittest discover -s tests -p 'test_rare19.py' -v
```

경로를 생략하면 JSON을 표준 출력에 한 줄로 내보낸다. 감사기에 `--run`은 필수다. 관문이 실패하면 첫 실패와 나머지 미실행 관문을 JSON에 기록하고 종료 코드 1을 반환한다. 감사 문서의 `humanAuditorSignature`는 항상 비워 둔다. `evidenceSha256`는 해당 필드만 뺀 본문을 키 정렬 UTF-8 JSON(공백 없음, 마지막 개행 없음)으로 직렬화해 계산한다.

## 역할과 네 관문

| 역할 | 입력과 책임 |
| --- | --- |
| 자료 큐레이터 | `solver.lock.json`의 고정 SHA-256과 각 공개 입력 파일의 바이트 해시를 검사한다. 참조 테이블·질환표·주석표·근거표·표현형·네 VCF의 관계를 검증한다. |
| 변이 주석 | 빌드·염색체·위치·REF·ALT 다섯 값이 모두 같을 때 가상 레지스트리의 유전자와 결과를 결합한다. 일치하지 않은 변이도 `null` 주석과 함께 보존한다. |
| 표현형 정렬 | 양성 입력 HPO와 질환 용어가 같으면 2점, 입력 용어의 조상이 질환 용어면 1점, 아니면 0점이다. 명시적으로 없다고 기록한 표현형이 질환 용어 또는 그 조상이면 항목당 2점 차감한다. 양성 입력에 이미 함의된 소견을 음성으로 기록하면 중단한다. 유전자마다 여러 질환 중 최고 점수와 동점 질환 ID를 모두 보존한다. 유전 방식·접합성·병인 확률은 계산하지 않는다. |
| ACMG 근거 제안 | 동결된 가상 레지스트리에서 관측된 변이의 기준 ID와 근거 키를 옮긴다. 자유 기술·근거 생성·임상 해석 필드를 허용하지 않는다. |
| 독립 감사 | G1에서 고정 입력과 사례 범위, G2에서 누락·중복·변이/질환·근거 키/종류·코드·공급자와 버전, G3에서 별도 정답과 상위 5위 동점 정책, G4에서 별도 HPO 계산 결과와 제출 해시를 확인한다. |

실행기는 모델 API를 호출하지 않는 결정론적 역할 분리다. 감사기는 실행기 모듈을 가져오지 않으며 HPO 점수를 별도로 계산한다. 양쪽 모두 같은 입력과 VCF 파서를 사용한다. `heldout/`은 감사기만 읽고, 실행기 파일과 `fixtures/`만 복사해도 실행 결과가 일치했다. 두 역할은 같은 파일 권한으로 동작한다.

## HPO 순위 대조

실행기는 관측 용어에서 조상을 찾고 감사기는 질환 용어에서 자기 자신과 자손을 찾는다. 따라서 `관측 P가 질환 D의 자기 자신 또는 자손`과 `질환 D가 관측 P의 자기 자신 또는 조상`은 같은 조건이다. 감사기의 `covered`는 이 조건을 만족하는 관측 항목을 한 번 세고, `exact`는 그중 정확히 같은 항목에 1점을 추가한다. 부재 용어 A의 감점은 질환에 A 자체 또는 그 자손이 하나라도 있을 때 A당 2점이다. 두 계산 모두 양성 관측의 자기 자신 또는 조상이 동시에 부재로 기록되면 중단한다.

`자식`은 양측 강직간대 발작(`HP:0002069`), `부모`는 발작(`HP:0001250`), `별개`는 전반적 발달 지연(`HP:0001263`)이다. 다음 기대값을 먼저 정하고 테스트에서 실행기와 감사기의 개별 결과에 대조했다.

| 관측 | 부재 | 질환 용어 | 기대 점수 |
| --- | --- | --- | ---: |
| 자식 | 없음 | 자식 | 2 |
| 자식 | 없음 | 부모 | 1 |
| 자식 | 없음 | 부모와 조부모 | 1 |
| 부모 | 없음 | 자식 | 0 |
| 별개 | 부모 | 자식 | −2 |
| 별개 | 부모 | 부모 | −2 |
| 별개 | 자식 | 부모 | 0 |
| 별개 | 부모 | 별개 | 2 |

동점군의 마지막 순번은 `공동 순위 + 동점 인원 − 1`이다. 공동 4위가 2건이면 마지막 순번이 5여서 두 후보 모두 인정한다. 공동 4위가 3건이면 마지막 순번이 6이어서 세 후보 모두 상위 5위 성공으로 세지 않는다. 순위가 같은 후보의 표시 순서는 유전자 ID로 정한다.

| 고정 사례 | 별도 정답 유전자 | 점수 및 정답 순번 | 상위 5위 결과 |
| --- | --- | --- | --- |
| SIM-01 | SYN-GENE-A | 3점, 1위. 별개 후보 5개의 공동 3위 묶음은 7번째까지 이어진다. | 성공 |
| SIM-02 | SYN-GENE-F | 2점, 1위. 3개 후보 중 단독 최고점이다. | 성공 |
| SIM-03 | SYN-GENE-E | 0점, 공동 2위 6개 후보 중 하나다. 묶음은 7번째에서 끝난다. | 미탐 |
| SIM-04 | SYN-GENE-E | 관측 VCF에서 일치하는 후보는 C와 D다. E는 후보에 없다. | 미탐 |

## 가상 ACMG 근거 확인

스냅숏 검증은 `evidence.json`의 각 `variantKey`를 주석표에, `diseaseId`를 질환표에 찾고 두 행의 유전자가 같은지 확인한다. 예를 들어 `SYN-EV-01`의 `GRCh38:1:101:A:G`와 `SYN-DIS-A1`은 모두 `SYN-GENE-A`에 속한다. 같은 위치의 미주석 ALT `T`와 `SYN-GENE-B` 질환으로 바꾼 두 경우를 각각 반려하는 시험이 있다. 가상 근거 레지스트리

등록 공급자는 `APOSTOLUS-MOCK-ACMG-RECORDS`, 버전은 `fixture-1`이다. 같은 변이·질환에서 중복 코드를 허용하지 않으며, `PP3`/`BP4`와 `PS3`/`BS3`를 가상 충돌 쌍으로 각각 다룬다. 감사기는 제출된 근거 행 전체를 등록 행과 대조하고 알 수 없는 행, 누락, 중복 및 제출 필드 추가를 반려한다. 출처 버전 · 충돌 정의 · 감사 코드

## 측정값과 범위

- 독립 자동 감사 G1–G4 통과. 고정 가상 사례 4건 중 상위 5위 2건. 2건은 실패 분기를 검증하도록 넣었다. 하나는 정답 유전자가 5위를 넘는 동점군에 있고, 하나는 제출된 VCF 주석에 해당 유전자가 없다. 동점군 전체가 상위 5위에 있을 때만 점수를 준다. 첨부 계획의 ≥90% 목표는 이 수치로 판정하지 않는다.
- VCF 4.3의 사이트 행 중 합성 출처가 표시된 PASS 이중대립 단일염기 변이만 읽는다. `GRCh38`은 키 규약이며 합성 참조표는 실제 참조 FASTA를 대체하지 않는다. 환자 파일, genotype 열, 다중 대립, indel, 구조변이, 스플라이싱 추론 및 실제 변이 호출은 지원하지 않는다.
- ACMG/AMP PP3·BP4·PS3·BS3는 코드 명칭과 가상 근거 종류를 연결하는 예시다. 코드를 임상적으로 적용할 수 있는지, 근거 세기나 충돌을 실제 진료에서 어떻게 합칠지 판정하지 않는다. HPO 일치로 ACMG 코드를 부여하지 않는다.
- 해시는 고정 비교 대상과의 차이를 검출한다. 실행기와 감사기가 같은 신뢰 경계 안에 있으며 외부 타임스탬프·감사자 서명·네트워크 차단 인증으로 간주하지 않는다.

## 바이트 재현 대조

macOS `sandbox-exec`의 `(deny network*)` 프로필 아래에서 새 디렉터리로 실행기와 감사기를 다시 실행하고, 일반 실행과 두 파일의 바이트 일치를 `cmp`로 확인했다. 별도 호스트나 컨테이너 격리는 검증 범위에 포함하지 않는다.

| 결과 파일 | 바이트 SHA-256 | 본문 `evidenceSha256` |
| --- | --- | --- |
| `run.json` | `5ae7109993ea35969d4cf16248428a39867d1c0ed5b8b9041986a7ee42e57273` | `835296f37d150650c0fa67b970174b77fbdbe33eb6b7ceb1d322806a7cb00187` |
| `audit.json` | `53bca4bb94935346a04a018e9e1d0fa1d14767967e823457710e893d7e33d28c` | `8a022416f18903fd26d08cf4aad487335fe0dc42b0cebb72afae9c6435379678` |

## 확인한 원문

- 파일 헤더, 위치와 REF·ALT 정의. [GA4GH VCF 4.3 규격](https://samtools.github.io/hts-specs/VCFv4.3.pdf)
- 공식 `hp.obo`에서 12개 용어 ID와 표기, 4개 부모 관계를 대조했다. [HPO v2026-09-01](https://github.com/obophenotype/human-phenotype-ontology/releases/tag/v2026-09-01)
- 기준 코드 원문과 상세 해석 권고. [ACMG/AMP Richards 외 (2015)](https://www.acmg.net/docs/standards_guidelines_for_the_interpretation_of_sequence_variants.pdf) · [ClinGen SVI](https://clinicalgenome.org/working-groups/sequence-variant-interpretation/)