--- 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 自動測試_`. - 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). ---