import streamlit as st st.markdown( """ # GSM Capacity Analysis Documentation """ """ This documentation provides a technical and practical reference for the GSM Capacity Analysis application, detailing input/output columns, processing workflow, and key metrics as implemented in: - apps/kpi_analysis/gsm_capacity.py - process_kpi/process_gsm_capacity.py - utils/kpi_analysis_utils.py --- ## 1. Input Files and Expected Columns ### a. Dump File (XLSB) - Contains network configuration and hardware data. - Parsed columns (see `GSM_COLUMNS`, `TRX_COLUMNS` in `process_gsm_capacity.py`): - ID_BTS, site_name, name, BSC, BCF, BTS, code, Region, adminState, frequencyBandInUse, amrSegLoadDepTchRateLower, amrSegLoadDepTchRateUpper, dedicatedGPRScapacity, defaultGPRScapacity, cellId, band, site_config_band, trxRfPower, BCCH, number_trx_per_cell, number_trx_per_bcf, TRX_TCH, MAL_TCH - TRX-related: number_tch_per_cell, number_sd_per_cell, number_bcch_per_cell, number_ccch_per_cell, number_cbc_per_cell, number_total_channels_per_cell, number_signals_per_cell ### b. Daily KPI Report (CSV) - Columns (see `KPI_COLUMNS`): - date, BTS_name, TCH_availability_ratio, 2G_Carried_Traffic, TCH_call_blocking, TCH_ABIS_FAIL_CALL_c001084, SDCCH_real_blocking ### c. Busy Hour (BH) KPI Report (CSV) - Same structure as Daily KPI, focused on peak hour data. --- ## 2. Output Columns and Their Meaning ### a. Busy Hour (BH) Analysis Output (`BH_COLUMNS_FOR_CAPACITY`): - Max_Traffic BH: Maximum traffic during busy hour in the analysis window - Avg_Traffic BH: Average traffic during busy hour - max_tch_call_blocking_bh: Max TCH call blocking during BH - avg_tch_call_blocking_bh: Average TCH call blocking during BH - number_of_days_with_tch_blocking_exceeded_bh: Days with TCH blocking above threshold - max_sdcch_real_blocking_bh: Max SDCCH blocking during BH - avg_sdcch_real_blocking_bh: Average SDCCH blocking during BH - number_of_days_with_sdcch_blocking_exceeded_bh: Days with SDCCH blocking above threshold - tch_call_blocking_bh_comment: Comments on TCH blocking - sdcch_real_blocking_bh_comment: Comments on SDCCH blocking ### b. Daily KPI Analysis Output (`DAILY_COLUMNS_FOR_CAPACITY`): - Average_cell_availability: Mean cell availability over period - number_of_days_exceeding_threshold: Days exceeding availability threshold - availability_comment: Comments on availability - avg_tch_abis_fail_daily: Average TCH ABIS fails per day - max_tch_abis_fail_daily: Max TCH ABIS fails per day - number_of_days_with_tch_abis_fail_exceeded_daily: Days with TCH ABIS fails above threshold - tch_abis_fail_daily_comment: Comments on TCH ABIS fails ### c. GSM Database Output (from dump parsing): - All columns from GSM_COLUMNS and TRX_COLUMNS - hf_rate_coef: Coefficient mapped from amrSegLoadDepTchRateLower - GPRS: Calculated as (dedicatedGPRScapacity * number_tch_per_cell) / 100 - TCH Actual HR%: number_tch_per_cell * hf_rate_coef - Offered Traffic BH: Mapped from TCH Actual HR% using ErlangB table --- ## 3. Processing Workflow 1. **Validation**: Checks file format, data completeness, and consistency. 2. **Parsing**: Extracts relevant columns and normalizes data. 3. **Analysis**: - **Busy Hour Analysis**: Computes traffic and blocking metrics for peak hours. - **Daily Analysis**: Tracks availability, blocking, and failure metrics per day. - **Capacity Estimation**: Uses traffic and configuration data to estimate TRX/channel requirements. 4. **Comments Generation**: Flags and annotates cells/sites where metrics exceed thresholds. 5. **Reporting**: Combines results into DataFrames for export/visualization. --- ## 4. Utility Functions (from `kpi_analysis_utils.py`) - `create_dfs_per_kpi(df, ...)`: Pivots and prepares KPI-specific DataFrames. - `cell_availability_analysis(df, days, threshold)`: Analyzes and comments on cell availability. - `analyze_tch_abis_fails`, `analyze_tch_call_blocking`, `analyze_sdcch_call_blocking`: Analyze blocking/failure metrics and flag threshold exceedances. - `combine_comments(df, ...)`: Combines multiple comment columns into one. --- ## 5. Example Usage ```python from process_kpi.process_gsm_capacity import analyze_gsm_data # Example call results = analyze_gsm_data( dump_path, daily_report_path, bh_report_path, number_of_kpi_days=7, number_of_threshold_days=3, availability_threshold=95, tch_abis_fails_threshold=10, sdcch_blocking_threshold=0.5, tch_blocking_threshold=0.5, max_traffic_threshold=80, ) # results: [gsm_db_df, daily_kpi_df, bh_kpi_df] ``` --- ## 6. Column Reference Table (Expanded) | Column Name | Description | |---------------------------------------------|------------------------------------------------------------------| | number_trx_per_cell | Number of TRXs (transceivers) configured per cell. Extracted from network dump. | | number_trx_per_bcf | Number of TRXs per BCF (Base Control Function). From dump. | | number_tch_per_cell | Number of Traffic Channels (TCH) per cell. Calculated from config.| | number_sd_per_cell | Number of Standalone Dedicated Control Channels per cell. From config.| | number_bcch_per_cell | Number of Broadcast Control Channels per cell. From config. | | number_ccch_per_cell | Number of Common Control Channels per cell. From config. | | number_cbc_per_cell | Number of Cell Broadcast Channels per cell. From config. | | number_total_channels_per_cell | Total channels (sum of all logical channels) per cell. | | number_signals_per_cell | Total signaling channels per cell. From config. | | hf_rate_coef | Half-rate coefficient mapped from `amrSegLoadDepTchRateLower` using a lookup table (see `GsmAnalysis.hf_rate_coef`). | | GPRS | Calculated as `(dedicatedGPRScapacity * number_tch_per_cell) / 100`. Represents estimated GPRS capacity. | | TCH Actual HR% | Calculated as `number_tch_per_cell * hf_rate_coef`. Represents the effective TCHs considering half-rate usage. | | Offered Traffic BH | Estimated offered traffic (in Erlangs) during busy hour, mapped from `TCH Actual HR%` using ErlangB table (`GsmAnalysis.erlangB_table`). | | Max_Traffic BH | Maximum traffic observed during busy hour in the analysis window. Computed from BH KPI data. | | Avg_Traffic BH | Average traffic during busy hour over the analysis period. | | max_tch_call_blocking_bh | Maximum TCH call blocking ratio during busy hour. | | avg_tch_call_blocking_bh | Average TCH call blocking ratio during busy hour. | | number_of_days_with_tch_blocking_exceeded_bh | Number of days TCH call blocking exceeded the set threshold during BH. | | max_sdcch_real_blocking_bh | Maximum SDCCH real blocking ratio during busy hour. | | avg_sdcch_real_blocking_bh | Average SDCCH real blocking ratio during busy hour. | | number_of_days_with_sdcch_blocking_exceeded_bh | Number of days SDCCH blocking exceeded threshold during BH. | | tch_call_blocking_bh_comment | Generated comment if TCH blocking exceeds threshold in BH. | | sdcch_real_blocking_bh_comment | Generated comment if SDCCH blocking exceeds threshold in BH. | | Average_cell_availability | Mean cell availability over the analysis period. | | number_of_days_exceeding_threshold | Number of days cell/site availability fell below threshold. | | availability_comment | Generated comment on site/cell availability status. | | avg_tch_abis_fail_daily | Average daily TCH ABIS fails. | | max_tch_abis_fail_daily | Maximum daily TCH ABIS fails. | | number_of_days_with_tch_abis_fail_exceeded_daily | Number of days TCH ABIS fails exceeded threshold. | | tch_abis_fail_daily_comment | Generated comment if TCH ABIS fails exceed threshold. | | TCH UTILIZATION (@Max Traffic) | TCH utilization at maximum observed traffic. Calculated as (Max_Traffic BH / TCH Actual HR%) * 100%. | | Tch utilization comments | Comments generated based on TCH utilization (e.g., if utilization is high or exceeds limits). | | BH Congestion status | Status flag/comment if congestion detected during busy hour (based on blocking/utilization thresholds). | | ErlabngB_value | Value from Erlang B table for required channels and blocking probability. Used for dimensioning. | | Target FR CHs | Calculated target number of Full Rate channels needed. | | Target HR CHs | Calculated target number of Half Rate channels needed. | | Target TCHs | Total target Traffic Channels (FR + HR) required for desired performance. | | Target TRXs | Target number of TRXs required, based on channel requirements and configuration. | | Number of required TRXs | Final computed number of TRXs required to meet traffic and blocking targets. | | operational_comment | Generated operational comment based on analysis (e.g., upgrade needed, OK, etc.). | | Final comment | Final summary comment combining all relevant flags, operational status, and recommendations. | | Final comment summary | Final summary comment combining all relevant flags, operational status, and recommendations. | --- """ )