# 열차 운행 시각표 데이터 명세서 (Unified Timetable Specification)

본 문서는 `unified_timetable.parquet` 데이터 파일의 구조와 활용 방법을 설명합니다. 이 데이터는 엑셀 형태의 열차 다이아그램을 분석하여 분석 및 서비스에 적합한 세로형(Long-format) 데이터 구조로 변환된 것입니다.

## 1. 파일 정보
*   **파일 이름**: `unified_timetable.parquet`
*   **포맷**: Apache Parquet (zstd 압축)
*   **생성 시점**: 2026-02-14
*   **포함 데이터**: 평일(weekday), 주말(weekend), 공휴일(holiday) 통합 데이터

## 2. 데이터 구조 (Schema)

| 컬럼명 | 타입 | 설명 | 비고 |
| :--- | :--- | :--- | :--- |
| `line` | `int8` | 호선 정보 | 예: 1 |
| `diagram_type` | `string` | 다이어그램 종류 | `weekday`, `weekend`, `holiday` |
| `duty_id` | `int16` | 운용 번호 (DIA) | 다이아그램 상의 순번 |
| `train_number` | `int32` | 열차 번호 | 고유 열차 식별 번호 |
| `direction` | `string` | 운행 방향 | `up` (상행), `down` (하행) |
| `run_type` | `string` | 운행 타입 | `regular`, `depot_in` (입고), `depot_out` (출고) |
| `depot` | `string` | 기지/출발지 정보 | 엑셀의 '기지' 컬럼 데이터 |
| `depot_detail` | `string` | 입출고 상세 | 입출고 시의 상세 텍스트 |
| `track_no` | `int16` | 선로 번호 | 다이아그램 좌측의 트랙 번호 |
| `station` | `string` | 역 이름 | 정차 또는 통과하는 역 명칭 |
| `seq` | `int16` | 운행 순번 | 해당 열차 내에서의 역 정차 순서 |
| `time` | `string` | 시각 | `HH:MM:SS` 형식의 문자열 |

## 3. 샘플 데이터

```csv
line,diagram_type,duty_id,train_number,direction,run_type,depot,depot_detail,track_no,station,seq,time
1,holiday,1,1017,up,regular,06:31:30,,2,노포,1,06:32:30
1,holiday,1,1017,up,regular,06:31:30,,2,범어사,2,06:34:25
1,holiday,1,1017,up,regular,06:31:30,,2,남산,3,06:36:15
1,holiday,1,1017,up,regular,06:31:30,,2,두실,4,06:37:50
1,holiday,1,1017,up,regular,06:31:30,,2,구서,5,06:39:35
```

## 4. 입출력 가이드

### 데이터 읽기 (Python/Pandas)
```python
import pandas as pd

# 데이터 로드
df = pd.read_parquet("data/unified_timetable.parquet")

# 특정 열차의 운행 경로 조회 (예: 평일 1002열차)
train_info = df[(df['diagram_type'] == 'weekday') & (df['train_number'] == 1002)]
train_info = train_info.sort_values('seq')

print(train_info[['station', 'time']])
```

### 데이터 특징
1.  **세로형 구조**: 하나의 열차-역 조합이 하나의 로우(row)를 구성하여 SQL 쿼리나 필터링에 최적화되어 있습니다.
2.  **시간 정규화**: 엑셀의 다양한 시간 형식을 `HH:MM:SS` 문자열로 통일하여 정렬과 비교가 용이합니다.
3.  **통합성**: 날짜 타입별로 별도 관리하던 데이터를 하나의 파일에서 `diagram_type`으로 구분하여 관리할 수 있습니다.
