How karim-071/flood-prediction works
1. Overall shape
- This repository is a small, self-contained Python analytics application with two distinct execution paths:
- Interactive inference/UI via app.py
- Offline model training via train_model.py
- The app is focused on historical flood-risk assessment, not forecasting. The bundled model artifact in models/flood_risk_model.pkl is loaded at runtime by the Streamlit app.
2. Primary runtime entrypoint: app.py
- app.py is the user-facing entrypoint and is the main Streamlit application.
- It likely orchestrates the entire UI: loading data, generating rainfall charts, calling the prediction helper, and rendering model explanation outputs.
- In an architecture diagram, this is the top-level presentation layer and the central consumer of the model and data utilities.
3. Data source boundary
- The repository uses a local CSV file at data/rainfall.csv as the core dataset.
- This file is the system’s main analytical input for both:
- descriptive rainfall exploration
- feature engineering for flood-risk classification
- There are no external databases or APIs in the repo; the data boundary is local file-based.
4. Model artifact boundary
- models/flood_risk_model.pkl is a persisted scikit-learn model artifact.
- The Streamlit app likely loads this file through utils/predict.py to produce probability and risk labels.
- This separation means training is offline, while inference is lightweight and file-based.
5. Training pipeline: train_model.py
- train_model.py is the offline ML pipeline that builds the classifier from the rainfall dataset.
- It likely:
- reads data/rainfall.csv
- creates engineered climatic features
- derives flood-risk labels
- trains a Random Forest Classifier
- saves the fitted model into models/flood_risk_model.pkl
- This training script is the only place where model generation happens; the app itself is not retraining the model.
6. Feature engineering layer: utils/features.py
- This module is the feature boundary between raw rainfall records and model-ready inputs.
- Based on the README, it likely computes:
- annual rainfall
- monsoon rainfall
- pre-monsoon rainfall
- post-monsoon rainfall
- monsoon anomaly
- monsoon percentile
- This is a key subsystem because both training and inference must use the same feature definitions.
7. Label generation and risk definition: utils/labeling.py
- This module likely converts historical rainfall patterns into flood-risk labels for supervised training.
- The README suggests the target is derived from extreme monsoon rainfall percentiles rather than from actual flood-event operational data.
- In an architecture diagram, this is the domain logic that defines what “flood risk” means in this system.
8. Prediction workflow: utils/predict.py
- This module is the inference adapter used by the app.
- Its role is likely to load the trained model, assemble the feature vector for a selected state/period, and return:
- flood probability
- risk class such as low / medium / high
- This module sits between the UI and the persisted model artifact.
9. Explainability layer: utils/explain.py
- The app includes model explainability, and this module likely extracts or formats feature-importance information from the trained Random Forest.
- This is a presentation-support subsystem, not part of the prediction logic itself.
- It helps the Streamlit UI visualize why the model produced a certain risk score.
10. Data loading boundary: utils/data_loader.py
- This module likely centralizes CSV ingestion and preprocessing of the rainfall dataset.
- Keeping loading logic isolated avoids duplicating file-path and parsing assumptions across the app and training script.
- It is the first step in both the analytical and ML flows.
11. User-facing analytical features
- The README describes a second major app section for rainfall analysis and visualization.
- That part likely reads directly from the dataset and produces Plotly charts and monthly/period statistics without involving the ML model.
- So the app has two parallel flows:
- descriptive analytics from raw data
- risk scoring through the trained classifier
12. Technology and packaging boundaries
- Core stack: Streamlit, Pandas, scikit-learn, Plotly, Joblib.
- requirements.txt defines the runtime dependencies.
- .devcontainer/ suggests the repo is set up for containerized development, but it does not appear to affect runtime architecture.
13. End-to-end data flow
- The likely end-to-end flow is:
- CSV dataset → loading/preprocessing → feature engineering → model training → serialized model
- At runtime: user interaction in Streamlit → data selection/aggregation → feature construction → model inference → probability/risk output → explanation/chart rendering
- The key architectural boundary is between offline training and online inference/UI.
14. What to show in a diagram
- At minimum, depict these nodes and connections:
- app.py as the UI orchestrator
- data/rainfall.csv as the source dataset
- utils/data_loader.py, utils/features.py, utils/labeling.py as preprocessing/domain logic
- train_model.py as offline model builder
- models/flood_risk_model.pkl as the persisted ML artifact
- utils/predict.py and utils/explain.py as inference/explainability services inside the app
- The architecture is monolithic and local, with no distributed services or external APIs.
Main entry points: app.py app.py · train_model.py train_model.py · features.py Features · predict.py Predict
Components 11
Interactive runtime
Streamlit app and inference-side support
Offline training
Model build and serialization flow
- train_model.py · Offline pipeline that trains the classifier and saves the artifact
train_model.py
Data boundary
Local dataset and persisted artifact
- rainfall.csv · Local rainfall history used for analysis and model building
data/rainfall.csv - model.pkl · Persisted flood-risk classifier loaded at runtime
models/flood_risk_model.pkl
Domain logic
Feature and label preparation
- Data loader · Centralizes CSV reading and dataset preparation
utils/data_loader.py - Features · Builds rainfall-based model features from raw records
utils/features.py - Labeling · Derives historical flood-risk labels for supervised training
utils/labeling.py
Other components
- requirements · Python package set for app and training execution
requirements.txt - Dev container · Containerized development configuration
.devcontainer/devcontainer.json
Connections 17
- app.py → Predict: score risk · Interactive UI requests flood-risk predictions
- app.py → Explain: show reasons · UI renders model interpretation outputs
- app.py → Data loader: load data · UI reads the rainfall dataset for descriptive analysis
- app.py → Features: build inputs · UI prepares feature vectors for selected views
- Predict → model.pkl: load model · Inference uses the persisted classifier artifact
- Predict → Features: assemble features · Prediction depends on the shared feature definitions
- Explain → model.pkl: inspect model · Explainability derives outputs from the trained classifier
- train_model.py → Data loader: ingest data · Training starts from the local rainfall dataset
- train_model.py → Features: engineer inputs · Training converts raw rainfall records into model features
- train_model.py → Labeling: derive labels · Training creates flood-risk targets from historical rainfall patterns
- train_model.py → model.pkl: save artifact · Training persists the fitted model for later inference
- Data loader → rainfall.csv: read · CSV ingestion boundary
- Features → rainfall.csv: transform · Feature engineering consumes raw rainfall history
- Labeling → rainfall.csv: derive target · Label logic analyzes the same historical dataset
- app.py → requirements: depends on · Runtime package boundary
- train_model.py → requirements: depends on · Training package boundary
- app.py → Dev container: dev setup · Development environment support