161 lines
8.4 KiB
Markdown
161 lines
8.4 KiB
Markdown
# 🌤️ 기상청 3차원 객관분석 기상 데이터 추출 및 바람 벡터 검증 시스템
|
|
> **KMA 3D Objective Analysis Grid Data Extraction & Wind Vector Verification System**
|
|
|
|
본 프로젝트는 기상청(KMA)의 수치 객관분석 시스템(NetCDF 격자 자료)과 지상 기상 실측 API 데이터를 유기적으로 연계하여, 특정 타겟 위·경도에 대해 정밀한 5분 간격 기상 데이터를 추출하고 바람 벡터 데이터(U, V 성분)의 일관성 및 정합성을 수학적·과학적으로 검증 및 시각화하는 시스템입니다.
|
|
|
|
---
|
|
|
|
## 📂 디렉토리 구조 및 파일 역할
|
|
```text
|
|
weather-api/
|
|
│
|
|
├── .gitignore # Git 저장소 등록 제외 패턴 설정 (venv, .env, *.csv, *.png)
|
|
├── .env.example # API 인증키 환경변수 설정 예시 파일
|
|
├── requirements.txt # 프로젝트 실행에 필요한 의존성 라이브러리 목록
|
|
│
|
|
├── PROJECT_INFO.md # 프로젝트의 핵심 가치, 연구 배경 및 주요 결론 요약
|
|
├── README.md # 본 파일 (전체 상세 사용 가이드)
|
|
│
|
|
# [1] 데이터 추출 및 API 연동 스크립트
|
|
├── extract_weather_data.py # 특정 관심 시점(visible-times.txt)의 전후 기상 데이터 단일 추출
|
|
├── extract_continuous_data.py # 장기(4월 1일 ~ 5월 7일) 5분 연속 데이터 순차 추출 (싱글 스레드)
|
|
├── extract_continuous_data_fast.py # ThreadPoolExecutor(스레드 5개) 기반 고속 연속 데이터 추출 및 정렬 병합
|
|
├── check_api_columns.py # KMA API 컬럼 헤더 정보 디버깅 및 확인
|
|
│
|
|
# [2] 격자 분석 및 좌표 매핑
|
|
├── verify_grid.py # sfc_grid_latlon.nc(NetCDF) 격자망 로드 후 최인접 3x3 실제 격자 좌표 탐색
|
|
├── visualize_grid.py # 가상 500m 기상 격자점 좌표 공간 시각화 및 검증
|
|
│
|
|
# [3] 바람 벡터 정합성 분석 및 검증
|
|
├── verify_wind_vectors.py # 풍향/풍속 & U/V 성분 기상 삼각 공식 역산 및 기본 검증
|
|
├── analyze_relative_error.py # 동서(U), 남북(V) 성분별 절대/상대/벡터 총합 오차율 정량화 분석
|
|
├── analyze_ws_error.py # U, V 성분을 활용한 바람 크기(Wind Speed) 역산 및 오차 검증
|
|
│
|
|
# [4] 데이터 시각화
|
|
├── plot_weather_data.py # 2중 축(기온·이슬점 vs 풍속) 시계열 그래프 생성 및 특정 타임스탬프 실선 표기
|
|
├── plot_weather_no_wind.py # 풍속 제외 기온 및 이슬점 시계열 분석 차트 생성
|
|
├── plot_weather_with_humidity.py # 기온, 이슬점 온도와 상대습도 변화를 다중 차트로 시각화
|
|
│
|
|
# [5] 원천 데이터 및 메타데이터 (설정)
|
|
├── sfc_grid_latlon.nc # 기상청 3차원 객관분석 500m 해상도 격자 위/경도 원천 파일
|
|
├── weather_data_definition.csv # 수집되는 10개 기상 관측 변수의 의미 및 단위 정의서 (핵심 메타데이터)
|
|
├── visible-times.txt # 시각화 그래프 상에 하이라이트할 핵심 관측 시점 목록
|
|
└── target-coord.txt # 분석 타겟 중심 좌표
|
|
```
|
|
|
|
---
|
|
|
|
## 📊 기상 관측 변수 상세 정의 (Weather Data Columns)
|
|
본 시스템에서 추출 및 정제하여 처리하는 기상 변수는 `weather_data_definition.csv`에 정의되어 있으며 다음과 같습니다:
|
|
|
|
| 컬럼명 (Column) | 설명 (Description) | 단위 (Unit) | 비고 (Remark) |
|
|
| :--- | :--- | :---: | :--- |
|
|
| **tm** | 관측시각 (KST) | `YYYYMMDDHHMI` | 한국 표준시 기준 |
|
|
| **ta** | 기온 | `°C` | 지상 1.5m 높이 |
|
|
| **hm** | 상대습도 | `%` | - |
|
|
| **td** | 이슬점 온도 | `°C` | - |
|
|
| **wd_10m** | 10분 평균 풍향 | `deg` | 0~360도 (북:0, 동:90, 남:180, 서:270) |
|
|
| **ws_10m** | 10분 평균 풍속 | `m/s` | - |
|
|
| **uu** | 동서 바람 성분 (U) | `m/s` | **서풍(+)**, 동풍(-) |
|
|
| **vv** | 남북 바람 성분 (V) | `m/s` | **남풍(+)**, 북풍(-) |
|
|
| **rn_ox** | 강수 유무 | `-` | 0: 무강수, 1: 강수 |
|
|
| **vs** | 시정 | `km` | 가시거리 |
|
|
|
|
---
|
|
|
|
## ⚙️ 설치 및 개발 환경 구축 (Setup & Installation)
|
|
|
|
본 프로젝트는 **Python 3.8 이상** 환경에서 정상 동작합니다.
|
|
|
|
### 1. 가상환경 구축 및 의존성 라이브러리 설치
|
|
```bash
|
|
# 프로젝트 디렉토리로 이동
|
|
cd weather-api
|
|
|
|
# 가상환경 생성 (venv)
|
|
python3 -m venv venv
|
|
|
|
# 가상환경 활성화
|
|
# Windows (cmd): venv\Scripts\activate.bat
|
|
# Windows (PowerShell): .\venv\Scripts\Activate.ps1
|
|
# Linux / macOS:
|
|
source venv/bin/activate
|
|
|
|
# 의존성 패키지 설치
|
|
pip install --upgrade pip
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
### 2. KMA API 인증키 설정 (`.env`)
|
|
기상청 API 허브(APIS) 연동을 위해 인증키 설정이 필요합니다.
|
|
프로젝트 루트 디렉토리에 `.env` 파일을 생성하고 발급받은 인증키를 입력합니다:
|
|
```bash
|
|
# .env 파일 생성 및 편집
|
|
echo "KMA_API_KEY=발급받은_기상청_인증키" > .env
|
|
```
|
|
> ⚠️ **보안 경고 (CWE-798 방지)**: `.env` 파일은 인증키를 안전하게 로컬 환경에 보관하기 위한 파일입니다. **절대로 이 파일을 Git 원격 저장소에 커밋/업로드하지 마십시오.** `.gitignore` 설정에 의해 자동 차단되지만, 항상 주의가 필요합니다.
|
|
|
|
---
|
|
|
|
## 🚀 파이프라인 실행 가이드 (Usage Pipeline)
|
|
|
|
데이터 분석과 정밀 격자 정합성 검증을 완벽하게 재현하기 위해 다음 순서로 스크립트를 실행해 주십시오.
|
|
|
|
### Step 1. 최인접 실제 기상 격자 매핑
|
|
로컬의 NetCDF 격자망 파일(`sfc_grid_latlon.nc`)을 분석하여 타겟 위·경도와 매핑되는 기상청 격자의 인덱스(`ny`, `nx`) 및 인접 3x3 격자점 좌표를 확보합니다.
|
|
```bash
|
|
python verify_grid.py
|
|
```
|
|
- **출력 결과**: 최인접 격자 좌표가 `exact_grid_points.txt`로 저장됩니다.
|
|
|
|
### Step 2. 격자 시각화 검증
|
|
격자망 공간을 가시화하여 올바른 격자점이 설정되었는지 플롯을 생성해 확인합니다.
|
|
```bash
|
|
python visualize_grid.py
|
|
```
|
|
- **출력 결과**: `grid_points_visualization.png` 생성 (중앙 좌표 빨간색 매핑)
|
|
|
|
### Step 3. 5분 연속 데이터 고속 추출
|
|
스레드 풀 기반 병렬 처리를 통해 4월 1일부터 5월 7일까지의 기상 연속 데이터를 수집합니다.
|
|
```bash
|
|
python extract_continuous_data_fast.py
|
|
```
|
|
- **출력 결과**: 대용량 통합 기상 데이터 파일 `weather_data_continuous_20260401_20260507.csv` 생성
|
|
|
|
### Step 4. 바람 벡터 정합성 분석 및 오차 규명
|
|
수집된 기상 실측 데이터의 풍향/풍속 정보와 U/V 성분 정보의 물리적/수학적 정합성을 정량 검증합니다.
|
|
```bash
|
|
# 1. 기본적인 U/V 벡터 공식 역산 및 차이 확인
|
|
python verify_wind_vectors.py
|
|
|
|
# 2. 성분별 절대, 상대오차 및 벡터 총합 오차 종합 분석
|
|
python analyze_relative_error.py
|
|
|
|
# 3. U/V 기반 풍속 역산 정밀도 분석
|
|
python analyze_ws_error.py
|
|
```
|
|
- **주요 결론**: 평균 절대 오차가 `0.05 m/s` 미만으로 산출되어, 소수점 처리 과정의 절사 오차를 제외하면 완벽하게 수학적 일관성을 가짐을 확인할 수 있습니다.
|
|
|
|
### Step 5. 기상 변화 다중 차트 시각화
|
|
추출된 데이터로부터 온도, 이슬점, 풍속 등의 시계열 추이 분석 그래프를 생성합니다. `visible-times.txt`에 정의된 핵심 타겟 시점들이 붉은색 수직 실선으로 매핑됩니다.
|
|
```bash
|
|
python plot_weather_data.py
|
|
```
|
|
- **출력 결과**: `weather_timeseries_plot.png` 이미지 생성
|
|
|
|
---
|
|
|
|
## 🧮 바람 벡터 역산 공식 (Scientific Formulas)
|
|
기상학적 바람 벡터 구성 공식은 다음과 같으며, `verify_wind_vectors.py` 등에 탑재되어 실증 검증을 수행합니다.
|
|
|
|
- **바람 벡터 성분 분해 (Decomposition)**
|
|
바람이 불어오는 방향(풍향 $\theta$)과 강도(풍속 $WS$)로부터 불어나가는 벡터 $U$(동서성분)와 $V$(남북성분)를 구합니다:
|
|
$$U = -WS \cdot \sin\left(\frac{\theta \cdot \pi}{180}\right)$$
|
|
$$V = -WS \cdot \cos\left(\frac{\theta \cdot \pi}{180}\right)$$
|
|
|
|
- **바람 벡터 합성 (Reconstruction)**
|
|
$$WS_{calc} = \sqrt{U^2 + V^2}$$
|
|
|
|
- **오차 평가 지표 (Vector Relative Error)**
|
|
$$Error_{mag} = \sqrt{(U_{calc} - U_{obs})^2 + (V_{calc} - V_{obs})^2}$$
|
|
$$Error_{rel} = \frac{Error_{mag}}{WS_{obs}}$$
|