ONCycle

Table of Contents

• Project Overview
• Features
• Demo
• Project Structure
• Technologies Used
• Model Performance
• References
• Legal Notice
• License

Project Overview

ONCycle is a platform designed to follow the status of trains delays in real-time. It provides users with the ability to track train delays, view historical data, and predict future delays based on historical patterns.

Features

• Real-time train delay tracking
• Historical delay data visualization
• Predictive analytics for future delays
• User-friendly interface
• Responsive design for mobile and desktop

Demo

ONCycle_preview.mp4

Check out the full website here

Project Structure

Repository Structure

ONCycle/
├── app/                                      # Main application package
│   ├── main.py                               # FastAPI app entry point
│   ├── api/routes/                           # API endpoint definitions
│   │   ├── health.py                         # Health check endpoints
│   │   └── prediction.py                     # ML prediction endpoints
│   ├── core/                                 # Core application components
│   │   ├── config.py                         # Configuration management
│   │   └── logging.py                        # Logging setup
│   ├── models/                               # ML model classes
│   │   └── predictors.py                     # Prediction model implementations
│   ├── schemas/                              # Pydantic data validation
│   │   └── prediction.py                     # Request/response schemas
│   └── services/                             # Business logic layer
│       └── model_service.py                  # Model loading and inference
├── models/                                   # Trained model files (.joblib)
├── scripts/                                  # Utility scripts
│   ├── train_models.py                       # Model training script
│   ├── test_api.py                           # API testing script
│   └── run_dev.py                            # Development server runner
├── requirements.txt                          # App dependencies
├── ui/                                       # User Interface package
│   ├── client/                               # React frontend (Vite + TypeScript)
│   └── server/                               # NextJS backend for SSR
├── experiments/                              # Model development and research
│   ├── notebooks/                            # Jupyter notebooks for analysis
|   |   ├── 00_data_cleaning.ipynb            # Initial data cleaning and exploration
|   |   ├── 01_EDA.ipynb                      # Exploratory Data Analysis
|   |   └── 02_model_selection.ipynb          # Model selection and evaluation
|   ├──scripts/                               # Utility scripts for experiments
|   ├──screenshots/                           # EDA and results screenshots
│   ├── data/                                 # Training data
│   ├── models/                               # Experimental models
|   └── README.md                             # Model metrics history

Technologies Used

• Interface: React, ViteJS, Tremor, Tremor Blocks
• Backend: FastAPI, NextJS
• Database: PostgreSQL, Supabase
• Modeling: Python, Scikit-learn, XGBoost
• Deployment: DigitalOcean, Vercel

Development Process

1. Data Science & Modeling

• Data Exploration: Explored and visualized historical train delay data to identify trends and anomalies.
• Feature Engineering: Developed temporal (hour, day, month) and route-specific features to enhance predictive power.
• Model Experimentation: Evaluated multiple algorithms; selected XGBoost for its superior performance (high accuracy, fast training/inference times, and low resource consumption).
• Validation & Testing: Used cross-validation to ensure model robustness and generalizability.

2. Backend Engineering

• API Architecture: Designed RESTful APIs using FastAPI for efficient communication between frontend and backend.
• Model Deployment: Implemented scalable model serving with optimized loading and inference pipelines.
• Data Integrity: Leveraged Pydantic for strict request/response validation and type safety.
• Monitoring: Integrated logging and health checks for reliability.

3. Frontend Development

• User Interface: Built a modern, accessible UI with React, Vite, and Tremor components.
• State Management: Implemented efficient state handling and caching for smooth user experience.
• Responsiveness: Ensured seamless usability across devices with a mobile-first design.

4. Continuous Improvement

• Continuous model training and monitoring: Regularly updated the model with new data to maintain accuracy.
• Documentation: Maintained clear documentation for contributors and users.

Model Performance

Our machine learning model is trained on historical train data and achieves:

Metric	Value
R² Score	0.852
Mean Absolute Error	3.62 minutes
Features Used	26
Training Samples	321,269
Model Version	v1.0

Model metrics history: experiments/README.md

The model uses XGBoost with engineered features including:

• Temporal features (hour, day of week, month)
• Route characteristics (distance, duration, route, number of stops, sequence...)
• Historical delay patterns

References

• Short-term train arrival delay prediction: a data-driven approach ^[Paper]
• A review of data-driven approaches to predict train delays ^[Paper]
• Prediction of rail transit delays with machine learning: How to exploit open data sources ^[Paper]
• RATPstatus.fr ^{[Inspiration]}
• xgboosting ^[Code]

Legal Notice

This project is not affiliated with or endorsed by ONCF or any other official railway authority. It is an independent project created for educational and proof of concept (POC) purposes.

License

This project is licensed under the MIT License. See the LICENSE file for details.