AI 튜토리얼

Python으로 DHIS2 예방접종 데이터를 감사하고 예측하기

월별 DHIS2 예방접종 데이터를 감사하고, 누락된 보고서를 추정하며, 반복되거나 뒤바뀐 값을 식별하고, 미래 정보 누수 없이 계절 나이브, SARIMA, 그래디언트 부스팅 예측을 비교하는 Python 및 Jupyter 워크플로를 실행하는 방법을 알아보세요.

2026년 9월 29일약 15분 소요

이 프로젝트가 하는 일

이 프로젝트는 DHIS2에서 월별 예방접종 데이터를 추출하고, 감사하고, 보완하고, 예측하는 엔드투엔드 워크플로를 제공합니다. 2021년 9월부터 2026년 8월까지 완료된 60개월 동안 13개 지구에서 보고된 홍역, BCG, OPV1 접종 데이터를 사용합니다.

포함된 데이터셋은 버전 2.43.1을 실행하는 공개 DHIS2 데모 인스턴스에서 가져왔습니다. 샘플 데이터이며 개인 정보나 직장 정보는 포함하지 않습니다. 따라서 결과는 분석 방법과 데이터 품질 문제를 보여 주기 위한 것이며, 실제 보건 추세에 관한 결과로 해석해서는 안 됩니다.

워크플로는 네 가지 주요 단계로 구성됩니다.

DHIS2 분석 API를 통해 집계된 월별 데이터를 가져오거나 저장된 CSV 스냅샷을 불러옵니다.
보고 완전성, 전년 대비 반복, 큰 변동, 인접 월의 교체 가능성을 감사합니다.
모델 학습을 위해 결측값을 추정하되, 추정값임을 식별하는 플래그는 유지합니다.
예측 모델이 전년도 값을 반복하는 계절 기준선보다 성능이 좋은지 검증합니다.

주요 기능

DHIS2 API 추출: pull_dhis2_data.py의 함수가 필요한 지표를 찾고 가져옵니다.
오프라인 재현성: 노트북은 기본적으로 dhis2_raw_data.csv를 읽으므로 인터넷 연결이나 로그인이 없어도 실행할 수 있습니다.
완전성 감사: 각 지표에 지구와 월별로 하나의 값이 있는지 확인합니다.
반복 감지: 지구의 값이 1년 전 같은 달의 값과 정확히 일치하는 빈도를 측정합니다.
교체 감지: 전년도의 순서와 반대로 나타나는 인접 월의 값을 표시합니다.
구조화된 결측값 보완: 다른 연도의 같은 달 값 또는 지구 수준 및 지구 간 계절성을 사용해 결측값을 추정합니다.
누수 방지 예측: 학습과 테스트를 시간순으로 분리하고, 학습 구간의 결측값은 학습 데이터만 사용해 보완합니다.
모델 비교: 계절 순진 모델, SARIMA, 그래디언트 부스팅을 MAE와 WAPE로 평가합니다.

프로젝트 파일 이해하기

DHIS2_Immunisation_Audit_and_Forecast.ipynb: 차트, 감사 로직, 결측값 보완, 예측을 포함한 전체 분석입니다.
pull_dhis2_data.py: 지표를 찾고 DHIS2에서 데이터를 가져오는 함수입니다.
dhis2_raw_data.csv: 기본 오프라인 실행에 사용하는 저장된 스냅샷입니다.
requirements.txt: Python 패키지 종속 항목입니다.
README.md: 프로젝트 문서와 요약된 결과입니다.

설치 및 설정

1. 저장소 받기

저장소를 복제하거나 다운로드한 다음 루트 디렉터리에서 터미널을 엽니다. 프로젝트 패키지가 다른 Python 프로젝트와 격리되도록 가상 환경을 사용하는 것이 좋습니다.

python -m venv .venv

운영 체제에 맞는 명령으로 환경을 활성화한 다음 필요한 패키지를 설치합니다.

pip install -r requirements.txt

2. Jupyter Notebook 시작

jupyter notebook DHIS2_Immunisation_Audit_and_Forecast.ipynb

노트북 셀을 위에서 아래 순서로 실행합니다. 기본적으로 분석은 dhis2_raw_data.csv를 불러옵니다. 네트워크 연결이나 DHIS2 인증 정보가 필요하지 않으므로 워크플로를 살펴보는 가장 간단하고 재현성 높은 방법입니다.

3. 선택적으로 실시간 DHIS2 액세스 설정

