Timetable Plotter

A Python utility for generating visual timetable diagrams from CSV data, showing train movements across stations over time as distance-vs-time plots.

Features

• Interactive HTML charts with hover information (using Plotly)
• Static PNG charts for printing and documentation (using Matplotlib)
• Flexible column configuration for different CSV layouts
• Row range selection from file or command-line
• Train code-based styling: Colors by first digit, markers by second letter
• Arrival/departure tracking: Properly connects train paths through stops

Requirements

pip install pandas matplotlib plotly

Basic Usage

Generate PNG output

python plot_timetable.py "Down.csv" "Up.csv" --out timetable.png

Generate interactive HTML output

python plot_timetable.py "Down.csv" "Up.csv" --plotly --out timetable.html

Command-Line Options

Input Files

python plot_timetable.py <csv1> <csv2> ... [options]

Provide one or more CSV files containing timetable data.

Column Configuration

• --distance-col N - Distance column (1-based, default: 1 → column A)
• --stop-name-col N - Stop name column (1-based, default: 2 → column B)
• --event-col N - ARR/DEP marker column (1-based, default: 4 → column D)
• --train-code-row N - Row containing train codes (1-based, default: 4)
• --train-time-col-start N - First train time column (1-based, default: 5 → column E)

Row Selection

• --start-row N - First stop row (1-based, default: 20)
• --end-row N - Last stop row (1-based, default: 38)
• --row-range RANGE - Per-file ranges like filename=start-end or bare ranges in CSV order
• --row-range-from-file - Read row ranges from cell A1 of each CSV (format: start-end)

Output Options

• --out FILE - Output filename (default: timetable.png)
• --plotly - Generate interactive HTML instead of PNG
• --prefix-filename - Prefix train codes with source filename to avoid collisions

CSV File Format

Expected Structure

Row 1: Optional row-range metadata (if using --row-range-from-file)
Row 2-3: Header information
Row 4: Train codes (configurable with --train-code-row)
Row 5+: Stop data

Columns:
A: Distance (configurable with --distance-col)
B: Stop name (configurable with --stop-name-col)
C: Additional info
D: ARR/DEP markers (configurable with --event-col)
E+: Train times (configurable with --train-time-col-start)

Example CSV Layout

19-36,,,,,,
Distance,Stop Name,Info,Event,Train 1,Train 2,Train 3
0.0,Station A,,ARR,08:00,09:15,10:30
0.0,Station A,,DEP,08:05,09:20,10:35
5.5,Station B,,ARR,08:25,09:40,10:55
5.5,Station B,,DEP,08:30,09:45,11:00

Time Format

Accepts multiple formats:

• 5:40a or 5:40p (converts to AM/PM)
• 17:40 (24-hour)
• 6:10:00 PM (12-hour with seconds)
• - or blank for no stop

Examples

Using column B for distances, C for stop names

python plot_timetable.py "Down3.csv" "Up3.csv" \
  --distance-col 2 \
  --stop-name-col 3 \
  --row-range-from-file \
  --plotly \
  --out timetable.html

Multiple files with specific row ranges

python plot_timetable.py "Down.csv" "Up.csv" \
  --row-range "Down.csv=20-35" \
  --row-range "Up.csv=18-33" \
  --out timetable.png

Positional row ranges (applied in order)

python plot_timetable.py "Down.csv" "Up.csv" \
  --row-range "20-35" \
  --row-range "18-33" \
  --out timetable.png

Train Code Styling

The plotter uses train codes to automatically assign colors, markers, and line styles:

• Color: Based on the first digit of the train code
• Marker: Based on the second letter of the train code
• Line Style: Based on train type (first digit)
• Solid lines: Passenger trains (digits 1, 2)
• Dotted lines: Freight trains (digits 3, 4, 5, 7, 8, 9)
• Dashed lines: ECS and parcels (digit 6), light engines (digit 0)

Example codes:

• 2L00 → Color for "2", marker for "L", solid line (passenger)
• 4P00 → Color for "4", marker for "P", dotted line (freight)
• 6B00 → Color for "6", marker for "B", dashed line (ECS/parcels)
• 0X00 → Color for "0", marker for "X", dashed line (light engine)

Output Files

PNG Output

• Static image suitable for printing
• Shows station names on Y-axis
• Legend with train codes
• No time labels on individual points

HTML Output

• Interactive Plotly chart
• Hover over any point to see:
• Station name
• Arrival time
• Departure time
• Zoomable and pannable
• Downloadable as PNG from browser

Tips

1. Station Names Truncated? The script automatically adjusts left margin based on label length. If truncation occurs, try using shorter station names in your CSV.

2. Missing Endpoint Stops? Ensure your CSV has either ARR or DEP markers, or at least one time entry for endpoint stations. The script uses fallback rows when explicit markers are missing.

3. Lines Not Connecting? The script links arrivals to previous departures in time order. Verify your time formats are consistent and parseable.

4. Duplicate Train Codes? By default, duplicates are auto-suffixed as (2), (3), etc. Use --prefix-filename to prefix with source filename instead.

Troubleshooting

"No series found"

• Check --train-code-row matches your CSV
• Verify --train-time-col-start points to first train column
• Ensure train codes are in the specified row

"tight_layout warning"

• This is normal when many stations/trains are shown
• The plot still saves successfully
• Consider reducing the number of trains or stations displayed

Times Not Parsing

• Supported formats: 5:40a, 17:40, 6:10:00 PM
• Use - or leave blank for no stop
• Avoid special characters or extra spaces

License

This utility is provided as-is for timetable visualization purposes.