# 열차 운행 시각표 데이터 명세서 (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`으로 구분하여 관리할 수 있습니다.

### 주박지(다대포해수욕장역)

1. 다대포해수욕장 주박지 4개 편성의 입출고 순서

입고순서 : 2번선 > 3번선 > 4번선 > 상선승강장
출고순서 : 4번선 > 상선승강장 > 3번선 > 2번선


2. 각각의 입,출고 열번
평일 입고열번 : 1335(31다이아), 1339(33다이아), 1349(45다이아), 1351(13다이아)
평일 출고열번 : 2002(1다이아), 2004(3다이아), 2022(9다이아), 2036(17다이아)

토요일 입고열번 : 1315(27다이아), 1319(31다이아), 1329(7다이아), 1331(11다이아)
토요일 출고열번 : 2002(1다이아), 2004(3다이아), 2022(9다이아), 2038(17다이아)

휴일 입고열번 : 1301(29다이아), 1305(31다이아), 1315(37다이아), 1317(13다이아)
휴일 출고열번 : 2002(1다이아), 2004(3다이아), 2022(11다이아), 2038(19다이아)


3. 입출고 순서
평일 입고 - 평일 출고는
평일 1335 2번선 입고 > 1339 3번선 입고 > 1349 4번선 입고 > 1351 상선승강장 입고
평일 2002 4번선 출고 > 2004 상선승강장 출고 > 2022 3번선 출고 > 2036 2번선 출고

평일 입고 - 토요일 출고는
평일 1335 2번선 입고 > 1339 3번선 입고 > 1349 4번선 입고 > 1351 상선승강장 입고
토요일 2002 4번선 출고 > 2004 상선승강장 출고 > 2022 3번선 출고 > 2038 2번선 출고

토요일 입고 - 휴일 출고는
토요일 1315 2번선 입고 > 1319 3번선 입고 > 1329 4번선 입고 > 1331 상선승강장 입고
휴일 2002 4번선 출고 > 2004 상선승강장 출고 > 2022 3번선 출고 > 2038 2번선 출고

평일입고 - 휴일출고는
평일 1335 2번선 입고 > 1339 3번선 입고 > 1349 4번선 입고 > 1351 상선승강장 입고
휴일 2002 4번선 출고 > 2004 상선승강장 출고 > 2022 3번선 출고 > 2038 2번선 출고

휴일입고 - 휴일출고는
휴일 1301 2번선 입고 > 1305 3번선 입고 > 1315 4번선 입고 > 1317 상선승강장 입고
휴일 2002 4번선 출고 > 2004 상선승강장 출고 > 2022 3번선 출고 > 2038 2번선 출고
