kalviumcommunity/datadrivers

Purpose and entry points

This is a Python analytics pipeline for identifying hotel customer segments associated with occupancy volatility, aimed at revenue-management decisions. The main operational entry points are the orchestration script at pipeline.py and the dashboard at streamlit_app.py. Analysis can also be run as discrete stages through modules such as cleaning.py, segmentation.py, and volatility.py.

Source data and persistence boundary

The pipeline consumes hotel booking data from data/hotel_bookings.csv. It materializes processed CSV artifacts under data/processed/ and includes a SQLite database, hotel_bookings.db, as a structured-query boundary. The repository therefore supports both file-based analytical handoffs and SQL-based aggregation.

Data cleaning and quality stage

Booking records are normalized before downstream metrics and segmentation. Cleaning implementations exist at cleaning.py and scripts/cleaning.py; their output is represented by data/processed/cleaned_data.csv and data/processed/cleaned_hotel_bookings.csv. Validation/reporting artifacts are written separately, including data/processed/reports/validation_check.md, keeping data-quality evidence outside dashboard presentation.

KPI and SQL aggregation layer

kpi_engine.py computes business-level metrics from cleaned data, producing data/processed/kpis.csv. sql_aggregation.py provides the database-oriented aggregation path, likely using hotel_bookings.db to derive grouped booking, cancellation, or occupancy-related measures. This layer is the boundary between raw record transformations and stakeholder-facing summaries.

Segmentation and volatility analysis

segmentation.py assigns or derives customer groups from available booking attributes and persists the analytical population to data/processed/segmented_data.csv. volatility.py then evaluates fluctuation measures by segment, with results stored in data/processed/volatility.csv. This is the core decision flow: cleaned bookings → segment labels → segment-level volatility comparisons.

Insights and exploration outputs

eda_analysis.py and notebooks/data_audit.ipynb support exploratory analysis and audit work rather than the primary production path. Generated narrative findings are retained at data/processed/reports/business_insights.txt, allowing business conclusions to be consumed independently of the dashboard.

Presentation and runtime

streamlit_app.py is the presentation boundary: it should read persisted KPI, segmentation, and volatility artifacts to visualize booking/cancellation trends and compare segments. The material runtime is Python with pandas-style file processing, SQLite-backed SQL aggregation, and Streamlit for the interactive dashboard; no external APIs or cloud services are indicated by the repository tree.