최신 데이터를 가져오려면 노트북의 첫 번째 코드 셀에서 REFRESH = True로 설정합니다. 서버 주소와 로그인 정보는 DHIS2_URL, DHIS2_USER, DHIS2_PASSWORD 환경 변수로 제공할 수 있습니다.

DHIS2_URL=https://your-dhis2-server.example
DHIS2_USER=your_username
DHIS2_PASSWORD=your_password

환경 변수 설정의 정확한 문법은 셸과 운영 체제에 따라 다릅니다. 인증 정보를 환경 변수에 보관하면 노트북에 포함되거나 소스 관리 시스템에 커밋되는 것을 방지할 수 있습니다.

데이터 소유자의 승인을 받은 경우에만 실시간 DHIS2 인스턴스에 연결하십시오. 비식별 집계 데이터를 사용하고 조직의 보안 및 거버넌스 요구 사항을 따르십시오.

기본 워크플로 실행

1단계: 월별 데이터 불러오기 또는 가져오기

각 행은 하나의 지표, 하나의 지구, 하나의 월을 나타냅니다. 전체 분석은 각 예방접종 지표에 대해 13개 지구와 60개월을 사용합니다. 홍역은 감사와 예측 단계 모두에 포함되며, BCG와 OPV1은 감사 대상입니다. ANC 지표는 20개월만 제공되어 이 워크플로에서 연간 패턴을 연구하기에 너무 짧으므로 제외합니다.

REFRESH = False인 경우 노트북은 저장된 스냅샷을 읽습니다. REFRESH = True인 경우 API 도우미 함수를 사용해 설정된 서버에서 최신 결과를 가져옵니다.

2단계: 보고 완전성 확인

각 지표의 예상 관측값 수는 다음과 같이 계산합니다.

13개 지구 × 60개월 = 780개 지구-월

샘플에는 예방접종 지표별로 725개의 보고값이 있으며, 55개의 결측값, 즉 7.1%가 남습니다. 결측은 무작위라기보다 매우 구조적인 양상을 보입니다.

모든 결측은 10월, 11월 또는 12월에 발생합니다.
2021년부터 2025년까지 매년 11개의 값이 누락되어 있습니다.
영향을 받은 지구는 Pujehun, Bonthe, Koinadugu, Kono, Bombali, Port Loko입니다.
Pujehun은 이용 가능한 모든 연도에서 10월부터 12월까지 보고값이 없습니다.
2026년에는 누락된 값이 없습니다.

보고된 지역만 합산하면 국가 전체 합계가 인위적으로 낮아 보이기 때문에 이 점이 중요합니다. 영향을 받은 15개월 동안 보정하지 않은 합계는 평균 14.3%, 최대 17.1% 과소 집계됩니다.

3단계: 전년 동월의 정확한 반복 감지

이 노트북은 각 지역-월 데이터를 12개월 전의 해당 월과 비교합니다. 정확히 일치하는 경우는 자연스럽게 발생할 수 있지만, 실제 월별 보건 집계에서 이러한 반복이 광범위하게 나타나는 경우는 드뭅니다.

예시 데이터에서 2024년 홍역 지역-월 데이터의 65.5%, 2025년의 92.4%, 2026년 1월부터 8월까지의 71.2%가 전년 동월과 정확히 일치합니다. BCG와 OPV1도 거의 같은 패턴을 보입니다.

이 패턴은 해석에 중요합니다. 이는 템플릿에서 생성되거나 복사된 샘플 데이터와 유사하며, 지난해 값을 기반으로 예측하는 기준 모델에 이례적으로 큰 이점을 제공합니다.

4단계: 큰 변동 및 월 순서 교체 가능성 검토

전년 대비 큰 변동은 유용한 경고 신호이지만, 자동으로 오류를 의미하지는 않습니다. 이 노트북은 전년 대비 두 인접 값의 위치가 서로 바뀌었는지도 확인합니다.

2024년 3월과 4월, 2024년 10월과 11월, 2026년 3월과 4월에 순서가 바뀌었을 가능성이 나타납니다. 예를 들어 포트 로코에는 3월과 4월에 535와 313이라는 값이 있으며, 연도별로 그 순서가 바뀝니다. 이러한 순서 교체는 두 달에 큰 오차를 만들지만, 두 달을 합한 총합은 변하지 않습니다.

이 워크플로는 순서가 바뀌었을 가능성을 표시하지만 수정하지는 않습니다. 데이터만으로는 어느 순서가 올바른지 확인할 수 없으므로, 변경하기 전에 원본 보고서를 확인해야 합니다.

5단계: 학습 데이터의 누락값 채우기

이 프로젝트는 2단계 방법으로 각 누락 구간을 채웁니다.

