VOC_Monitor/test/dia/TIMETABLE_SPEC.md

열차 운행 시각표 데이터 명세서 (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. 샘플 데이터

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)

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으로 구분하여 관리할 수 있습니다.