Skip to content

README.md

Latest commit

 

History

History
149 lines (119 loc) · 7.58 KB

README.md

File metadata and controls

149 lines (119 loc) · 7.58 KB
Raw

ONCycle

ONCycle

Table of Contents

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

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

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

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.