# MASHBiospecimenCoC-Kor (매시바이오스페시먼체인코어)

MASH 임상시험 검체(liver biopsy block · 혈액 NIT: ELF · PRO-C3 · FibroScan-VCTE)의
**chain-of-custody & central lab 물류 추적기** (standalone Streamlit).

- **도메인**: MASLD (Metabolic dysfunction-Associated Steatotic Liver Disease / MASH)
- **카테고리**: 인체실험 도구 (임상시험 운영 물류)
- **기술스택**: Python + Streamlit + pandas + plotly (+ numpy)

> ⚠️ **디스클레이머**: 본 도구는 연구·운영 보조용 참고 도구이며 실제 임상시험 규제 의사결정을 대체하지 않습니다.
> 표시되는 데이터는 전부 합성(데모) 또는 사용자가 업로드한 데이터이며, 외부 네트워크/API 호출은 일절 없습니다(오프라인).

---

## 핵심 기능 5개

1. **검체 schedule window 준수 추적** — 환자별 visit별(Baseline·Week24·Week52) biopsy·ELF·PRO-C3·VCTE
   채취 due/완료/window 위반 alert. due 도래 검체 대비 채취율, missed, window 위반 집계 및 alert 목록 다운로드.
2. **chain-of-custody 원장** — 채취(collection) → site 보관(site_storage) → shipment(dispatch) →
   central lab 인수(central_receipt) 각 단계의 timestamp·담당자·온도 기록(GCP/GLP 사슬).
   검체별 사슬 완전성(누락 단계) 검증. (VCTE는 영상 결과로 collection 1단계만으로 완전.)
3. **cold-chain shipment QC** — IATA PI650 개념 기반 운송 조건·온도일탈(temp excursion)·용혈(hemolysis)/
   integrity reject 사유 분류 및 재채취(recollection) trigger.
4. **central pathology turnaround** — block 접수→판독 완료 turnaround(목표 ≤14일)·적체(backlog/pending)·재판독(reread) 추적.
5. **block 재고·재채취 대장** — 잔여 block 슬라이드(residual sections)·재채취 필요 환자 대장·
   evaluable 손실 위험 환자 list (1차 조직학 종결점 LiverBiopsy 관점).

---

## 실행법

```bash
pip install -r requirements.txt
streamlit run app.py
```

- CSV 업로드 없이도 합성 데모 데이터로 **즉시 시연 가능**.
- 사이드바에서 `specimen_manifest.csv` / `custody_log.csv` / `shipment_log.csv` /
  `pathology_turnaround.csv` 를 업로드하면 해당 데이터셋만 교체됩니다.
- plotly 미설치 환경에서도 앱은 동작하며, 차트는 Streamlit 기본 차트로 자동 대체됩니다.

### 데모 데이터 재생성

```bash
cd data && python3 generate_demo_data.py
```

numpy 시드(20260531) 고정으로 항상 동일한 합성 데이터가 생성됩니다.

### 단위 테스트

```bash
python3 test_logic.py
```

---

## 데이터 소스 / 파일 구조

```
2026-05-31-3-mashbiospecimencoc-kor/
├── app.py                 # Streamlit 진입점 (5개 기능 탭)
├── logic.py               # 순수 로직(window/custody/QC/TAT/재고) — streamlit 비의존, 테스트 가능
├── test_logic.py          # 순수 로직 단위 테스트
├── requirements.txt       # pinned 버전
├── README.md
├── QA.md                  # 검수 로그
└── data/
    ├── generate_demo_data.py  # 합성 데모 데이터 생성 스크립트(시드 고정)
    ├── visit_schedule.csv     # MASH 시험 typical visit schedule window 참조
    ├── specimen_manifest.csv  # 환자별·visit별·검체별 due/완료/window
    ├── custody_log.csv        # chain-of-custody 단계별 timestamp/담당자/온도
    ├── shipment_log.csv       # cold-chain 운송 QC
    └── pathology_turnaround.csv # central pathology 접수→판독 turnaround
```

### 데이터 컬럼 요약

- **specimen_manifest.csv**: patient_id, site_id, visit, specimen_type, target_due_date,
  window_start, window_end, collected_date, status(scheduled/collected/missed/discontinued), window_violation
- **custody_log.csv**: specimen_uid, patient_id, site_id, specimen_type, step, timestamp, handler, temp_c, location, notes
- **shipment_log.csv**: shipment_id, specimen_uid, courier, dispatch/central_receipt timestamp, transit_hours,
  target_temp_range_c, max_temp_observed_c, temp_excursion, iata_pi650_compliant, qc_result, reject_reason, recollection_triggered
- **pathology_turnaround.csv**: block_id, specimen_uid, central_receipt_date, read_complete_date, turnaround_days,
  read_status(read_complete/pending), target_tat_days, tat_breach, reread_required, residual_sections

---

## 검수 체크리스트

- [x] `python3 -c "import ast; ast.parse(open('app.py').read())"` 구문 OK
- [x] `data/generate_demo_data.py` 실행 → 5개 CSV 생성
- [x] 합성 CSV가 pandas로 로드됨 (manifest 440×10, custody 1075×10, shipment 245×16, pathology 51×12, schedule 3×4)
- [x] requirements: streamlit/pandas/numpy import 확인, plotly는 명시(미설치 환경에서도 fallback 동작)
- [x] window 준수·turnaround 등 순수 로직 함수 단위 테스트 통과 (`test_logic.py`)
- [x] 디스클레이머가 app.py UI 상단/하단 및 README에 포함
- [x] 외부 네트워크/API 호출 없음 (전부 합성/사용자 입력)

---

## 출처 / 참조 표준 (개념 차용)

- **IATA Packing Instruction 650 (PI650)** — UN3373 Biological Substance Category B 검체 운송 포장·라벨 규정 개념.
- **ICH E6(R2/R3) GCP** — 임상시험 검체 chain-of-custody(채취·보관·이송·인수 추적 가능성) 원칙.
- **MASH phase 2/3 시험 typical visit schedule** — liver biopsy(baseline/wk52), 혈액 NIT(ELF·PRO-C3) 및 VCTE(baseline/wk24/wk52)
  채취 시점 및 window 개념 (예: REGENERATE, MAESTRO-NASH 등 공개 프로토콜에서 일반적으로 사용되는 schedule 패턴을 합성에 참고).

본 참조는 도구의 합성 데이터 구조와 판정 로직 설계를 위한 **개념적 차용**이며, 특정 규정의 정확한 수치 준수를 보증하지 않습니다.
실제 운영 시 해당 시험의 승인된 프로토콜·랩 매뉴얼·규제 문서를 따라야 합니다.