Spaces:
Sleeping
Sleeping
| 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). | |
| --- |