How sonnguyen129/accident-severity-prediction works
Project Type and Purpose
• This is a machine learning web application that predicts road traffic accident severity using a trained XGBoost model. The application has an interactive front-end built with Streamlit and is deployed on Heroku. The project includes both training (data preprocessing, model training, evaluation) and production components (web UI for prediction).
File Structure
• Top-Level Files:
• app.py: The main Streamlit application.
• prediction.py: A separate script likely used for batch or API-based predictions.
• config.py: Contains configuration parameters.
• requirements.txt, runtime.txt, Procfile, setup.sh: Deployment and configuration files for Heroku.
• Directories:
• dataset: Contains the raw input dataset (RTA_Dataset.csv).
• doc: Contains documentation assets (for example, a demo GIF).
• model: Stores the trained ML artifacts (checkpoint.pkl and model_xgb.bin).
• notebooks: Contains Jupyter notebooks for exploratory data analysis and model building.
Extracting Architectural Insights from the README
• The README explains the ML pipeline (data exploration, preprocessing including imputation and balancing, feature selection, training via XGBoost with cross-validation and hyper-parameter tuning, and explainability using SHAP).
• It also highlights the separation of concerns – the offline workflow (model training and analysis within notebooks) and the production environment (Streamlit web application and prediction scripts).
Main Components
a. User Interface / Frontend:
• Streamlit application (app.py) as the entry point for end-users.
b. ML Prediction / Inference Engine:
• Prediction.py component that ties into the model-loading process.
• Model storage (model directory with checkpoint.pkl and model_xgb.bin) from which predictions are made.
c. Configuration and Environment:
• Config.py which supplies configuration details to both training and inference modules.
d. Offline Training / Data Processing Pipeline:
• Data ingestion from the dataset directory (RTA_Dataset.csv).
• Notebooks directory to indicate that exploratory data analysis and model building occurred offline.
• Mention that preprocessing, handling of missing values, SMOTE for balancing, and feature selection were key data pipeline steps.
e. Deployment / Cloud Component:
• That the entire web application is deployed on Heroku.
• Heroku as the cloud hosting component interacting with the front-end and backend services.
Relationships and Data Flows
• A directional flow from data ingestion (raw CSV file in the dataset) to the model training phase (notebooks and scripts) that produces saved model artifacts.
• User requests (via the Streamlit UI) being processed through the prediction module and then returning outputs (predictions and possibly SHAP-based explanations).
Architectural Patterns & Technologies
• Separation between offline (training/preprocessing) and online (production inference) environments.
• Use of a configuration management approach (via config.py) and the utilization of external services (Heroku deployment).
• Technologies (Python, XGBoost, SMOTE, SHAP, Streamlit) as labels near the corresponding components.
Putting It All Together
• Drill down further into how the front-end (Streamlit) connects to the backend (prediction.py and model serving), which in turn retrieves the model from stored files.
• Finally, reference the offline training components as a separate segment that produced the artifacts now in use.