README.md

---
title: Power & ER Calibration App
emoji: 🌍
colorFrom: red
colorTo: purple
sdk: gradio
sdk_version: 5.25.2
app_file: app.py
pinned: false
license: apache-2.0
short_description: Power and ER Calibration with Hierarchical-Quadratic-RSM
---

# RSM Model Trainer

This Gradio-based web app lets you:

1. **Load & preview** your Excel (.xlsx) device data (hex settings + measurements).
2. **Train** a quadratic response-surface model (RSM) mapping hex settings to measured Power and ER.
3. **Predict** optimal hex settings for a new device given target Power & ER values.

---

## Files

- `app.py` – The Gradio application.
- `requirements.txt` – Python dependencies.
- `README.md` – This file.

---

## Setup & Run Locally

1. Create a virtual environment and install dependencies:
   ```bash
   python3 -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt
   ```
2. Launch the app:
   ```bash
   python app.py
   ```
3. Open the provided local URL in your browser.

---

# Power & ER Calibration App

A Gradio-based web application for calibrating “Power” and “ER” settings on RF devices using response-surface methodology (RSM) with hierarchical (mixed-effects) quadratic models. Designed to run as a self-contained Hugging Face Space, it streamlines the entire workflow from raw Excel data to per-device calibration recommendations.

---

## 🚀 Features

1. **Data Ingestion & Preview**  
   - Upload one or more `.xlsx` files containing sheets named `Tx 自動測試_<DeviceID>`.  
   - Extract hex-encoded “Setting Power” and “Setting ER” values, convert to integers, and pair with measured outputs from an EA-4000 instrument.  
   - Preview the first *N* rows in an interactive table.

2. **Model Training**  
   - Automatically build second-degree polynomial features from your two inputs (`power_dec`, `er_dec`).  
   - Fit two separate **hierarchical quadratic RSM** models—one for Power and one for ER—using `statsmodels.MixedLM`.  
   - Display goodness-of-fit metrics (R², RMSE) for each response.

3. **Calibration & Prediction**  
   - Enter up to 5 new calibration samples (hex settings + measured outputs) and your desired target values (decimal).  
   - Compute sample-based offsets to correct for device-specific systematic error.  
   - Use a bounded optimizer (`scipy.optimize.minimize`) to find the hex settings that best achieve the target Power & ER.

4. **Hex & Decimal Transparency**  
   - All user‐facing inputs for settings remain in hex (with or without `0x`).  
   - Measured values and targets are always decimal numbers.  
   - Predictions are returned in hex.

---

## 📖 Theory

### Response Surface Methodology (RSM)

RSM is a collection of statistical techniques for:
- **Modeling** the relationship between one or more continuous input variables (factors) and one or more output responses.  
- **Optimizing** those inputs to achieve desired response targets.

A **quadratic model** augments a linear regression with squared and cross-term features:

\[
\begin{aligned}
y &= \beta_0 + \beta_1 x_1 + \beta_2 x_2 \\
  &\quad + \beta_{11} x_1^2 + \beta_{22} x_2^2 \\
  &\quad + \beta_{12} x_1 x_2 + \varepsilon
\end{aligned}
\]


where \(x_1\) = Power setting (decimal), \(x_2\) = ER setting (decimal), and \(y\) = measured output.

### Hierarchical (Mixed-Effects) Modeling

When calibrating **multiple devices**, each device may exhibit its own baseline offset or variability. A **mixed-effects** model decomposes:

- **Fixed effects** (\(\beta\)) shared across all devices.  
- **Random effects** (\(b_i\)) that capture device-specific shifts:

\[
y_{i,j} = (X_{i,j}\beta) + (Z_{i,j} b_i) + \varepsilon_{i,j}
\]

- \(i\): device index, \(j\): sample index  
- \(X\): design matrix for fixed effects (our polynomial features)  
- \(Z\): often a subset of \(X\) (here, typically an intercept term per device)  
- \(b_i \sim N(0, \Psi)\), \(\varepsilon_{i,j} \sim N(0, \sigma^2)\)

This “hierarchical quadratic RSM” lets us borrow statistical strength across devices while accounting for per-device differences.

### Calibration via Optimization

Given a trained model \(\hat{y}(x_1, x_2)\), we solve:

\[
\begin{aligned}
\min_{x_1, x_2}\quad 
&\bigl(\hat{y}_{\mathrm{Power}}(x_1,x_2) - \mathrm{TargetPower}\bigr)^2 \\[6pt]
&\!+\;\bigl(\hat{y}_{\mathrm{ER}}(x_1,x_2) - \mathrm{TargetER}\bigr)^2
\end{aligned}
\]


subject to \(x_k \in [\min_k, \max_k]\) observed in training. We use SciPy’s `optimize.minimize` under these bounds and then round & re-encode the solution back to hex.

---

## ⚙️ Installation & Setup

1. **Clone the repo**  
   ```bash
   git clone https://github.com/your-org/power-er-calibration.git
   cd power-er-calibration
   ```

2. **Install dependencies**  
   Create a virtual environment and install:
   ```bash
   python -m venv .venv
   source .venv/bin/activate
   pip install --upgrade pip
   pip install -r requirements.txt
   ```

3. **Run locally**  
   ```bash
   python app.py
   ```
   Then open the local URL (e.g. `http://localhost:7860`) in your browser.

4. **Deploy on Hugging Face Spaces**  
   - Push your `app.py`, `requirements.txt`, and `README.md` to a public or private Space.  
   - HF will automatically build and launch the Gradio UI.

---

## 🔧 Usage

1. **Tab 1 – Load Data**  
   - Click **Upload `.xlsx`**, select your calibration file.  
   - Adjust **Rows to preview** and inspect the first *N* rows.  
   - Ensure “power_hex” and “er_hex” columns look correct.

2. **Tab 2 – Train Model**  
   - Click **Train RSM**.  
   - Wait for “✅ Trained…” message showing R² & RMSE for both Power & ER.

3. **Tab 3 – Calibrate & Predict**  
   - Enter up to five new samples in hex & their measured decimal outputs.  
   - Set **Target Power (dec)** and **Target ER (dec)**.  
   - Click **Predict Settings** to receive the recommended hex settings.

---

## 📂 File Structure

```
├── app.py
├── requirements.txt
├── README.md
└── examples/
    └── sample_data.xlsx
```

- **app.py**: Main Gradio application.  
- **requirements.txt**: Python dependencies.  
- **README.md**: This documentation.  
- **examples/**: (optional) sample calibration files.

---

## 📋 Dependencies

```text
gradio>=3.20
pandas>=2.0
numpy>=1.24
scikit-learn>=1.2
statsmodels>=0.14
scipy>=1.10
openpyxl>=3.1
```

---

## 🤝 Contributing

1. Fork the repo  
2. Create a feature branch (`git checkout -b feat/your-feature`)  
3. Commit your changes (`git commit -m "Add …"`)  
4. Push to your branch (`git push origin feat/your-feature`)  
5. Open a Pull Request

---

## 📄 License

This project is licensed under the [Apache-2.0 License](LICENSE).

---