# DMAESentinel-Kor (디엠에이이센티넬코어)

한국 당뇨 약물 post-marketing AE / safety signal disproportionality 알림 도구.

## 1. 목적 / 도메인 / 카테고리

- 도메인: DM (당뇨병)
- 카테고리: 연구 알림 (post-marketing safety signal curation)
- 대상 사용자: 내분비내과 임상의, 약물안전관리실, 의약품안전관리원 / MFDS 신고담당, 약물역학 연구자
- 목표:
  - 다중 source(FAERS / EudraVigilance / VigiBase / KAERS / 사이트 cohort / PubMed case report / 학회 abstract)에서 한국 당뇨 약물 관련 AE를 통합한다.
  - ROR / PRR / IC(BCPNN) / EBGM 등 disproportionality 통계를 자동 산출한다.
  - cross-source 동시 검출 시 우선 큐로 올리고, 한국어 weekly safety digest를 생성한다.
  - 식약처 PSUR Form 1/2/3 한국어 자동 초안을 출력한다.
  - cross-discipline 알림(NAION → 안과, suicidal ideation → 정신과, sarcopenia → 재활의학 등)을 시뮬레이션한다.

## 2. 설치

- Python 3.11 이상.
- 표준 라이브러리만 사용한다(stdlib: `argparse`, `csv`, `json`, `math`, `sqlite3`, `pathlib`, `random`, `datetime`).
- 외부 패키지 설치 불필요. (pandas/numpy 의존성 제거)
- 외부 네트워크 호출 없음. 모든 데이터는 합성(synthetic).

```bash
# 별도 설치 없음. 확인만:
python3 --version
```

## 3. 실행법

```bash
# 0) 도움말
python3 main.py --help

# 1) 합성 데이터 적재 (data/ 생성 + dmae_sentinel.db 빌드)
python3 main.py ingest                 # 모든 source 적재
python3 main.py ingest --source faers  # 단일 source 한정도 가능

# 2) Disproportionality 산출 (ROR/PRR/IC/EBGM)
python3 main.py analyze --top 20
python3 main.py analyze --drug semaglutide
python3 main.py analyze --threshold 3.0

# 3) 한국어 weekly safety digest
python3 main.py digest --korean

# 4) 식약처(MFDS) PSUR Form 1/2/3 자동 초안
python3 main.py psur --drug empagliflozin
python3 main.py psur --drug semaglutide
python3 main.py psur --drug finerenone

# 5) cross-source / cross-discipline alert
python3 main.py alert
python3 main.py alert --cross-discipline
```

## 4. 데이터 출처

본 MVP는 모두 **합성(synthetic) 데이터**를 사용하며, 어떤 외부 API도 호출하지 않는다. 실제 운영 시 연동을 가정한 출처는 다음과 같다(모두 공개 또는 학술/규제 무료):

| 약자 | 명칭 | 비고 |
|---|---|---|
| FAERS | FDA Adverse Event Reporting System | 분기별 quarterly file 공개 |
| EudraVigilance | EU pharmacovigilance database | EMA 공개 line listings |
| VigiBase | WHO global pharmacovigilance | UMC, 학술 access |
| KAERS | 한국의약품안전관리원 의약품이상사례보고시스템 | 한국 자발보고 |
| 사이트 cohort | 자체 처방 cohort | EMR/EDW 추출 가정 |
| PubMed | E-utilities | case report metadata |
| ADA/EASD/KDA/ATTD | 학회 abstract | 매년 공개 |

## 5. 알고리즘 / 통계

- 2x2 표 (a=drug+AE, b=other+AE, c=drug+otherAE, d=other+otherAE)
- 0 셀에 Haldane–Anscombe 보정 (+0.5).
- ROR = (a·d) / (b·c), 95% CI = exp(ln(ROR) ± 1.96·√(1/a+1/b+1/c+1/d))
- PRR = (a/(a+c)) / (b/(b+d))
- IC(BCPNN 근사) = log2((a+0.5) / (E+0.5)), E = (a+b)(a+c)/N
- EBGM ≈ 2^IC (단순 근사, MGPS의 정식 EB shrinkage는 별도 구현 필요)
- 시그널 기준: ROR ≥ 2.0, n ≥ 3, lower 95% CI ≥ 1
- cross-source 우선순위: signal이 ≥ 2 source에서 동시에 양성

## 6. 구조

```
2026-05-07-1-dm-ae-sentinel-kor/
├── main.py
├── README.md
├── QA.md
├── CHANGELOG.md
├── dmae_sentinel.db        (ingest 후 생성)
└── data/
    ├── faers_synthetic.csv
    ├── eudra_synthetic.csv
    ├── vigibase_synthetic.csv
    ├── kaers_synthetic.csv
    ├── site_cohort_synthetic.csv
    ├── pubmed_case_reports_synthetic.json
    ├── abstract_synthetic.json
    ├── meddra_korean_terms.csv
    └── kfda_drug_codes.csv
```

## 7. 검수 체크리스트

QA.md 참조. 자동 검수:

```bash
python3 -c "import ast; ast.parse(open('main.py').read())"   # 구문 OK
python3 main.py --help
python3 main.py ingest
python3 main.py analyze --top 5
python3 main.py digest --korean
python3 main.py psur --drug empagliflozin
python3 main.py alert --cross-discipline
```

## 8. 의학적 디스클레이머

- 본 도구는 **연구·참고용**이다. 임상 의사결정의 단독 근거로 사용하지 말 것.
- Disproportionality 통계(ROR/PRR/IC/EBGM)는 spontaneous reporting bias, Weber 효과, notoriety bias 등이 큰 영향을 준다. 시그널은 "가설 생성"이지 "인과 증명"이 아니다.
- 한국 외삽 호환성 점수는 단순 BMI/연령 기반 mock score이며, 실제 한국 데이터 외삽 시에는 PK/PD, 다인종 상호작용, 한국인 알릴 빈도 등을 별도 평가해야 한다.
- 실제 식약처 PSUR 제출 전 식약처/한국의약품안전관리원/약물역학팀 검토 필요.

## 9. 한계 / 노트

- 모든 데이터는 합성. 실제 분포·signal과 다르다.
- 외부 API 미호출(요구사항). FAERS quarterly ZIP, KAERS API, PubMed E-utilities 연동은 후속 작업.
- 연도(year) stratification, 계열(class) effect, indication 보정, drug-drug 동시노출 보정은 단순화되어 있다.
- EBGM은 정식 MGPS Empirical Bayes shrinkage가 아닌 IC 기반 근사.
- 한국어 약물명/AE 매핑은 ~20 약물, ~16 AE에 한정. 본격 운영 시 KIMS/MedDRA Korean 라이선스 매핑 필요.
- manuals/ 폴더가 사용자 환경에 존재하지 않아 글로벌 워크플로우 규칙 1번(매뉴얼 확인)은 "관련 매뉴얼 없음"으로 진행했다.

## 10. 의문점 자율 처리 노트

- "한국어 PDF report" 요건: 외부 라이브러리 금지로 PDF 생성기 의존 곤란. 대신 한국어 텍스트 리포트(`digest --korean`, `psur`)를 출력하고 향후 reportlab/wkhtmltopdf 추가로 전환 가능하도록 함수 분리.
- pandas/numpy도 결과적으로 사용하지 않고 stdlib만으로 구현 → 환경 portability 극대화.
- "사이트 자체 cohort denominator"는 BMI/연령/한국 외삽 점수까지만 표기, 실제 IRR은 source별 sponsor 데이터 부족으로 보류.