add gsm capacity docs

app.py

@@ -150,6 +150,10 @@ if check_password():
             st.Page(
                 "documentations/core_dump_doc.py", title="📗Dump core Documentation"
             ),
+            st.Page(
+                "documentations/gsm_capacity_docs.py",
+                title="📘GSM Capacity Documentation",
+            ),
         ],
     }
 

documentations/gsm_capacity_docs.py

@@ -0,0 +1,154 @@
+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. |
+| Numberof 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. |
+
+---
+
+"""
+)