해당 지역이 다른 연도에 같은 달을 보고했다면, 이용 가능한 값들의 평균을 사용합니다.
해당 지역이 그 달을 한 번도 보고하지 않았다면, 해당 지역의 평균 수준에 모든 지역에서 관찰된 그 달의 일반적인 계절 패턴을 곱해 추정합니다.

두 번째 방법은 이용 가능한 모든 연도에서 10월부터 12월까지의 값이 누락된 푸제훈과 같은 경우에 필요합니다.

이 방법을 확인하기 위해 분석에서는 알려진 10월부터 12월까지의 값 중 15%를 숨긴 뒤 이를 채우고, 추정값을 실제 관측값과 비교합니다. 숨긴 21개 값에서 평균 오차는 8.2%, 중앙값 오차는 7.9%였습니다. 이는 소규모 검증 표본에 불과하므로, 이 수치는 확정적인 정확도 추정치가 아니라 대략적인 참고값으로 보아야 합니다.

추정값은 관측값으로 취급하지 않습니다. 추정값은 모델 학습 데이터와 시차 특성을 구성하는 데만 사용됩니다. 누락된 테스트 관측값은 채우지 않고 평가에서 제외합니다.

홍역 접종량 예측

시간순 학습-테스트 분할 사용

예측의 목적은 각 지역의 향후 12개월 홍역 접종량을 지난해 값을 반복하는 것보다 정확하게 예측할 수 있는지 확인하는 것입니다.

학습 기간: 2021년 9월부터 2025년 8월까지, 총 48개월.
테스트 기간: 2025년 9월부터 2026년 8월까지, 총 12개월.
평가 대상 관측값: 보고된 테스트 값 145개.

무작위로 분할하면 미래 관측값이 이전 달의 예측에 영향을 줄 수 있습니다. 시간 기반 분할은 이러한 정보 누수를 방지합니다. 학습 데이터의 누락값은 학습 기간의 정보만 사용해 채우며, 2025년 10월부터 12월까지 보고되지 않은 테스트 값은 평가에서 제외합니다.

세 가지 모델 비교

계절 단순 기준 모델: 1년 전 같은 달에 관측된 값을 예측값으로 사용합니다.
SARIMA: 각 지역에 대해 SARIMA(0,1,1)(0,1,1,12)를 별도로 적합합니다. 이 설정은 테스트 결과를 보기 전에 선택했으며 조정하지 않았습니다.
그래디언트 부스팅: 12개월 전과 24개월 전의 값, 달, 지역을 사용해 모든 지역에 하나의 공유 모델을 학습합니다. 지역별 평균에 따라 값을 조정하므로 규모가 다른 지역도 하나의 모델에서 함께 사용할 수 있습니다.

그래디언트 부스팅 특성은 최소 12개월 전의 관측값만 사용합니다. 이는 향후 12개월 전체를 예측할 때 이용 가능한 정보를 반영합니다.

MAE와 WAPE 해석

이 노트북은 두 가지 평가 지표를 보고합니다.

MAE: 지역-월별 접종량의 평균 절대 오차입니다.
WAPE: 총 절대 오차를 실제 접종량 총합으로 나눈 값입니다. 예를 들어 0.036은 3.6% 오차를 의미합니다.

계절 단순 기준 모델의 MAE는 16.1, WAPE는 3.6%입니다. SARIMA의 MAE는 30.0, WAPE는 6.6%이며, 그래디언트 부스팅의 MAE는 32.9, WAPE는 7.3%입니다.

2026년 3월과 4월을 제외하면 계절 단순 기준 모델의 WAPE는 0.8%로 낮아집니다. SARIMA는 5.4%, 그래디언트 부스팅은 5.7%입니다. 따라서 기준 모델의 오차 대부분은 명백해 보이는 3월과 4월의 순서 교체에서 발생합니다.

단순한 기준 모델이 우수한 이유

테스트 기간의 대부분 값이 전년 동월의 값을 정확히 복사한 것이기 때문에 계절 단순 방식의 성능이 가장 좋습니다. 이러한 조건에서는 지난해 관측값을 반복하는 모델이 거의 완벽하게 작동합니다.

반면 SARIMA와 그래디언트 부스팅은 4개의 연간 주기만으로 더 광범위한 패턴을 추정합니다. 이 모델들은 시계열을 평활화하므로, 정확히 복사된 값을 안정적으로 재현하지 못합니다. 또한 이전 관측값만으로는 인접 월의 순서 교체를 예측할 수 없습니다.

