documentations/lte_capacity_docs.py

import streamlit as st

st.markdown(
    """
# LTE Capacity Analysis Documentation

This documentation provides a technical and practical reference for the LTE Capacity Analysis application, detailing input/output columns, processing workflow, and key metrics as implemented in:
- apps/kpi_analysis/lte_capacity.py
- process_kpi/process_lte_capacity.py
- utils/kpi_analysis_utils.py

---

## 1. Input Files and Expected Columns

### a. Dump File (XLSB)
- Contains network configuration and site data.
- Expected columns (see `LTE_DATABASE_COLUMNS` in `process_lte_capacity.py`):
    - code: Unique site identifier
    - Region: Geographical region of the site
    - site_config_band: Configured frequency bands at the site
    - final_name: Formatted site name

### b. Busy Hour (BH) KPI Report (CSV)
- Contains performance metrics for LTE cells during busy hours.
- Key columns (see `KPI_COLUMNS` in `process_lte_capacity.py`):
    - date: Timestamp of the measurement
    - LNCEL_name: Cell identifier (format: SiteName_LBand_CellID)
    - Cell_Avail_excl_BLU: Cell availability percentage excluding BLU
    - E_UTRAN_Avg_PRB_usage_per_TTI_DL: Average Physical Resource Block usage in downlink

---

## 2. Output Columns and Their Meaning

### a. LTE Analysis Output (`LTE_ANALYSIS_COLUMNS`):
- **Site Information**:
  - code: Site identifier
  - Region: Geographical region
  - site_config_band: Configured frequency bands

- **Cell Configuration**:
  - LNCEL_name_l800: Cell name for 800MHz band
  - LNCEL_name_l1800: Cell name for 1800MHz band
  - LNCEL_name_l2300: Cell name for 2300MHz band
  - LNCEL_name_l2600: Cell name for 2600MHz band
  - LNCEL_name_l1800s: Cell name for 1800MHz supplementary band

- **PRB Usage Metrics**:
  - avg_prb_usage_bh_l800: Average PRB usage for 800MHz band
  - avg_prb_usage_bh_l1800: Average PRB usage for 1800MHz band
  - avg_prb_usage_bh_l2300: Average PRB usage for 2300MHz band
  - avg_prb_usage_bh_l2600: Average PRB usage for 2600MHz band
  - avg_prb_usage_bh_l1800s: Average PRB usage for 1800s band

- **Cell Status**:
  - num_congested_cells: Number of cells exceeding PRB usage threshold
  - num_cells: Total number of cells at the site
  - num_cell_with_kpi: Number of cells with valid KPI data
  - num_down_or_no_kpi_cells: Number of down or non-reporting cells
  - prb_diff_between_cells: Maximum PRB usage difference between cells at the site
  - load_balance_required: Flag indicating if load balancing is needed

- **Analysis Results**:
  - congestion_comment: Comments on cell congestion status
  - final_comments: Summary of site status and recommendations

---

## 3. Processing Workflow

1. **Data Loading and Validation**:
   - Load and validate the dump file and BH report
   - Check for required columns and data integrity

2. **Data Processing**:
   - Parse site and cell information from the dump file
   - Process KPI data from the BH report
   - Calculate average PRB usage per cell and band

3. **Analysis**:
   - Identify congested cells based on PRB usage threshold
   - Calculate load balancing requirements
   - Determine site-level congestion status
   - Generate recommendations for capacity expansion

4. **Reporting**:
   - Combine all analysis results into a comprehensive DataFrame
   - Generate final comments and recommendations
   - Prepare data for visualization and export

---

## 4. Key Functions

### a. `process_lte_bh_report` (in `process_lte_capacity.py`)
- Main function that orchestrates the LTE capacity analysis
- Parameters:
  - dump_path: Path to the site dump file
  - bh_report_path: Path to the Busy Hour KPI report
  - num_last_days: Number of days to analyze
  - num_threshold_days: Number of days for threshold calculations
  - availability_threshold: Minimum required cell availability (%)
  - prb_usage_threshold: Threshold for PRB usage (%)
  - prb_diff_between_cells_threshold: Maximum allowed PRB difference between cells (%)

### b. `lte_analysis_logic` (in `process_lte_capacity.py`)
- Core logic for analyzing LTE capacity
- Identifies congested cells and calculates load balancing requirements
- Generates comments and recommendations
### c. analyze_prb_usage (in kpi_analysis_utils.py)
- Analyzes PRB usage patterns
- Identifies cells with high PRB utilization
- Generates comments on congestion status

### d. cell_availability_analysis (in kpi_analysis_utils.py)
- Analyzes cell availability metrics
- Identifies cells with availability issues
- Generates availability-related comments

---

## 5. Configuration Parameters

### a. Band Mapping (from LteCapacity class):
- Defines the recommended next band for capacity expansion
- Example: L1800 → L800, L800 → L1800, etc.

### b. Thresholds (configurable via UI/parameters):
- Availability Threshold: Default 95%
- PRB Usage Threshold: Default 80%
- PRB Difference Threshold: Default 20%
- Analysis Period: Default 7 days
- Threshold Days: Default 3 days

---

## 6. Example Usage and Output Analysis

### Basic Usage
```python
from process_kpi.process_lte_capacity import process_lte_bh_report
import pandas as pd

# Process LTE capacity analysis
results = process_lte_bh_report(
    dump_path="network_dump_202305.xlsb",
    bh_report_path="lte_bh_report_20230501_20230507.csv",
    num_last_days=7,                    # Analyze last 7 days
    num_threshold_days=3,                # Consider threshold violations if seen on ≥3 days
    availability_threshold=95.0,          # Minimum acceptable cell availability (%)
    prb_usage_threshold=80.0,            # PRB usage threshold for congestion (%)
    prb_diff_between_cells_threshold=20.0 # Max allowed PRB difference between cells (%)
)

# Unpack results
bh_report_df, lte_analysis_df = results

# Example: Display sites with congestion
congested_sites = lte_analysis_df[lte_analysis_df['num_congested_cells'] > 0]
print(f"Found {len(congested_sites)} sites with congestion")

# Example: Export results to Excel
with pd.ExcelWriter('lte_capacity_analysis.xlsx') as writer:
    lte_analysis_df.to_excel(writer, sheet_name='LTE_Analysis', index=False)
    bh_report_df.to_excel(writer, sheet_name='BH_Report', index=False)
```

### Understanding the Output
- `lte_analysis_df`: Contains per-site analysis with capacity recommendations
- `bh_report_df`: Raw busy hour metrics for detailed investigation


## 7. Column Reference Table

### Site Information
| Column | Type | Description | Example |
|--------|------|-------------|---------|
| code | str | Unique site identifier | SITE123 |
| Region | str | Mali Geographical region | CENTRAL |
| site_config_band | str | Configured frequency bands | L1800/L800 |

### Cell Configuration
| Column | Type | Description | Example |
|--------|------|-------------|---------|
| LNCEL_name_l800 | str | 800MHz cell name | SITE123_L800_1 |
| LNCEL_name_l1800 | str | 1800MHz cell name | SITE123_L1800_1 |
| LNCEL_name_l2300 | str | 2300MHz cell name | SITE123_L2300_1 |
| LNCEL_name_l2600 | str | 2600MHz cell name | SITE123_L2600_1 |
| LNCEL_name_l1800s | str | 1800s cell name | SITE123_L1800S_1 |

### PRB Usage Metrics
| Column | Type | Description | Range |
|--------|------|-------------|-------|
| avg_prb_usage_bh_l800 | float | Avg PRB usage 800MHz | 0-100% |
| avg_prb_usage_bh_l1800 | float | Avg PRB usage 1800MHz | 0-100% |
| avg_prb_usage_bh_l2300 | float | Avg PRB usage 2300MHz | 0-100% |
| avg_prb_usage_bh_l2600 | float | Avg PRB usage 2600MHz | 0-100% |
| avg_prb_usage_bh_l1800s | float | Avg PRB usage 1800s | 0-100% |

### Cell Status
| Column | Type | Description |
|--------|------|-------------|
| num_cells | int | Total cells at site |
| num_cell_with_kpi | int | Cells with valid KPI data |
| num_down_or_no_kpi_cells | int | Non-reporting cells |
| num_congested_cells | int | Cells exceeding PRB threshold |
| prb_diff_between_cells | float | Max PRB difference between cells |
| load_balance_required | bool | If load balancing is needed |

### Analysis Results
| Column | Type | Description |
|--------|------|-------------|
| congestion_comment | str | Analysis of congestion status |
| final_comments | str | Summary and recommendations |
| recommended_action | str | Suggested capacity actions |
| next_band | str | Recommended band for expansion |


"""
)