How sid72020123/earthquake-data-analyzer works
1. Overall architecture
- This repo is a single-process Streamlit dashboard backed by local CSV files. There is no separate API server, database, or cloud service in the tree.
- The application is organized as a small pipeline: CSV data → loading/cleaning → analytics/ML → Streamlit UI rendering.
2. Data layer
- The data/ directory is the only persistent data source.
- It contains:
- historical.csv and historical_processed.csv for broader/global analysis,
- yearly slices year_2020.csv through year_2026.csv for time-based views and filtering.
- The app appears to use these files as offline datasets rather than fetching live earthquake feeds.
3. Application entry point
- main.py is the dashboard orchestrator.
- It likely defines the Streamlit layout, tabs, filters, and the order in which data loading, chart generation, mapping, and ML outputs are shown.
- From the README, the UI is structured around multiple sections such as Charts, Maps, Advanced, 3D & Animation, and ML Trend Forecasting.
4. Data preparation boundary
- load_data.py is the ingestion/cleaning boundary between raw CSVs and the rest of the app.
- Its role is likely to normalize columns, filter by date/country/magnitude, and provide reusable dataframes to the UI and visualization modules.
- historical_processed.csv suggests there is some precomputed or cleaned dataset used to reduce runtime preprocessing.
5. Visualization subsystem
- visualization.py is the main chart/map generation module.
- It likely contains reusable functions for:
- magnitude distributions,
- correlation analysis,
- time trends,
- categorical summaries,
- map layers and geographic summaries.
- plot.py appears to be an additional plotting helper layer, probably for specialized figures or shared chart utilities.
6. Geospatial rendering
- The map features are a distinct subsystem built on Folium and streamlit-folium, with country lookup support via reverse_geocoder and pycountry.
- This boundary turns earthquake latitude/longitude data into interactive map outputs such as heatmaps, clustered markers, and magnitude/depth-based styling.
- The geospatial layer is presentation-oriented; it does not appear to introduce a separate spatial database or GIS service.
7. Statistical/charting stack
- The dashboard uses a mixed plotting stack:
- matplotlib and seaborn for classic statistical plots,
- plotly for interactive 3D/animated visuals,
- likely Streamlit-native widgets for interactivity.
- This indicates two rendering modes: static analytical charts and richer interactive visualizations.
8. Machine learning subsystem
- ml_prediction.py encapsulates the forecasting logic for earthquake frequency trends.
- The README describes a moving average-based approach over monthly aggregated counts from historical data, with train/test evaluation and a 12-month forecast.
- This module is a separate analytical boundary from the dashboard visuals: it consumes the processed time series and emits predictions, error metrics, and forecast series for display in main.py.
9. Model evaluation/testing
- test_model.py suggests an offline verification or evaluation script for the ML forecasting path.
- This likely serves as a check on the prediction module rather than part of the interactive dashboard runtime.
- In architecture terms, it is the validation boundary around the ML subsystem.
10. Runtime and dependency implications
- The project is explicitly designed to run with Streamlit via streamlit run main.py, so the app is user-driven and executes in a single Python runtime.
- The dependency set is important architecturally because it explains the output channels:
- pandas for data shaping,
- scikit-learn for ML metrics/utilities,
- folium/streamlit-folium for maps,
- plotly for interactive charts,
- matplotlib/seaborn for statistical plots.
- The README notes the ML model uses recent historical data and emphasizes limitations, which means the ML output should be diagrammed as an auxiliary insight panel, not as an operational prediction service.
11. Key data flow to capture in a diagram
- A good architecture diagram would show:
- Local CSV datasets feeding load_data.py,
- cleaned/filtered data flowing into main.py,
- branching into visualization.py / plot.py for charts and maps,
- branching into ml_prediction.py for forecasting,
- and the rendered results returning to the Streamlit UI.
- The central boundary is the Streamlit app; the rest of the code is supporting analysis and presentation modules.
Main entry points: main.py Dashboard · load_data.py Loader · ml_prediction.py Forecasting · visualization.py Charts & maps
Components 11
Data
Local CSV datasets used by the dashboard
- CSV data · Local offline earthquake datasets stored under data/
data - Historical · Broad historical earthquake dataset
data/historical.csv - Processed hist. · Pre-cleaned historical dataset for faster analysis
data/historical_processed.csv - Year slices · Yearly partitioned datasets used for time-based views
Application
Streamlit entry point and UI orchestration
- Dashboard · Single-process dashboard entry point and orchestration layer
main.py - UI render · Rendered Streamlit tabs, filters, charts, maps, and forecasts
Analytics
Loading, visualization, and forecasting modules
- Loader · Boundary for CSV loading, cleaning, and filtering
load_data.py - Charts & maps · Reusable analytical charts, summaries, and geographic views
visualization.py - Plot helpers · Supplementary plotting utilities for specialized figures
plot.py - Forecasting · Monthly trend forecasting and evaluation logic
ml_prediction.py - Model test · Offline verification of the forecasting path
test_model.py
Connections 13
- CSV data → Loader: source · Raw datasets are ingested and normalized
- Historical → Loader: historical input · Main historical dataset feeds cleaning and aggregation
- Processed hist. → Loader: clean input · Preprocessed historical data can bypass repeated cleaning
- Year slices → Loader: time views · Yearly slices support filtering and segmented analysis
- Loader → Dashboard: prepared data · Cleaned dataframes flow into the dashboard orchestrator
- Dashboard → Charts & maps: charts/maps · Dashboard requests analytical plots and map views
- Dashboard → Plot helpers: plot support · Specialized figures use shared plotting helpers
- Dashboard → Forecasting: forecast panel · Dashboard invokes the forecasting module for trend insight
- Charts & maps → UI render: render · Charts and geographic summaries are presented in the UI
- Plot helpers → UI render: render · Supplementary plots are displayed in the dashboard
- Forecasting → UI render: forecast output · Predictions, metrics, and forecast series are surfaced to users
- Dashboard → UI render: orchestrates · Main.py composes the Streamlit layout and user flow
- Model test → Forecasting: verify · Offline checks exercise the forecasting logic