이 결과가 계절 단순 예측이 일반적으로 우수하다는 것을 입증하는 것은 아닙니다. 이는 이 데모 데이터셋의 특이한 구조를 반영합니다. 실제 데이터에서 연도별 변동이 발생한다면, 더 정교한 모델이 기준 모델보다 개선될 의미 있는 가능성이 생깁니다.

워크플로 조정을 위한 고급 팁

관측값과 추정값을 구분해 유지하기

입력된 모든 관측값에 대해 명시적인 플래그를 추가하거나 유지하세요. 완전한 학습 시계열이 기술적으로 필요한 경우 추정값을 사용하되, 이를 보고된 값인 것처럼 암묵적으로 표시하지 마세요. 점수 산정은 실제로 보고된 관측값을 기준으로 유지해야 합니다.

이상을 자동으로 수정하지 말고 조사하기

보고 누락, 반복 값, 큰 변동, 월 데이터가 뒤바뀌었을 가능성에는 서로 다른 대응이 필요합니다. 모델링을 위해 누락값을 추정할 수는 있지만, 월이 바뀐 것으로 보이는 경우에는 원본 문서와 대조해 확인해야 합니다. 자동 수정은 눈에 보이는 경고를 숨겨진 오류로 바꿀 수 있습니다.

롤링 오리진 평가 사용하기

이 저장소에서는 12개월 테스트 기간 하나를 사용합니다. 더 견고하게 평가하려면 여러 시간순 기간에 걸쳐 평가를 반복하세요. 각 실행에서는 예측 기간 이전에 사용할 수 있었던 데이터만으로 학습해야 합니다. 이를 통해 모델 성능이 시간에 따라 안정적인지, 아니면 특정한 이례적 연도 하나에 좌우되는지 확인할 수 있습니다.

복잡한 모델은 항상 벤치마크하기

튜닝된 SARIMA 모델, 새로운 특성 또는 다른 머신러닝 알고리즘을 추가하더라도 계절 나이브 예측을 유지하세요. 복잡한 방법은 관측에 사용되지 않은 기간에서 단순하면서 운영상 신뢰할 수 있는 기준 모델을 일관되게 능가할 때만 유용합니다.

실제 데이터를 다룰 때는 불확실성 추가하기

제안된 다음 단계에는 예측 구간 추가가 포함됩니다. 점 예측만으로는 정상적인 변동, 제한된 과거 데이터 또는 추정된 학습 공백에서 비롯되는 불확실성을 전달할 수 없습니다.

반복 감사를 자동화하기

동일한 검사를 각 보고 주기 후에 실행하도록 예약할 수 있습니다. 반복 프로세스를 통해 새로 누락된 지역-월 조합, 예상치 못한 전년 대비 반복, 큰 변동, 검토가 필요한 월 데이터 교체 의심 사례를 보고할 수 있습니다.

다른 지표로 확장할 때는 신중하기

다른 지표를 예측하기 전에 계절 주기를 분석할 수 있을 만큼 충분한 과거 데이터가 있는지 확인하세요. 사용 가능한 ANC 지표는 2025년 1월부터 시작하는 20개월의 데이터만 포함하므로, 이 프로젝트에서는 연간 패턴을 분석하는 데 이를 사용하지 않습니다.

중요한 제한 사항

출처가 데모 서버이므로 이 분석은 실제 예방접종 추세에 대해 아무것도 말해 주지 않습니다.
예측 비교는 단일 12개월 테스트 기간을 사용합니다.
Measles만 예측합니다.
SARIMA 구성은 튜닝하지 않고 고정되어 있습니다.
공백 채우기 검증에는 숨긴 관측값이 21개뿐입니다.
Pujehun의 10월~12월 추정값은 다른 지역의 계절 패턴에 의존합니다.
월 데이터 교체 의심 사례는 표시하지만 수정하지 않습니다.

결론

이 프로젝트는 예측에 앞서 데이터 품질 감사를 수행해야 한다는 점을 보여 줍니다. 검사 결과 구조적인 누락, 광범위한 전년 대비 반복, 인접 월 데이터가 뒤바뀌었을 가능성이 드러나며, 이는 합계와 모델 평가에 큰 영향을 미칩니다.

먼저 저장된 스냅샷에 대해 노트북을 실행하고 각 감사 단계를 점검한 다음, 승인된 DHIS2 출처를 사용할 준비가 되었을 때만 API 새로 고침을 활성화하세요. 워크플로를 조정할 때는 시간순 평가를 유지하고, 추정값에 라벨을 지정하며, 원본 보고서와 대조해 이상을 확인하고, 모든 모델을 간단한 계절 기준 모델과 비교하세요.