metadata

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:

Load & preview your Excel (.xlsx) device data (hex settings + measurements).
Train a quadratic response-surface model (RSM) mapping hex settings to measured Power and ER.
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

Create a virtual environment and install dependencies:

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Launch the app:
```
python app.py
```
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

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

Clone the repo

git clone https://github.com/your-org/power-er-calibration.git
cd power-er-calibration

Install dependencies
Create a virtual environment and install:

python -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

Run locally
```
python app.py
```
Then open the local URL (e.g. http://localhost:7860) in your browser.
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

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.
Tab 2 – Train Model
- Click Train RSM.
- Wait for “✅ Trained…” message showing R² & RMSE for both Power & ER.
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

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

🤝 Contributing

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

📄 License

This project is licensed under the Apache-2.0 License.