| 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. | | |
| --- | |
| """ | |
| ) | |